2.4 Checks
The library checks texts in three steps. Each problem it finds is a diagnostic: a range of the text, a severity, a code and a message. The code names the kind of problem and stays the same across versions, while the message may change. An error means the text is wrong. A warning means the text is accepted but very likely does not do what was meant.
2.4.1 What is checked when#
The reader of a language parses a text and reports its syntax errors. The parser recovers from an error and reads on, so one text may show several syntax errors.
The reader then checks the text on its own: the KMeta reader the types, the KModel reader the objects against the metamodel, and the KStates reader the states, transitions and macros of the state machine. Where a syntax error may have cost the reader part of the text, it leaves out the checks that would report what the lost part might hold. A text with a syntax error therefore gets no report of an unknown state or macro in KStates, of an unknown target type or a missing type in KMeta, or of a knows to a missing object in KModel.
The verifier checks the state machines of a project against the domain metamodel, the event metamodel and the model: paths, operations, values, macro calls, events in scope, the states that can be reached, the names of the attachable state machines that behaves after, ATTACH and EXCHANGE use, and the compositions of fragments. It reports its problems in the text of the state machine they concern, and the problems of behaves after in the text of the metamodel. It leaves out a state machine with a syntax error, and each of its checks needs the texts it relies on without errors: the checks of types a domain metamodel without errors, the checks of event fields an event metamodel without errors, the checks of values a model without errors and the object the state machine runs on, and the checks of states and events a state machine whose state names are unique and known.
The IDE shows the problems of the readers and of the verifier, see 4.4 Validating. From code, the readers and the verifier are called as 2.5 Using the library shows.
2.4.2 Syntax#
These codes are the same in every language.
| Code | Severity | Meaning | Example |
|---|---|---|---|
syntax.unrecognized-input | error | The text holds characters that start nothing the language knows. The reader skips them. | type 'Bulb' "A bulb" { } in KMeta, which has no single quotes |
syntax.error | error | A word or sign stands where the language does not allow it, or a required one is missing. | type "Bulb" { }, which lacks the description |
reader.failure | error | The reader failed and read nothing, for example on states or objects nested deeper than the parser can follow. |
2.4.3 KMeta#
| Code | Severity | Meaning | Example |
|---|---|---|---|
kmeta.no-types | error | The text defines no type, so the metamodel has no root type. | a text that holds only comments |
kmeta.unknown-property-type | error | A prop names a type other than string, number and boolean. | prop("watts", "Number") |
kmeta.unknown-target-type | error | A has or knows names a type that the metamodel does not define. | has("bulb", "Bulb") without a type Bulb |
kmeta.duplicate-type | error | A type has the name of an earlier type. Reported at the later name. | two types "Bulb" |
kmeta.duplicate-key | error | A type uses a key twice, for properties, relations or both. Reported at the later key. | prop("watts", "number") and prop("watts", "string") in one type |
2.4.4 KModel#
The examples are read against the lamp metamodel of 2 Modeling languages.
| Code | Severity | Meaning | Example |
|---|---|---|---|
kmodel.unknown-class-type | error | An object is of a type that the metamodel does not define. | make object "lamp":"Lantern" { } |
kmodel.unknown-property | error | A prop names a property that the type of its object does not define. | prop("color") -> "red" in a bulb |
kmodel.unknown-relation | error | A has or knows names a relation that the type of its object does not define. | knows("room") -> "living room" in a lamp |
kmodel.wrong-relation-kind | error | A has names a knows relation, or a knows names a has relation. | knows("bulb") -> "bulb" in a lamp |
kmodel.invalid-number | error | A number property gets a value that is not a number. The value is left out. | prop("watts") -> "forty" |
kmodel.invalid-boolean | error | A boolean property gets a value other than true or false in any case. The value reads as false. | prop("lit") -> "yes" |
kmodel.several-values | error | A property or relation that is not a list gets several values. Reported at each further statement. | prop("watts") -> "20" and prop("watts") -> "40" in one bulb |
kmodel.duplicate-id | error | An object has the key of an earlier object, embedded objects included. Reported at the later key. | two objects "lamp" |
kmodel.unresolved-reference | error | A knows names a key that no object has. | knows("control") -> "kitchenSwitch" |
kmodel.reference-type-mismatch | error | A knows names an object of another type than the relation declares. | knows("control") -> "bulb" in the lamp |
kmodel.embedded-type-mismatch | warning | A has embeds an object of another type than the relation declares. | has("bulb") -> make object "s":"Switch" { } |
2.4.5 KStates#
The examples are parts of a state machine attached to Lamp.
| Code | Severity | Meaning | Example |
|---|---|---|---|
kstates.initial-state-count | error | No state or more than one state is marked INITIAL. | STATES { STATE "off" { } STATE "on" { } } |
kstates.action-arity | error | An action rule has another number of operands than its operation takes. | SET("mode") |
kstates.tick-count | error | A DELAY or TIMEOUT counts its ticks with a number that is not whole. The part is left out. | DELAY: 2.5 TICKS |
kstates.feature-off | error | A construct of an optional feature that is switched off, see 2.3.10 Optional features. | SHALLOW HISTORY STATE "on" while histories are off |
kstates.duplicate-state | error | A state has the name of an earlier state, at any depth. Reported at the later name. | STATE "on" { STATE "on" { } } |
kstates.unknown-state | error | A transition, split, join or timeout names a state that does not exist. | TRANSITION "off" -> "dimmed" { } without a state dimmed |
kstates.repeated-split-target | error | A split names the same target twice. | SPLIT "off" -> "on", "on" { } |
kstates.repeated-join-source | error | A join names the same source twice. | JOIN "on", "on" -> "off" { } |
kstates.duplicate-macro | error | A macro has the name of an earlier macro. The runtime only calls the earlier one. | two macros "half" |
kstates.duplicate-parameter | error | A macro takes two parameters of the same name. | TAKES("w", "number") twice in one macro |
kstates.unknown-macro | error | A MACRO(...) call, or an @name(...) call in EVAL code, names a macro that does not exist. | MACRO("half", "bulb->maxWatts") without a macro half |
kstates.macro-argument-count | error | A MACRO(...) call passes more arguments than the macro takes, or an @name(...) call passes another number. | @half(1, 2) for a macro with one TAKES |
kstates.missing-macro-arguments | warning | A MACRO(...) call passes fewer arguments than the macro takes. The runtime reads each missing one from the path named like its parameter. | MACRO("half") for a macro with one TAKES |
kstates.several-event-clauses | error | A condition has more than one EVENT clause. The runtime only matches the first. | CONDITION { EVENT("switch", "press") EVENT("switch", "dim") } |
kstates.event-clause-not-first | warning | An EVENT clause is not the first clause of its condition. The runtime finds it in any place, but it reads better first. | CONDITION { VALUE("bulb->lit") EVENT("switch", "press") } |
kstates.history-without-inner-states | warning | A state without inner states has a history. | SHALLOW HISTORY STATE "off" { } |
kstates.empty-breakpoint | warning | A BREAKPOINT block marks nothing. | BREAKPOINT { } |
kstates.empty-tick-limit | warning | A TICK LIMIT block has neither a DELAY nor a TIMEOUT. | TICK LIMIT { } |
kstates.delay-beyond-timeout | warning | A DELAY is longer than the TIMEOUT of its block, so the timeout fires only after the delay. | TICK LIMIT { DELAY: 5 TICKS TIMEOUT: AFTER 2 TICKS TRANSITION TO "off" } |
kstates.comment-in-eval | warning | EVAL code holds // outside a string literal, which starts a KStates comment, so a closing brace after it on its line does not count. | return $(bulb->watts) // 2 in an EVAL |
kstates.eval-without-return | warning | EVAL code has no return, so it yields no value. | EVAL { $(bulb->maxWatts) } |
kstates.missing-state-machine-name | error | An attachable state machine or a fragment has no name. Reported at ATTACHABLE or FRAGMENT, or at the empty string for an empty name. | STATEMACHINE ATTACHABLE TO "Bulb" |
kstates.attached-header | error | A state machine ATTACHED TO a type has a name or a second type. Reported at each. | STATEMACHINE "lamp" ATTACHED TO "Lamp" |
kstates.repeated-attachable-type | error | An attachable state machine lists a type twice. Reported at the later one. | STATEMACHINE "glowing" ATTACHABLE TO "Bulb", "Bulb" |
kstates.container-use | error | A CONTAINER STATE lacks USE "fragment", reported at CONTAINER, or uses an empty name, reported at the empty string, or another state has a USE, reported at USE. | CONTAINER STATE "self test" { } |
kstates.container-state-content | error | A container state has an ENTRY or DO block or inner states. Reported at each. | CONTAINER STATE "self test" USE "bulb test" { ENTRY { SET("mode", "test") } } |
kstates.final-state-content | error | A final state is INITIAL, has a history, or holds more than a BREAKPOINT block. Reported at each. | FINAL STATE "passed" { TICK LIMIT { DELAY: 2 TICKS } } |
kstates.misplaced-final-state | error | A final state stands in a state machine that is no fragment, or inside another state of a fragment. Reported at its name. | FINAL STATE "done" { } in the lamp |
kstates.fragment-without-final-state | error | A fragment has no final state at its top level. Reported at STATES. | a fragment with only INITIAL STATE "powered" { } |
kstates.transition-from-final-state | error | A transition, split or join leaves a final state. Reported at its name. | TRANSITION "passed" -> "powered" { } |
kstates.misplaced-done | error | DONE stands on a TRANSITION or SPLIT whose source is no container state, or on a JOIN of which no source is a container state. Reported at DONE. | TRANSITION "off" -> "on" { CONDITION { DONE } } |
kstates.fragment-uses-itself | error | A container state of a fragment uses the fragment itself. Reported at the name after USE. | CONTAINER STATE "again" USE "bulb test" { } in bulb test |
A header without a type after TO is a syntax error, and so is ATTACH after any rule other than SETOBJ and APPENDOBJ.
The checks of names and calls are left out for a text with a syntax error: kstates.unknown-state, kstates.unknown-macro, kstates.macro-argument-count and kstates.missing-macro-arguments. So is the count of initial states when the STATES block has a syntax error.
A text that is a fragment or has a container state may call a macro that another file of its composition defines, so the reader reports no kstates.unknown-macro there and does not count the arguments of such a call; the verifier checks these calls against the whole composition. A container state with a history gets no kstates.history-without-inner-states, since its inner states come from its fragment. kstates.misplaced-done is left out while a source of the transition names no state, and kstates.fragment-without-final-state while the STATES block has a syntax error.
2.4.6 Project#
The verifier reports these problems. The examples are parts of a state machine attached to Lamp in a project with the lamp metamodel and the lamp model of 2 Modeling languages, and with a macro half that takes a number.
| Code | Severity | Meaning | Example |
|---|---|---|---|
project.unknown-attached-type | error | The domain metamodel defines no type of the name after ATTACHED TO, or of a name after ATTACHABLE TO, which is reported at that name. | STATEMACHINE ATTACHED TO "Lantern" |
project.attached-object-type | error | The model has no object of the key the state machine runs on, or that object is of another type than the state machine is attached to. | the lamp state machine run on "wallSwitch" |
project.unknown-path | error | The path of an action rule or of a VALUE condition leads nowhere. | SET("bulb->color", "red") |
project.operation-mismatch | error | An operation does not fit what its path leads to, see 2.4.6.2 Operations. | APPEND("mode", "on") |
project.literal-mismatch | error | The string value of a SET, APPEND or SETLIST cannot be read as the type of its property. | SET("bulb->watts", "bright") |
project.unresolved-code-reference | error | A $(path) in EVAL code leads nowhere. | EVAL { return $(bulb->power) } |
project.unknown-macro-type | error | A TAKES or RETURNS names no primitive type, no domain type and no event type, or uses a function other than list and reference. | TAKES("w", "Watt") |
project.unresolved-macro-argument | error | An argument of a MACRO(...) call leads nowhere. | MACRO("half", "bulb->power") |
project.macro-argument-type | error | An argument of a MACRO(...) call leads to a value of another type than its parameter takes. | MACRO("half", "mode") |
project.unknown-event-field | error | event->... reads a field that no event that can be in scope there carries, or the event metamodel does not declare the event. | VALUE("event->level") after EVENT("switch", "dim") |
project.unreachable-state | warning | A state can never be active. Only the outermost of such states is reported. | a state that no transition leads into |
project.shadowed-transition | warning | An earlier transition from the same state has no condition and no NOT LOOPING, so it always fires first and this one never fires. | TRANSITION "off" -> "on" { } before another transition from off |
project.join-never-fires | warning | No split leads to branches in which each source of the join is active in a branch of its own. | JOIN "full", "dimmed" -> "off" { } without a split into them |
project.split-inside-parallel | warning | The source of a split is active only inside a branch of a split, where no split fires. | a split from a target of another split |
project.event-not-in-scope | warning | Code or a condition reads event where no event can be in scope. | $(event->bright) in the initial state |
project.unset-property | warning | The model gives the object the state machine runs on no value on the way of a read, and no action of the project writes any key of the path. | $(bulb->lit) when the model gives the bulb no lit and no action sets it |
project.duplicate-state-machine-name | error | Two named state machines of the project, attachable ones or fragments, have the same name. Reported at the name in each. | two files with STATEMACHINE "glowing" ATTACHABLE TO ... |
project.unknown-state-machine | error | A behaves after, an ATTACH or an EXCHANGE names, as a string, no attachable state machine of the project. | EXCHANGE("bulb", "flashing") without a state machine flashing |
project.attachable-type-mismatch | error | A behaves after, an ATTACH or an EXCHANGE names a state machine that does not list the type of the object in question. | EXCHANGE("bulb", "keeper") when keeper is attachable to Room only |
project.attach-on-knows | error | ATTACH follows a SETOBJ or APPENDOBJ on a knows relation, which links an existing object instead of creating one. Reported at the clause. | SETOBJ("self", "control", "switch") ATTACH "pressing" |
project.behaves-after-in-events | error | A type of the event metamodel has behaves after. Reported at the clause, in the event metamodel. | type "press" "A press" behaves after "glowing" { } |
project.attached-fragment | error | A behaves after, an ATTACH or an EXCHANGE names a fragment, which only a container state runs. Reported at the name. | EXCHANGE("bulb", "bulb test") |
project.unknown-fragment | error | A container state uses a name that no fragment of the project has. Reported at the name after USE. | CONTAINER STATE "self test" USE "bulb tset" { } |
project.not-a-fragment | error | A container state uses a state machine that is no fragment. Reported at the name after USE. | CONTAINER STATE "self test" USE "glowing" { } |
project.fragment-cycle | error | A fragment contains itself through other fragments. Reported once, at the name after USE of the container state that closes the cycle. | bulb test uses wiring test, which uses bulb test |
project.qualified-name-clash | error | A flattened name equals another state name of the composition. Reported at the later state. | a state "self test/powered" next to the container state self test |
project.conflicting-macros | error | Two files of a composition define macros of the same name with different definitions. Reported at the later macro. | half in the lamp and another half in the bulb test |
project.unknown-macro | error | A call in a fragment, or in a file with a container state, names a macro that no file of the composition defines. Reported at the call, and only if every state machine of the project could be read. | MACRO("third", "bulb->maxWatts") in the bulb test |
project.macro-from-other-file | warning | A call names a macro that only another file of the composition defines. Reported at the call. | MACRO("half", "bulb->maxWatts") in a fragment without a macro half |
kstates.macro-argument-count | error | A call of a macro that only another file of the composition defines passes a number of arguments the macro does not take, by the rule of the reader. The composition does not flatten. Reported at the call. | MACRO("half", "bulb->maxWatts", "bulb->power") in a fragment without a macro half |
2.4.6.1 Paths#
The verifier follows a path key by key, the way the runtime follows it. Each key names a relation or a property of the type reached so far. A path goes on from the first object of a list relation, but not from a property. In the code of a macro, a path cannot go on from a list. A path starts at a binding of a WITH block if it starts with its name, at the event in scope if it starts with event, in the code of a macro at a parameter if it starts with its name, and otherwise at the object the state machine runs on.
The paths of IF IN SCOPE blocks are never reported. A path inside such a block that starts with one of its paths, or with event if one of its paths does, is not reported as leading nowhere.
2.4.6.2 Operations#
SET needs a property that is not a list. APPEND, SETLIST and DROPLIST need a list property. On a relation, the message names the relation operation to use instead. SETOBJ needs a relation that holds one object and APPENDOBJ a list relation. A string target of either must be a path to one object of the type of the relation, and only a knows relation may take it, since a has relation takes a new object. DROPOBJ and EXCHANGE need a path to one object. A VALUE condition needs a boolean or a string property that is not a list.
2.4.6.3 Events and states#
An event comes into scope at the target of the transition or split whose EVENT clause matched it, and stays while that state is active. The code of a state sees the events of the transitions into the state, into a state around it and into a state inside it. The conditions of a transition see the event of their own EVENT clause, or else the events in scope in the state the transition starts in. The conditions of a join see none.
A state is reachable if a transition, split, join or timeout leads into it, or into a state inside it, from the initial state. Every condition counts as possibly true. A transition into a state enters none of its inner states.
2.4.6.4 Attachment#
An attachable state machine runs on objects of each type it lists, so the verifier checks the paths and operations of such a state machine once for each type. A problem found for every type is reported once, as it is. A problem found for some types only names the type in front of its message, as in For type 'Dimmer': Type 'Dimmer' has no property or relation 'lit'.
The names that behaves after, ATTACH and EXCHANGE use are checked only where they are written as strings; a name that an EVAL or a MACRO computes is checked by the runtime when the action runs. The type an ATTACH is checked against is the type of its relation, and the type an EXCHANGE is checked against is the type of the object its path leads to; EXCHANGE needs a path to one object, like DROPOBJ. A name that no attachable state machine has is not reported while a state machine of the project has a syntax error, since that state machine might carry the name. The behaves after clauses are checked in a domain metamodel without syntax errors.
2.4.6.5 Pages#
The verifier flattens each state machine of the project that is no fragment with the fragments of the project, the same way the runtime does, see 2.3.12 Pages. A problem that prevents the flattening is reported in the text where it stands, a fragment included. A problem the reader of that text reports already, such as a fragment that uses itself, is not repeated. project.unknown-fragment is not reported while a state machine of the project has a syntax error, since that state machine might be the fragment.
The other checks of the project then run on the flattened state machine, so the content of a fragment is checked where it runs, with the type of the state machine that uses it. A problem inside a fragment is reported in the text of the fragment, once for each place however often the fragment is used. A state of a fragment is reachable when the container state that uses it is, through the start path of the fragment and its transitions.
A composition that does not flatten is checked as the single state machine it starts from, as written. A fragment that no state machine uses is checked on its own, as far as it can be without the type of a host: its states and transitions, the fragments it uses and its macro calls. A fragment that a state machine uses, but whose compositions do not flatten, is checked on its own as well, without its macro calls, which may rely on the macros of the state machine that uses it.