Metadata-Version: 1.1
Name: greptools
Version: 0.9b0
Summary: A collection of grep wrappers and tools for various filetypes.
Home-page: https://github.com/nicr9/greptools
Author: Nic Roland
Author-email: nicroland9@gmail.com
License: MIT
Download-URL: https://github.com/nicr9/greptools/tarball/0.9b
Description: GrepTools
        =========
        
        Installation
        ------------
        
        From source:
        
        ::
        
            $ git clone https://github.com/nicr9/greptools.git
            $ cd greptools
            $ sudo python2.7 setup.py develop
        
        About
        -----
        
        ``greptools`` is a collection of CLI search tools similar to ``grep`` or
        ``ack``. These tools were designed with programmers in mind and each
        tool is targetted at a different programming language or structured file
        format.
        
        Each language specific tool recursively searches files relating to that
        language in the current directory and sorts results into a context tree
        (refered to as a grep tree). The exact format of the grep tree depends
        on the language in question but it takes the form of nested datstructure
        with each level representing a file, class or function.
        
        Each tool uses ``grep`` to perform the actual searching, and for each
        result it opens the file and reads it to decide which class/function it
        belongs to.
        
        Usage
        -----
        
        It's simple to use. Here's an example using the tool for python code:
        ``pygt``.
        
        To look for usages of the word "traceback" inside a subdirectory of the
        core Python source code:
        
        ::
        
            $ cd Python-2.7.3/Lib/multiprocessing
            $ pygt traceback
            ./reduction.py
                def _serve
                     132:^                import traceback$
                     135:^                    '-'*79 + '\n' + traceback.format_exc() + '-'*79$
        
            ./queues.py
                class Queue
                    def _feed
                         280:^                    import traceback$
                         281:^                    traceback.print_exc()$
        
            ./managers.py
                 49:^from traceback import format_exc$
        
                class Server
                    def shutdown
                         368:^                import traceback$
                         369:^                traceback.print_exc()$
        
            ./util.py
                def _run_finalizers
                     263:^            import traceback$
                     264:^            traceback.print_exc()$
        
            ./process.py
                class Process
                    def _bootstrap
                         273:^            import traceback$
                         276:^            traceback.print_exc()$
        
        Command-line options
        --------------------
        
        These options should apply to all the available greptools so just use
        the name of the tool you're using in place of ``<greptool>`` below:
        
        Case-insensitive search
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        ``<greptool> -i <SEARCH_TERM>``
        
        Debug information
        ~~~~~~~~~~~~~~~~~
        
        Turning this on prints out lots of additional information (e.g. raw grep
        results) that can be used to diagnose bugs in the logic at various
        stages. Useful if you're trying to develop your own greptool or add
        features to the base classes.
        
        ``<greptool> -d <SEARCH_TERM>``
        
        Set operations
        ~~~~~~~~~~~~~~
        
        One of the really useful features these greptools is that they support
        treating the results like sets and quickly filtering results by applying
        set operations.
        
        Let's look at a simple example.
        
        Let's say you need to quickly look through all the ``import``\ s in your
        python project. That's simple: ``pygt import``.
        
        Now lets say you want to narrow down those results to those that mention
        ``os.path``. This can be done by piping the results from our earlier
        search into a new search for the new term like so:
        
        ::
        
            $ pygt import | pygt os.path
        
        This will effectively perform an intersection on both sets of results
        and so only provide matches that contain both ``import`` and
        ``os.path``.
        
        You can perform other set operations too! Let's say you don't want any
        results containing ``os.path``. You can get the relative complement by
        piping like we did before and setting the ``-F`` (filter) flag on the
        last search command like so:
        
        ::
        
            $ pygt import | pygt -F os.path
        
        You can add both sets of results together with ``-U`` (union) and only
        return results that contain one and not the other by using ``-X`` (XOR,
        a.k.a symetric difference).
        
        Caveats with using set operations
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Both the default (intersection) set op and the filter set op shown above
        aren't actually true set operations.
        
        It turns out treating search results like sets and performing these
        operations isn't that fast as we hoped so we made a compromise. These
        two work by iterating through that first set of results and checking for
        the second search term using python's built in regex engine.
        
        You may experience issues from the use of two different engines. For
        example, if you are using complicated regular expressions you may find
        that they behave differently when using intersection or filter set
        operations.
        
        You can choose to use the slow intersection (``-N``) and the slow filter
        (``-E``) instead which work by building both sets of results and
        comparing.
        
        In order to use the pipe to pass one set of results to an other pygt
        process we had to serialise them first. This means that if you try
        piping the results to any other process (like ``less`` for example)
        they'll show up in json format. This will happen even if you use other
        output formats like the histogram format.
        
        If this causes problems for you, use ``-p``. This will force it to pipe
        out results in what ever format you've choosen (except the default
        'colour' format. It will be changed to clean because it looks really
        ugly when it's piped out).
        
        Writing a new greptool
        ----------------------
        
        So you've decided you need a greptool for your favourite language X.
        
        Here are a basic set of instructions to create a new greptool:
        
        1) Implement a new Reader class.
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Are code blocks in X based on indentation or deliniated by braces?
        
        There are some classes you can inherit from (``IndentReader`` and
        ``BraceReader``) that are generalised for these cases. The docstrings
        should have details that tell you what needs to be implemented by
        subclasses. ``PythonReader`` and ``JavaReader`` are good examples of
        ``IndentReader`` and ``BraceReader`` subclasses respectively.
        
        If neither of these suit your purposes, you may need to inherit from
        ``BaseReader``. The logic you need to implement in this case is a little
        more abstract, I'm not sure the docstrings are detailed enough. If you
        can't figure out what to do from a reading of the code feel free to drop
        me an email with an outline of what you're working on, I'd be glad to
        help!
        
        2) Add details to ``greptools/reader/__init__.py``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Two things you'll need to do: include a relative import of your new
        reader class and add the name of that class to ``__all__``.
        
        3) Add new script to ``bin/``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        My advice is to copy a preexisting script. The convention is to base the
        script name on the language file extention (e.g. Python files have a
        ``.py`` extention so the Python greptool is called ``pygt``).
        
        Don't forget to change the name of the Reader class used in the script.
        
        ::
        
            $ cp bin/pygt bin/xgt
            $ sed -i "s/PythonReader/XReader/g" bin/xgt
        
        4) Mention script in setup.py.
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        There's a ``scripts`` list in setup.py. Add your new script here so that
        it's installed with all the others.
        
        5) Reinstall.
        ~~~~~~~~~~~~~
        
        ::
        
            $ sudo python2.7 setup.py develop
        
        Author
        ------
        
        ::
        
            Name: Nic Roland
            Twitter: @nicr9_
            Email: nicroland9@gmail.com
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing :: Filters
Classifier: Topic :: Utilities
