Project creation#

This section provides the elements for creating or modifying a Scade One project. An example is provided in Create a Scade One project.

Best practices#

Constructing a Scade One project can be a complex task. The following best practices are recommended:

Create objects in the order of their dependencies. For example, create a module before creating its declarations.
Create a use directive before adding objects from other modules to its module. For instance, if a constant is created in a module, that constant cannot be used in another module unless the proper directive is created first. In the consumer module, the identifier of the constant depends on the use directive.

Project creation#

Following ScadeOne method is used for creation:

ScadeOne.new_project(project_path: str | Path) → Project#

Create a new project.

Parameters:

project_pathUnion[str, Path]: Project location.

Returns:

Project: Project object.

property ScadeOne.version: str#: API version.

Resource creation#

Resource files can be added to a project and used on it. For more information about resources, see Resources.

For simulation data creation or edition, see Simulation data.

Following Project methods are used for managing resources:

Project.add_resource(kind: ResourceKind, file_path: Path | str, key_name: str | None = None, exist_check: bool = True) → Resource#

Add a new resource to the project. For simulation data files (ResourceKind.SIMULATION_DATA), key_name must be provided.

Parameters:

kindResourceKind: Kind of the resource.
file_pathUnion[Path, str]: Path to the resource file.
key_nameOptional[str]: Key of the resource (for simulation data only).
exist_checkbool: Checks if file exists, raises exception if not. Default True. Can be disabled for debugging or placeholder use.

Returns:

Resource: The created resource object.

Raises:

ScadeOneException: If the resource file does not exist and exist_check is True. If the key name is already used in the project. If the file path is already in the project resources.

Dependencies management#

Following Project methods are used for managing dependencies:

Project.add_dependency(project: IProject) → None#

Add a project as a dependency.

Parameters:

projectIProject: Project to add as a dependency.

Raises:

ScadeOneException: If the project is the same as the current project.

Project.remove_dependency(project: IProject) → None#

Remove a project from the dependencies.

Parameters:

projectIProject: Project to remove from the dependencies.

Raises:

ScadeOneException: If the project is not a dependency.

Module body and interface creation#

A module body or a module interface can be created from a model or a project. When added to a project, the module body or interface is automatically added to the model and its source is updated with respect to the project path.

Following Model methods are used for creation:

Model.add_body(swan_elt: ModuleBody) → None#

Add a module body to the model.

Parameters:

swan_eltswan.ModuleBody: Content of the module body

Model.add_interface(swan_elt: ModuleInterface) → None#

Add a module interface to the model.

Parameters:

swan_eltswan.ModuleInterface: Content of the module interface

Following Project methods are used for creation:

Project.add_module_body(name: str) → ModuleBody#

Create a module body and add it to the model.

Parameters:

name: str: Module name.

Returns:

Module: Module object.

Project.add_module_interface(name: str) → ModuleInterface#

Create a module interface and add it to the model.

Parameters:

name: str: Module name.

Returns:

ModuleInterface: ModuleInterface object.

Module declarations#

Following ModuleBody and ModuleInterface methods are used for creation:

Any declaration#

Add a declaration of any kind.

ModuleBodyCreator.add_declaration(decl_expr: str) → common.Declaration#

Add a declaration to the module.

Parameters:

decl_expr: str: Declaration expression.

Returns:

Declaration: Declaration object.

Use directive creation#

ModuleBodyCreator.use(module: swan.Module | str, alias: str = None) → swan.UseDirective#

Add a use directive to the module.

Parameters:

module: Module: Module name.
alias: str: Module alias.

Returns:

UseDirective: UseDirective object.

Constant and sensor declarations#

ModuleBodyCreator.add_constant(name: str, type_str: str, value: str) → swan.ConstDecl#

Add a constant to the module.

Parameters:

name: str: Constant name.
type_str: str: Constant type.
value: str: Constant value.

Returns:

ConstDecl: Constant object.

ModuleBodyCreator.add_sensor(name: str, type_str: str) → swan.SensorDecl#

Add a sensor to the module.

Parameters:

name: str: Sensor name.
type_str: str: Sensor type.

Returns:

SensorDecl: Sensor object.

Type creation#

ModuleBodyCreator.add_enum(name: str, values: List[str]) → swan.TypeDecl#

Add an enum to the module.

Parameters:

name: str: Enum name.
values: List[str]: Enum values.

Returns:

TypeDecl: Type object.

ModuleBodyCreator.add_struct(name: str, fields: dict[str, str]) → swan.TypeDecl#

Add a struct to the module.

Parameters:

name: str: Struct name.
fields: dict[str, str]: Struct fields (name, type).

Returns:

TypeDecl: Type object.

ModuleBodyCreator.add_group(name: str, types: str | List[str] | dict[str, str]) → swan.GroupDecl#

Add a group to the module.

Parameters:

name: str: Group name.
types: Union[str, List[str], dict[str, str]]: List of types (type or {name: type}).

Returns:

GroupDecl: Group object.

ModuleBodyCreator.add_type(name: str, type_str: str) → swan.TypeDecl#

Add a type to the module.

Parameters:

name: str: Type name.
type_str: str: Type definition as a string.

Returns:

TypeDecl: Type object.

Operator creation#

ModuleBodyCreator.add_operator_definition(name: str, is_node: bool = True, is_inlined: bool = False) → swan.OperatorDefinition#

Add an operator definition to the module body or the test module.

Parameters:

name: str: Operator name.
is_node: bool: True if Node, otherwise Function.
is_inlined: bool: True if inline operator.

Returns:

Operator: Operator definition object.

ModuleBodyCreator.add_operator_declaration(name: str, is_node: bool = True, is_inlined: bool = False) → swan.OperatorDeclaration#

Add an operator declaration to the module.

Parameters:

name: str: Operator name.
is_node: bool: True if Node, otherwise Function.
is_inlined: bool: True if inline operator.

Returns:

OperatorDeclaration: Operator declaration object.

ModuleBodyCreator.add_textual_operator_definition(operator_str: str) → swan.OperatorDefinition#

Add a textual operator definition to the module body.

Parameters:

operator_str: str: Operator string.

Returns:

Operator: Operator definition object.

ModuleBodyCreator.add_textual_operator_declaration(operator_str: str) → swan.OperatorDeclaration#

Add a textual operator declaration to the module.

Parameters:

operator_str: str: Operator string.

Returns:

OperatorDeclaration: Operator declaration object.

Operator content creation#

Following OperatorDefinition methods are used for creation:

Add an input to the operator declaration. Input can be defined by name, type, … or by a text declaration.

Parameters:

name: str: Input name.
input type: str or Declaration: Input type. It could be a text declaration or a Declaration object.
is_probe: bool: Probe variable.
default: str: Default value.
last: str: Last value.
declaration: str: Text declaration.

Returns:

VarDecl: Variable object.

Add an output to the operator declaration. Output can be defined by name, type, … or by a text declaration.

Parameters:

name: str: Variable name.
output_type: str or Declaration: Output type. It could be a text declaration or a Declaration object.
is_probe: bool: Probe variable.
default: str: Default value.
last: str: Last value.
declaration: str: Textual declaration.

Returns:

VarDecl: Variable object.

OperatorDefinition.add_diagram() → swan.Diagram#

Add a diagram to the operator definition.

Returns:

Diagram: Diagram object.

Equation content creation#

Equations are grouped in a let section. For more information about LetSection, see Equations.

Following LetSection methods are used for creation:

LetCreator.add_automaton(name: str | None = None, lhs: list[swan.LHSItem | str] | None = None, is_partial: bool = False) → swan.StateMachine#

Create and add an automaton as equation of the LetSection.

Parameters:

namestr, optional: The optional name of the automaton to create.
lhsList[swan.LHSItem | str] | None, optional: List of LHS (left-hand side) items or None. Can be provided as string list for convenience.
is_partialbool, optional: Flag indicating whether the LHS equation is partial or complete. Default is False.

Returns:

StateMachine: The created automaton.

LetCreator.remove_automaton(name: str) → None#

Remove by name an automaton from the LetSection.

Parameters:

namestr: The name of the automaton to remove.

Raises:

ValueError: If the automaton name is not defined.

Diagram content creation#

Following Diagram methods are used for creation:

DiagramCreator.add_block(instance: swan.OperatorDefinition) → swan.Block#

Add an operator call to the operator.

Parameters:

instance: OperatorDefinition: OperatorDefinition instance.

Returns:

Block: Block object.

DiagramCreator.add_def_block(variable: swan.VarDecl) → swan.DefBlock#

Add a definition block to the operator.

Parameters:

variable: VarDecl: Local, input or output variable.

Returns:

DefBlock: DefBlock object.

DiagramCreator.add_expr_block(declaration: swan.Declaration) → swan.ExprBlock#

Add an expression block to the operator.

Parameters:

declaration: Declaration: Local or output variable.

Returns:

ExprBlock: ExprBlock object.

DiagramCreator.add_bar() → swan.Bar#

Add a bar to the operator.

Returns:

Bar: Bar object.

DiagramCreator.add_automaton(name: str) → swan.StateMachine#

Add an automaton to the operator diagram.

Parameters:

namestr: Automaton name.

Returns:

StateMachine: The created state machine instance.

DiagramCreator.connect(source: swan.DiagramObject | tuple[swan.DiagramObject, str], targets: swan.DiagramObject | tuple[swan.DiagramObject, str] | List[swan.DiagramObject] | List[tuple[swan.DiagramObject, str]]) → swan.Wire#

Connect a block to one or more blocks.

Parameters:

source: DiagramObject: Block object.
targets: Union[DiagramObject, List[DiagramObject]]: A block object or a list of block objects.

Returns:

Wire: Wire object that connects the blocks.

State machine creation#

Following StateMachine methods are used for creation:

StateMachineCreator.add_state(name: str, is_initial: bool = False, is_default: bool = False) → swan.State#

Add a state to the state machine.

Parameters:

namestr: The name of the state.
is_initialOptional[bool], optional: Whether the state is an initial state, by default False.
is_defaultOptional[bool], optional: Whether the state is a default state, by default False.

Returns:

State: The created state.

StateMachineCreator.add_weak_transition(source: swan.State, target: swan.State, priority: int | None = None, guard: swan.Expression | str = 'true', action: swan.Scope | str | None = None) → swan.Transition#

Add a weak transition between states.

The created transition declaration is added to StateMachine.transition_decls property of the state machine.

Parameters:

sourceswan.State: The state from which the transition starts.
targetswan.State: The state to which the transition goes.
priorityOptional[int], optional: The transition priority when several transitions have the same source state.
guardUnion[swan.Expression | str], optional: Expression representing the guard condition. Can be either a swan.Expression or a string. Default value is the swan.BooleanLiteral true.
actionOptional[swan.Scope | str], optional: Expression representing the action to trigger. Can be either a swan.Scope or a string.

Returns:

Transition: The created transition.

StateMachineCreator.add_strong_transition(source: swan.State, target: swan.State, priority: int | None = None, guard: swan.Expression | str = 'true', action: swan.Scope | str | None = None) → swan.Transition#

Add a strong transition between states.

The created transition declaration is added to StateMachine.transition_decls property of the state machine.

Parameters:

sourceswan.State: The state from which the transition starts.
targetswan.State: The state to which the transition goes.
priorityOptional[int], optional: The transition priority when several transitions have the same source state.
guardUnion[swan.Expression | str], optional: Expression representing the guard condition. Can be either a swan.Expression or a string. Default value is the swan.BooleanLiteral true.
actionOptional[swan.Scope | str], optional: Expression representing the action to trigger. Can be either a swan.Scope or a string.

Returns:

Transition: The created transition.

StateMachineCreator.remove_transition(transition: swan.Transition) → None#

Remove a transition from its owner.

Parameters:

transitionTransition: The transition to remove.

State content creation#

Following State methods are used for creation:

StateCreator.add_local_variable(name: str, var_type: str) → swan.VarDecl#

Add a local variable to the state’s diagram.

Parameters:

namestr: The name of the local variable.
var_typestr: The type of the local variable.

Returns:

LocalVariable: The created local variable.

StateCreator.add_section(section: str | swan.Scope) → None#

Add a section to the state.

Parameters:

sectionScope: The section to add to the state.

Transition content creation#

Following Transition methods are used for creation:

TransitionCreator.add_fork(guard: swan.Expression | str = 'true', action: swan.Scope | str | None = None) → tuple[swan.Fork, swan.Transition]#

Add a fork to the transition (either between two states or between a fork and a state).

The target of the transition is modified to point to the future fork. The returned fork is created with one default outgoing transition pointing to the original transition target. The outgoing transition type (strong or weak) is the same as the original transition type.

Parameters:

guardUnion[swan.Expression | str], optional: Expression representing the guard condition. Can be either a swan.Expression or a string. Default value is the swan.BooleanLiteral true.
actionOptional[swan.Section | str], optional: Expression representing the action to trigger. Can be either a swan.Section or a string.

Returns:

Fork, Transition: The created fork with one outgoing transition between the fork and the original transition target

Fork content creation#

Following Fork methods are used for creation:

ForkCreator.add_fork_transition(target: swan.State, priority: int, guard: swan.Expression | str = 'true', action: swan.Scope | str | None = None, is_resume: bool = False, is_else: bool = False) → swan.Transition#

Add a new transition starting from the fork to the state provided in argument.

The transition type (weak or strong) is the same as the incoming transition of the fork. To create an else branch transition, do not provide any guard condition, use parameter is_else=True and invoke this method last after creating all other fork transitions.

Parameters:

targetswan.State: The state to which the transition goes.
priorityint: The transition priority when several transitions have the same source fork.
guardUnion[swan.Expression | str], optional: Expression representing the guard condition. Can be either a swan.Expression or a string. Default value is the swan.BooleanLiteral true.
actionOptional[swan.Scope | str], optional: Expression representing the action to trigger. Can be either a swan.Scope or a string.
is_resumebool, optional: True if the transition is a resume transition, False for restart transition. Default is False.
is_elsebool, optional: True if the transition is an else branch transition, False otherwise. Default is False. Note that an else branch transition must not have any guard condition.

Returns:

Transition: The transition starting from the fork to the target state

Test creation#

Test module creation#

Module level:

TestModuleCreator.add_test_harness(name: str) → swan.TestHarness#

Add a test harness to the module.

Parameters:

name: str: Test harness name.

Returns:

TestHarness: Test harness object.

Test harness creation#

A harness contains a diagram.

TestHarness.add_diagram() → swan.Diagram#

Add a diagram to the operator definition.

Returns:

Diagram: Diagram object.

see Diagram content creation section.

Harness specific methods:

DiagramCreator.add_data_source(key: str) → swan.Block#

Add a data source.

Parameters:

key: str: Source key.

Returns:

Block: Block object.

DiagramCreator.add_oracle(key: str) → swan.Block#

Add an oracle block.

Parameters:

key: str: Oracle key.

Returns:

Block: Block object.

DiagramCreator.add_set_sensor(instance: swan.SensorDecl) → swan.SetSensorBlock#

Add a set sensor block to the diagram.

Parameters:

instance: SensorDecl: Sensor instance.

Returns:

SetSensorBlock: Set sensor block object.

DiagramCreator.add_instance_under_test(instance: swan.OperatorDefinition) → swan.Block#

Add an under test operator to the test harness.

Parameters:

instance: OperatorDefinition: Operator instance.

Returns:

Block: Block object.