Runtime API: package grammarinator.runtime

class grammarinator.runtime.CooldownModel(model, *, cooldown=1.0, weights=None, lock=None)

Bases: Model

Custom model (or model wrapper) that updates (practically downscales) the weights of alternatives chosen by the underlying model.

Parameters:

• model (Model) – The underlying model.

• cooldown (float) – The cooldown factor (default: 1.0, meaning no cooldown).

• weights (dict[tuple,float]) – Initial multipliers of alternatives. It is only useful, if the same dictionary object is passed to every instantiation of this class so that the decisions made during test case generation can affect those that follow. The keys of the dictionary are tuples in the form of (str, int, int), each denoting an alternative: the first element specifies the name of the rule that contains the alternative, the second element specifies the index of the alternation containing the alternative within the rule, and the third element specifies the index of the alternative within the alternation (both indices start counting from 0). The first and second elements correspond to the node and idx parameters of choice(), while the third element corresponds to the indices of the weights parameter.

• lock (multiprocessing.Lock) – Lock object when generating in parallel (optional).

charset(node, idx, chars)

Trampoline to the charset method of the underlying model.

choice(node, idx, weights)

Transitively calls the choice method of the underlying model with multipliers applied to weights first, and updates the multiplier of the chosen alternative with the cooldown factor afterwards.

quantify(node, idx, cnt, start, stop)

Trampoline to the quantify method of the underlying model.

class grammarinator.runtime.DefaultModel

Bases: Model

Default decision model implementation.

charset(node, idx, chars)

A single character is chosen randomly from the set of possible options (chars).

Parameters node and idx are unused.

choice(node, idx, weights)

The decision is solely based upon the provided weights.

Parameters node and idx are unused.

quantify(node, idx, cnt, start, stop)

After generating the minimum expected items (start) and before reaching the maximum expected items (stop), quantify decides about the expansion of the optional items based on a random binary decision.

Parameters node, idx, cnt, start, and stop are unused.

class grammarinator.runtime.DispatchingListener

Bases: Listener

Base class of custom listeners that aim to override the enter and exit actions for specific rules. Subclassing DispatchingListener enables to define the enter and exit methods of a rule in the form of [enter|exit]_{rule_name}.

enter_rule(node)

Trampoline to the enter_{node.name} method of the subclassed listener, if it is defined.

exit_rule(node)

Trampoline to the exit_{node.name} method of the subclassed listener, if it is defined.

class grammarinator.runtime.DispatchingModel

Bases: DefaultModel

Base class of custom models that aim to override the decisions in specific rules. To override a decision point, the subclass must define methods in the form of choice_{rule_name}, quantify_{rule_name} or charset_{rule_name} - with the same signature as their counterparts in DefaultModel - in case of overriding an alternation, quantifier or charset decision, respectively.

charset(node, idx, chars)

Trampoline to the charset_{node.name} method of the subclassed model, if it exists. Otherwise, it calls the default implementation (DefaultModel.charset()).

choice(node, idx, weights)

Trampoline to the choice_{node.name} method of the subclassed model, if it exists. Otherwise, it calls the default implementation (DefaultModel.choice()).

quantify(node, idx, cnt, start, stop)

Trampoline to the quantify_{node.name} method of the subclassed model, if it exists. Otherwise, it calls the default implementation (DefaultModel.quantify()).

class grammarinator.runtime.Generator(*, model=None, listeners=None, limit=None)

Bases: object

Base class of the generated Generators. Stores the decision model, the listeners, and additional internal state used during generation.

Parameters:

• model (Model) – Model object responsible for every decision during the generation. (default: DefaultModel).

• listeners (list[Listener]) – Listeners that get notified whenever a rule is entered or exited.

• limit (RuleSize) – The limit on the depth of the trees and on the number of tokens (number of unlexer rule calls), i.e., it must be possible to finish generation from the selected node so that the overall depth and token count of the tree does not exceed these limits (default: RuleSize. max).

class grammarinator.runtime.Listener

Bases: object

Base class of listeners that get notified by generators whenever a rule is entered or exited. which needs to be subclassed.

enter_rule(node)

Actions to take when a rule is entered, i.e., before creating the derivation of node.

No-op by default.

Parameters:

node (Rule) – Empty node (it has no children yet, but node.name and node.parent are already valid) that is about to have a subtree generated.

exit_rule(node)

Actions to take when a rule is exited, i.e., after creating the derivation of node.

No-op by default.

Parameters:

node (Rule) – Node with its subtree just generated.

class grammarinator.runtime.Model

Bases: object

Abstract base class of models that make decisions for generators at alternations, quantifiers, and charsets.

charset(node, idx, chars)

Choose a character from a charset.

Raises NotImplementedError by default.

Parameters:

• node (Rule) – The current node. Its name field identifies the corresponding grammar rule, which contains the charset.

• idx (int) – Index of the charset inside the current rule.

• chars (list[str]) – List of characters to choose a single character from.

Returns:

The chosen character.

Return type:

str

choice(node, idx, weights)

Choose an alternative from an alternation.

Raises NotImplementedError by default.

Parameters:

• node (Rule) – The current node. Its name field identifies the corresponding grammar rule, which contains the alternation to choose an alternative from.

• idx (int) – Index of the alternation inside the current rule.

• weights (list[float]) – Weights assigned to alternatives of the selected alternation.

Returns:

The index of the chosen alternative.

Return type:

int

quantify(node, idx, cnt, start, stop)

Guide the loop of subtree quantification. This has to make a binary decision to tell whether to enable the next iteration or stop the loop.

Raises NotImplementedError by default.

Parameters:

• node (Rule) – The current node. Its name field identifies the corresponding grammar rule, which contains the quantified subtree.

• idx (int) – Index of the quantified subtree inside the current rule.

• cnt (int) – Number of the already generated subtrees, guaranteed to be between start (inclusive) and stop (exclusive).

• start (int) – Lower bound of the quantification range.

• stop (int) – Upper bound of the quantification range.

Returns:

Boolean value enabling the next iteration or stopping it.

Return type:

bool

class grammarinator.runtime.ParentRule(*, name, children=None)

Bases: Rule

Abstract base class of tree nodes that can have children.

Parameters:

• name (str) – Name of the corresponding parser rule in the grammar.

• children (list[Rule]) – Children of the rule (default: no children).

Variables:

children (list[Rule]) – Children of the rule.

__iadd__(item)

Support for += operation to add one or more children to the current node. An alias to add_child() or add_children() depending on the type of child.

Parameters:

item (Rule or list[Rule]) – The node(s) to be added as child.

Returns:

The current node with extended children.

Return type:

Rule

add_child(node)

Add node to the end of the list of the children.

Parameters:

node (Rule) – Node to be added to children.

add_children(nodes)

Add mulitple nodes to the end of the list of the children.

Parameters:

nodes (list[Rule]) – List of nodes to be added to children.

insert_child(idx, node)

Insert node as child at position.

Parameters:

• idx (int) – Index of position to insert node at.

• node (Rule) – Node to be inserted.

property last_child

Get the last child of the current node if any. Return None if the node has no children.

class grammarinator.runtime.Population

Bases: object

Abstract base class of populations that store test cases in tree form (i.e., individuals) and can select trees for mutation or recombination based on some strategy.

add_individual(root, annotations=None, path=None)

Add a tree to the population.

Raises NotImplementedError by default.

Parameters:

• root (Rule) – Root of the tree to be added.

• annotations (object) – Data to be stored along the tree, if possible. No assumption should be made about the structure or the contents of the data, it should be treated as opaque.

• path (str) – The pathname of the test case corresponding to the tree, if it exists. May be used for debugging.

select_individual()

Select an individual of the population.

Raises NotImplementedError by default.

Returns:

Root of the selected tree, and any associated information that was stored along the tree when it was added (if storing/restoring that information was possible).

Return type:

tuple[Rule,object]

class grammarinator.runtime.Rule(*, name)

Bases: object

Abstract base class of tree nodes.

Tree nodes support deep copying via copy.deepcopy() (but no shallow copying via copy.copy()). A deep copy of a node is the copy of the whole subtree rooted at that node. However, the parent of a copy node is always None, even if the original node had a parent.

Tree nodes support various string representations:

• The “informal” representation of a node consists of the concatenation of the string contents of all tokens found in the tree rooted at the node in depth-first order. No extra whitespace is inserted for separation.

• The “official” representation of a node is an (almost) valid Python expression to recreate the tree rooted at the node. If the node has any children, the representation consists of multiple lines.

• The “debug” representation of a node is a multi-line string with the most important attributes of the tree rooted at the node, using vertical bars for visual guidance.

The builtins str and repr() can be used to compute the “informal” and “official” representations, respectively, while format() can produce all of the above. When string formatting is used, the following format specifiers are recognized:

Specifier	Meaning
'' or 's'	“Informal” representation.
'r'	“Official” representation.
'|'	“Debug” representation.

Thus, if n is a node, the following expressions give equivalent results:

• str(n), f'{n}', f'{n!s}', f'{n:s}', '{}'.format(n), '{!s}'.format(n), and '{:s}'.format(n)

• repr(n), f'{n!r}', f'{n:r}', '{!r}'.format(n), and '{:r}'.format(n)

• f'{n:|}' and '{:|}'.format(n)

Parameters:

name (str) – Name of the node, i.e., name of the corresponding parser or lexer rule in the grammar.

Variables:

• name (str) – Name of the node, i.e., name of the corresponding parser or lexer rule in the grammar.

• parent (UnparserRule) – Parent node object.

property left_sibling

Get the left sibling of the node if any. Return None if the node has no parent or is the leftmost child of its parent.

Returns:

The left sibling of the current node or None.

Return type:

Rule

remove()

Remove the current node from its parent.

replace(node)

Replace the current node with node among its siblings.

Parameters:

node (Rule) – The replacement node.

Returns:

node

Return type:

Rule

property right_sibling

Get the right sibling of the node if any. Return None if the node has no parent or is the rightmost child of its parent.

Returns:

The right sibling of the current node or None.

Return type:

Rule

property root

Get the root of the node, i.e., the node at the top of the parent chain.

Returns:

The root of the current node.

Return type:

Rule

class grammarinator.runtime.RuleSize(depth=0, tokens=0)

Bases: object

Size information about a grammar rule or a (sub)tree (generated based on a grammar rule), expressed using different metrics (both vertical and horizontal).

This class can be used to describe various size-related concepts, e.g.:

• The minimum depth of derivation of a grammar rule and the minimum number of tokens generated by a grammar rule.

• The actual depth of derivation of a grammar rule and the actual number of tokens generated by a grammar rule.

• The maximum allowed depth of derivation in a tree and the maximum number of tokens allowed in a tree.

• The depth of derivation reaching a node from the root of the tree and the number of tokens in the tree outside the subtree of the node.

The class supports additive arithmetics (+, +=, -, -=) and comparisons (==, <=, <). Note, however, that the type is not totally but partially ordered, i.e., a size object is less than another size object iff all its metrics compare less than the corresponding metrics of the other size object.

Parameters:

• depth (int or float) – Derivation length (default: 0).

• tokens (int or float) – Token count (default: 0).

Variables:

• depth (int or float) – Derivation length.

• tokens (int or float) – Token count.

• max (RuleSize) – All size metrics set to inf.

class grammarinator.runtime.UnlexerRule(*, name=None, src=None, size=None)

Bases: Rule

Tree node representing a lexer rule or token. It has a string constant set in its src field.

Parameters:

• name (str) – Name of the corresponding lexer rule in the grammar.

• src (str) – String content of the lexer rule (default: “”).

• size (RuleSize) – Size of the lexer rule (default: (1,1) if src is not empty, (0,0) otherwise).

Variables:

• src (str) – String content of the lexer rule.

• size (RuleSize) – Size of the lexer rule, aggregated from the token fragments it is composed of.

class grammarinator.runtime.UnparserRule(*, name, children=None)

Bases: ParentRule

Tree node representing a parser rule. It can have zero or more UnparserRule, UnlexerRule, UnparserRuleQuantifier or UnparserRuleAlternative children.

Parameters:

• name (str) – Name of the corresponding parser rule in the grammar.

• children (list[Rule]) – Children of the rule (default: no children).

Variables:

children (list[Rule]) – Children of the rule.

class grammarinator.runtime.UnparserRuleAlternative(*, alt_idx, idx, children=None)

Bases: ParentRule

Tree node representing a sub-tree of an alternative. It can have zero or more UnparserRule, UnlexerRule, UnparserRuleQuantifier or UnparserRuleAlternative children.

class grammarinator.runtime.UnparserRuleQuantified(*, children=None)

Bases: ParentRule

Tree node representing a single instance of quantified sub-tree. It can have one or more UnparserRule, UnlexerRule, UnparserRuleQuantifier or UnparserRuleAlternative children.

class grammarinator.runtime.UnparserRuleQuantifier(*, idx, start, stop, children=None)

Bases: ParentRule

Tree node representing the root of a quantified sub-tree. It can have one or more UnparserRuleQuantified children.

grammarinator.runtime.simple_space_serializer(root)

Simple serializer concatenating the children of UnparserRule s with a single space.

Parameters:

root (Rule) – The root node of the tree or subtree to serialize.

Returns:

The serialized tree as string.

Return type:

str