Metadata-Version: 1.0
Name: rl
Version: 1.14
Summary: Alternative Python bindings for GNU Readline
Home-page: http://pypi.python.org/pypi/rl
Author: Stefan H. Holek
Author-email: stefan@epy.co.at
License: GPL or PSF
Description: ==
        rl
        ==
        --------------------------------------------
        Alternative Python bindings for GNU Readline
        --------------------------------------------
        
        Introduction
        ============
        
        The `GNU Readline Library`_ is the canonical implementation of command line
        editing, tab completion, and history for console-based applications.
        It is developed as part of Bash and available on virtually any platform.
        
        While Python ships with readline bindings in its standard library, they
        only implement a subset of readline's features, just enough to perform
        identifier completion at the Python interpreter prompt.
        
        The **rl** package aims to provide full implementations of GNU Readline's
        `Custom Completer`_ and `History`_ interfaces.
        It also contains high-level APIs to better organize the namespace and
        shield applications from low-level verbosity.
        
        .. _`GNU Readline Library`: http://tiswww.case.edu/php/chet/readline/rltop.html
        .. _`Custom Completer`: http://tiswww.case.edu/php/chet/readline/readline.html#SEC44
        .. _`History`: http://tiswww.case.edu/php/chet/readline/history.html#SEC6
        
        Package Contents
        ----------------
        
        rl exports these components:
        
        completer
            Interface to the readline completer. Used to configure the completion
            aspects of readline.
        
        completion
            Interface to the active readline completion. Used to interact
            with readline when a completion is in progress.
        
        generator
            A factory turning any callable into a *completion entry function* that
            can be handed to readline.
        
        print_exc
            A decorator printing exceptions to stderr. Useful when writing Python
            completions and hooks, as exceptions occurring there are usually
            swallowed by the in-between C code.
        
        history
            Interface to the readline history. Used to read and write history files
            and to manipulate history entries.
        
        readline
            The readline bindings module. Contains everything known from the standard
            library plus extensions specific to the rl package.  The *completer*,
            *completion*, and *history* interfaces make use of this module, and you
            should rarely need to interact with it directly.
        
        For further details, please refer to the `API Documentation`_.
        
        .. _`API Documentation`: http://packages.python.org/rl
        
        Example Code
        ------------
        
        The code below implements system command completion similar to Bash::
        
            import os
            from rl import completer
            from rl import generator
        
            def complete_command(text):
                # Return executables matching 'text'
                for dir in os.environ.get('PATH').split(':'):
                    dir = os.path.expanduser(dir)
                    if os.path.isdir(dir):
                        for name in os.listdir(dir):
                            if name.startswith(text):
                                if os.access(os.path.join(dir, name), os.R_OK|os.X_OK):
                                    yield name
        
            def main():
                # Set the completion function
                completer.completer = generator(complete_command)
        
                # Enable TAB completion
                completer.parse_and_bind('TAB: complete')
        
                command = raw_input('command> ')
                print 'You typed:', command
        
        More examples_ are included in the package source. Also see gpgkeys_, a
        front-end for GnuPG built entirely around tab completion.
        
        .. _examples: http://github.com/stefanholek/rl/tree/master/rl/examples
        .. _gpgkeys: http://pypi.python.org/pypi/gpgkeys
        
        Repository Access
        -----------------
        
        rl development is hosted on github_.
        
        .. _github: http://github.com/stefanholek/rl
        
        Installation
        ============
        
        rl requires Python 2.5 or higher and GNU Readline 5.0 or higher.
        
        On Linux, install libreadline5-dev (or equivalent) before attempting to build
        rl. On Mac OS X, make sure you have Xcode Tools installed (Mac OS X Install
        DVD /Optional Installs/Xcode Tools). Then type::
        
            easy_install rl
        
        and watch the console. When it reads::
        
            Finished processing dependencies for rl
        
        you are done and rl is ready to use.
        
        
        Changelog
        =========
        
        1.14 - 2011-05-05
        -----------------
        
        - Add xfree.c to sources when building GNU Readline 6.2.
          [stefan]
        
        - Allow history indexes of type long.
          [stefan]
        
        
        1.13 - 2011-03-11
        -----------------
        
        - Use a custom build_ext command to find the best termcap library.
          [stefan]
        
        - Update static builds to GNU Readline 6.2.
          [stefan]
        
        
        1.12 - 2010-08-04
        -----------------
        
        - Fix memory leaks in ``py_remove_history`` and ``py_replace_history``.
          See Python `issue 9450`_.
          [stefan]
        
        .. _`issue 9450`: http://bugs.python.org/issue9450
        
        
        1.11 - 2010-05-21
        -----------------
        
        - Update README, API documentation, and examples.
          [stefan]
        
        - MacPython detection caught other framework builds as well.
          [stefan]
        
        
        1.10 - 2010-05-05
        -----------------
        
        - Rework the history interface: Implement iteration and remove redundant APIs.
          [stefan]
        
        - History stifling could cause duplicate history entries.
          [stefan]
        
        - Make sure ``begidx`` and ``endidx`` completion variables are reset to 0.
          [stefan]
        
        
        1.9 - 2010-04-02
        ----------------
        
        - Remove unused defines; we don't support libedit or readline < 5.0.
          [stefan]
        
        - Improve performance of ``get_current_history_length``.
          [stefan]
        
        
        1.8 - 2010-03-14
        ----------------
        
        - Make ``get_history_item`` zero-based and remove ``get_history_base``.
          [stefan]
        
        
        1.7 - 2010-03-09
        ----------------
        
        - Support installation into MacPython for Mac OS X.
          [stefan]
        
        
        1.6 - 2010-03-07
        ----------------
        
        - The history size can now be limited ("stifled") by setting
          ``history.max_entries``. This supersedes ``history.length`` which has been
          removed.
          [stefan]
        
        - Close a memory leak in ``get_current_history_length``. Also see Python
          `issue 8065`_.
          [stefan]
        
        .. _`issue 8065`: http://bugs.python.org/issue8065
        
        
        1.5.4 - 2010-03-01
        ------------------
        
        - Avoid segfaults during codec lookup by calling ``PyGILState_Ensure`` in all
          the right places. Fixes rl `issue/5`_. Removes the workaround introduced in
          1.5.2.
          [stefan]
        
        
        1.5.3 - 2010-02-26
        ------------------
        
        - Re-release with link to the correct issue.
          [stefan]
        
        
        1.5.2 - 2010-02-26
        ------------------
        
        - Work around segfaults under Python 3 on Linux, which are caused by bad or
          missing codecs. This restricts Linux to UTF-8 and Latin-1 locales only.
          Also see rl `issue/5`_.
          [stefan]
        
        .. _`issue/5`: http://github.com/stefanholek/rl/issues#issue/5
        
        
        1.5.1 - 2010-02-25
        ------------------
        
        - Switch readline download location to ftp.gnu.org for speed.
          [stefan]
        
        
        1.5 - 2010-02-25
        ----------------
        
        - In Python 3, convert to and from Unicode using filesystem encoding
          and "surrogateescape" error handler. See `PEP 383`_ for the low-down.
          [stefan]
        
        .. _`PEP 383`: http://www.python.org/dev/peps/pep-0383/
        
        
        1.4.1 - 2010-02-13
        ------------------
        
        - Fix GPL trove classifier.
          [stefan]
        
        
        1.4 - 2010-02-13
        ----------------
        
        - rl can now be installed into the system Python on Mac OS X, the only
          dependency being Xcode Tools.
          [stefan]
        
        - Change license to PSF or GPL.
          [stefan]
        
        
        1.3 - 2010-01-03
        ----------------
        
        - Fix header detection under Fink on Mac OS X.
          [stefan]
        
        - Add ``readline_version`` API.
          [stefan]
        
        
        1.2 - 2009-11-24
        ----------------
        
        - Improve API documentation and examples.
          [stefan]
        
        
        1.1 - 2009-11-16
        ----------------
        
        - Remove all occurrences of old-style function typedefs to silence
          compiler warnings.
          [stefan]
        
        - Make the ``display_matches_hook`` work in Python 2.5. Fixes rl `issue/1`_.
          [stefan]
        
        - No longer auto-refresh the prompt at the end of ``display_match_list``.
          Applications should call ``redisplay(force=True)`` to restore the prompt.
          [stefan]
        
        .. _`issue/1`: http://github.com/stefanholek/rl/issues#issue/1
        
        
        1.0 - 2009-11-08
        ----------------
        
        - No changes since 1.0a8.
        
        
        1.0a8 - 2009-11-07
        ------------------
        
        - Close a memory leak in ``word_break_hook``. Three cheers for Xcode's
          ``leaks`` tool.
          [stefan]
        
        
        1.0a7 - 2009-11-05
        ------------------
        
        - Rename ``_readline`` module to ``readline`` since it's not private.
          [stefan]
        
        - Remove ``dump`` and ``read_key`` APIs from public interfaces.
          [stefan]
        
        
        1.0a6 - 2009-10-30
        ------------------
        
        - Unclutter the ``completer`` interface by removing settings that can
          just as well be made with ``parse_and_bind``.
          [stefan]
        
        - Fix a memory leak in ``username_completion_function`` and
          ``filename_completion_function``.
          [stefan]
        
        - Add a custom epydoc stylesheet to make its reST rendering more pleasant.
          [stefan]
        
        
        1.0a5 - 2009-10-29
        ------------------
        
        - Make all ``completion`` properties writable. While not useful in
          production, this allows us to write better tests.
          [stefan]
        
        - Improve API documentation and add a call graph for the completion
          process. This goes a long way in explaining how readline completion
          works.
          [stefan]
        
        
        1.0a4 - 2009-10-27
        ------------------
        
        - Implement the ``generator`` factory using an iterator instead of a list.
          [stefan]
        
        - Remove ``find_completion_word`` so people don't get ideas.
          [stefan]
        
        - Don't list distribute as dependency, setuptools will do the
          right thing.
          [stefan]
        
        
        1.0a3 - 2009-10-22
        ------------------
        
        - Add ``__slots__`` to interface objects to make them immutable.
          [stefan]
        
        - Support Python 2.5, 2.6, and 3.1 (thanks to distribute).
          [stefan]
        
        - Approach something like test coverage.
          [stefan]
        
        
        1.0a2 - 2009-10-08
        ------------------
        
        - Make the ``generator`` factory work for all types of callables.
          [stefan]
        
        - Improve examples.
          [stefan]
        
        
        1.0a1 - 2009-10-04
        ------------------
        
        - Initial release.
        
Keywords: gnu readline bindings
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
