jssm 5.65.1 → 5.65.4

package/dist/es6/jssm.d.ts

@@ -4,12 +4,168 @@ JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmAr
 import { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
 import { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { version } from './version';
+/*********
+ *
+ *  Return the direction of an arrow - `right`, `left`, or `both`.
+ *
+ *  ```typescript
+ *  import { arrow_direction } from './jssm';
+ *
+ *  arrow_direction('->');    // 'right'
+ *  arrow_direction('<~=>');  // 'both'
+ *  ```
+ *
+ */
 declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
+/*********
+ *
+ *  Return the direction of an arrow - `right`, `left`, or `both`.
+ *
+ *  ```typescript
+ *  import { arrow_left_kind } from './jssm';
+ *
+ *  arrow_left_kind('<-');    // 'legal'
+ *  arrow_left_kind('<=');    // 'main'
+ *  arrow_left_kind('<~');    // 'forced'
+ *  arrow_left_kind('<->');   // 'legal'
+ *  arrow_left_kind('->');    // 'none'
+ *  ```
+ *
+ */
 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';
+ *
+ *  arrow_left_kind('->');    // 'legal'
+ *  arrow_left_kind('=>');    // 'main'
+ *  arrow_left_kind('~>');    // 'forced'
+ *  arrow_left_kind('<->');   // 'legal'
+ *  arrow_left_kind('<-');    // 'none'
+ *  ```
+ *
+ */
 declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
+/*********
+ *
+ *  This method wraps the parser call that comes from the peg grammar,
+ *  {@link parse}.  Generally neither this nor that should be used directly
+ *  unless you mean to develop plugins or extensions for the machine.
+ *
+ *  Parses the intermediate representation of a compiled string down to a
+ *  machine configuration object.  If you're using this (probably don't,) you're
+ *  probably also using {@link compile} and {@link Machine.constructor}.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = wrap_parse('a -> b;', {});
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  Operator {@link sm}:
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  Method {@link from}:
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ *  `wrap_parse` itself is an internal convenience method for alting out an
+ *  object as the options call.  Not generally meant for external use.
+ *
+ */
 declare function wrap_parse(input: string, options?: Object): any;
+/*********
+ *
+ *  Compile a machine's JSON intermediate representation to a config object.  If
+ *  you're using this (probably don't,) you're probably also using
+ *  {@link parse} to get the IR, and the object constructor
+ *  {@link Machine.construct} to turn the config object into a workable machine.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = parse('a -> b;');
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  Operator {@link sm}:
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  Method {@link from}:
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ */
 declare function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>;
+/*********
+ *
+ *  An internal convenience wrapper for parsing then compiling a machine string.
+ *  Not generally meant for external use.  Please see {@link compile} or
+ *  {@link sm}.
+ *
+ */
 declare function make<mDT>(plan: string): JssmGenericConfig<mDT>;
+/*********
+ *
+ *  An internal method meant to take a series of declarations and fold them into
+ *  a single multi-faceted declaration, in the process of building a state.  Not
+ *  generally meant for external use.
+ *
+ */
 declare function transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration;
 declare class Machine<mDT> {
     _state: StateType;
@@ -129,6 +285,39 @@ declare class Machine<mDT> {
     instance_name(): string | undefined;
     sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
 }
+/*********
+ *
+ *  Create a state machine from a template string.  This is one of the two main
+ *  paths for working with JSSM, alongside {@link from}.
+ *
+ *  Use this method when you want to work directly and conveniently with a
+ *  constant template expression.  Use `.from` when you want to pull from
+ *  dynamic strings.
+ *
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
+/*********
+ *
+ *  Create a state machine from an implementation string.  This is one of the
+ *  two main paths for working with JSSM, alongside {@link sm}.
+ *
+ *  Use this method when you want to conveniently pull a state machine from a
+ *  string dynamically.  Use operator `sm` when you just want to work with a
+ *  template expression.
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>> | undefined): Machine<mDT>;
 export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors };

package/dist/es6/jssm.js

@@ -6,6 +6,18 @@ import { parse } from './jssm-dot';
 import { version } from './version'; // replaced from package.js in build
 import { JssmError } from './jssm_error';
 /* eslint-disable complexity */
+/*********
+ *
+ *  Return the direction of an arrow - `right`, `left`, or `both`.
+ *
+ *  ```typescript
+ *  import { arrow_direction } from './jssm';
+ *
+ *  arrow_direction('->');    // 'right'
+ *  arrow_direction('<~=>');  // 'both'
+ *  ```
+ *
+ */
 function arrow_direction(arrow) {
     switch (String(arrow)) {
         case '->':
@@ -59,6 +71,21 @@ function arrow_direction(arrow) {
 }
 /* eslint-enable complexity */
 /* eslint-disable complexity */
+/*********
+ *
+ *  Return the direction of an arrow - `right`, `left`, or `both`.
+ *
+ *  ```typescript
+ *  import { arrow_left_kind } from './jssm';
+ *
+ *  arrow_left_kind('<-');    // 'legal'
+ *  arrow_left_kind('<=');    // 'main'
+ *  arrow_left_kind('<~');    // 'forced'
+ *  arrow_left_kind('<->');   // 'legal'
+ *  arrow_left_kind('->');    // 'none'
+ *  ```
+ *
+ */
 function arrow_left_kind(arrow) {
     switch (String(arrow)) {
         case '->':
@@ -101,6 +128,21 @@ function arrow_left_kind(arrow) {
 }
 /* eslint-enable complexity */
 /* eslint-disable complexity */
+/*********
+ *
+ *  Return the direction of an arrow - `right`, `left`, or `both`.
+ *
+ *  ```typescript
+ *  import { arrow_left_kind } from './jssm';
+ *
+ *  arrow_left_kind('->');    // 'legal'
+ *  arrow_left_kind('=>');    // 'main'
+ *  arrow_left_kind('~>');    // 'forced'
+ *  arrow_left_kind('<->');   // 'legal'
+ *  arrow_left_kind('<-');    // 'none'
+ *  ```
+ *
+ */
 function arrow_right_kind(arrow) {
     switch (String(arrow)) {
         case '<-':
@@ -142,6 +184,12 @@ function arrow_right_kind(arrow) {
     }
 }
 /* eslint-enable complexity */
+/*********
+ *
+ *  Internal method meant to perform factory assembly of an edge.  Not meant for
+ *  external use.
+ *
+ */
 function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     const kind = isRight ? arrow_right_kind(this_se.kind) : arrow_left_kind(this_se.kind), edge = {
         from,
@@ -172,9 +220,68 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     }
     return edge;
 }
+/*********
+ *
+ *  This method wraps the parser call that comes from the peg grammar,
+ *  {@link parse}.  Generally neither this nor that should be used directly
+ *  unless you mean to develop plugins or extensions for the machine.
+ *
+ *  Parses the intermediate representation of a compiled string down to a
+ *  machine configuration object.  If you're using this (probably don't,) you're
+ *  probably also using {@link compile} and {@link Machine.constructor}.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = wrap_parse('a -> b;', {});
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  Operator {@link sm}:
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  Method {@link from}:
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ *  `wrap_parse` itself is an internal convenience method for alting out an
+ *  object as the options call.  Not generally meant for external use.
+ *
+ */
 function wrap_parse(input, options) {
     return parse(input, options || {});
 }
+/*********
+ *
+ *  Internal method performing one step in compiling rules for transitions.  Not
+ *  generally meant for external use.
+ *
+ */
 function compile_rule_transition_step(acc, from, to, this_se, next_se) {
     const edges = [];
     const uFrom = (Array.isArray(from) ? from : [from]), uTo = (Array.isArray(to) ? to : [to]);
@@ -198,9 +305,21 @@ function compile_rule_transition_step(acc, from, to, this_se, next_se) {
         return new_acc;
     }
 }
+/*********
+ *
+ *  Internal method performing one step in compiling rules for transitions.  Not
+ *  generally meant for external use.
+ *
+ */
 function compile_rule_handle_transition(rule) {
     return compile_rule_transition_step([], rule.from, rule.se.to, rule.se, rule.se.se);
 }
+/*********
+ *
+ *  Internal method performing one step in compiling rules for transitions.  Not
+ *  generally meant for external use.
+ *
+ */
 function compile_rule_handler(rule) {
     if (rule.key === 'transition') {
         return { agg_as: 'transition', val: compile_rule_handle_transition(rule) };
@@ -229,6 +348,53 @@ function compile_rule_handler(rule) {
     }
     throw new JssmError(undefined, `compile_rule_handler: Unknown rule: ${JSON.stringify(rule)}`);
 }
+/*********
+ *
+ *  Compile a machine's JSON intermediate representation to a config object.  If
+ *  you're using this (probably don't,) you're probably also using
+ *  {@link parse} to get the IR, and the object constructor
+ *  {@link Machine.construct} to turn the config object into a workable machine.
+ *
+ *  ```typescript
+ *  import { parse, compile, Machine } from './jssm';
+ *
+ *  const intermediate = parse('a -> b;');
+ *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
+ *
+ *  const cfg = compile(intermediate);
+ *  // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] }
+ *
+ *  const machine = new Machine(cfg);
+ *  // Machine { _instance_name: undefined, _state: 'a', ...
+ *  ```
+ *
+ *  This method is mostly for plugin and intermediate tool authors, or people
+ *  who need to work with the machine's intermediate representation.
+ *
+ *  # Hey!
+ *
+ *  Most people looking at this want either the `sm` operator or method `from`,
+ *  which perform all the steps in the chain.  The library's author mostly uses
+ *  operator `sm`, and mostly falls back to `.from` when needing to parse
+ *  strings dynamically instead of from template literals.
+ *
+ *  Operator {@link sm}:
+ *
+ *  ```typescript
+ *  import { sm } from './jssm';
+ *
+ *  const switch = sm`on <=> off;`;
+ *  ```
+ *
+ *  Method {@link from}:
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const toggle = jssm.from('up <=> down;');
+ *  ```
+ *
+ */
 function compile(tree) {
     const results = {
         graph_layout: [],
@@ -286,9 +452,23 @@ function compile(tree) {
     });
     return result_cfg;
 }
+/*********
+ *
+ *  An internal convenience wrapper for parsing then compiling a machine string.
+ *  Not generally meant for external use.  Please see {@link compile} or
+ *  {@link sm}.
+ *
+ */
 function make(plan) {
     return compile(wrap_parse(plan));
 }
+/*********
+ *
+ *  An internal method meant to take a series of declarations and fold them into
+ *  a single multi-faceted declaration, in the process of building a state.  Not
+ *  generally meant for external use.
+ *
+ */
 function transfer_state_properties(state_decl) {
     state_decl.declarations.map((d) => {
         switch (d.key) {
@@ -1019,6 +1199,23 @@ class Machine {
         return sm(template_strings, ...remainder);
     }
 }
+/*********
+ *
+ *  Create a state machine from a template string.  This is one of the two main
+ *  paths for working with JSSM, alongside {@link from}.
+ *
+ *  Use this method when you want to work directly and conveniently with a
+ *  constant template expression.  Use `.from` when you want to pull from
+ *  dynamic strings.
+ *
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 function sm(template_strings, ...remainder /* , arguments */) {
     // foo`a${1}b${2}c` will come in as (['a','b','c'],1,2)
     // this includes when a and c are empty strings
@@ -1032,6 +1229,22 @@ function sm(template_strings, ...remainder /* , arguments */) {
     /* eslint-enable  prefer-rest-params */
     )));
 }
+/*********
+ *
+ *  Create a state machine from an implementation string.  This is one of the
+ *  two main paths for working with JSSM, alongside {@link sm}.
+ *
+ *  Use this method when you want to conveniently pull a state machine from a
+ *  string dynamically.  Use operator `sm` when you just want to work with a
+ *  template expression.
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 function from(MachineAsString, ExtraConstructorFields) {
     const to_decorate = make(MachineAsString);
     if (ExtraConstructorFields !== undefined) {

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.65.1";
+const version = "5.65.4";
 export { version };