Generating Python parser & usage code
This tutorial will demonstrate how to use the The program interface definition framework to generate a Python command line parser for your program.
Step 1. Defining the options
The first step is to describe the program options in a XML file. The XML elements have to follow the program interface XML Schema.
miniapp.xml
<?xml version="1.0" encoding="utf-8"?>
<prg:program version="2.0" xmlns:prg="http://xsd.nore.fr/program">
<prg:name>miniapp</prg:name>
<prg:version>1.0</prg:version>
<prg:options>
<prg:switch>
<prg:databinding>
<prg:variable>displayHelp</prg:variable>
</prg:databinding>
<prg:names>
<prg:long>help</prg:long>
<prg:short>h</prg:short>
</prg:names>
</prg:switch>
<prg:argument>
<prg:databinding>
<prg:variable>arg</prg:variable>
</prg:databinding>
<prg:names>
<prg:long>some-arg</prg:long>
<prg:short>a</prg:short>
</prg:names>
</prg:argument>
</prg:options>
</prg:program>
You can use any editor to write this file but an XML editor with auto-completion and XML Schema support will greatly increase the writing speed.
Step 2. Generate parser and program description
Using the build-python command line tool
${NS_XML_PATH}/ns/sh/build-python.sh --xml-description miniapp.xml --embed --output miniapp_info.py
This command line will generate miniapp_info.py which will contains
-
A copy of the Python parser classes
-
A miniappProgramInfo class, extending ProgramInfo, which is a Python representation of the XML file.
Step 3. Write your program
Let's write a little and useless Python program miniapp.py
#!/usr/bin/env python
import sys
from miniapp_info import *
"""
Include the parser program interface definition
generated by build-python
"""
info = miniappProgramInfo();
"""
Represents the miniapp interface description
"""
parser = Parser(info);
"""
Create a command line parser
"""
result = parser.parse(sys.argv, 1);
"""
Parse all command line arguments except the first (the program path)
The returned value is an instance of ProgramResult
populated dynamically with the value of miniapp's options
"""
usg = UsageFormat();
"""
Define several display options for program usg such as
- maximum line length
- indentation style
- usg verbosity
"""
if not result():
"""
PregramResult redefines the __call__ magic method.
This will return True if no error occurs
"""
for m in result.getMessages():
print " - ", m
# Prints all warnings and errors
usg.format = UsageFormat.SHORT_TEXT
print info.usg(usg)
# Prints a short program usg
exit (1)
if result.displayHelp():
"""*
ProgramResult redefines __getattr__, so option variables
can be accessed directly
Thus, OptionResult redefines __call__ to return the value of the option.
In this case, a switch will return a boolean to indicates if it was present or not
Other available syntax are:
result.displayHelp.isSet
or
result["displayHelp"].isSet
or
result["displayHelp"].value()
...
"""
usg.format = UsageFormat.DETAILED_TEXT
print info.usage(usg)
# Prints a detailed program usg
exit (0)
if result["arg"].isSet:
print "Value of arg: ", result.arg()
# Here, __call__ returs the option argument value
Step 4. Run!
python ./miniapp.py -- --help --some-arg "Bleeeh Blaaah"
You should try to type invalid options or forget the --some-arg argument to see what's happen.
Step 5. Beyond the Python program
Auto complete
To get a bash auto-completion command file, use the bashcompletion.xsl style sheet to transform the option specification file
xsltproc -o miniapp-autocomplete.inc.sh ${NS_XML_PATH}/ns/xsl/program/${SCHEMA_VERSION}/bashcompletion.xsl miniapp.xml
Then, include the generated file in your current environment
. miniapp-autocomplete.inc.sh
And try typing
./miniapp -<TAB>
The shell will propose...
$ ./miniapp -
-a -h --help --some-arg
See the Bash auto-complete file generation for more details.
XUL Frontend
You can automatically build a XUL application without more work. Follow the XUL Tutorial to learn how.
See also
The program interface definition framework