Metadata-Version: 2.1
Name: ret
Version: 0.1.3
Summary: A pure-python command-line regular expression tool for stream filtering, extracting, and parsing.
Home-page: https://github.com/ThatXliner/ret/
License: GPL-3.0-or-later
Keywords: regex,cli,tool,grep
Author: Bryan Hu
Author-email: bryan.hu.2020@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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 :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Provides-Extra: regex
Project-URL: Bug Tracker, https://github.com/ThatXliner/ret/issues
Project-URL: Source Code, https://github.com/ThatXliner/ret
Project-URL: Say Thanks! , https://saythanks.io/to/bryan.hu.2020@gmail.com
Description-Content-Type: text/x-rst

===
Ret
===
A pure-python command-line regular expression tool for stream filtering, extracting,
and parsing, designed to be minimal with an intuitive command-line interface.

Installation
-------------

You can install this via

.. code-block:: bash

    $ python3 -m pip install ret
    ✨🍰✨


or using pipx

.. code-block:: bash

    $ pipx install ret
    ✨🍰✨

Ret is pure python (tested on python 3.6+) with no dependencies.

That way, you can get a clean uninstall.

.. note::

	If you want to install the bleeding edge version of ret, right when it gets pushed to master, see `here <https://github.com/ThatXliner/ret/blob/master/CONTRIBUTING.md#development-installation>`_ for instructions.



Usage
------

Example
~~~~~~~~

You can use ``Ret`` to extract text via regex capture groups:

.. code-block:: bash

    $ git branch
    * master
    $ git branch | ret "\* (\w+)" s --group 1
    master

...finding all occurrences of a pattern:

.. code-block:: bash

    $ ls | ret ".*\.py" findall
    foo.py
    bar.py

and even all occurrences of a pattern **with capture groups**:

.. code-block:: bash

    $ ls | ret "(.*)\.py" findall --group 1
    foo
    bar

----

While those may seem untypical use cases, I have found myself using ``Ret`` countless times.

Imagine this: you have just downloaded a bunch of tarballs, and have ran

.. code-block:: bash

   for x in $(grep ".+\.tar\.gz"); do tar -xzf $x; done

Now you just want to ``cd`` into all of the extracted files, run :code:`./configure && make && make install`.

You could use ``Ret`` to get the names of the extracted files, just from the tarballs' names. Like this:

.. code-block:: bash

   $ ls | grep ".+\.tar\.gz"
   foo.tar.gz
   bar.tar.gz
   foobar.tar.gz
   extractme.tar.gz


   $ ls | ret "(.+\.tar\.gz)" f -g 1
   foo
   bar
   foobar
   extractme


and with that combined, we can do

.. code-block:: bash

   $ for x in (ls | ret "(.+\.tar\.gz)" f -g 1); do {
      current_dir=`pwd`;
      cd $current_dir &&
      ./configure && make && make install &&
      cd $current_dir}; done
   ✨🍰✨

A life saver.

----

And remember, this is python regex: a very powerful regular expression engine.

The possibilities of usage are endless.

Demonstration
~~~~~~~~~~~~~

.. image:: https://raw.githubusercontent.com/ThatXliner/ret/master/assets/demo.svg
   :alt: Demonstration photo


Background
-------------
I love ``grep``. But grep isn't really for text extraction.

For example, you cannot extract regexes via capture groups.

Since I wanted that functionality, I decided to build this, ``Ret``.

Why the name?
~~~~~~~~~~~~~

``Ret`` is an acronym for **r**\ egular **e**\ xpression **t**\ ool.


Why it can't replace grep (yet)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Ret`` originally was designed to provide some features ``grep`` lacks.
It never intended to replace good ol' ``grep``.

Grep is great for searching directories while
``ret`` (currently) can only read from a file or stdin.

Furthermore, you cannot guarantee that ``ret`` is installed on the machine.

Also, ``Ret`` relies on the (slow) python regex engine.

Feel free to contribute!

