Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 141 lines (99 sloc) 4.397 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
==
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

Development
-----------

rl development is hosted on GitHub_ where it also has an `issue tracker`_.

.. _GitHub: http://github.com/stefanholek/rl
.. _`issue tracker`: https://github.com/stefanholek/rl/issues

Installation
============

rl requires Python 2.5 or higher and GNU Readline 5.0 or higher.

On Linux, install libreadline6-dev before attempting to build
rl. On Mac OS X, make sure you have Xcode Tools installed. 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.

Static Builds
-------------

Normally, rl.readline will attempt to link against your system's libreadline.
If this is not possible, notably on Mac OS X which ships with libedit, a
static version of GNU Readline 6.2 is built.

To force a static build, set the RL_BUILD_STATIC_READLINE environment
variable.

Related
=======

`kmd.Kmd`_ is an rl-aware replacement for `cmd.Cmd`_.

.. _`kmd.Kmd`: http://pypi.python.org/pypi/kmd
.. _`cmd.Cmd`: http://docs.python.org/library/cmd.html

Something went wrong with that request. Please try again.