Metadata-Version: 2.4
Name: not-grep
Version: 1.0.1
Summary: kinda like grep but not quite
Home-page: https://github.com/mattsb42-meta/not-grep
Author: Matt Bullock
Author-email: m@ttsb42.com
Maintainer: Matt Bullock
License: Apache 2.0
Keywords: not-grep not_grep
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Utilities
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
License-File: LICENSE
Requires-Dist: click>=7.1.1
Requires-Dist: attrs>=19.3.0
Requires-Dist: toml>=0.10.0
Requires-Dist: setuptools<=81.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: requires-dist
Dynamic: summary

########
not-grep
########

.. image:: https://img.shields.io/pypi/v/not-grep.svg
   :target: https://pypi.python.org/pypi/not-grep
   :alt: Latest Version

.. image:: https://img.shields.io/pypi/pyversions/not-grep.svg
   :target: https://pypi.python.org/pypi/not-grep
   :alt: Supported Python Versions

.. image:: https://img.shields.io/badge/code_style-black-000000.svg
   :target: https://github.com/ambv/black
   :alt: Code style: black

.. image:: https://readthedocs.org/projects/not-grep/badge/
   :target: https://not-grep.readthedocs.io
   :alt: Documentation Status

``not-grep`` is kind of like grep, but different.

WAT?
====

If you have ever needed to inspect a file for particular patterns,
you probably used ``grep``.

.. code-block:: bash

    grep FooClassName file.py

If you needed to do that for a lot of files, you might have combined it with ``find``.

.. code-block:: bash

    find . -type f -name "*.py" -exec grep -n FooClassName {} /dev/null \;

This works great for one-off checks
but less great if you need to do those checks repeatedly,
if you need to do lots of such checks,
if you need to do those checks somewhere that you don't have access to ``grep``,
or if you need to do things that ``grep`` cannot do.

Not Grep?
=========

``not-grep`` is designed for static use, not ad-hoc use.
For example, as part of a continuous integration test suite.
This is why it gets its configuration from a config file, not the CLI.
Because of this, the ``not-grep`` CLI is very simple:
the only things you can specify are the config file and verbosity.

.. code-block:: bash

    not-grep --config config.toml -vv

Inside the config file, things start to get interesting.

``not-grep`` is built around checker plugins.
Each plugin takes a map as input:
the file glob pattern for the files you want to check
and a value that tells the plugin what to do with that file.

The config file is a collection of TOML tables.
The table name identifies the plugin
and the table members are the input to that plugin.

.. code-block:: toml

    # The "include" checker will error unless the specified value is include.
    [include]
    "src/**/*.py" = "__all__"

    # The "exclude" checker will error if the specified value is include.
    [exclude]
    "src/**/*.py" = "FooClassName"


The output shows you, for each plugin,
whether each matched file met or failed the plugin requirements.
In lower verbosity levels, ``not-grep`` only shows failed checks.

.. code-block:: bash

    $ not-grep --config config.toml -vv
    ================Running include checks================
    -----------Checking src/**/*.py for pattern-----------
    __all__
    ******************************************************
    src/foo/__init__.py.............................. PASS
    src/foo/bar.py................................... FAIL

    ================Running exclude checks================
    -----------Checking src/**/*.py for pattern-----------
    FooClassName
    ******************************************************
    src/foo/__init__.py.............................. PASS
    src/foo/bar.py................................... PASS

Awesome! Can I use it in GitHub Actions?
========================================

Yes. Yes you can.

.. code-block:: yaml

    - uses: mattsb42/not-grep@master
      with:
        # If you don't set config-file the action uses ".github/not-grep.toml".
        config-file: ./github/config/check-things.toml
        # If you don't set debug, passing checks will be hidden.
        debug: true
