nunavut.lang

Language-specific support in nunavut.

This package contains modules that provide specific support for generating source for various languages using templates.

class nunavut.lang.LanguageLoader(*additional_config_files)[source]

Bases: object

Factory class that loads language meta-data and concrete nunavut.lang.Language objects.

Parameters:additional_config_files

A list of paths to additional configuration files to load as configuration. These will override any values found in the nunavut.lang.properties.yaml file and files appearing later in this list will override value found in earlier entries.

classmethod load_language_module(language_name: str) → module[source]
config

Meta-data about all languages merged from the Nunavut internal defaults and any additional configuration files provided to this class’s constructor.

load_language(language_name: str, omit_serialization_support: bool, language_options: Optional[Mapping[str, Any]] = None) → nunavut.lang.Language[source]
Parameters:
  • language_name (str) – The name of the language used by the nunavut.lang module.
  • config (LanguageConfig) – The parser to load language properties into.
  • omit_serialization_support (bool) – The value to set for the omit_serialization_support() property for this language.
  • typing.Any]] language_options (typing.Optional[typing.Mapping[str,) – Opaque arguments passed through to the target nunavut.lang.Language object.
Returns:

A new object that extends nunavut.lang.Language.

Return type:

nunavut.lang.Language

lang_c = LanguageLoader().load_language('c', True)
assert lang_c.name == 'c'
class nunavut.lang.Language(language_module: module, config: nunavut.lang._config.LanguageConfig, omit_serialization_support: bool, language_options: Optional[Mapping[str, Any]] = None)[source]

Bases: object

Facilities for generating source code for a specific language. Concrete Language classes must be implemented by the language support package below lang and should be instantiated using nunavut.lang.LanguageLoader.

Parameters:
classmethod default_filter_id_for_target(instance: Any) → str[source]

The default transformation of any object into a string.

Parameters:instance (any) – Any object or data that either has a name property or can be converted to a string.
Returns:Either str(instance.name) if the instance has a name property or just str(instance)
get_support_module() → Tuple[str, Tuple[int, int, int], Optional[module]][source]

Returns the module object for the language support files. :return: A tuple of module name, x.y.z module version, and the module object itself.

get_dependency_builder[source]
get_includes(dep_types: nunavut.dependencies.Dependencies) → List[str][source]

Get a list of include paths that are specific to this language and the options set for it. :param Dependencies dep_types: A description of the dependencies includes are needed for. :return: A list of include file paths. The list may be empty if no includes were needed.

filter_id(instance: Any, id_type: str = 'any') → str[source]

Produces a valid identifier in the language for a given object. The encoding may not be reversible.

Parameters:
  • instance (any) – Any object or data that either has a name property or can be converted to a string.
  • id_type (str) – A type of identifier. This is different for each language. For example, for C this value can be ‘typedef’, ‘macro’, ‘function’, or ‘enum’. Use ‘any’ to apply stropping rules for all identifier types to the instance.
Returns:

A token that is a valid identifier in the language, is not a reserved keyword, and is transformed in a deterministic manner based on the provided instance.

filter_short_reference_name(t: pydsdl._serializable._composite.CompositeType, stropping: nunavut._utilities.YesNoDefault = <YesNoDefault.DEFAULT: 2>, id_type: str = 'any') → str[source]

Provides a string that is a shorted version of the full reference name omitting any namespace parts of the type.

Parameters:
  • t (pydsdl.CompositeType) – The DSDL type to get the reference name for.
  • stropping (YesNoDefault) – If DEFAULT then the stropping value configured for the target language is used else this overrides that value.
  • id_type (str) – A type of identifier. This is different for each language. For example, for C this value can be ‘typedef’, ‘macro’, ‘function’, or ‘enum’. Use ‘any’ to apply stropping rules for all identifier types to the instance.
get_config_value(key: str, default_value: Optional[str] = None) → str[source]

Get an optional language property from the language configuration.

Parameters:
  • key (str) – The config value to retrieve.
  • default_value (typing.Optional[str]) – The value to return if the key was not in the configuration. If provided this method will not raise.
Returns:

Either the value from the config or the default_value if provided.

Return type:

str

Raises:

KeyError if the section or the key in the section does not exist and a default_value was not provided.

get_config_value_as_bool(key: str, default_value: bool = False) → bool[source]

Get an optional language property from the language configuration returning a boolean.

Parameters:
  • key (str) – The config value to retrieve.
  • default_value (bool) – The value to use if no value existed.
Returns:

The config value as either True or False.

Return type:

bool

get_config_value_as_dict(key: str, default_value: Optional[Dict[KT, VT]] = None) → Dict[str, Any][source]

Get a language property parsing it as a map with string keys.

Parameters:
  • key (str) – The config value to retrieve.
  • default_value (typing.Optional[typing.Mapping[str, typing.Any]]) – The value to return if the key was not in the configuration. If provided this method will not raise a KeyError nor a TypeError.
Returns:

Either the value from the config or the default_value if provided.

Return type:

typing.Mapping[str, typing.Any]

Raises:

KeyError if the key does not exist and a default_value was not provided.

Raises:

TypeError if the value exists but is not a dict and a default_value was not provided.

get_config_value_as_list(key: str, default_value: Optional[List[T]] = None) → List[Any][source]

Get a language property parsing it as a map with string keys.

Parameters:
  • key (str) – The config value to retrieve.
  • default_value (typing.Optional[typing.List[typing.Any]]) – The value to return if the key was not in the configuration. If provided this method will not raise a KeyError nor a TypeError.
Returns:

Either the value from the config or the default_value if provided.

Return type:

typing.List[typing.Any]

Raises:

KeyError if the key does not exist and a default_value was not provided.

Raises:

TypeError if the value exists but is not a dict and a default_value was not provided.

extension

The extension to use for files generated in this language.

namespace_output_stem

The name of a namespace file for this language.

name

The name of the language used by the nunavut.lang module.

support_namespace

The hierarchical namespace used by the support software. The property is a dot separated string when specified in configuration. This property returns that value split into namespace components with the first identifier being the first index in the array, etc.

enable_stropping

Whether or not to strop identifiers for this language.

has_standard_namespace_files

Whether or not the language defines special namespace files as part of its core standard (e.g. python’s __init__).

stable_support

Whether support for this language is designated ‘stable’, and not experimental.

omit_serialization_support

If True then generators should not include serialization routines, types, or support libraries for this language.

get_support_files(resource_type: nunavut._utilities.ResourceType = <ResourceType.ANY: 0>) → Generator[pathlib.Path, None, None][source]

Iterates over supporting files embedded within the Nunavut distribution.

Parameters:resource_type – The type of support resources to enumerate.
get_option(option_key: str, default_value: Union[Mapping[str, Any], str, None] = None) → Union[Mapping[str, Any], str, None][source]

Get a language option for this language.

# Values can come from defaults...
assert lang_cpp.get_option('target_endianness') == 'little'

# ... or can come from a sane default.
assert lang_cpp.get_option('foobar', 'sane_default') == 'sane_default'
Returns:Either the value provided to the Language instance, the value from properties.yaml, or the default_value.
get_templates_package_name() → str[source]

The name of the nunavut python package containing filters, types, and configuration for this language.

get_named_types() → Mapping[str, str][source]

Get a map of named types to the type name to emit for this language.

get_named_values() → Mapping[str, str][source]

Get a map of named values to the token to emit for this language.

get_globals() → Mapping[str, Any][source]

Get all values for this language that should be available in a global context.

Returns:A mapping of global names to global values.
get_options() → Mapping[str, Any][source]

Get all language options for this Language.

Returns:A mapping of option names to option values.
class nunavut.lang.LanguageContext(target_language: Optional[str] = None, extension: Optional[str] = None, namespace_output_stem: Optional[str] = None, additional_config_files: List[pathlib.Path] = [], omit_serialization_support_for_target: bool = True, language_options: Optional[Mapping[str, Any]] = None, include_experimental_languages: bool = True)[source]

Bases: object

Context object containing the current target language (if any) and used to access Language objects.

Parameters:
  • target_language (str) – If provided a Language object will be created to hold the target language set for this context. If None then there is no target language.
  • extension (str) – The extension to use for generated file types or None to use a default based on the target_language.
  • namespace_output_stem (str) – The filename stem to give to Namespace output files if emitted or None to use a default based on a target_language.
  • additional_config_files (typing.List[pathlib.Path]) – A list of paths to additional files to load as configuration. These will override any values found in the nunavut.lang.properties.yaml file and files appearing later in this list will override value found in earlier entries.
  • omit_serialization_support_for_target (bool) – If True then generators should not include serialization routines, types, or support libraries for the target language.
  • typing.Any]] language_options (typing.Optional[typing.Mapping[str,) – Opaque arguments passed through to the target nunavut.lang.Language object.
  • include_experimental_languages (bool) – If True, expose languages with experimental (non-stable) support.
Raises:
  • ValueError – If extension is None and no target language was provided.
  • KeyError – If the target language is not known.
get_language(key_or_module_name: str) → nunavut.lang.Language[source]

Get a Language object for a given language identifier.

Parameters:key_or_module_name (str) – Either one of the Nunavut mnemonics for a supported language or the __name__ of one of the nunavut.lang.[language] python modules.
Returns:A Language object cached by this context.
Return type:Language
get_supported_language_names() → Iterable[str][source]

Get a list of target languages supported by Nunavut.

Returns:An iterable of strings which are languages with special support within Nunavut templates.
get_output_extension() → str[source]

Gets the output extension to use regardless of a target language being available or not.

Returns:A file extension name with a leading dot.
get_default_namespace_output_stem() → Optional[str][source]

The filename stem to give to Namespace output files if emitted or None if there was none specified and there is no target language.

Returns:A file name stem or None
get_target_language() → Optional[nunavut.lang.Language][source]

Returns the target language configured on this object or None if no target language was specified.

filter_id_for_target(instance: Any, id_type: str = 'any') → str[source]

A filter that will transform a given string or pydsdl identifier into a valid identifier in the target language. A default transformation is applied if no target language is set.

Parameters:
  • instance (any) – Any object or data that either has a name property or can be converted to a string.
  • id_type (str) – A type of identifier. This is different for each language. Use ‘any’ to apply stropping rules for all identifier types to the instance.
Returns:

A token that is a valid identifier in the target language, is not a reserved keyword, and is transformed in a deterministic manner based on the provided instance.

get_supported_languages() → Dict[str, nunavut.lang.Language][source]

Returns a collection of available language support objects.

config