parselglossy.api module#
Top-level functions for parselglossy.
- parselglossy.api.document(template: Union[str, Path], outfile: Optional[Union[str, Path]] = None, header: str = 'Input parameters') str [source]#
Generate documentation in reStructuredText format from validation template.
- Parameters
template (Union[str, Path]) – Which validation template to use.
output (Union[str, Path]) – Where to save the generated documentation. Defaults to
None
.header (str) – Header for the documentation page. Defaults to
Input parameters
.
- Return type
The documentation page as a string.
- parselglossy.api.generate(template: Union[str, Path], *, where: Union[str, Path] = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/parselglossy/checkouts/v0.8.0/docs/input_parser'), grammar: Union[str, Path, List[Path]] = 'standard', tokenize: Optional[str] = None, docfile: str = 'input.rst', doc_header: str = 'Input parameters') Path [source]#
Generate parser for client.
- Parameters
template (Union[str, Path]) – Which validation template to use.
where (Union[str, Path]) – Where to generate the parsing module. Default to
input_parser
folder under current working directory.grammar (Union[str, Path, List[Path]]) – The file containing the grammar to use to tokenize user input. Defaults to
standard
, i.e. use one of the grammars packaged with the library, based onpyparsing
.tokenize (Optional[str]) – The commands to perform lexing of the input with a custom grammar. The result of these commands must be a variable named
ir
of typeDict[str, Any]
. Defaults toNone
.docfile (str) – The name of the documentation file for the input. Defaults to
input.rst
.doc_header (str) – Header for the documentation page. Defaults to
Input parameters
.
- Return type
Location of generated parser Python module as a
Path
object.
Notes
This function will generate a Python module for parsing inputs as defined by the template and grammar provided as parameters.
The user can provide a grammar as (a list of) external file(s). There are a few constraints:
The function performing tokenization must return an object of
Dict[str, Any]
type: a, potentially recursive, dictionary of keys and values.Commands to perform tokenization are passed via the
tokenize
input parameters. This is a string that will copied verbatim in the generated code, relevantimport
statements have to be included in this string!The result of the commands in
tokenize
must be a variable namedir
.It is the responsibility of the user to satisfy any dependencies of the parsing grammar they provided.
- Raises
- parselglossy.api.lex(infile: Union[str, Path], grammar: str = 'standard', ir_file: Optional[Union[str, Path]] = None) Dict[str, Any] [source]#
Run grammar of choice on input string.
- Parameters
infile (Union[str, Path]) – The string to be parsed.
grammar (str) – Grammar to be used.
ir_file (Union[str, Path]) – File to write intermediate representation to (JSON format). None by default, which means file is not written out.
- Return type
The contents of the input string as a dictionary.
- parselglossy.api.parse(infile: Union[str, Path], template: Union[str, Path], outfile: Optional[Union[str, Path]] = None, grammar: str = 'standard', dump_ir: bool = False) Dict[str, Any] [source]#
Parse input file.
- Parameters
infile (Union[str, Path]) – The input file to be parsed.
template (Union[str, Path]) – Which validation template to use.
outfile (Optional[Union[str, Path]]) – The output file. Defaults to
None
, which means writing to<infile>_fr.json
.grammar (str) – Which grammar to use. Defaults to
standard
.dump_ir (bool) – Whether to write out the intermediate representation to file (JSON format). False by default. If true the filename if
<infile>_ir.json
- Return type
The validated input as a dictionary.
- parselglossy.api.validate(infile: Union[str, Path], template: Union[str, Path], fr_file: Optional[Union[str, Path]] = None) Dict[str, Any] [source]#
Validate intermediate representation into final representation.
- Parameters
infile (Union[str, Path]) – The file with the intermediate representation (JSON format).
template (Union[str, Path]) – Which validation template to use.
fr_file (Union[str, Path]) – File to write final representation to (JSON format). None by default, which means file is not written out.
- Return type
The validated input as a dictionary.