Common classes

This section contains the description of classes that are commonly used by other classes.

SwanItem class

The SwanItem is the top-level class for all constructs.

class ansys.scadeone.core.swan.SwanItem

Base class for Scade objects.

get_full_path() → str

Full path of Swan construct.

static set_owner(owner: Self, children: Self | Iterable[Self])

Helper to set owner as the owner of each item in the Iterable items.

Parameters:

ownerSwanItem

Owner of the items.

childrenUnion[SwanItem, Iterable[SwanItem]]

Items to set owner.

property is_protected: bool

Tell if a construct item is syntactically protected with some markup and is stored as a string (without the markup).

property model: Model

Return model containing the Swan item.

property module: ModuleBase

Module containing the item.

Returns:

ModuleBase: module container, see ModuleBody and ModuleInterface

property owner: Self

Owner of current Swan construct.

Identifier classes

Swan identifiers are represented by the following classes with a simple identifier or a path identifier, which is a list of identifiers separated by ‘::’.

A luid is used to identify diagram blocks, connections, but also to name instances of operators, or parts of automata.

class ansys.scadeone.core.swan.Identifier(value: str, pragmas: List[Pragma] | None = None, comment: str | None = None, is_name: bool | None = False)

Bases: SwanItem, PragmaBase

Class for identifier.

An Identifier can be invalid if it was protected while saving it for some reason. In that case, the property _is_valid_ is set to True.

The class stores the pragmas associated with the Identifier.

get_full_path() → str

Full path of Swan construct.

pragma_str() → str

Return a string with all pragmas.

static set_owner(owner: Self, children: Self | Iterable[Self])

Helper to set owner as the owner of each item in the Iterable items.

Parameters:

ownerSwanItem

Owner of the items.

childrenUnion[SwanItem, Iterable[SwanItem]]

Items to set owner.

property comment: str

Comment part string.

property is_name: bool

Return true when Identifier is a name.

property is_protected: bool

Return true when Identifier is protected.

property is_valid: bool

Return true when Identifier is valid.

property model: Model

Return model containing the Swan item.

property module: ModuleBase

Module containing the item.

Returns:

ModuleBase: module container, see ModuleBody and ModuleInterface

property owner: Self

Owner of current Swan construct.

property pragmas: List[Pragma]

List of pragmas.

property value: str

Identifier as a string.

class ansys.scadeone.core.swan.PathIdentifier(path_id: List[Identifier] | str)

Bases: SwanItem

Class for path identifiers, i.e: P1::Id.

The class manipulates the PathIdentifier as separate items.

If the original path was protected (given as a string), the property is_valid is False, and the path is considered to be a single string and is_protected is True.

path_id argument is:

• a list of identifiers, for a valid path.

• a string if the path was protected.

static from_string(path: str) → PathIdentifier

Create a PathIdentifier from a string.

Parameters:

pathstr

String containing the path identifier.

Returns:

PathIdentifier

PathIdentifier instance.

get_full_path() → str

Full path of Swan construct.

classmethod is_valid_file_path(path: str) → bool

Check if path is a valid file path identifier, i.e. id {- id}, with no possible spaces around ‘-‘.

The path string is the basename of a module or an instance file.

Parameters:

pathstr

String containing the path identifier.

Returns:

bool

True when path is valid.

classmethod is_valid_path(path: str) → bool

Check if path is a valid path identifier, i.e. id {:: id}, with possible spaces around ‘::’.

Parameters:

pathstr

String containing the path identifier.

Returns:

bool

True when path is valid.

static set_owner(owner: Self, children: Self | Iterable[Self])

Helper to set owner as the owner of each item in the Iterable items.

Parameters:

ownerSwanItem

Owner of the items.

childrenUnion[SwanItem, Iterable[SwanItem]]

Items to set owner.

static split(path: str) → Tuple[str, str]

Split a path into path::name.

Parameters:

pathstr

Path string.

Returns:

Tuple[str, str]

path, name.

property as_string: str

Compute name by joining name parts with ‘::’.

property is_protected: bool

True when path is from a protected source, i.e., a string.

property is_valid: bool

True when path is a sequence of Identifier.

property model: Model

Return model containing the Swan item.

property module: ModuleBase

Module containing the item.

Returns:

ModuleBase: module container, see ModuleBody and ModuleInterface

property owner: Self

Owner of current Swan construct.

property path_id: List[Identifier] | str

PathId as a list of Identifier, or a string if protected.

property pragmas: List[Pragma]

List of Pragma associated with the path_id.

class ansys.scadeone.core.swan.Luid(value: str)

Bases: SwanItem

Class for LUID support. The ‘$’ prefix is not saved (potentially removed at creation).

as_luid() → str

Luid value with ‘$ prefix.

get_full_path() → str

Full path of Swan construct.

static is_valid(luid: str) → bool

True when a luid is a valid LUID.

static set_owner(owner: Self, children: Self | Iterable[Self])

Helper to set owner as the owner of each item in the Iterable items.

Parameters:

ownerSwanItem

Owner of the items.

childrenUnion[SwanItem, Iterable[SwanItem]]

Items to set owner.

property is_protected: bool

Tell if a construct item is syntactically protected with some markup and is stored as a string (without the markup).

property model: Model

Return model containing the Swan item.

property module: ModuleBase

Module containing the item.

Returns:

ModuleBase: module container, see ModuleBody and ModuleInterface

property owner: Self

Owner of current Swan construct.

property value: str

Luid value.

Pragma class

The Pragma stores a pragma information given in the code.

class ansys.scadeone.core.swan.Pragma(pragma: str)

Bases: object

Stores a pragma.

extract() → dict | None

Extract pragma information as a tuple if pragma is valid, namely: #pragma key value#end.

Returns:

tuple | None

The Tuple (pragma name, pragma value) if pragma is valid, None else.

static filter(pragmas: List[Pragma], key: str, with_key: bool = True) → List[Pragma]

Filter a list of pragmas with/without a given key.

Parameters:

pragmasList[Pragma]

List of pragmas

keystr

Key to filter

with_keybool, optional

True when pragmas with the key are selected, False when without the key, by default True

Returns:

List[Pragma]

List of pragmas with the given key.

property pragma: str

Full pragma string

Returns:

str

Pragma string

Protection class

User code may be syntactically incorrect in a model, but must be saved and read without errors by the parser. Such invalid code is protected by markups. Other markups are used by the serialization mechanism of the editor.

Such piece of code is represented with a ProtectedItem (or derived class) instance, which stores the code text and the markup.

class ansys.scadeone.core.swan.ProtectedItem(data: str, markup: str | None = 'syntax')

Bases: SwanItem

Base class for protected data. A protected data is a piece of Swan code enclosed between markups, mostly to store syntactically incorrect code. A protected data is enclosed within the pair {markup% .. %markup}, where markup is defined by the regular expression: [‘a’-‘z’ ‘A’-‘Z’ 0-9 _]*.

See Markup for existing markups.

get_full_path() → str

Full path of Swan construct.

has_markup(markup: str) → bool

Check if protected data has the specified markup.

Parameters:

markupstr

String markup.

Returns:

result: bool

True when instance markup is same as parameter.

static set_owner(owner: Self, children: Self | Iterable[Self])

Helper to set owner as the owner of each item in the Iterable items.

Parameters:

ownerSwanItem

Owner of the items.

childrenUnion[SwanItem, Iterable[SwanItem]]

Items to set owner.

property data: str

Protected data between markups.

Returns:

str

Protected data.

property is_protected

Tell if item is syntactically protected and provided as a string.

property markup: str

Protection markup.

Returns:

str

Markup string.

property model: Model

Return model containing the Swan item.

property module: ModuleBase

Module containing the item.

Returns:

ModuleBase: module container, see ModuleBody and ModuleInterface

property owner: Self

Owner of current Swan construct.

class ansys.scadeone.core.swan.Markup

Bases: object

Class defining the markups used by the Swan serialization.

static to_str(text: str, is_protected: bool = True, markup: str | None = None) → str

Return text as the protected string {markup%text%markup} if required.

Parameters:

textstr

Text to protect

is_protectedbool, optional

True when text shall be protected, by default True

markupstr, optional

Markup to use, by default None, resulting in using Markup.Syntax

Returns:

str

Protected string {markup%text%markup} if is_protected is True, else text.

Const = 'const'

Incorrect const declaration.

Dim = 'dim'

Incorrect forward dimension.

Empty = 'empty'

Empty instance block body. This is an invalid construct, but it is needed for the editor.

Group = 'group'

Incorrect group declaration.

Luid = 'luid'

Protected instance id.

OpExpr = 'op_expr'

Operator expression. Specific markup for the editor. The content is re-parsed by the API.

Sensor = 'sensor'

Incorrect sensor declaration.

Signature = 'signature'

Incorrect operator signature in interface.

Syntax = 'syntax'

General syntax error.

SyntaxText = 'syntax_text'

Textual operator with syntax error.

Text = 'text'

Textual operator or generic operator content. The content is re-parsed by the API.

Type = 'type'

Incorrect type declaration.

Use = 'use'

Incorrect use declaration.

Var = 'var'

Incorrect variable declaration.

Miscellaneous

The following class is a helper for Swan literal expressions.

class ansys.scadeone.core.swan.SwanRE

Bases: object

Container of compiled regular expressions. These expressions can be matched with some strings. Some regular expressions use groups to extract parts.

Attributes:

TypedInteger: regular expressions for integers with post type (_i, _ui).

Integer part is in the value group, type in the type group, and size in the size group.

TypeFloat: regular expression for floats with post type (_f).

Mantissa is in the mantissa group, exponent in the exp group, type in the type group, and size in the size group.

classmethod is_bool(string: str) → bool

Check whether a string is a Swan boolean value.

Parameters:

stringstr

String to check.

Returns:

bool

True if string is a Swan char value

classmethod is_char(string: str) → bool

Check whether a string is a Swan char value.

Parameters:

stringstr

String to check.

Returns:

bool

True if string is a Swan char value.

classmethod is_float(string: str) → bool

Check whether a string is a Swan integer.

Parameters:

stringstr

Integer value, as decimal, bin, octal, or hexadecimal, with or without type information.

Returns:

bool

True when string is an integer.

classmethod is_integer(string: str) → bool

Check whether a string is a Swan integer.

Parameters:

stringstr

Integer value, as decimal, bin, octal, or hexadecimal, with or without type information.

Returns:

bool

True when string is an integer.

classmethod is_numeric(string: str) → bool

Check whether a string is a Swan numeric value, that is, an integer of float value.

Parameters:

stringstr

String to check.

Returns:

bool

True if string is a Swan numeric value.

classmethod parse_float(string: str, minus: bool = False) → FloatTuple | None

Match a string representing a float and return a description of that float as a FloatTuple.

Parameters:

stringstr

String representing a float, with or without type information.

minusbool

True when the value is preceded with a ‘-’ minus operator.

Returns:

FloatTuple or None

If the string value matches SwanRE.TypedFloat pattern, a FloatTuple is returned. It is a namedtuple with fields:

• value: computed value

• mantissa: the mantissa part

• exp: the exponent part

• size: the size part

Note: if there is no type information, type is _f32.

classmethod parse_integer(string: str, minus: bool = False) → IntegerTuple | None

Match a string representing an integer and returns a description of that integer as an IntegerTuple.

Parameters:

stringstr

String representing an integer, with or without type information.

minusbool

True when the value is preceded with a ‘-’ minus operator.

Returns:

IntegerTuple or None

If the string value matches SwanRE.TypedInteger pattern, an IntegerTuple is returned. It is a namedtuple with fields:

• value: computed value

• is_bin, is_oct, is_hex, is_dec: flags set according to found type

• is_signed: True when integer is signed

• size: the size part

Note: if there is no type information, type is _i32.