From 5214965716889f37c515f954d0f30099c6656176 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Fri, 17 Mar 2017 00:32:44 -0400 Subject: Converted README.rst to README.md. Was having so much trouble with GitHub recognizing the README.rst, converted it to Markdown. --- README.md | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100755 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100755 index 00000000..be75fa4f --- /dev/null +++ b/README.md @@ -0,0 +1,221 @@ +cmd2 +==== +[![Build status](https://secure.travis-ci.org/python-cmd2/cmd2.png?branch=master)](https://travis-ci.org/python-cmd2/cmd2) +[![Appveyor build status](https://ci.appveyor.com/api/projects/status/github/python-cmd2/cmd2?branch=master)](https://ci.appveyor.com/project/FedericoCeratto/cmd2) +[![Documentation Status](https://readthedocs.org/projects/cmd2/badge/?version=latest)](http://cmd2.readthedocs.io/en/latest/?badge=latest) +[![Latest Version](https://img.shields.io/pypi/v/cmd2.svg)](https://pypi.python.org/pypi/cmd2/) +[![License](https://img.shields.io/pypi/l/cmd2.svg)](https://pypi.python.org/pypi/cmd2/) + +cmd2 is a tool for writing command-line interactive applications for Python 2.7 and Python 3.3+. It is based on the +Python Standard Library's [cmd](https://docs.python.org/3/library/cmd.html) module, and can be used any place cmd is used simply by importing cmd2 instead. It is +pure Python code with the only 3rd-party dependencies being on [six](https://pypi.python.org/pypi/six) and [pyparsing](http://pyparsing.wikispaces.com). + +The latest documentation for cmd2 can be read online here: https://cmd2.readthedocs.io/en/latest/ + +See the [Installation Instructions](https://cmd2.readthedocs.io/en/latest/install.html) in the cmd2 documentation for instructions on installing, upgrading, and +uninstalling cmd2. + +Bug reports may be submitted directly to the [issue tracker](https://github.com/python-cmd2/cmd2/issues). Pull Requests are welcome, see the +[Contributor's Guide](https://github.com/python-cmd2/cmd2/blob/master/CONTRIBUTING.md) for more information. + +Feature Support +--------------- + +cmd2 provides the following features, in addition to those already existing in cmd: + +- Searchable command history +- Load commands from file, save to file, edit commands in file +- Multi-line commands +- Case-insensitive commands +- Special-character shortcut commands (beyond cmd's `@` and `!`) +- Settable environment parameters +- Parsing commands with flags +- Redirection to file with `>`, `>>`; input from file with `<` +- Bare `>`, `>>` with no filename send output to paste buffer +- Pipe output to shell commands with `|` +- Simple transcript-based application testing +- Unicode character support (*Python 3 only*) + +Instructions for implementing each feature follow. + +- Searchable command history + + All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's excludeFromHistory attribute. + The history is accessed through the ``history``, ``list``, and ``run`` commands. + If you wish to exclude some of your custom commands from the history, append their names + to the list at Cmd.ExcludeFromHistory. + +- Load commands from file, save to file, edit commands in file + + Type ``help load``, ``help save``, ``help edit`` for details. + +- Multi-line commands + + Any command accepts multi-line input when its name is listed in ``Cmd.multilineCommands``. + The program will keep expecting input until a line ends with any of the characters + in ``Cmd.terminators`` . The default terminators are ``;`` and ``/n`` (empty newline). + +- Case-insensitive commands + + All commands are case-insensitive, unless ``Cmd.caseInsensitive`` is set to ``False``. + +- Special-character shortcut commands (beyond cmd's "@" and "!") + + To create a single-character shortcut for a command, update ``Cmd.shortcuts``. + +- Settable environment parameters + + To allow a user to change an environment parameter during program execution, + append the parameter's name to ``Cmd.settable``. + +- Parsing commands with ``optparse`` options (flags) + + :: + + @options([make_option('-m', '--myoption', action="store_true", help="all about my option")]) + def do_myfunc(self, arg, opts): + if opts.myoption: + ... + + See Python standard library's ``optparse`` documentation: http://docs.python.org/lib/optparse-defining-options.html + + +Tutorials +--------- + +A couple tutorials on using cmd2 exist: + + * A detailed PyCon 2010 talk by `Catherine Devlin`_, the original author + * http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html + * A nice brief step-by-step tutorial + * https://kushaldas.in/posts/developing-command-line-interpreters-using-python-cmd2.html + +.. _Catherine Devlin: https://github.com/catherinedevlin + + +Example Application +------------------- + +Example cmd2 application (**examples/example.py**) :: + + '''A sample application for cmd2.''' + + from cmd2 import Cmd, make_option, options + + class CmdLineApp(Cmd): + multilineCommands = ['orate'] + Cmd.shortcuts.update({'&': 'speak'}) + maxrepeats = 3 + Cmd.settable.append('maxrepeats') + + # Setting this true makes it run a shell command if a cmd2/cmd command doesn't exist + # default_to_shell = True + + @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), + make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), + make_option('-r', '--repeat', type="int", help="output [n] times") + ]) + def do_speak(self, arg, opts=None): + """Repeats what you tell me to.""" + arg = ''.join(arg) + if opts.piglatin: + arg = '%s%say' % (arg[1:], arg[0]) + if opts.shout: + arg = arg.upper() + repetitions = opts.repeat or 1 + for i in range(min(repetitions, self.maxrepeats)): + self.stdout.write(arg) + self.stdout.write('\n') + # self.stdout.write is better than "print", because Cmd can be + # initialized with a non-standard output destination + + do_say = do_speak # now "say" is a synonym for "speak" + do_orate = do_speak # another synonym, but this one takes multi-line input + + if __name__ == '__main__': + c = CmdLineApp() + c.cmdloop() + +The following is a sample session running example.py. +Thanks to Cmd2's built-in transcript testing capability, it also serves as a test +suite for example.py when saved as *exampleSession.txt*. +Running:: + + python example.py -t exampleSession.txt + +will run all the commands in the transcript against `example.py`, verifying that the output produced +matches the transcript. + +example/exampleSession.txt:: + + (Cmd) help + + Documented commands (type help ): + ======================================== + _relative_load edit help list orate py run say shell show + cmdenvironment eof history load pause quit save set shortcuts speak + + (Cmd) help say + Repeats what you tell me to. + Usage: speak [options] arg + + Options: + -h, --help show this help message and exit + -p, --piglatin atinLay + -s, --shout N00B EMULATION MODE + -r REPEAT, --repeat=REPEAT + output [n] times + + (Cmd) say goodnight, Gracie + goodnight, Gracie + (Cmd) say -ps --repeat=5 goodnight, Gracie + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + (Cmd) set maxrepeats 5 + maxrepeats - was: 3 + now: 5 + (Cmd) say -ps --repeat=5 goodnight, Gracie + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + (Cmd) hi + -------------------------[1] + help + -------------------------[2] + help say + -------------------------[3] + say goodnight, Gracie + -------------------------[4] + say -ps --repeat=5 goodnight, Gracie + -------------------------[5] + set maxrepeats 5 + -------------------------[6] + say -ps --repeat=5 goodnight, Gracie + (Cmd) run 4 + say -ps --repeat=5 goodnight, Gracie + + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + OODNIGHT, GRACIEGAY + (Cmd) orate Four score and + > seven releases ago + > our BDFL + > blah blah blah + Four score and + seven releases ago + our BDFL + blah blah blah + (Cmd) & look, a shortcut! + look, a shortcut! + (Cmd) show color + colors: True + (Cmd) set prompt "---> " + prompt - was: (Cmd) + now: ---> + ---> say goodbye + goodbye -- cgit v1.2.1