jssm 5.65.8 → 5.65.11

package/dist/es6/jssm.d.ts

@@ -9,7 +9,7 @@ import { version } from './version';
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_direction } from './jssm';
+ *  import { arrow_direction } from 'jssm';
  *
  *  arrow_direction('->');    // 'right'
  *  arrow_direction('<~=>');  // 'both'
@@ -22,7 +22,7 @@ declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('<-');    // 'legal'
  *  arrow_left_kind('<=');    // 'main'
@@ -38,7 +38,7 @@ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('->');    // 'legal'
  *  arrow_left_kind('=>');    // 'main'
@@ -60,7 +60,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  probably also using {@link compile} and {@link Machine.constructor}.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = wrap_parse('a -> b;', {});
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -85,7 +85,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -93,7 +93,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -111,7 +111,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  {@link Machine.construct} to turn the config object into a workable machine.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = parse('a -> b;');
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -136,7 +136,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -144,7 +144,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -213,13 +213,18 @@ declare class Machine<mDT> {
     _forced_transition_hook: HookHandler | undefined;
     _any_transition_hook: HookHandler | undefined;
     constructor({ start_states, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name }: JssmGenericConfig<mDT>);
+    /********
+     *
+     *  Internal method for fabricating states.  Not meant for external use.
+     *
+     */
     _new_state(state_config: JssmGenericState): StateType;
     /*********
      *
      *  Get the current state of a machine.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.state() );             // 'on'
@@ -230,7 +235,38 @@ declare class Machine<mDT> {
      *
      */
     state(): StateType;
+    /********
+     *
+     *  Check whether a given state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from 'jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.state_is_final('first') );   // false
+     *  console.log( final_test.state_is_final('second') );  // true
+     *  ```
+     *
+     */
     state_is_final(whichState: StateType): boolean;
+    /********
+     *
+     *  Check whether the current state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from 'jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.is_final() );   // false
+     *  state.transition('second');
+     *  console.log( final_test.is_final() );   // true
+     *  ```
+     *
+     */
     is_final(): boolean;
     graph_layout(): string;
     dot_preamble(): string;
@@ -253,7 +289,7 @@ declare class Machine<mDT> {
      *  these states is not guaranteed.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.states() );             // ['on', 'off']
@@ -267,16 +303,45 @@ declare class Machine<mDT> {
      *  Check whether the machine knows a given state.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
-  
+     *
      *  console.log( switch.has_state('off') );     // true
      *  console.log( switch.has_state('dance') );   // false
      *  ```
      *
      */
     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>;
@@ -284,14 +349,99 @@ declare class Machine<mDT> {
     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;
     probabilistic_walk(n: number): Array<StateType>;
     probabilistic_histo_walk(n: number): Map<StateType, number>;
+    /********
+     *
+     *  List all actions available from this state.  Please note that the order of
+     *  the actions is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('next');            // true
+     *  console.log( machine.state() );    // logs 'green'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('shutdown');        // true
+     *  console.log( machine.state() );    // logs 'off'
+     *  console.log( machine.actions() );  // logs ['start']
+     *
+     *  machine.action('start');           // true
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *  ```
+     *
+     */
     actions(whichState?: StateType): Array<StateType>;
+    /********
+     *
+     *  List all states that have a specific action attached.  Please note that
+     *  the order of the states is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.list_states_having_action('next') );    // ['red', 'green', 'yellow']
+     *  console.log( machine.list_states_having_action('start') );   // ['off']
+     *  ```
+     *
+     */
     list_states_having_action(whichState: StateType): Array<StateType>;
     list_exit_actions(whichState?: StateType): Array<StateType>;
     probable_action_exits(whichState?: StateType): Array<any>;
@@ -338,7 +488,7 @@ declare class Machine<mDT> {
  *
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```
@@ -355,7 +505,7 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *  template expression.
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```

package/dist/es6/jssm.js

@@ -11,7 +11,7 @@ import { JssmError } from './jssm_error';
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_direction } from './jssm';
+ *  import { arrow_direction } from 'jssm';
  *
  *  arrow_direction('->');    // 'right'
  *  arrow_direction('<~=>');  // 'both'
@@ -76,7 +76,7 @@ function arrow_direction(arrow) {
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('<-');    // 'legal'
  *  arrow_left_kind('<=');    // 'main'
@@ -133,7 +133,7 @@ function arrow_left_kind(arrow) {
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('->');    // 'legal'
  *  arrow_left_kind('=>');    // 'main'
@@ -231,7 +231,7 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  probably also using {@link compile} and {@link Machine.constructor}.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = wrap_parse('a -> b;', {});
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -256,7 +256,7 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -264,7 +264,7 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -356,7 +356,7 @@ function compile_rule_handler(rule) {
  *  {@link Machine.construct} to turn the config object into a workable machine.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = parse('a -> b;');
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -381,7 +381,7 @@ function compile_rule_handler(rule) {
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -389,7 +389,7 @@ function compile_rule_handler(rule) {
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -643,6 +643,11 @@ class Machine {
             }
         });
     }
+    /********
+     *
+     *  Internal method for fabricating states.  Not meant for external use.
+     *
+     */
     _new_state(state_config) {
         if (this._states.has(state_config.name)) {
             throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
@@ -655,7 +660,7 @@ class Machine {
      *  Get the current state of a machine.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.state() );             // 'on'
@@ -675,9 +680,40 @@ class Machine {
         return true; // todo whargarbl
       }
     */
+    /********
+     *
+     *  Check whether a given state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from 'jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.state_is_final('first') );   // false
+     *  console.log( final_test.state_is_final('second') );  // true
+     *  ```
+     *
+     */
     state_is_final(whichState) {
         return ((this.state_is_terminal(whichState)) && (this.state_is_complete(whichState)));
     }
+    /********
+     *
+     *  Check whether the current state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from 'jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.is_final() );   // false
+     *  state.transition('second');
+     *  console.log( final_test.is_final() );   // true
+     *  ```
+     *
+     */
     is_final() {
         //  return ((!this.is_changing()) && this.state_is_final(this.state()));
         return this.state_is_final(this.state());
@@ -748,7 +784,7 @@ class Machine {
      *  these states is not guaranteed.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.states() );             // ['on', 'off']
@@ -772,10 +808,10 @@ class Machine {
      *  Check whether the machine knows a given state.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
-  
+     *
      *  console.log( switch.has_state('off') );     // true
      *  console.log( switch.has_state('dance') );   // false
      *  ```
@@ -784,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;
     }
@@ -812,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
@@ -851,6 +953,36 @@ class Machine {
     probabilistic_histo_walk(n) {
         return histograph(this.probabilistic_walk(n));
     }
+    /********
+     *
+     *  List all actions available from this state.  Please note that the order of
+     *  the actions is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('next');            // true
+     *  console.log( machine.state() );    // logs 'green'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('shutdown');        // true
+     *  console.log( machine.state() );    // logs 'off'
+     *  console.log( machine.actions() );  // logs ['start']
+     *
+     *  machine.action('start');           // true
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *  ```
+     *
+     */
     actions(whichState = this.state()) {
         const wstate = this._reverse_actions.get(whichState);
         if (wstate) {
@@ -860,6 +992,24 @@ class Machine {
             throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
     }
+    /********
+     *
+     *  List all states that have a specific action attached.  Please note that
+     *  the order of the states is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.list_states_having_action('next') );    // ['red', 'green', 'yellow']
+     *  console.log( machine.list_states_having_action('start') );   // ['off']
+     *  ```
+     *
+     */
     list_states_having_action(whichState) {
         const wstate = this._actions.get(whichState);
         if (wstate) {
@@ -1252,7 +1402,7 @@ class Machine {
  *
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```
@@ -1281,7 +1431,7 @@ function sm(template_strings, ...remainder /* , arguments */) {
  *  template expression.
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.65.8";
+const version = "5.65.11";
 export { version };