Textual Notation

Loading a Model

In Syside, a model is represented using Model class. It can be loaded using try_load_model or load_model functions, which take a list of KerML and SysML v2 files as input and return a tuple of Model and Diagnostics instances:

model, diagnostics = syside.load_model(paths)

Note

Files can be collected using collect_files_recursively function, which collects all files in a directory recursively.

Additionally, models can be loaded directly from source strings:

model, diagnostics = syside.load_model(sysml_source="package P;")

model, diagnostics = syside.load_model(kerml_source="package P;")

The key difference between load_model and try_load_model is that the former raises a ModelError exception if the model contains errors, or warnings with warnings_as_errors=True, while the latter produces some model even for files with errors. Both functions return a Diagnostics object containing the errors, warnings, and informational messages found when loading the model. Diagnostic is modelled after LSP Diagnostic.

Additionally, models can be loaded with different Environments which are used as model dependencies. If an Environment is not provided, it defaults to the bundled standard library environment. Other models can be used as dependencies:

dependent_model, diagnostics = syside.load_model(
    sysml_source="private import P;",
    environment=syside.Environment.from_documents(
        model.all_docs, model.index
    ),
)

For details on model structure, see Model Structure. For low-level details, see Low-Level API.

Exporting

A SysML model rooted at element can be printed with syside.pprint(element), or with

cfg = syside.PrinterConfig()  # optional
options = syside.conf.FormatOptions()  # optional
# change format options here
printer = syside.ModelPrinter.sysml(format=options)  # optional
text: str = syside.pprint(element, printer=printer, config=cfg)

where

  • PrinterConfig controls the text formatting options.

  • FormatOptions controls the textual syntax output options. Both KerML and SysML have multiple ways to write the same models, therefore it contains a lot of configuration options. By default, the options are set to preserve the original source text formatting but can be overridden, e.g. replace all redefines with :>> by setting options.declaration_redefinition.preserve to False and options.declaration_redefinition.fallback to KwToken.Token.

  • ModelPrinter converts model elements into the textual syntax. kerml and sysml static methods are used to select the output language of the printer.

  • pprint converts element into the textual syntax in a single function.

If exporting multiple models back into the textual syntax, prefer reusing ModelPrinter for best performance. Note that pprint has some limitations, see its documentation.

S-expressions

S-expressions can be used to quickly print the model structure to a simple text format. This is most useful for debugging that the model has the expected structure.

print(syside.sexp(element, print_references=True))

See sexp for more details. Note that print_references is available from Syside v0.6.4, and prints the referenced but not owned element strings for non-owning binary relationships.