Update the state machine specification for do actions as lists

docs/spec/State-Machine-Behavior-Elements/Do-Expressions.adoc

@@ -0,0 +1,45 @@
+=== Do Expressions
+
+An *do expression* specifies a list of actions as part of an
+<<State-Machine-Behavior-Elements_Initial-Transition-Specifiers,initial transition>>,
+a <<State-Machine-Behavior-Elements_State-Transition-Specifiers,state transition>>,
+a <<State-Machine-Behavior-Elements_State-Entry-Specifiers,state entry>>,
+a <<State-Machine-Behavior-Elements_State-Exit-Specifiers,state exit>>,
+or
+a <<State-Machine-Behavior-Elements_Junction-Definitions,junction>>.
+
+==== Syntax
+
+`do` {_action-sequence_}
+
+_action-sequence_ is an
+<<Element-Sequences,element sequence>> in
+which each element is an <<Lexical-Elements_Identifiers,_identifier_>>
+and the terminating punctuation is a comma.
+
+==== Semantics
+. The _action-sequence_ after the keyword `do` must
+<<Definitions_State-Machine-Definitions_Scoping-of-Names,refer>>
+to a list of 
+<<State-Machine-Behavior-Elements_Action-Definitions,action definitions>>.
+
+==== Examples
+
+[source,fpp]
+----
+state machine Device {
+
+  action powerActuator
+  action powerGyro
+  action powerGimbal
+
+  state ON {
+    enter do {
+      powerActuator
+      powerGyro
+      powerGimbal
+    }
+  }
+
+}
+----

docs/spec/State-Machine-Behavior-Elements/Enter-Expressions.adoc

@@ -11,17 +11,13 @@ some action.
 ==== Syntax
 
 _[_
-`do` <<Lexical-Elements_Identifiers,_identifier_>>
+<<State-Machine-Behavior-Elements_Do-Expressions,_do-expression_>>
 _]_
 `enter` <<Scoping-of-Names_Qualified-Identifiers,_qual-ident_>>
 
-==== Semantics
 
-. If present, the optional identifier after the keyword `do` must
-<<Definitions_State-Machine-Definitions_Scoping-of-Names,refer>>
-to an 
-<<State-Machine-Behavior-Elements_Action-Definitions,action definition>>.
-It specifies an action to perform when making the transition.
+==== Semantics
+. If present, the _do-expression_ specifies the list of actions to be performed
 
 . The qualified identifier after the keyword `enter` must
 <<Definitions_State-Machine-Definitions_Scoping-of-Names,refer>>
@@ -37,19 +33,17 @@ It is the state or junction that is entered.
 ----
 state machine Device {
 
-  signal PowerOn
-
-  action getReady
-
-  guard initComplete
+  action initDev1
+  action initDev2
 
-  initial enter OFF
-
-  state OFF {
-    on PowerOn if initComplete do getReady enter ON
+  initial do {
+    initDev1
+    initDev2
   }
+  enter OFF
 
-  state ON
+  state OFF {
 
+  }
 }
 ----

docs/spec/State-Machine-Behavior-Elements/Initial-Transition-Specifiers.adoc

@@ -26,15 +26,20 @@ transition specifier appears.
 ----
 state machine Device {
 
-  action initDevices
+  action initDev1
+  action initDev2
 
   # When the state machine starts up, enter the ON state
   initial enter ON
 
   state ON {
 
     # When entering the ON state, enter the POWERING_UP substate
-    initial do initDevices enter POWERING_UP
+    initial do {
+      initDev1
+      initDev2
+    }
+    enter POWERING_UP
 
     state POWERING_UP
 

docs/spec/State-Machine-Behavior-Elements/Junction-Definitions.adoc

@@ -42,7 +42,10 @@ state machine Device {
 
   junction J1 {
     if coldStart enter OFF \
-    else do initPower enter ON
+    else do {
+      initPower
+    } 
+    enter ON
   }
 
   state OFF

docs/spec/State-Machine-Behavior-Elements/State-Definitions.adoc

@@ -23,6 +23,8 @@ A state definition member is one of the following:
 * A <<State-Machine-Behavior-Elements_Junction-Definitions,junction definition>>
 * A <<State-Machine-Behavior-Elements_State-Definitions,state definition>>
 * A <<State-Machine-Behavior-Elements_State-Transition-Specifiers,state transition specifier>>
+* A <<State-Machine-Behavior-Elements_State-Entry-Specifiers,state entry specifier>>
+* A <<State-Machine-Behavior-Elements_State-Exit-Specifiers,state exit specifier>>
 
 ==== Semantics
 
@@ -56,37 +58,65 @@ state machine MonitorSm {
   signal Stop
   signal Fault
 
+  action init1
   action init2
   action doCalibrate
   action motorControl
   action reportFault
+  action heaterOff
+  action monitorOff
+  action heaterOn
+  action monitorOn
+  action stopMotor
 
   guard calibrateReady
 
   initial enter DEVICE_ON
 
   state DEVICE_ON {
 
-    initial do init2 enter INITIALIZING
+    initial do {
+      init1
+      init2
+     } 
+     enter INITIALIZING
 
     state INITIALIZING {
       on Complete enter IDLE
     }
 
     state IDLE {
+      entry do {
+        heaterOff
+        monitorOff
+      }
+      exit do {
+        heaterOn
+        monitorOn
+      }
       on Drive enter DRIVING
       on Calibrate if calibrateReady enter CALIBRATING
     }
 
     state CALIBRATING {
-      on RTI do doCalibrate
-      on Fault do reportFault enter Idle
+      on RTI do {
+        doCalibrate
+      }
+      on Fault do {
+        reportFault
+       }
+      enter Idle
       on Complete enter IDLE
     }
 
     state DRIVING {
-      on RTI do motorControl
-      on Stop enter IDLE
+      on RTI do {
+        motorControl
+      }
+      on Stop do {
+        stopMotor
+      }
+      enter IDLE
     }
 
   }

docs/spec/State-Machine-Behavior-Elements/State-Entry-Specifiers.adoc

@@ -0,0 +1,31 @@
+=== State Entry Specifiers
+
+A *state entry specifier* is part of a
+<<State-Machine-Behavior-Elements_State-Definitions,state definition>>.
+It specifies the state's entry actions
+
+==== Syntax
+
+`entry` <<State-Machine-Behavior-Elements_Do-Expressions,_do-expression_>>
+
+==== Semantics
+
+. The _do-expression_ specifies a list of entry actions that get executed
+when entering a state
+
+==== Examples
+
+[source,fpp]
+----
+state machine Device {
+
+  action heaterOn
+  action monitorOn
+
+  state RUNNING {
+    entry do {
+      heaterOn
+      monitorOn
+    }
+}
+----

docs/spec/State-Machine-Behavior-Elements/State-Exit-Specifiers.adoc

@@ -0,0 +1,31 @@
+=== State Exit Specifiers
+
+A *state exit specifier* is part of a
+<<State-Machine-Behavior-Elements_State-Definitions,state definition>>.
+It specifies the state's exit actions
+
+==== Syntax
+
+`exit` <<State-Machine-Behavior-Elements_Do-Expressions,_do-expression_>>
+
+==== Semantics
+
+. The _do-expression_ specifies a list of exit actions that get executed
+when exiting a state
+
+==== Examples
+
+[source,fpp]
+----
+state machine Device {
+
+  action heaterOff
+  action monitorOff
+
+  state RUNNING {
+    exit do {
+      heaterOff
+      monitorOff
+    }
+}
+----

docs/spec/State-Machine-Behavior-Elements/State-Transition-Specifiers.adoc

@@ -16,11 +16,16 @@ _enter-or-do_ is one of the following:
 
 .  <<State-Machine-Behavior-Elements_Enter-Expressions,_enter-expression_>>
 
-.  `do` <<Lexical-Elements_Identifiers,_identifier_>>
+.  <<State-Machine-Behavior-Elements_Do-Expressions,_do-expression_>>
+
+_action-sequence_ is an
+<<Element-Sequences,element sequence>> in
+which each element is an <<Lexical-Elements_Identifiers,_identifier_>>
+and the terminating punctuation is a comma.
 
 ==== Semantics
 
-. The identifier after the keyword `on` must
+. The _identifier_ after the keyword `on` must
 <<Definitions_State-Machine-Definitions_Scoping-of-Names,refer>>
 to a
 <<State-Machine-Behavior-Elements_Signal-Definitions,signal definition>>.
@@ -40,13 +45,13 @@ When making a self transition, the state machine runs the code associated with
 exiting and then re-entering the state.
 
 . Second form of the syntax specifies an
-*internal transition*, i.e., an action to take while remaining
+*internal transition*, i.e., a list of actions to take while remaining
 in the same state.
 When making an internal transition, the exit and re-entry code is not run.
-The identifier after the keyword `do` must
+The list of actions specified in the _do-expression) must
 <<Definitions_State-Machine-Definitions_Scoping-of-Names,refer>>
-to an
-<<State-Machine-Behavior-Elements_Action-Definitions,action definition>>.
+to a list of 
+<<State-Machine-Behavior-Elements_Action-Definitions,action definitions>>.
 
 ==== Examples
 
@@ -58,14 +63,19 @@ state machine Device {
   signal PowerOn
 
   action performStuff
-  action getReady
+  action powerHeater
+  action powerSensor
 
   guard initComplete
 
   initial enter OFF
 
   state OFF {
-    on PowerOn if initComplete do getReady enter ON
+    on PowerOn if initComplete do {
+      powerHeater
+      powerSensor
+    }
+    enter ON
   }
 
   state ON {

docs/spec/State-Machine-Behavior-Elements/defs.sh

@@ -9,11 +9,14 @@ redo-ifchange defs.sh
 export FILES="
 Introduction.adoc
 Action-Definitions.adoc
+Do-Expressions.adoc
 Enter-Expressions.adoc
 Guard-Definitions.adoc
 Initial-Transition-Specifiers.adoc
 Junction-Definitions.adoc
 Signal-Definitions.adoc
 State-Definitions.adoc
+State-Entry-Specifiers.adoc
+State-Exit-Specifiers.adoc
 State-Transition-Specifiers.adoc
 "