model-lang/docs/overview.md

what is modellang?

modellang is an event modeling language built with ease of use and flexibility in mind. The driving concept behind this is the separation of model description into two distinct parts: behaviors and interactions. To wit, let us describe a model where one task sends messages and another task will then receieve them:

SYSTEM: task_a = send*;
SYSTEM: task_b = receive*;

INTERACTION: task_a:send -> task_b:receive;

modellang is not just an ergonomic language, though. Its trace generator is able to simulate all possible scenarios of a model within a small scope, producing a queryable set of results (known as event traces).

language

A modellang model is composed of systems of behaviors, interactions between the systems, and triggers that control properties.

A system is a top-level event, and is where trace generation starts. Can consist of composite events (behaviors) or atomic events.

SYSTEM: sys = behavior_pattern atomic_event;
BEHAVIOR: behavior_pattern = expanded detail;

An interaction defines a relation between two or more systems, and optionally enforce conditional requirements:

• the two relations supported are:
  • a -> b (then) - orders events such that the traces will always result in a, then b
  • a == b (join) - joins systems together in the traces by treating a and b as the same event
• conditions can be attached by including a { code block } before or after a selector
  • { /* condition */ } system:thing (pre) - executes before the event; if it returns false, the event is not inserted
  • system:thing { /* condition */ } (post) - executes after the event and its triggers; if it returns false, the event is removed and the branch is pruned

• selectors (also found in triggers) are patterns just like system and behavior definitions, but come with a prepended system: to inform the generator where to look for the pattern

  INTERACTION: sys:before -> other_sys:after;
  INTERACTION: sys:shared_event == other_sys:shared_event;
  INTERACTION: { property > 5 } thing:happens_above_5 -> other_thing:stays_above_two { other_property >= 3 };
  

A trigger is a chunk of code that will execute whenever the specified selector pattern occurs during trace generation.

WHEN: sys:event1 event2 { property++ };

Behavior patterns are the way in which events are described.

SYSTEM: sequence = a whitespace delimited list of events occurring in order;
SYSTEM: group = you can even (wrap stuff into groups);
SYSTEM: alternation = a (pipe | vertical bar | stick) delimited list of sequences;
BEHAVIOR: quantifiers = none_or_more* one_or_more+ none_or_one?;
BEHAVIOR: ranges = do_exactly_n_times{n} do_at_least_n_times{n,} do_n_to_m{n,m};

An init establishes the initial state of the model or a system through a code block.

INIT: { initial_property = 5 };
INIT: system_a { SYSTEM.initial_property = 9001 };

Whitespace is insignificant.
Comments are C-style.

code blocks

In their current form, the code blocks found in modellang are embedded JavaScript. They have access to different variables depending on what construct they are being used in.

Conditionals are lambdas that do not have access to any special scope except MODEL
Inits have access to MODEL, and SYSTEM if a system is specified
Triggers have access to MODEL, SYSTEM, PREVIOUS, THIS

MODEL: contains information about the systems in the model
SYSTEM: contains information about the events in the current system
PREVIOUS: a reference to the previous node in the event trace
THIS: a reference to the current node in the event trace