Usage#

As a generator#

parselglossy can be used to generate a parser for your project. This relieves you and your users from depending on parselglossy itself for running your code.

Let us look at an example. We will assume your validation specification is in a file template.yml and that your input conforms to the standard grammar provided with parselglossy. You can then run the following command:

parselglossy generate --target input_parser --template template.yml --grammar standard

You will notice a folder input_parser has been generated, with the following contents:

input_parser
├── api.py
├── cli.py
├── docs
│   └── input.rst
├── __init__.py
├── plumbing
│   ├── atoms.py
│   ├── exceptions.py
│   ├── getkw.py
│   ├── lexer.py
│   ├── pyparsing.py
│   ├── types.py
│   ├── utils.py
│   ├── validation_plumbing.py
│   ├── validation.py
│   └── views.py
└── README.md

This is a complete Python module containing the parser specific to your project. This module only depends on functionality provided with any standard Python installation: no need for additional dependencies! The generator will copy files from parselglossy in the plumbing subfolder and generate documentation in reStructuredText format. The two source files api.py and cli.py will be the most useful to actually use the generated parser. The former exposes an API similar to that of parselglossy, the latter defines a minimal argparse CLI on top of this API. An interface to the generated parser would look as follows:

from input_parser import cli

cli.cli()

It is also possible to generate parser with grammars outside of what parselglossy provides. In that case, you will need to invoke the generate subcommand with arguments:

  • Listing all Python files defining your grammar:

    -g file1.py -g file2.py -g file3.py
    
  • Giving the Python commands to use your grammar:

    --tokenize "import file1; ir = file1.command()"
    

    Note that the result of such a command has to be in a variable called ir.

As a Python module#

To use parselglossy in a project:

import parselglossy

Validation specifications#

Possible fields for keywords are:

name

The name of the keyword. Mandatory.

type

Type of the corresponding value. Mandatory.

docstring

A documentation string, possibly multiline. Mandatory.

default

The default value. It can be a value of the declared type or a callable. The callable can be used to compute default values based on the default value of any other keyword in the input. If absent, the keyword is required, meaning that the user will have to supply it in their own input.

predicates

A list of callables to sanity-check the passed value. Note that type checking is always performed automatically.

Possible fields for sections are:

name

The name of the section. Mandatory.

docstring

A documentation string, possibly multiline. Mandatory.

keywords

A list of keywords belonging to the section.

sections

A list of sections belonging to the section.

One or both of keywords and sections must be present.