CMDSyntax is a Python module for matching command line arguments to a syntax definition.
Version: 0.91CMDSyntax is a Python module for matching command line arguments to a syntax definition.
License: MIT/X Consortium License
Operating System: Linux
Python programs which run from the command line have traditionally relied on a variety of libraries and methods to read and interpret the arguments passed to the program when it is executed. Such libraries offer fairly convenient facilities for checking the presence of options, commands and associated parameters but still require the developer to do much of the work of making sense of this information.
For more complex programs, the logic surrounding the options available becomes increasingly difficult to manage as developers must check for invalid combinations of large numbers of options. Therefore, for certain types of command line tool, with syntaxes which offer many conflicting choices for the user, a solution which scales to large numbers of options is required.
This module provides an alternative way to collect arguments passed to a script from the command line. Rather than treating the command line as a pool of arguments, the contents are matched against a specified syntax string. Any valid matches are presented to the program as dictionaries containing values referenced by keys in the syntax string. Since contradictory or inconsistent use of options is eliminated by the matching process, the developer can concentrate on providing the features of the program rather than having to validate the user input.
The values obtained from the command line are not converted from the default string type. It may be beneficial to use features of other option parsing libraries to provide this functionality.
Methods of input
The module allows the user to pass arguments to a script in the conventional manner from the command line according to an agreed style of command line arguments.
The use of a syntax definition to validate the command line input is also useful for users of graphical user interfaces (GUIs) since it may be used to automate the construction of simple GUI forms. Therefore, some level of consistency is introduced between the two alternative interfaces with little effort from the developer. Additionally, the information obtained from invalid input can be used to assist the user by incorporating the user's valid input into the form being built.
The GUI form generation is achieved using the Tkinter module to utilise the Tk toolkit. This toolkit is in widespread use and is therefore likely to be available on the user's machine.
A simple example
Using an existing tool demonstrates the capabilities of the library. The tool in question, impconvert (see this page), converts documents stored in a legacy document format to a series of files corresponding to the pages in the document. The tool creates a Syntax object from the definition given:
syntax = "< Input file > < Output directory > < File extension >" +
" [-s < Starting page >] [-f < Finishing page >]"
Consider the case where the user invokes the impconvert tool with the following arguments:
impconvert /home/anon/input/myfile,bc5 /home/anon/output/
This input is incomplete and, as a result, the syntax object created by the tool will not return any matches. However, the tool can do two things to help the user supply valid input: it can generate a form for the user to fill in and it can interpret the failed input to provide useful default values for various parameters which the user specified correctly.
More descriptive GUI forms
Using a modified style which allows commands (arguments which must be supplied exactly as specified) to contain whitespace, more elaborate forms can be generated, although this is not the primary goal of the module.
Consider the following syntax definition:
syntax = """
"Woodland census 2002"
[ --Squirrels=Number ]
[ --Badgers=Number ]
[ --Hippos=Number ]
"Types of trees in the forest"