Skip to content

Syntax: Annotations and Pragmas

Jump to bottom
Alexander SR edited this page May 25, 2022 · 13 revisions

Annotations

The textual SCCharts language supports several annotations to influence the visual representation of the model. Annotations are processed in sequential order.

@diagram[<key>] <value>

Usage Description Example

Location: scchart

<key>: The name of the synthesis option. The given name is evaluated case-insensitive and whitespace-ignoring. The options are searched for the first matching prefix.

<value>: The value type depends on the option type:

  • CheckBox: true or false
  • Choice: Name of choice item
  • Slider: Float value
 Sets the synthesis option identified by to the given value. The available synthesis options for a diagram are displayed in the sidebar of the diagram view. The values from the sidebar will be ignored if a corresponding annotation is present.

Commonly Used:

  • initiallycollapseregions: Collapses all regions. Very helpful for lager models, since it fastens initial diagram rendering.
 
@diagram[paper] true
scchart Testing {
  initial state A
  --> B;
  final state B;
}

@layout[<key>] <value>

Usage Description Example

Location: scchart, state, region, transition

<key>: The ID of the layout option. The options are searched for the first matching postfix.

<value>: The value type depends on the option type. The value is parsed case-sensitive.

 Sets the layout property identified by to the given value on the annotated element.

The available layout options are documented here.

Layout options will only affect the annotated element and no underlying hierarchy levels.

If a layout direction is specified with this annotation it overrides the layout direction set by HV-/VH-Layout in any parent element for this element.

Special case: If the direction is set on the scchart element (top level) it overrides the default alternating layout.

The layout option is identified by matching a postfix. Hence the key direction matches both org.eclipse.elk.direction and org.eclipse.elk.layered.priority.direction. If none or multiple options match a warning is displayed.

Commonly Used:

  • elk.direction: Layout direction
  • elk.priority: Influences the order of regions
 
scchart Testing {
    @layout[algorithm]
          org.eclipse.elk.graphviz.circo
    region:
    initial final state A
    --> B;
    state B
    --> C;
    state C
    --> A;
}

scchart Testing {
    @layout[elk.direction] UP
    region "up":
    initial state A
    --> B;
    final state B;
    @layout[elk.direction] LEFT
    region "left":
    initial state A
    --> B;
    final state B;
}

@HVLayout, @VHLayout

Usage Description Example

Location: scchart, state, region

 Defines the order of the alternating layout directions.

The annotation can be mixed and nested in the SCChart and will only affect succeeding hierarchy levels.

The default is an implicit HVLayout starting at the top level state.

 
@VHLayout
scchart Testing {
  initial state A
    go to B;
  final state B;
}

@collapse, @expand

Usage Description Example

Location: region

 The annotated region will be initially collapse or expanded. 
scchart Testing {
  @collapse  
  region {
    initial state A
      go to B;
    final state B;
  }
}

@hide

Usage Description Example

Location: scchart, state, region, transition

 The annotated element will be excluded from the diagram.

Transitions with a hidden source or target state will be hidden as well.

 
scchart Testing {
  initial state A
    go to B;
  @hide
  final state B;
}

Pragmas

Pragmas are annotations that are valid for the whole file in contrast to annotations that are valid for semantic model elements. They are placed in front of an .sctx.

Example

#pragma
scchart Testing {
  ...
}
Pragma Effect
#KiCoEnv {<json>} Configures the compiler environment.

#hostcode <code>

#hostcode-[c | c-header | java] <code>

Allows hostcode additions that are placed at the beginning of the generated code file. The exact handling may depend on the used code generator.

There are also language specific variants that will only affect the specific code generation, e.g. #hostcode-java.
#code.naming

Configures the code generation to use different names for generated functions.

#code.naming <TICK_FUNCTION_NAME>, <RESET_FUNCTION_NAME>, <LOGIC_FUNCTION_NAME>, <TICKDATA_STRUCT_NAME>
Sets the name for the four functions. All four parameters must be present.

#code.naming suffix
#code.naming prefix
Code generation will use default function names but will prefix/suffix these names with the model name.
#resource <file |  directory>

The given resources (single files or directories) will be copied to the generated code folder (usually kieler-gen). Since this is the working directory for the compilation KIELER these files can be included via hostcode integration.
If the compilation contains any down-stream compiler invocation (e.g. gcc) all given files and all files in given directories that match the usual source code file extension (e.g. *.c) will be included in the compilation and compile into an executable with the generated code.

All non-absolute paths will be resolved relative to the model file.

Example 
#resource "myheader.h"
#resource "mycode.c"
#hostcode "#include \"myheader.h\""
scchart Testing {
  ...
}
#HideImportedSCCharts

This will hide all SCCharts that are imported from other files in the diagram, if the 'All SCCharts' synthesis option is activated.

KIELER is an open source software project by the RTSYS Group at Kiel University, licensed under the Eclipse Public License or Eclipse Public License 2.0 | KIELER Mailing List

General:

Syntax references:

For KIELER Developers:

Clone this wiki locally