Marquee sample: add README.md, add test_viewer

test_viewer makes same output as test_graphics, but uses pmv so it is shorter
also regenerate files in fsmpy/ and svg/

Author: jon-jacky

samples/Marquee/README.md

@@ -4,13 +4,20 @@ Marquee
 This sample models a marquee with one line of text scrolling from
 right to left.
 
-- *Marquee*: model program, defines *Load* and *Shift*,
-   but only includes *Shift* in the *actions*.  Initializes
-   model state *display* with uninteresting text.
+This sample demonstrates how the size and structure of the data affect
+the number of states, how a configuration file can augment or replace
+items in the model, and how composition with a scenario machine can
+restrict the behavior of a model.
+
+- *Marquee*: model program, defines *Load* and *Shift*, but only
+   includes *Shift* in the *actions*.  Initializes model state
+   *display* with uninteresting text, a pattern of two characters
+   repeated thirteen times: _'* * * * * * * * * * * * * '_
+
+- *DisplayFive*: configuration, redefines *actions* to also include *Load*,
+  defines *domains* for *Load* with slightly more interesting text,
+  a *pattern* of five characters repeated five times: *'Bye  Bye  Bye  Bye  Bye  '*
 
-- *DisplayFive*: configuration, redefines *actions* to include *Load*,
-  defines domain for *Load* with more interesting *pattern* argument.
-   
 - *LoadFirst*: scenario machine, forces the *Load* action to execute
   just once at the beginning of the run.
 
@@ -22,7 +29,37 @@ right to left.
    appear on the command line in different orders (to show that
    doesn't matter).
 
-- *fsmpy*, *svg*: directories of output files from *test_graphics*
+- *test_viewer*: Generate the same output as *test_graphics*, but this
+  script is shorter because it uses *pmv* instead of *pma* + *pmg* +
+  *dot*
+
+- *fsmpy*, *svg*: directories of output files from *test_graphics* or
+   *test_viewer*
+
+You can view the generated *.svg* files in a browser.  Hover the 
+pointer over any state bubble to see a tooltip that shows the marquee
+display in that state.
+
+- *MarqueeFSM*: the repeating *display* pattern with just two
+  characters results in two states.  Only *Select* is enabled.
+
+- *DisplayFiveFSM*: here *Marquee* imports *DisplayFive*.  The
+  repeating *pattern* with five characters results in five states.
+  *Load* is enabled in every state.
+
+- *LoadFirst*: graph of the scenario machine, shows how the *Load* action 
+  executes just once at the beginning of the run.
+
+- *PeriodFiveFSM*: compare to *DisplayFiveFSM*.  Here *Marquee* is
+   composed with *LoadFirst, so *Load* only executes once at the
+   beginning.
+
+- *DisplayFiveFSM1*, *PeriodFiveFSM1*, *PeriodFiveFSM2*: same as
+   *DisplayFiveFSM* and *PeriodFiveFSM*, but modules appear on the *pma*
+   (or *pmv*) command line in different order, to show that order
+   doesn't matter.  In particular, the configuration module
+   *DisplayFive* can appear on the command line before or after
+   *Marquee*, the model program it imports.
 
 There is no stepper in this sample.
 

samples/Marquee/fsmpy/DisplayFiveFSM.py

@@ -1,5 +1,5 @@
 
-# pma.py DisplayFive Marquee
+# pma.py --maxTransitions 100 DisplayFive Marquee
 # 7 states, 14 transitions, 7 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/fsmpy/DisplayFiveFSM1.py

@@ -1,5 +1,5 @@
 
-# pma.py -o DisplayFiveFSM1 Marquee DisplayFive
+# pma.py --maxTransitions 100 --output DisplayFiveFSM1 Marquee DisplayFive
 # 7 states, 14 transitions, 7 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/fsmpy/LoadFirstFSM.py

@@ -0,0 +1,32 @@
+
+# pma.py --maxTransitions 100 LoadFirst
+# 2 states, 2 transitions, 2 accepting states, 0 unsafe states, 0 finished and 0 deadend states
+
+# actions here are just labels, but must be symbols with __name__ attribute
+
+def Load(): pass
+def Shift(): pass
+
+# states, key of each state here is its number in graph etc. below
+
+states = {
+  0 : {'LoadFirst': 0},
+  1 : {'LoadFirst': 1},
+}
+
+# initial state, accepting states, unsafe states, frontier states, deadend states
+
+initial = 0
+accepting = [0, 1]
+unsafe = []
+frontier = []
+finished = []
+deadend = []
+runstarts = [0]
+
+# finite state machine, list of tuples: (current, (action, args, result), next)
+
+graph = (
+  (0, (Load, (), None), 1),
+  (1, (Shift, (), None), 1),
+)

samples/Marquee/fsmpy/MarqueeFSM.py

@@ -1,5 +1,5 @@
 
-# pma.py Marquee
+# pma.py --maxTransitions 100 Marquee
 # 2 states, 2 transitions, 2 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/fsmpy/PeriodFiveFSM.py

@@ -1,5 +1,5 @@
 
-# pma.py -o PeriodFiveFSM Marquee DisplayFive LoadFirst
+# pma.py --maxTransitions 100 --output PeriodFiveFSM Marquee DisplayFive LoadFirst
 # 6 states, 6 transitions, 6 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/fsmpy/PeriodFiveFSM1.py

@@ -1,5 +1,5 @@
 
-# pma.py -o PeriodFiveFSM1 LoadFirst Marquee DisplayFive
+# pma.py --maxTransitions 100 --output PeriodFiveFSM1 LoadFirst Marquee DisplayFive
 # 6 states, 6 transitions, 6 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/fsmpy/PeriodFiveFSM2.py

@@ -1,5 +1,5 @@
 
-# pma.py -o PeriodFiveFSM2 DisplayFive Marquee LoadFirst
+# pma.py --maxTransitions 100 --output PeriodFiveFSM2 DisplayFive Marquee LoadFirst
 # 6 states, 6 transitions, 6 accepting states, 0 unsafe states, 0 finished and 0 deadend states
 
 # actions here are just labels, but must be symbols with __name__ attribute

samples/Marquee/svg/LoadFirstFSM.svg

@@ -4,8 +4,8 @@
 
 cases = [
     ('One run',
-     'pmt.py Marquee -n 10'),
+     'pmt Marquee -n 10'),
 
     ('Request two runs, but no Reset function, so only one run executes',
-     'pmt.py Marquee -n 10 -r 2')
+     'pmt Marquee -n 10 -r 2')
 ]