Merge pull request #487 from StoneCypher/Doc_ListEdges_ListTransition…

…s_ListEntrances_ListExits Doc list edges list transitions list entrances list exits
StoneCypher · May 22, 2022 · e084bf4 · e084bf4
2 parents a7d9fba + b2558b2
commit e084bf4
Show file tree

Hide file tree

Showing 16 changed files with 601 additions and 161 deletions.
diff --git a/benchmark/results/general.chart.html b/benchmark/results/general.chart.html
@@ -28,7 +28,7 @@
   </head>
   <body>
     <div class="container">
-      <canvas id="chart1653257079920" width="16" height="9"></canvas>
+      <canvas id="chart1653259428897" width="16" height="9"></canvas>
     </div>
     <script>
       const format = (num) => {
@@ -51,18 +51,18 @@
           chunked.map((chunk) => chunk.join('')).join(' ') + fractionStr
         )
       }
-      const ctx1653257079920 = document
-        .getElementById('chart1653257079920')
+      const ctx1653259428897 = document
+        .getElementById('chart1653259428897')
         .getContext('2d')
-      const chart1653257079920 = new Chart(ctx1653257079920, {
+      const chart1653259428897 = new Chart(ctx1653259428897, {
         type: 'bar',
         data: {
           labels: ["Blind cycle a traffic light 500 times by transition","Blind cycle a traffic light 500 times by action","Blind cycle a basic-hooked traffic light 500 times by transition","Blind cycle a named-hooked traffic light 500 times by transition","Blind cycle an any-transition traffic light 500 times by transition","Blind cycle an exit hooked traffic light 500 times by transition","Blind cycle an enter hooked traffic light 500 times by transition","Blind cycle a standard-transition hooked light by transition","Blind cycle a main-transition hooked light by transition","Blind cycle a force-transition hooked light by transition","Blind cycle a traffic light 500 times by action","Blind cycle a basic-hooked traffic light 500 times by action","Blind cycle a named-hooked traffic light 500 times by action","Blind cycle an any-action traffic light 500 times by action","Blind cycle a global-action traffic light 500 times by action","Blind cycle an exit hooked traffic light 500 times by action","Blind cycle an enter hooked traffic light 500 times by action","Blind cycle a standard transition tl 500 times by action","Blind cycle a main transition tl 500 times by action","Blind cycle a forced transition tl 500 times by action","Kitchen Sink 500 times"],
           datasets: [
             {
-              data: [5740,11887,1378,6430,6154,5512,6030,6178,6149,28529,13667,1554,1383,10689,11135,9356,9591,66730,62427,68989,9307],
-              backgroundColor: ["hsl(9.983999999999991, 85%, 55%)","hsl(20.676000000000005, 85%, 55%)","hsl(2.4, 85%, 55%)","hsl(11.183999999999992, 85%, 55%)","hsl(10.704000000000002, 85%, 55%)","hsl(9.587999999999994, 85%, 55%)","hsl(10.487999999999994, 85%, 55%)","hsl(10.751999999999994, 85%, 55%)","hsl(10.691999999999997, 85%, 55%)","hsl(49.620000000000005, 85%, 55%)","hsl(23.772000000000002, 85%, 55%)","hsl(2.6999999999999997, 85%, 55%)","hsl(2.4, 85%, 55%)","hsl(18.587999999999994, 85%, 55%)","hsl(19.368000000000002, 85%, 55%)","hsl(16.272000000000002, 85%, 55%)","hsl(16.680000000000007, 85%, 55%)","hsl(116.07600000000001, 85%, 55%)","hsl(108.588, 85%, 55%)","hsl(120, 85%, 55%)","hsl(16.18799999999999, 85%, 55%)"],
-              borderColor: ["hsl(9.983999999999991, 85%, 55%)","hsl(20.676000000000005, 85%, 55%)","hsl(2.4, 85%, 55%)","hsl(11.183999999999992, 85%, 55%)","hsl(10.704000000000002, 85%, 55%)","hsl(9.587999999999994, 85%, 55%)","hsl(10.487999999999994, 85%, 55%)","hsl(10.751999999999994, 85%, 55%)","hsl(10.691999999999997, 85%, 55%)","hsl(49.620000000000005, 85%, 55%)","hsl(23.772000000000002, 85%, 55%)","hsl(2.6999999999999997, 85%, 55%)","hsl(2.4, 85%, 55%)","hsl(18.587999999999994, 85%, 55%)","hsl(19.368000000000002, 85%, 55%)","hsl(16.272000000000002, 85%, 55%)","hsl(16.680000000000007, 85%, 55%)","hsl(116.07600000000001, 85%, 55%)","hsl(108.588, 85%, 55%)","hsl(120, 85%, 55%)","hsl(16.18799999999999, 85%, 55%)"],
+              data: [32573,68310,6869,28116,24539,27922,26496,28325,29332,102621,69761,7706,7109,56396,55612,49902,49427,327884,327343,338499,45676],
+              backgroundColor: ["hsl(11.544000000000006, 85%, 55%)","hsl(24.216000000000008, 85%, 55%)","hsl(2.4360000000000017, 85%, 55%)","hsl(9.972000000000003, 85%, 55%)","hsl(8.7, 85%, 55%)","hsl(9.9, 85%, 55%)","hsl(9.395999999999997, 85%, 55%)","hsl(10.044000000000006, 85%, 55%)","hsl(10.404000000000002, 85%, 55%)","hsl(36.383999999999986, 85%, 55%)","hsl(24.732, 85%, 55%)","hsl(2.7360000000000015, 85%, 55%)","hsl(2.519999999999993, 85%, 55%)","hsl(19.991999999999997, 85%, 55%)","hsl(19.716000000000008, 85%, 55%)","hsl(17.687999999999995, 85%, 55%)","hsl(17.519999999999992, 85%, 55%)","hsl(116.232, 85%, 55%)","hsl(116.04, 85%, 55%)","hsl(120, 85%, 55%)","hsl(16.18799999999999, 85%, 55%)"],
+              borderColor: ["hsl(11.544000000000006, 85%, 55%)","hsl(24.216000000000008, 85%, 55%)","hsl(2.4360000000000017, 85%, 55%)","hsl(9.972000000000003, 85%, 55%)","hsl(8.7, 85%, 55%)","hsl(9.9, 85%, 55%)","hsl(9.395999999999997, 85%, 55%)","hsl(10.044000000000006, 85%, 55%)","hsl(10.404000000000002, 85%, 55%)","hsl(36.383999999999986, 85%, 55%)","hsl(24.732, 85%, 55%)","hsl(2.7360000000000015, 85%, 55%)","hsl(2.519999999999993, 85%, 55%)","hsl(19.991999999999997, 85%, 55%)","hsl(19.716000000000008, 85%, 55%)","hsl(17.687999999999995, 85%, 55%)","hsl(17.519999999999992, 85%, 55%)","hsl(116.232, 85%, 55%)","hsl(116.04, 85%, 55%)","hsl(120, 85%, 55%)","hsl(16.18799999999999, 85%, 55%)"],
               borderWidth: 2,
             },
           ],

diff --git a/benchmark/results/general.json b/benchmark/results/general.json
@@ -1,132 +1,132 @@
 {
   "name": "General performance suite",
-  "date": "2022-05-22T22:04:39.920Z",
+  "date": "2022-05-22T22:43:48.897Z",
   "version": "1.2.0",
   "results": [
     {
       "name": "Blind cycle a traffic light 500 times by transition",
-      "ops": 5740,
-      "margin": 2.42,
-      "percentSlower": 91.68
+      "ops": 32573,
+      "margin": 1.07,
+      "percentSlower": 90.38
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 11887,
-      "margin": 1.73,
-      "percentSlower": 82.77
+      "ops": 68310,
+      "margin": 1.92,
+      "percentSlower": 79.82
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by transition",
-      "ops": 1378,
-      "margin": 0.81,
-      "percentSlower": 98
+      "ops": 6869,
+      "margin": 0.91,
+      "percentSlower": 97.97
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by transition",
-      "ops": 6430,
-      "margin": 3.39,
-      "percentSlower": 90.68
+      "ops": 28116,
+      "margin": 7.66,
+      "percentSlower": 91.69
     },
     {
       "name": "Blind cycle an any-transition traffic light 500 times by transition",
-      "ops": 6154,
-      "margin": 2.67,
-      "percentSlower": 91.08
+      "ops": 24539,
+      "margin": 13.36,
+      "percentSlower": 92.75
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by transition",
-      "ops": 5512,
-      "margin": 7.71,
-      "percentSlower": 92.01
+      "ops": 27922,
+      "margin": 1.05,
+      "percentSlower": 91.75
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by transition",
-      "ops": 6030,
-      "margin": 0.9,
-      "percentSlower": 91.26
+      "ops": 26496,
+      "margin": 1.69,
+      "percentSlower": 92.17
     },
     {
       "name": "Blind cycle a standard-transition hooked light by transition",
-      "ops": 6178,
-      "margin": 1.11,
-      "percentSlower": 91.04
+      "ops": 28325,
+      "margin": 1.32,
+      "percentSlower": 91.63
     },
     {
       "name": "Blind cycle a main-transition hooked light by transition",
-      "ops": 6149,
-      "margin": 1.2,
-      "percentSlower": 91.09
+      "ops": 29332,
+      "margin": 1.13,
+      "percentSlower": 91.33
     },
     {
       "name": "Blind cycle a force-transition hooked light by transition",
-      "ops": 28529,
-      "margin": 0.85,
-      "percentSlower": 58.65
+      "ops": 102621,
+      "margin": 9.03,
+      "percentSlower": 69.68
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 13667,
-      "margin": 0.7,
-      "percentSlower": 80.19
+      "ops": 69761,
+      "margin": 0.6,
+      "percentSlower": 79.39
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by action",
-      "ops": 1554,
-      "margin": 0.7,
-      "percentSlower": 97.75
+      "ops": 7706,
+      "margin": 1.6,
+      "percentSlower": 97.72
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by action",
-      "ops": 1383,
-      "margin": 0.87,
-      "percentSlower": 98
+      "ops": 7109,
+      "margin": 0.38,
+      "percentSlower": 97.9
     },
     {
       "name": "Blind cycle an any-action traffic light 500 times by action",
-      "ops": 10689,
-      "margin": 0.97,
-      "percentSlower": 84.51
+      "ops": 56396,
+      "margin": 0.7,
+      "percentSlower": 83.34
     },
     {
       "name": "Blind cycle a global-action traffic light 500 times by action",
-      "ops": 11135,
-      "margin": 0.86,
-      "percentSlower": 83.86
+      "ops": 55612,
+      "margin": 2.76,
+      "percentSlower": 83.57
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by action",
-      "ops": 9356,
-      "margin": 1.67,
-      "percentSlower": 86.44
+      "ops": 49902,
+      "margin": 0.84,
+      "percentSlower": 85.26
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by action",
-      "ops": 9591,
-      "margin": 0.88,
-      "percentSlower": 86.1
+      "ops": 49427,
+      "margin": 0.86,
+      "percentSlower": 85.4
     },
     {
       "name": "Blind cycle a standard transition tl 500 times by action",
-      "ops": 66730,
-      "margin": 1.23,
-      "percentSlower": 3.27
+      "ops": 327884,
+      "margin": 0.73,
+      "percentSlower": 3.14
     },
     {
       "name": "Blind cycle a main transition tl 500 times by action",
-      "ops": 62427,
-      "margin": 6.85,
-      "percentSlower": 9.51
+      "ops": 327343,
+      "margin": 0.71,
+      "percentSlower": 3.3
     },
     {
       "name": "Blind cycle a forced transition tl 500 times by action",
-      "ops": 68989,
-      "margin": 0.88,
+      "ops": 338499,
+      "margin": 0.89,
       "percentSlower": 0
     },
     {
       "name": "Kitchen Sink 500 times",
-      "ops": 9307,
-      "margin": 1.82,
+      "ops": 45676,
+      "margin": 0.76,
       "percentSlower": 86.51
     }
   ],

diff --git a/dist/es6/jssm.d.ts b/dist/es6/jssm.d.ts
@@ -313,15 +313,81 @@ declare class Machine<mDT> {
      *
      */
     has_state(whichState: StateType): boolean;
+    /*********
+     *
+     *  Lists all edges of a machine.
+     *
+     *  ```typescript
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *
+     * lswitch.list_edges();
+     * [
+     *   {
+     *     from: 'on',
+     *     to: 'off',
+     *     kind: 'main',
+     *     forced_only: false,
+     *     main_path: true,
+     *     action: 'toggle'
+     *   },
+     *   {
+     *     from: 'off',
+     *     to: 'on',
+     *     kind: 'main',
+     *     forced_only: false,
+     *     main_path: true,
+     *     action: 'toggle'
+     *   }
+     * ]
+     * ```
+     *
+     */
     list_edges(): Array<JssmTransition<mDT>>;
     list_named_transitions(): Map<StateType, number>;
     list_actions(): Array<StateType>;
     theme(): FslTheme;
     flow(): FslDirection;
     get_transition_by_state_names(from: StateType, to: StateType): number;
     lookup_transition_for(from: StateType, to: StateType): JssmTransition<mDT>;
+    /********
+     *
+     *  List all transitions attached to the current state, sorted by entrance and
+     *  exit.  The order of each sublist is not defined.  A node could appear in
+     *  both lists.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_transitions();    // { entrances: [ 'yellow', 'off' ], exits: [ 'green', 'off' ] }
+     *
+     */
     list_transitions(whichState?: StateType): JssmTransitionList;
+    /********
+     *
+     *  List all entrances attached to the current state.  Please note that the
+     *  order of the list is not defined.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_entrances();      // [ 'yellow', 'off' ]
+     *
+     */
     list_entrances(whichState?: StateType): Array<StateType>;
+    /********
+     *
+     *  List all exits attached to the current state.  Please note that the order
+     *  of the list is not defined.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_exits();          // [ 'green', 'off' ]
+     *
+     */
     list_exits(whichState?: StateType): Array<StateType>;
     probable_exits_for(whichState: StateType): Array<JssmTransition<mDT>>;
     probabilistic_transition(): boolean;

diff --git a/dist/es6/jssm.js b/dist/es6/jssm.js
@@ -820,6 +820,35 @@ class Machine {
     has_state(whichState) {
         return this._states.get(whichState) !== undefined;
     }
+    /*********
+     *
+     *  Lists all edges of a machine.
+     *
+     *  ```typescript
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *
+     * lswitch.list_edges();
+     * [
+     *   {
+     *     from: 'on',
+     *     to: 'off',
+     *     kind: 'main',
+     *     forced_only: false,
+     *     main_path: true,
+     *     action: 'toggle'
+     *   },
+     *   {
+     *     from: 'off',
+     *     to: 'on',
+     *     kind: 'main',
+     *     forced_only: false,
+     *     main_path: true,
+     *     action: 'toggle'
+     *   }
+     * ]
+     * ```
+     *
+     */
     list_edges() {
         return this._edges;
     }
@@ -848,14 +877,51 @@ class Machine {
         const id = this.get_transition_by_state_names(from, to);
         return ((id === undefined) || (id === null)) ? undefined : this._edges[id];
     }
+    /********
+     *
+     *  List all transitions attached to the current state, sorted by entrance and
+     *  exit.  The order of each sublist is not defined.  A node could appear in
+     *  both lists.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_transitions();    // { entrances: [ 'yellow', 'off' ], exits: [ 'green', 'off' ] }
+     *
+     */
     list_transitions(whichState = this.state()) {
         return { entrances: this.list_entrances(whichState), exits: this.list_exits(whichState) };
     }
+    /********
+     *
+     *  List all entrances attached to the current state.  Please note that the
+     *  order of the list is not defined.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_entrances();      // [ 'yellow', 'off' ]
+     *
+     */
     list_entrances(whichState = this.state()) {
         return (this._states.get(whichState)
             || { from: undefined }).from
             || [];
     }
+    /********
+     *
+     *  List all exits attached to the current state.  Please note that the order
+     *  of the list is not defined.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_exits();          // [ 'green', 'off' ]
+     *
+     */
     list_exits(whichState = this.state()) {
         return (this._states.get(whichState)
             || { to: undefined }).to