Format:

A data set consists of zero or more records seperated by one or more empty lines.

Lines starting with the comment mark (default: #) are ignored.

A record consists of one or more fields.

A field is a line that has the form:

key: value

key is a string that

• doesn't contain a colon
• doesn't start with the comment mark (see above)
• doesn't start with the continuation mark (see below)

value is an arbitrary string

If a line starts with the continuation mark (default: " " (one blank)) it gets appended to the preceding line, with the continuation mark removed (the newline is kept)

Example:

The navigation menu on the Shipyard homepage is created from a shipyard file files.sy that contains the following lines:

ID: shipyard
Section: /software/shipyard
Path: software/shipyard
Short: Shipyard
Desc: Shipyard is a Python module to process data in a format
 inspired by email headers (RFC 2822).

ID: firkin
Section: /software/firkin
Path: software/firkin
Short: firkin
Desc: Firkin is a Python module to convert between units

#ID: loci
#Section: /software/loci
#Path: software/loci
#Short: Loci

loci isn't ready for release yet so its data lines are commented out.

First we open the file:

>>> f=open(path, "rb")

Then we create a parser object:

>>> reader=shipyard.Parser(keys=['ID', 'Section', 'Path','Short',
                                 'Long', 'Desc'])

For every record the given C{keys} are initialized with C{None}.

To get some fancy output we create a pretty printer:

>>> import pprint
>>> pp = pprint.PrettyPrinter(indent=4)

Now we can iterater through the records:

>>> for record in reader.parse(input):
...      pp.pprint(record)
{   'Desc': 'Shipyard is a Python module to process data in a format'
            'inspired by email headers (RFC 2822).',
    'ID': 'shipyard',
    'Long': None,
    'Path': 'software/shipyard',
    'Section': '/software/shipyard',
    'Short': 'Shipyard'}
{   'Desc': 'Firkin is a Python module to convert between units',
    'ID': 'firkin',
    'Long': None,
    'Path': 'software/firkin',
    'Section': '/software/firkin',
    'Short': 'firkin'}

We don't need the file anymore so we close it:

>>> input.close()