Declarative Config Parsing API

Declaring a Configuration File

class yosys_mau.config_parser.ConfigParser(contents)

Base class for config parsers.

Derive from this class to implement a config parser. To specify the sections that can be present, assign SectionParser objects to class attributes of the derived class.

Initializing a config parser will automatically start parsing the contents of the config file.

A config parser first splits the file contents into sections. Next it invokes all registered section parsers in order, each of which can parse one or more sections. The config parser keeps track of which sections are parsed. Then a second pass through the registered section parsers is done giving each a chance to perform validation on the parsed sections. Finally any unparsed sections are treated as errors.

Parameters:

contents (str) – The contents of the config file. This should be a SourceStr for proper error reporting.

See the extending page for details on how to use this class when extending the declarative API.

setup()

Invoked before any sections are parsed.

validate()

Invoked after all sections are parsed and validated.

property contents: str

The complete unprocessed contents of the config file.

Declaring Individual Configuration Sections

class yosys_mau.config_parser.SectionParser

Base class for section parsers.

See the extending page for details on how to use this class when extending the declarative API.

class yosys_mau.config_parser.RawSection(required=False, unique=False, arguments=None, all_sections=False)

Bases: SectionParser[list[ConfigSection]]

Section parser that returns the raw ConfigSection objects.

Parameters:
required: bool = False

Passed to SectionParser.matching_sections().

unique: bool = False

Passed to SectionParser.matching_sections().

arguments: None | bool = None

Passed to SectionParser.matching_sections().

all_sections: bool = False

Passed to SectionParser.matching_sections().

class yosys_mau.config_parser.SectionContentsParser

Bases: SectionParser[T]

Base class for section parsers that only handle section contents, not arguments.

This allows delegating the parsing of section arguments, e.g. by using with_arguments.

See the extending page for details on how to use this class when extending the declarative API.

with_arguments(value_parser: ValueParser[A]) → ArgSection[A, T]
with_arguments(value_parser: None = None) → ArgSection[str, T]

Wraps this section parser in an ArgSection parser.

class yosys_mau.config_parser.StrSection(concat=False, default=None)

Bases: SectionContentsParser[str]

Section parser that returns the section contents as a single string.

Parameters:

  • concat (bool)

  • default (str | None)

concat: bool = False

Specifies the behavior when multiple sections match. If True, the contents of all matching sections are concatenated, for False, an error is raised.

default: str | None = None

The default value to return when no sections match. If None, the section must be present or an error is raised.

class yosys_mau.config_parser.ArgSection(content_parser, arguments_parser=<factory>)

Bases: SectionParser[Mapping[A, T]]

Section parser that handles section arguments and delegates to another section parser for the section contents. It uses a ValueParser to parse the argument value.

When using a fixed content_parser, prefer using SectionContentsParser.with_arguments over using this class directly.

Parameters:
content_parser: SectionContentsParser[T] | Callable[[A], SectionContentsParser[T]]

The section content parser to use for the section contents. If a callable is passed, the specific parser used can be selected based on the parsed arguments.

arguments_parser: ValueParser[A]

The parser to use for parsing the section arguments.

yosys_mau.config_parser.postprocess_section(inner)

Decorator for postprocessing the result of another section parser.

Within a config parser class, use it like this:

@postprocess_section(InnerSection(...))
def some_name(self, result: S) -> T:
    ...

Here InnerSection(...) is another section parser, like e.g. RawSection or StrSection, with S being the result type of InnerSection(...) and T the result type of the postprocessing section parser. The name some_name of the post-processing method is forwarded to the inner parser, as if it were declared like some_name = InnerSection(...).

Parameters:

inner (SectionParser[S]) – The inner section parser.

Returns:

A decorator for the postprocessing method, which when applied to a method, returns a new section parser.

Return type:

Callable[[Callable[[Any, S], T]], SectionParser[T]]

class yosys_mau.config_parser.PostprocessSection(inner_parser, postprocess)

Bases: SectionParser[T], Generic[T, S]

Section parser that postprocesses the result of another section parser.

Prefer using the postprocess_section() decorator over using this class directly.

Parameters:
inner_parser: SectionParser[S]

Section parser used to initially parse the section.

postprocess: Callable[[Any, S], T]

Function that postprocesses the result of inner_parser.

Declaring Options Sections

class yosys_mau.config_parser.ConfigOptions(contents)

Base class for defining options sections.

Derive from this class to implement an options section parser. To specify the options that can be present, assign OptionParser objects to class attributes of the derived class.

Note that this is not an instance of SectionParser but needs to be wrapped by OptionsSection to be included in a ConfigParser.

Initializing an options section parser will automatically start parsing the contents of the config file.

An options section parser first splits the file contents into commands. Next it invokes all registered option parsers in order, each of which can parse one or more commands as options. The options section parser keeps track of which options are parsed. Then a second pass through the registered option parsers is done giving each a chance to perform validation on the parsed options. Finally any unparsed sections are treated as errors.

Note that the validation is not done during construction but only when the validate() method is called. This is different from the ConfigParser to ensure that all other sections have been parsed before the options are validated.

Parameters:

contents (str) – The contents of the config file. This should be a SourceStr for proper error reporting.

See the extending page for details on how to use this class when extending the declarative API.

setup()

Invoked before any options are parsed.

validate()

Invoked after all options are parsed and validated.

property contents: str

The complete unprocessed contents of the options section.

class yosys_mau.config_parser.OptionParser

Bases: Generic[T]

Base class for option parsers.

class yosys_mau.config_parser.RawOption(required=False, unique=False)

Bases: OptionParser[list[ConfigCommand]]

Returns a list of unparsed ConfigCommands for every use of this option.

Parameters:
required: bool = False

Raise an error if no matching sections are found. Requires a section name.

unique: bool = False

Raise an error if, among the matching sections, two share the same header (name + arguments).

class yosys_mau.config_parser.Option(value_parser, default=<factory>)

Bases: OptionParser[T]

An option that can be specified at most once.

This uses a ValueParser to parse the option’s arguments and directly sets the result to the parsed value.

Parameters:

  • value_parser (ValueParser[T])

  • default (T | Literal[<dataclasses._MISSING_TYPE object at 0x7f834e60fd90>])

value_parser: ValueParser[T]

The parser for the option’s arguments.

default: _MISSING_TYPE object at 0x7f834e60fd90>]

The default value for the option. If the option is not specified, this value is used. If no default value is specified, the option is required.

class yosys_mau.config_parser.MultiOption(value_parser, default=())

Bases: OptionParser[List[T]]

An option that can be specified multiple times.

This uses a ValueParser to parse the option’s arguments and sets the result to a list of all parsed values.

Parameters:
value_parser: ValueParser[T]

The parser for the arguments, used each time the option is specified.

default: _MISSING_TYPE object at 0x7f834e60fd90>] = ()

The default values for the option. If the option is not present at all, this value is used, by default an empty list. If the default is the special value dataclasses.MISSING, the option is required to be used at least once.

class yosys_mau.config_parser.OptionsSection(config_options, unique=False)

Bases: SectionContentsParser[SomeConfigOptions]

A section parser that parses a section into a ConfigOptions instance. Use this to add ConfigOptions to a ConfigParser.

Parameters:
config_options: Callable[[str], SomeConfigOptions]

A callable that returns a ConfigOptions instance for a given section content.

Usually this is the ConfigOptions subclass itself.

unique: bool = False

If set, raises an error if the section is present multiple times. Otherwise the options of all sections are combined.

Declaring Commands Sections

class yosys_mau.config_parser.ConfigCommands(contents)

Base class for defining commands sections.

Parameters:

contents (str)

setup()

Invoked before any commands are parsed.

validate()

Invoked after all commands are parsed.

unrecognized_command(command)

Invoked when a command is not recognized.

By default this raises an InputError, but subclasses may override this to provide different behavior

Parameters:

command (ConfigCommand)

yosys_mau.config_parser.command(arguments)

Decorator for defining command handlers.

Decorate a method with this to turn it into a command handler for commands with the same name as the method.

Parameters:

arguments (ValueParser[T])

Return type:

Callable[[Callable[[Any, T], None]], CommandParser]

class yosys_mau.config_parser.CommandsSection(config_commands, required=False, unique=False)

Bases: SectionContentsParser[SomeConfigCommands]

A section parser that parses a section into a ConfigCommands instance. Use this to add ConfigCommands to a ConfigParser.

Parameters:
required: bool = False

If set, raises an error if the section is absent.

unique: bool = False

If set, raises an error if the section is present multiple times. Otherwise the commands of all sections are combined.