PythonTutorial

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.

• [Generating Python parser & usage code](#Generating Python parser & usage code)
• [Step 1. Defining the options](#Step 1. Defining the options)
• [Step 2. Generate parser and program description](#Step 2. Generate parser and program description)
• [Step 3. Write your program](#Step 3. Write your program)
• [Step 4. Run!](#Step 4. Run!)
• [Step 5. Beyond the Python program](#Step 5. Beyond the Python program)
• [Auto complete](#Auto complete)
• [XUL Frontend](#XUL Frontend)
• [See also](#See also)

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 <?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 #!bash ${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](https://github.com/noresources/ns-xml/wiki/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](https://github.com/noresources/ns-xml/wiki/miniapp.py) #!python #!/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!

#!bash
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 #!bash 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 #!bash . miniapp-autocomplete.inc.sh And try typing #!bash ./miniapp -<TAB> The shell will propose... #!bash $ ./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 Python parser API details
• build-python command line tool usage

---

The program interface definition framework