{
    "info": {
        "author": "Andy Pearce",
        "author_email": "andy@andy-pearce.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Natural Language :: English",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2",
            "Topic :: Software Development :: Libraries",
            "Topic :: Software Development :: Libraries :: Python Modules",
            "Topic :: Text Processing",
            "Topic :: Text Processing :: General"
        ],
        "description": "Overview\n========\n\nThe ``cmdparser`` package contains two modules which are useful for writing\ntext command parsers, particularly using the builtin Python ``cmd`` module.\n\nThe package consists of two modules:\n\n* ``cmdparser.cmdparser``\n* ``cmdparser.datetimeparse``\n\nThese two modules are discussed below briefly. For more information see the\ndocstrings of the two modules, and also the ``ttrack`` command-line application\n(from which these libraries originated) makes a good example of their use.\n\n\n\nInstallation\n============\n\nInstall the ``cmdparser`` package from PyPI. For example, to install using\n``pip``::\n\n    pip install cmdparser\n\n\n.. _cmdparser_overview:\n\ncmdparser Overview\n==================\n\nThis module allows the creation of parse trees from textual command\nspecifications of the following form::\n\n    ham ( eggs | chips [spam] | beans [spam [...]] )\n\nThese parse trees can then be used to check for matches against particular\ncommand strings, and also allow valid completions of partial command strings to\nbe listed. To build a parse tree and use it in a few examples, see the\nfollowing example code:\n\n.. code-block:: python\n\n    from cmdparser import cmdparser\n\n    parse_tree = cmdparser.parse_spec(\"one (two|three) <four> [five]\")\n\n    # Returns None to indicate successful parse\n    parse_tree.check_match((\"one\", \"two\", \"anything\"))\n    # Returns an appropriate parsing error message\n    parse_tree.check_match((\"one\", \"three\", \"anything\", \"six\"))\n    # Returns the list [\"two\", \"three\"]\n    parse_tree.get_completions((\"one\",))\n\nAs well as dealing with fixed token strings, dynamic tokens can also be set up\nwhere the list of strings accepted can change over time, or where arbitrary\nstrings or lists of strings can be accepted. See the module's docstrings for\nspecifics of the classes available, but as an example:\n\n.. code-block:: python\n\n    from cmdparser import cmdparser\n\n    class ColourToken(cmdparser.Token):\n        def get_values(self, context):\n            # Static list here, but could easily be dynamic\n            return [\"red\", \"orange\", \"yellow\", \"green\", \"blue\", \"purple\"]\n\n    def my_ident_factory(token):\n        if token == \"number\":\n            return cmdparser.IntegerToken(token)\n        elif token == \"colour\":\n            return ColourToken(token)\n        return None\n\n    parse_tree = cmdparser.parse_tree(\"take <number> <colour> balls\",\n                                      ident_factory=my_ident_factory)\n\n    # Returns None to indicate successful parse, and the \"cmd_fields\" dict will\n    # be initialised as:\n    # { \"take\": [\"take\"], \"<number>\": [\"23\"],\n    #   \"<colour>\": [\"blue\"], \"balls\": [\"balls\"] }\n    cmd_fields = {}\n    parse_tree.check_match((\"take\", \"23\", \"blue\", \"balls\"), fields=cmd_fields)\n    # Returns an appropriate parsing error message\n    parse_tree.check_match((\"take\", \"all\", \"red\", \"balls\"))\n    # Returns the list [\"red\", \"orange\", \"yellow\", ..., \"purple\"]\n    parse_tree.get_completions((\"take\", \"5\"))\n\n\nThere are four classes which are suitable base classes for user-derived\ntokens:\n\n``Token``\n  This is useful for cases where one of a set of fixed values is suitable,\n  where the list may be fixed or dynamic. The ``get_values()`` method should be\n  overridden to return a list of valid tokens as strings. Optionally, there is\n  also a ``convert()`` method which can be used to convert\n\n``AnyToken``\n  Similar to ``Token``, but any string is to be expected. Validation can be\n  performed via the ``validate()`` method, but that doesn't allow\n  tab-completion as it's only called once the entire command is parsed.\n  There is also a ``convert()`` method should it be required.\n\n``AnyTokenString``\n  As ``AnyToken`` but all remaining items on the command line are consumed.\n  There are ``validate()`` and ``convert()`` methods.\n\n``Subtree``\n  Matches an entire command subtree and stores the result against the specified\n  token in the ``fields`` dictionary. The command specification string must\n  be passed to the constructor, and typically classes will override the\n  ``convert()`` method to interpret the command in some way (although this\n  is strictly optional).\n\nThere are also decorators for use with command handlers derived from ``cmd.Cmd``\nwhich allow command strings to be automatically extracted from docstring help\ntext, allowing command parsing and completion to be transparently added to the\ncommand-handling methods of the class.\n\nTo implement the ``cmd.Cmd`` class, various methods of the form ``do_XXX()`` are\nimplemented. To add the ``cmdparser`` integration, these methods must contain a\ndocstring the first line(s) of which form a command specification as outlined\nabove, followed by a blank line and then any descriptive text for the operation\nof the command. The prototype is also altered, taking three arguments - the\nusual ``self`` argument, a list of parsed command line items and a\n``fields`` dictionary as demonstrated in the example immediately above.\n\nOnce the methods have been suitably modified, the ``CmdMethodDecorator``\ndecorator should be applied to each of them, and the ``CmdClassDecorator``\ndecorator should be applied to the class definition as a whole:\n\n.. code-block:: python\n\n    from cmdparser import cmdparser\n\n    @cmdparser.CmdClassDecorator()\n    class CommandHandler(cmd.Cmd):\n\n        @cmdparser.CmdMethodDecorator():\n        def do_command(self, args, fields):\n            \"\"\"command ( add | delete ) <name>\n\n            This is an example command to demonstrate use of the cmd\n            decorators.\n            \"\"\"\n\n            # Method body goes here - it will only be called if a command\n            # parses successfully according to the specification above.\n\nNote that due to the design of the ``cmd.Cmd`` class, the first token in the\nspecification must be the same as the method name after the ``do_`` prefix. An\nexception will be raised if this is not the case.\n\nThe method decorator adds some wrapper code which parses the entered command\naccording to the specification, and displays an error message if parsing fails.\nShould parsing succeed, the implementation method itself is called with the\nparsed arguments and fields passed as from the ``check_match()`` method of the\nparse tree. Note that when using these decorators, the ``cmd.Cmd`` class\ninstance is passed as the ``context`` parameter to many of the token methods,\nwhich can be useful for recovering dynamic state.\n\nThe class decorator then adds tab-completion methods for every decorated\ncommand method, so applications need not concern themselves with this at all.\n\nIt is not necessary to decorate every command method - for very simple commands\nwhich take no arguments it may be simpler to leave them bare. In this case, of\ncourse, the method prototype must match what is expected by ``cmd.Cmd``\n(i.e. a single ``string`` parameter beyond the ``self`` parameter). However,\nif any method is decorated then the class decorator is required to add the\ncompletion methods.\n\nFinally, note that as a convenience the docstring help for commands has the\nleading whitespace of the second line stripped from all lines (on the\nassumption that the first line immediately follows a triple quote and hence has\nno indentation). Lines are also wrapped to 80 columns in the help text.\n\n\ndatetimeparse Overview\n======================\n\nBuilding on the parse trees within the ``cmdparser`` module, this module adds\nspecific token types to parse human-readable specifications of date and time.\nIt allows both absolute and relative dates to be specified, and these are\nconverted to datetime and other instances as appropriate.\n\nSome examples of the type of specifications supported:\n\n* ``2:35pm on Wednesday last week``\n* ``3 days, 2 hours and 5 minutes ago``\n* ``3rd March 2012``\n\nThe following classes are currently defined:\n\n``DateSubtree``\n  Parses a calendar date, including literal dates (``2012-06-15``), descriptive\n  versions (``15th June 2012``), days of the week relative to the current day\n  (``Thursday last week``) as well as ``yesterday``, ``today`` and\n  ``tomorrow``. The returned value is a ``datetime.date`` instance.\n\n``TimeSubtree``\n  Parses a time of day in 12 or 24 hour format. The returned value is as\n  returned by ``time.localtime()``.\n\n``RelativeTimeSubtree``\n  Parses phrases which indicate a time offset from the present time, such as\n  ``3 days and 2 hours ago``. The returned value is an instance of\n  ``cmdparser.DateDelta``, which is a wrapper class containing a\n  ``datetime.timedelta`` and an additional offset in calendar months. It has\n  sufficient methods defined to allow it to be added or subtracted from\n  a ``datetime.datetime`` in the same way as ``datetime.timedelta``.\n\n``DateTimeSubtree``\n  Parses specifications of a date and time, accepting either a combination of\n  ``DateSubtree`` and ``TimeSubtree`` phrases, or a ``RelativeTimeSubtree``\n  phrase; in the latter case the time is taken as relative to the current\n  time. The returned value is a ``datetime.datetime`` instance.\n\n``PastCalendarPeriodSubtree``\n  Parses specifications of calendar periods in the past. Examples of the\n  phrases this will accept include ``last week``, ``3 months ago``,\n  ``week containing 24th March 2012`` and ``between 2012-02-03 and today``.\n  The returned value is a 2-tuple of ``datetime.date`` instances representing\n  the range of dates specified, where the first date is inclusive and the\n  second exclusive.\n\nSee the docstrings of the classes for more details and the ``spec`` class\nattribute for the complete specification of phrases that each class accepts.\n\n\nFeedback\n========\n\nIf you have any questions, problems or requests, please get in touch with me\nat andy@andy-pearce.com. If you want to submit a bug, please do so via\n`GitHub's issue tracker`_ for the TTrack application, with which ``cmdparser``\nshares a repository.\n\nIf you want to make changes, the source code is available at GitHub_ - feel\nfree to send me pull requests if you make an improvement you feel others would\nfind useful.\n\n.. _GitHub: https://github.com/Cartroo/ttrack\n.. _`GitHub's issue tracker`: https://github.com/Cartroo/ttrack/issues",
        "description_content_type": null,
        "docs_url": "https://pythonhosted.org/cmdparser/",
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://cartroo.github.com/ttrack/cmdparser.html",
        "keywords": null,
        "license": "LICENSE.txt",
        "maintainer": null,
        "maintainer_email": null,
        "name": "cmdparser",
        "package_url": "https://pypi.org/project/cmdparser/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/cmdparser/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://cartroo.github.com/ttrack/cmdparser.html"
        },
        "release_url": "https://pypi.org/project/cmdparser/1.0.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Command parsing extensions to the cmd module.",
        "version": "1.0.1"
    },
    "last_serial": 787531,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c0dcf404394cfda564f3494def2e9199",
                    "sha256": "5d914823e368ac9c687b7f1d14e1e944c1fa26be1dc9af45066a84d3b4b576f5"
                },
                "downloads": -1,
                "filename": "cmdparser-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "c0dcf404394cfda564f3494def2e9199",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 23502,
                "upload_time": "2012-12-18T13:33:39",
                "url": "https://files.pythonhosted.org/packages/c1/c4/86d363335c71a286fa432fdee4910d21b82093a74018c480ad941aec67d6/cmdparser-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c8c65aec080367a0928cb23cf0d90b43",
                    "sha256": "4d05afda12168c5125b164b3e1fc17b097db70558d5c02c1b32e59329bf7e5ed"
                },
                "downloads": -1,
                "filename": "cmdparser-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "c8c65aec080367a0928cb23cf0d90b43",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 28538,
                "upload_time": "2013-01-14T14:37:35",
                "url": "https://files.pythonhosted.org/packages/d8/01/6f68ab7b90ac908e223dcb8ba4015d7836e52a617c4f79114e875d214161/cmdparser-1.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "c8c65aec080367a0928cb23cf0d90b43",
                "sha256": "4d05afda12168c5125b164b3e1fc17b097db70558d5c02c1b32e59329bf7e5ed"
            },
            "downloads": -1,
            "filename": "cmdparser-1.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "c8c65aec080367a0928cb23cf0d90b43",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 28538,
            "upload_time": "2013-01-14T14:37:35",
            "url": "https://files.pythonhosted.org/packages/d8/01/6f68ab7b90ac908e223dcb8ba4015d7836e52a617c4f79114e875d214161/cmdparser-1.0.1.tar.gz"
        }
    ]
}