From b2b6003a8feec30490bf77daa2519afec187e438 Mon Sep 17 00:00:00 2001
From: Galin Simeonov <gts@volconst.com>
Date: Mon, 27 Sep 2021 22:53:48 +0300
Subject: added an english specification

---
 doc/en.txt | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 doc/en.txt

(limited to 'doc/en.txt')

diff --git a/doc/en.txt b/doc/en.txt
new file mode 100644
index 0000000..95f1f91
--- /dev/null
+++ b/doc/en.txt
@@ -0,0 +1,84 @@
+MEGATRON transpiler for a language describing automatas
+
+Here is a description of the language
+
+
+
+Things encased with "" are to be taken literally, things encased in [] are optional,
+things encased with () are grouped and are to be taken as a unit,
+things encased in {} can appear zero or more times and things encased in {}+ can appear one
+or more times
+
+Syntax:
+	<program> := { <machine definition> }+
+
+	<machine definition> := <id> "[" <machine internals> "]" ";"
+
+	<machine internals> := { <states definition> ";" | <events definition> ";" | <transitions definition> ";" \
+								| "starting" "on" <id> ";" }
+
+	<states definition> := "states" "[" { <id> [ "on" "entering" <execute statement> ] \
+	       	[ "on" "exiting" <execute statement> ] }+ "]"
+
+	<events definition> := "events" "[" { <id> }+ "]"	
+	<transitions definition> := "transitions" "[" { <transition> ";" }+ "]"
+	<transition> := "from" <id> "to" <id> "on" "event" <id> [ <granted statement> ] [ <if statement> ] ";"
+
+	<if statement> := <execute statement>
+	<if statement> := "if" "(" <expression> ")" <if statement> [ "else" <if statement> ]
+
+	<granted statement> := "granted" "(" <expression> ")" 
+
+	<execute statement> := "execute" <pipeline>
+	<pipeline> := <id> [ <string> ] [ "|" <pipeline> ]
+
+	<primary expression> := <id> "." <id> | "(" <expression> ")" 
+	<not expression> := "!" <not expression> | <primary expression> 
+	<and expression> := <not expression> "&&" <and expression>
+	<or expression> := <and expression> "||" <or expression>
+	<expression> := <or expression>
+
+Constraints:
+	The name of each machine id shall be unique in a program.
+
+	The order of the machine declarations do not matter to the constraint checks.
+
+	In the internals of each machine there will be exactly one states definition, events definition, transitions
+	definition and starting state declaration.
+
+	State ids shall not have duplicates in the same machine they are defined, meaning you could have a state
+	id appear in two machines.
+
+	Event ids shall not have duplicates across all machines, meaning you can not have an event id appear in
+	two machines at the same time in the same program. The same goes with machine ids.
+
+	Event ids, machine ids and pipeline ids share a namespace, meaning you can not have an id that is both 
+	a machine id and an event id at the same time or a pipeline id that is a machine id.
+
+	Let a primary expression be in the form <id> "." <id>. The first id shall be a machine id and the second
+	a state id that belongs to the denoted machine.
+
+	Transition ids shall be state id belonging to the machine the transitions declaration apears in.
+
+	The first id in a transition shall not appear as the first id in another transition in the same
+	transition definition. Meaning you can not have multiple transitions stemming from the same state.
+
+Semantics:
+	A program describes a set of possibly interdependant automata that execute external code upon certain conditions.
+
+	A machine is always in a single state, starting on the starting state.
+
+	The outside environment can pass events to any machine. The machine switches states and executes 
+	external functions. The events are processed in the order they arrive.
+
+	If no transition can take an event, the event is dropped.
+	A transition of states occurs if there is no granted part to the transition.
+	If there is a granted part of the transition then the expression in the granted part must evaluate to 1
+	otherwise the transition does not occur and the event is dropped.
+
+	If a transition occurs then and only then is the conditional execution of external functions executed.
+	Meaning that the if does not go off if the granted statement fails.
+
+	A primary expression in the form <id> "." <id> evaluates to 1 if the machine with the first id 
+	is currently in the state with the second id, otherwise it evaluates to 0. For example M.a is 1
+	if the machine 'M' is in the state 'a'.
-- 
cgit v1.2.3