The Parser Module

class smacha.parser.Parser(script_dirs=[], container_persistent_vars=['params'], sub_script_persistent_vars=['userdata', 'remapping', 'transitions'])

Main SMACHA YAML script parser class.

The parser uses ruamel.yaml as its main engine for reading, parsing and writing YAML files, while also providing methods for interpreting SMACHA-specific script constructs.

construct_string(script_vars, string_construct)

Construct a string given a list of script_vars lookups.

List of script_vars lookups is specified as 1 or 2-element lists- see :func:lookup method) and/or strings, e.g. the string_construct ['/', ['params', 'robot'], '/joint_states'] would return the string '/robot_1/joint_states' if script_vars['params']['robot'] == 'robot_1' and '/robot_2/joint_states' if script_vars['params']['robot'] = 'robot_2'.

Parameters:

• script_vars (dict) – Script variables.
• string_construct (list of lists or strings) – A list of either script_vars lookups or strings describing how a string should be constructed, as demonstrated in the above example.

Returns:

The constructed string is returned, as long as the string_construct can be parsed successfully and as long as it contains at least one script_vars lookup. If the string_construct can be parsed, but does not contain a lookup, the original string_construct list is returned as-is. This is done to avoid confusion with a genuine list.

Return type:

str or; list of lists or strings

contain(script, container_name, container_type, states, default_outcome_transition=None)

Convert a sequence of states in a script to a container state.

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• container_name (str) – A name for the container.
• container_type (str) – The container type (e.g. ‘StateMachine’ or ‘Concurrence’).
• states (list of str) – The sequence of states to be contained.
• default_outcome_transition (str or None) – The transition for the default_outcome associated with Concurrence containers. Set to container_name if None.

Returns:

Parsed YAML script with the specified states now contained in the container state.

Return type:

dict or ruamel.yaml.comments.CommentedMap

contains_lookups(script, lookup_vars)

Check if a script variable contains variable lookups.

Given a script and a list of possible lookup variables, e.g. ['params'], recursively check to see if the script contains any lookups to those variables, e.g. regular lookups like ['params', 'robot'] or string constructs like [['params', 'robot'], '/base'].

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• lookup_vars (list of str) – A list of names of possible lookup variables, e.g. ['params'].

Returns:

True if script contains lookups, False otherwise.

Return type:

bool

dump(script, output_file=None)

Dump YAML script to string and (optionally) write to file.

Parameters:script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script. Returns:The rendered script. Return type:str

extract(script, container_state, sub_script_filename=None)

Extract a container state from a script and export to sub-script and super-script.

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• state (str) – Name of container state to be extracted.
• sub_script_filename (str) – Desired name for prospective sub-script file.

Returns:

2-tuple of generated SMACHA YAML sub-script for container state and SMACHA YAML super-script that calls the sub-script.

load(script)

Search for the specified YAML script file and load it.

Parameters:script (str or file) – Either a file name or a file handle to a SMACHA YAML script. Returns:2-tuple of the file contents and the file name. Return type:tuple of str

lookup(script_vars, query)

Retrieve a variable from script_vars as specified by lookup query.

query should be either a 1 or 2-element list, e.g. ['params', 'robot'], in which case a robot name would be retrieved from the params entry in script_vars.

Parameters:

• script_vars (dict) – Script variables.
• query (list of str) – A 1-element or 2-element list of strings.

Returns:

script_vars[query[0]] if query is a 1-element list or script_vars[query[0]][query[1]] if query is a 2-element list.

Return type:

Unknown

parse(script)

Parse YAML script.

Parameters:script (str or bytes) – Either a script file name or script string. Returns:The parsed YAML script. Return type:dict or ruamel.yaml.comments.CommentedMap

sub_longhand(script, subs={'callbacks': 'cb', 'default_outcome': 'do', 'input_keys': 'ik', 'manifest': 'm', 'name': 'n', 'node_name': 'nn', 'outcome_map': 'om', 'outcomes': 'o', 'output_keys': 'ok', 'params': 'p', 'remapping': 'r', 'script': 'S', 'states': 's', 'template': 'T', 'transitions': 't', 'userdata': 'ud'})

Substitute longhand script notation for shorthand.

NOTE: This method, in its current form, will modify the input script object!

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• subs (dict) – A dict of key/val substitutions, where the keys are substituted for the vals in the script.

Returns:

The updated YAML script with substituted lookups.

Return type:

dict or ruamel.yaml.comments.CommentedMap

sub_longhand_defaults = {'callbacks': 'cb', 'default_outcome': 'do', 'input_keys': 'ik', 'manifest': 'm', 'name': 'n', 'node_name': 'nn', 'outcome_map': 'om', 'outcomes': 'o', 'output_keys': 'ok', 'params': 'p', 'remapping': 'r', 'script': 'S', 'states': 's', 'template': 'T', 'transitions': 't', 'userdata': 'ud'}

sub_lookups(script, old_key, old_val, new_key, new_val)

Substitute lookup key/value names throughout a script.

Given a script, recursively substitute [old_key, old_val] lookups with [new_key, new_val] lookups everywhere.

NOTE: This method, in its current form, will modify the input script object!

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• old_key (str) – The old_key in [old_key, old_val] lookups.
• old_val (str) – The old_val in [old_key, old_val] lookups.
• new_key (str) – The new_key in [new_key, new_val] lookups.
• new_val (str) – The new_val in [new_key, new_val] lookups.

Returns:

The updated YAML script with substituted lookups.

Return type:

dict or ruamel.yaml.comments.CommentedMap

sub_shorthand(script, subs={'S': 'script', 'T': 'template', 'cb': 'callbacks', 'do': 'default_outcome', 'ik': 'input_keys', 'm': 'manifest', 'n': 'name', 'nn': 'node_name', 'o': 'outcomes', 'ok': 'output_keys', 'om': 'outcome_map', 'p': 'params', 'r': 'remapping', 's': 'states', 't': 'transitions', 'ud': 'userdata'})

Substitute shorthand script notation for longhand.

NOTE: This method, in its current form, will modify the input script object!

Parameters:

• script (dict or ruamel.yaml.comments.CommentedMap) – The parsed YAML script.
• subs (dict) – A dict of key/val substitutions, where the keys are substituted for the vals in the script.

Returns:

The updated YAML script with substituted lookups.

Return type:

dict or ruamel.yaml.comments.CommentedMap

sub_shorthand_defaults = {'S': 'script', 'T': 'template', 'cb': 'callbacks', 'do': 'default_outcome', 'ik': 'input_keys', 'm': 'manifest', 'n': 'name', 'nn': 'node_name', 'o': 'outcomes', 'ok': 'output_keys', 'om': 'outcome_map', 'p': 'params', 'r': 'remapping', 's': 'states', 't': 'transitions', 'ud': 'userdata'}