YAML Parser

BLADE’s input syntax is comprised of specific YAML tags, each with a number of expected properties. The YAML syntax is extensive, and so is documented separately - the rest of this section gives a general overview of the parsing process.

For every supported tag, BLADE has an associated schema class to represent it. Basic properties of name, options, ld, and sd are common to almost all tag types - each tag then builds on these with its own specific properties.

Many tag types support both mapping and sequence node declarations. A mapping node representation uses a dictionary syntax similar to the following:

- !Field
  name : my_field
  width: 4
  lsb  : 8
  type : U
  reset: 0
  ld   : "My long description of this field"

Whereas a sequence node uses an arrayed syntax, with the order of arguments being critical:

- !Field [my_field, 4, 8, U, 0, "My long description of this field"]

The parser supports mapping and sequence nodes for all tag types, the order of the parameters is defined by the order they appear in the schema class’ initiator. Optional parameters can simply be left blank or not listed.

The parser enforces that only one definition of each parameter exists per tag instance and will raise an error if repetition is detected. For example, the following declaration would be illegal due to the reptition of the ‘enums’ field.

- !Field
  name : my_field
  width: 4
  lsb  : 8
  reset: 0
  enums:
  - !Enum [my_enum_val_0]
  enums: # <-- Illegal second definition
  - !Enum [my_enum_val_1]

As seen above, tags may be used as child attributes of a tag field if supported. These will be strictly type checked in the validation stage.

Note

During the parsing stage, no effort is made to verify the ‘correctness’ of the design nor of the syntax beyond complying with the basic YAML language, instead this is performed in a later stage.

API

exception blade.parser.PhhidleParseError(message, path=None)

Custom Exception type that allows YAML parsing errors to be reported

blade.parser.parse_phhidle_file(path, prefile=None, buffer=None)

Parse a Phhidle schema YAML file for all documents that are described.

Parameters

  • path – The path to the YAML file

  • prefile – The PreprocessorFile object (used to map line numbers, optional)

  • buffer – The contents of the YAML file (allow this to be either directly from the file, or post-preprocessor). This is optional, if not provided then the file will be loaded from disk.

Returns

Collection of documents parsed from the raw YAML input

Return type

list

blade.parser.schema_constructor(loader, node, deep=True)

Custom tag constructor for building mapping or sequence nodes.

Custom tag constructor that can either build mapping nodes or sequence nodes depending on the input. This automatically allows any schema class to support both methods of declaration. This constructor also performs a basic validation that all required keys are presented, and no unsupported keys are present.

Parameters

  • loader – The PyYAML loader instance

  • node – The current YAML node to digest

  • deep – Whether to perform deep population of the node

Returns

The parsed YAML tag as a Python object

Return type

TagBase