#######
Plugins
#######

Plugins are the basic unit for rules application. Plugins defines
:bolditalic:`actions` which can be either :bolditalic:`verbs` or
:bolditalic:`conditionals`.

* :bolditalic:`conditionals` filter the execution of verbs in a rule. If all the conditionals of a rule returns ``true``, the verbs are executed. Conditionals are identified because they start with the prefix ``if``.
* :bolditalic:`verbs` execute actions against the files defined in the special ``files`` property of each rule. They act like asserters.

*********
inclusion
*********

Plain content inclusion management.

includeLines
============

Check that the files include all lines passed as argument.

If the files don't include all lines specified as argument,
it will raise a checking error. Newlines are ignored, so they
should not be specified.

.. rubric:: Example

.. code-block:: js

   {
     rules: [
       files: [".gitignore"],
       includeLines: ["venv*/", "/dist/"]
     ]
   }

.. versionadded:: 0.1.0

ifIncludeLines
==============

Conditional to exclude rule only if some files include a set of lines.

If one file don't include all lines passed as parameter,
the rule will be ignored.

Accepts an object mapping files to lines that must be included in order
to execute the rule.

.. rubric:: Example

If the license defined in the `LICENSE` file is BSD-3, ``tool.poetry.license``
must correspont:

.. code-block:: js

   {
     rules: [
       files: ["pyproject.toml"],
       ifIncludeLines: {
         LICENSE: ["BSD 3-Clause License"],
       },
       JMESPathsMatch: [
         ["tool.poetry.license", "BSD-3-License"],
       ]
     ]
   }

.. versionadded:: 0.1.0

excludeContent
==============

Check that the files do not include certain content.

The specified partial contents can match multiple lines
and line ending characters.

.. rubric:: Example

Don't allow code blocks in RST documentation files:

* Bash is not a POSIX compliant shell.
* Pygments' JSON5 lexer is not implemented yet.

.. code-block:: js

   {
     rules: [
       files: ["docs/**/*.rst"],
       excludeContent: [
         ".. code-block::  ",
         ".. code-block:: bash",
         ".. code-block:: json5",
       ],
     ]
   }

.. versionadded:: 0.3.0

*********
existence
*********

Check existence of files.

ifFilesExist
============

Check if a set of files and/or directories exists.

Accepts an array of paths. If a path ends with ``/`` character it is
considered a directory.

.. rubric:: Examples

If the directory `src/` exists, a `pyproject.toml` file must exist also:

.. code-block:: js

   {
     rules: [
       files: ["pyproject.toml"],
       ifFilesExist: ["src/"],
     ]
   }

If the file `.pre-commit-hooks.yaml` exists, must be declared as an array:

.. code-block:: js

   {
     rules: [
       files: [".pre-commit-hooks.yaml"],
       ifFilesExist: [".pre-commit-hooks.yaml"],
       JMESPathsMatch: [["type(@)", "array"]]
     ]
   }

.. versionadded:: 0.4.0

********
jmespath
********

`JMES paths`_ manipulation against files.

The actions of this plugin operates against object-serialized versions
of files, so only files that can be serialized can be targetted (see
:ref:`in-depth/serialization:Objects serialization`).

You can use in expressions all `JMESPath builtin functions`_ plus a set of
convenient functions defined by the plugin internally:

.. function:: regex_match(pattern: str, string: str[, flags: int=0]) -> bool

   Match a regular expression against a string using the Python's built-in
   :py:func:`re.match` function.

   .. versionadded:: 0.1.0

   .. versionchanged:: 0.5.0

      Allow to pass ``flags`` optional argument as an integer.

.. function:: regex_matchall(pattern: str, strings: list[str]) -> bool

   Match a regular expression against a set of strings defined in an array
   using the Python's built-in :py:func:`re.match` function.

   .. versionadded:: 0.1.0

   .. deprecated:: 0.4.0

.. function:: regex_search(pattern: str, string: str[, flags: int=0]) -> list[str]

   Search using a regular expression against a string using the Python's
   built-in :py:func:`re.search` function. Returns all found groups in an
   array or an array with the full match as the unique item if no groups
   are defined. If no results are found, returns an empty array.

   .. versionadded:: 0.1.0

   .. versionchanged:: 0.5.0

      Allow to pass ``flags`` optional argument as an integer.

.. function:: regex_sub(pattern: str, repl: str, string: str[, count: int=0[, flags: int=0]]) -> str

   Replace using a regular expression against a string using the Python's
   built-in :py:func:`re.sub` function.

   .. versionadded:: 0.5.0

.. function:: op(source: type, operation: str, target: type) -> bool

   Applies the operator `operator` between the two values using the operators
   for two values defined in :py:mod:`op`. The next operators are available:

   * ``<``: :py:func:`operator.lt`
   * ``<=``: :py:func:`operator.le`
   * ``==``: :py:func:`operator.eq`
   * ``!=``: :py:func:`operator.ne`
   * ``>=``: :py:func:`operator.ge`
   * ``>``: :py:func:`operator.gt`
   * ``is``: :py:func:`operator.is_`
   * ``is_not``: :py:func:`operator.is_not`
   * ``is-not``: :py:func:`operator.is_not`
   * ``is not``: :py:func:`operator.is_not`
   * ``isNot``: :py:func:`operator.is_not`
   * ``+``: :py:func:`operator.add`
   * ``&``: :py:func:`operator.and_`
   * ``and``: :py:func:`operator.and_`
   * ``//``: :py:func:`operator.floordiv`
   * ``<<``: :py:func:`operator.lshift`
   * ``%``: :py:func:`operator.mod`
   * ``*``: :py:func:`operator.mul`
   * ``@``: :py:func:`operator.matmul`
   * ``|``: :py:func:`operator.or_`
   * ``or``: :py:func:`operator.or_`
   * ``**``: :py:func:`operator.pow`
   * ``>>``: :py:func:`operator.rshift`
   * ``-``: :py:func:`operator.sub`
   * ``/``: :py:func:`operator.truediv`
   * ``^``: :py:func:`operator.xor`
   * ``count_of``: :py:func:`operator.countOf`
   * ``count of``: :py:func:`operator.countOf`
   * ``count-of``: :py:func:`operator.countOf`
   * ``countOf``: :py:func:`operator.countOf`
   * ``index_of``: :py:func:`operator.indexOf`
   * ``index of``: :py:func:`operator.indexOf`
   * ``index-of``: :py:func:`operator.indexOf`
   * ``indexOf``: :py:func:`operator.indexOf`

   If ``source`` and ``target`` are both of type array and the operator
   is one of the next ones, the arrays are converted to
   :external:py:class:`set` before applying the operator:

   * ``<``: :py:func:`operator.lt`
   * ``<=``: :py:func:`operator.le`
   * ``>=``: :py:func:`operator.ge`
   * ``>``: :py:func:`operator.gt`
   * ``&``: :py:func:`operator.and_`
   * ``and``: :py:func:`operator.and_`
   * ``|``: :py:func:`operator.or_`
   * ``or``: :py:func:`operator.or_`
   * ``-``: :py:func:`operator.sub`
   * ``^``: :py:func:`operator.xor`

   .. versionadded:: 0.1.0

   .. versionchanged:: 0.4.0

      Convert to :external:py:class:`set` before applying operators if both
      arguments are arrays.

.. function:: shlex_split(cmd_str: str) -> list

   Split a string using the Python's built-in :py:func:`shlex.split` function.

   .. versionadded:: 0.4.0

.. function:: shlex_join(cmd_list: list[str]) -> str

   Join a list of strings using the Python's built-in :py:func:`shlex.join` function.

   .. versionadded:: 0.4.0

.. function:: round(number: float[, precision: int]) -> float

   Round a number to a given precision using the function :external:py:func:`round`.

   .. versionadded:: 0.5.0

.. function:: range([start: float,] stop: float[, step: float]) -> list

   Return an array of numbers from ``start`` to ``stop`` with a step of ``step``
   casting the result of the constructor :external:py:class:`range` to an array.

   .. versionadded:: 0.5.0

.. function:: capitalize(string: str) -> str

   Capitalize the first letter of a string using :py:meth:`str.capitalize`.

   .. versionadded:: 0.5.0

.. function:: casefold(string: str) -> str

   Return a casefolded copy of a string using :py:meth:`str.casefold`.

   .. versionadded:: 0.5.0

.. function:: center(string: str, width: int[, fillchar: str]) -> str

   Return centered in a string of length ``width`` using :py:meth:`str.center`.

   .. versionadded:: 0.5.0

.. function:: count(value: str | list, sub: any[, start: int[, end: int]]) -> int

   Return the number of occurrences of ``sub`` in ``value`` using :py:meth:`str.count`.
   If ``start`` and ``end`` are given, return the number of occurrences between
   ``start`` and ``end``.
   .

   .. versionadded:: 0.5.0

.. function:: find(string: str | list, sub: any[, start: int[, end: int]]) -> int

   Return the lowest index in ``value`` where subvalue ``sub`` is found.
   If ``start`` and ``end`` are given, return the number of occurrences between
   ``start`` and ``end``. If not found, ``-1`` is returned. If ``value`` is a string
   it uses internally the Python's built-in function :py:meth:`str.find`
   or :py:meth:`str.index` if ``value`` is an array.

   .. versionadded:: 0.5.0

.. function:: format(schema: str, *args: any) -> str

   Return a string formatted using the Python's built-in :py:func:`format` function.
   The variable ``schema`` only accepts numeric indexes delimited by braces ``{}``
   for positional arguments in ``*args``.

   .. versionadded:: 0.5.0

.. function:: isalnum(string: str) -> bool

   Return True if all characters in ``string`` are alphanumeric using :py:meth:`str.isalnum`.

   .. versionadded:: 0.5.0

.. function:: isalpha(string: str) -> bool

   Return True if all characters in ``string`` are alphabetic using :py:meth:`str.isalpha`.

   .. versionadded:: 0.5.0

.. function:: isascii(string: str) -> bool

   Return True if all characters in ``string`` are ASCII using :py:meth:`str.isascii`.

   .. versionadded:: 0.5.0

.. function:: isdecimal(string: str) -> bool

   Return True if all characters in ``string`` are decimal using :py:meth:`str.isdecimal`.

   .. versionadded:: 0.5.0

.. function:: isdigit(string: str) -> bool

   Return True if all characters in ``string`` are digits using :py:meth:`str.isdigit`.

   .. versionadded:: 0.5.0

.. function:: isidentifier(string: str) -> bool

   Return True if all characters in ``string`` are identifiers if the string is a valid
   identifier according to the Python language definition using :py:meth:`str.isidentifier`.

   .. versionadded:: 0.5.0

.. function:: islower(string: str) -> bool

   Return True if all characters in ``string`` are lowercase using :py:meth:`str.islower`.

   .. versionadded:: 0.5.0

.. function:: isnumeric(string: str) -> bool

   Return True if all characters in ``string`` are numeric using :py:meth:`str.isnumeric`.

   .. versionadded:: 0.5.0

.. function:: isprintable(string: str) -> bool

   Return True if all characters in ``string`` are printable using :py:meth:`str.isprintable`.

   .. versionadded:: 0.5.0

.. function:: isspace(string: str) -> bool

   Return True if all characters in ``string`` are whitespace using :py:meth:`str.isspace`.

   .. versionadded:: 0.5.0

.. function:: istitle(string: str) -> bool

   Return True if all characters in ``string`` are titlecased using :py:meth:`str.istitle`.

   .. versionadded:: 0.5.0

.. function:: isupper(string: str) -> bool

   Return True if all characters in ``string`` are uppercase using :py:meth:`str.isupper`.

   .. versionadded:: 0.5.0

.. function:: ljust(string: str, width: int[, fillchar: str]) -> str

   Return a left-justified version of the string using :py:meth:`str.ljust`.

   .. versionadded:: 0.5.0

.. function:: lower(string: str) -> str

   Return a lowercased version of the string using :py:meth:`str.lower`.

   .. versionadded:: 0.5.0

.. function:: lstrip(string: str[, chars: str]) -> str

   Return a left-stripped version of the string using :py:meth:`str.lstrip`.

   .. versionadded:: 0.5.0

.. function:: partition(string: str, sep: str) -> list[str]

   Return an array of 3 items containing the part before the separator,
   the separator itself, and the part after the separator.

   .. versionadded:: 0.5.0

.. function:: removeprefix(string: str, prefix: str) -> str

   Return a string with the given prefix removed using :py:meth:`str.removeprefix`.

   .. versionadded:: 0.5.0

.. function:: removesuffix(string: str, suffix: str) -> str

   Return a string with the given suffix removed using :py:meth:`str.removesuffix`.

   .. versionadded:: 0.5.0

.. function:: rfind(string: str | list, sub: any[, start: int[, end: int]]) -> int

   Return the highest index in ``value`` where subvalue ``sub`` is found.
   If ``start`` and ``end`` are given, return the number of occurrences between
   ``start`` and ``end``. If not found, ``-1`` is returned. If ``value`` is a string
   it uses internally the Python's built-in function :py:meth:`str.find`
   or :py:meth:`str.index` if ``value`` is an array.

   .. versionadded:: 0.5.0

.. function:: rjust(string: str, width: int[, fillchar: str]) -> str

   Return a right-justified version of the string using :py:meth:`str.rjust`.

   .. versionadded:: 0.5.0

.. function:: rpartition(string: str, sep: str) -> list[str]

   Return an array of 3 items containing the part after the separator,
   the separator itself, and the part before the separator splitting the
   string at the last occurrence of ``sep``.

   .. versionadded:: 0.5.0

.. function:: rsplit(string: str[, sep: str[, maxsplit: int]]) -> list[str]

   Return a list of the words in the string, using ``sep`` as the delimiter string
   as returned from the method :py:meth:`str.rsplit`. Except for splitting from the
   right, :py:func:`rsplit` behaves like :py:func:`split`.

   .. versionadded:: 0.5.0

.. function:: rstrip(string: str[, chars: str]) -> str

   Return a right-stripped version of the string using :py:meth:`str.rstrip`.

   .. versionadded:: 0.5.0

.. function:: split(string: str[, sep: str[, maxsplit: int]]) -> list[str]

   Return a list of the words in the string, using ``sep`` as the delimiter string
   as returned from the method :py:meth:`str.split`. If ``sep`` is not given,
   it defaults to ``None``, meaning that any whitespace string is a separator.

   .. versionadded:: 0.5.0

.. function:: splitlines(string: str[, keepends: bool]) -> list[str]

   Return a list of the lines in the string, breaking at line boundaries using
   the method :py:meth:`str.splitlines`.

   .. versionadded:: 0.5.0

.. function:: strip(string: str[, chars: str]) -> str

   Return a stripped version of the string using :py:meth:`str.strip`.

   .. versionadded:: 0.5.0

.. function:: swapcase(string: str) -> str

   Return a swapped-case version of the string using :py:meth:`str.swapcase`.

   .. versionadded:: 0.5.0

.. function:: title(string: str) -> str

   Return a titlecased version of the string using :py:meth:`str.title`.

   .. versionadded:: 0.5.0

.. function:: upper(string: str) -> str

   Return an uppercased version of the string using :py:meth:`str.upper`.

   .. versionadded:: 0.5.0

.. function:: zfill(string: str, width: int) -> str

   Return a zero-padded version of the string using :py:meth:`str.zfill`.

   .. versionadded:: 0.5.0

.. function:: enumerate(string: str | list | dict) -> list[list[int, str]]

   Return an array of arrays containing the index and value of each item in the iterable.
   If the iterable is an object, the value is converted before using :py:func:`to_items`.

   .. versionadded:: 0.5.0

.. function:: to_items(string: dict) -> list[list[str, any]]

   Convert an object to an array of arrays containing the key and value of each item.

   .. versionadded:: 0.5.0

.. function:: from_items(items: list[list[str, any]]) -> dict

   Convert an array of arrays containing the key and value of each item to an object.

   .. versionadded:: 0.5.0

.. function:: rootdir_name() -> str

   Returns the name if the root directory of the project (passed in :ref:`project-config---rootdir`
   CLI option or defined in ``cli.rootdir`` :doc:`configuration option <./config>`).

.. _JMES paths: https://jmespath.org
.. _JMESPath builtin functions: https://jmespath.org/proposals/functions.html#built-in-functions

JMESPathsMatch
==============

Compares a set of JMESPath expressions against results.

Object-serializes each file in the ``files`` property of the rule
and executes each expression given in the first item of the
tuples passed as value. If a result don't match, report an error.

.. rubric:: Example

The `.editorconfig` file must have the next content:

.. code-block:: ini

   root = true

   [*]
   end_of_line = lf
   charset = utf-8
   indent_style = space
   trim_trailing_whitespace = true

.. code-block:: js

   {
     rules: [
       {
         files: [".editorconfig"],
         JMESPathsMatch: [
           ['"".root', true],
           ['"*".end_of_line', "lf"],
           ['"*".indent_style', "space"],
           ['"*".charset', "utf-8"],
           ['"*".trim_trailing_whitespace', true],
         ],
       }
     ]
   }

.. versionadded:: 0.1.0

crossJMESPathsMatch
===================

JMESPaths matching between multiple files.

Accepts an array of arrays. Each one of these arrays must have the syntax:

.. code-block:: js

   [
     "filesJMESPathExpression",  // expression to query each file in `files` property of the rule
     ["otherFile.ext", "JMESPathExpression"]...,  // optionally other files
     "finalJMESPathExpression",  // an array with results of previous expressions as input
     expectedValue,  // value to compare with the result of final JMESPath expression
   ]

The executed steps are:

1. For each object-serialized file in ``files`` property of the rule.
2. Execute ``"filesJMESPathExpression"`` and append the result to a temporal array.
3. For each pair of ``["otherFile.ext", "JMESPathExpression"]``, execute
   ``"JMESPathExpression"`` against the object-serialized version of
   ``"otherFile.ext"`` and append each result to the temporal array.
4. Execute ``"finalJMESPathExpression"`` against the temporal array.
5. Compare the final result with ``expectedValue`` and raise error if not match.

.. tip::

   Other file paths can be URLs if you want to match against online sources.

.. rubric:: Example

The ``release`` field of a Sphinx configuration defined in a file
`docs/conf.py` must be the same that the version of the project metadata
defined in th file `pyproject.toml`, field ``tool.poetry.version``:

.. code-block:: js

   {
     rules: [
       {
         files: ["pyproject.toml"],
         crossJMESPathsMatch: [
           [
             "tool.poetry.metadata",
             ["docs/conf.py", "release"],
             "op([0], '==', [1])",
             true,
           ],
         ],
         hint: "Versions of documentation and metadata must be the same"
       }
     ]
   }

Note that you can pass whatever number of other files, even 0 and just apply
``files`` and ``final`` expressions to each file in ``files`` property of
the rule. For example, the next configuration would not raise errors:

.. tabs::

   .. tab:: style.json5

      .. code-block:: js

         {
           rules: [
             {
               files: ["foo.json"],
               crossJMESPathsMatch: [
                 ["bar", "[0].baz", 7],
               ]
             }
           ]
         }

   .. tab:: foo.json

      .. code-block:: json

         {"bar": {"baz": 7}}

You can also override the :doc:`../in-depth/serialization` to use for opening
other files using ``file/path.ext?serializer`` syntax. For example, to open a Python
file line by line:

.. tabs::

   .. tab:: file.py

      .. code-block:: py

         foo = True
         bar = False

   .. tab:: style.json5

      .. code-block:: js

         {
           rules: [
             {
               files: ["file.py"],  // just asserts that the file exists
               crossJMESPathsMatch: [
                 ["null", ["file.py?text", "[0]"], "[1]", "foo = True"],
               ]
             }
           ]
         }

.. versionadded:: 0.4.0

ifJMESPathsMatch
================

Compares a set of JMESPath expressions against results.

JSON-serializes each file in the ``ifJMESPathsMatch`` property
of the rule and executes each expression given in the first item of the
tuples passed as value for each file. If a result don't match,
skips the rule.

.. rubric:: Example

If ``inline-quotes`` config of flake8 is defined to use double quotes,
Black must be configured as the formatting tool in ``pyproject.toml``:

.. code-block:: js

   {
     rules: [
       {
         files: ["pyproject.toml"],
         ifJMESPathsMatch: {
           "pyproject.toml": [
              ["tool.flakeheaven.inline_quotes", "double"],
            ],
         },
         JMESPathsMatch: [
           ["contains(keys(@), 'tool')", true],
           ["contains(keys(tool), 'black')", true],
         }
       }
     ]
   }

.. versionadded:: 0.1.0