Browse Source

MPIDE-25: document high-level concepts and syntax

Added an overview.md to the docs to cover the conceptual and syntactical
part of the language. Gives simple, brief examples.
Austin Meagher 10 years ago
parent
commit
e803ed86c9
1 changed files with 53 additions and 0 deletions
  1. 53 0
      docs/overview.md

+ 53 - 0
docs/overview.md

@@ -0,0 +1,53 @@
+# 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.
+
+## 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_pattern1 behavior_pattern2;
+BEHAVIOR: behavior_pattern1 = expanded detail;
+```
+
+An **interaction** can fall into one of three categories: relations. pre-conditions, and post-conditions:
+- the two relations supported are "->" (order) and "==" (join)
+- pre- and post-conditions guarantee your resultant traces abide by certain rules
+
+```
+INTERACTION: sys:before -> other_sys:after;
+INTERACTION: sys:shared_event == other_sys:shared_event;
+INTERACTION: property > 5 -> thing:happens_only_above_5;
+INTERACTION: thing:never_drops_below_three -> other_property >= 3;
+```
+
+A **trigger** is a chunk of code that will execute whenever a specified 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};
+```  
+Notes on patterns:
+- alternations operate on sequences and groups, not individual events, so `a b c | d e | f` would separate into `a b c`, `d e`, and `f`
+
+**Whitespace** is insignificant.  
+**Comments** are C-style.