jssm 5.65.2 → 5.65.5

package/dist/es6/jssm.d.ts

@@ -51,13 +51,121 @@ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
 declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
 /*********
  *
- *  Internal convenience method for alting out an object as the options call.
- *  Not generally meant for external use.
+ *  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;
@@ -177,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

@@ -222,13 +222,66 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
 }
 /*********
  *
- *  Internal convenience method for alting out an object as the options call.
- *  Not generally meant for external use.
+ *  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]);
@@ -252,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) };
@@ -283,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: [],
@@ -340,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) {
@@ -1073,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
@@ -1086,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/jssm_util.d.ts

@@ -1,10 +1,52 @@
+/*******
+ *
+ *  Predicate for validating an array for uniqueness.  Not generally meant for
+ *  external use.
+ *
+ */
 declare function arr_uniq_p<T>(el: T, i: number, source: T[]): boolean;
 declare const array_box_if_string: (n: any) => any;
 declare const weighted_rand_select: Function;
-declare const seq: Function;
+/*******
+ *
+ *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
+ *
+ *  ```typescript
+ *  import { seq } from './jssm';
+ *
+ *  seq(5);  // [0, 1, 2, 3, 4]
+ *  seq(0);  // []
+ *  ```
+ *
+ */
+declare function seq(n: number): number[];
+/*******
+ *
+ *  Returns the histograph of an array as a `Map`.  Makes no attempt to cope
+ *  with deep equality; will fail for complex contents, as such.
+ *
+ *  ```typescript
+ *  import { histograph } from './jssm';
+ *
+ *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
+ *  ```
+ *
+ */
 declare const histograph: Function;
 declare const weighted_sample_select: Function;
 declare const weighted_histo_key: Function;
+/*******
+ *
+ *  Internal method generating names for edges for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 declare const hook_name: (from: string, to: string) => string;
+/*******
+ *
+ *  Internal method generating names for actions for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 declare const named_hook_name: (from: string, to: string, action: string) => string;
 export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name };

package/dist/es6/jssm_util.js

@@ -1,3 +1,9 @@
+/*******
+ *
+ *  Predicate for validating an array for uniqueness.  Not generally meant for
+ *  external use.
+ *
+ */
 function arr_uniq_p(el, i, source) {
     return source.indexOf(el) === i;
 }
@@ -17,8 +23,41 @@ const weighted_rand_select = (options, probability_property = 'probability') =>
     return options[cursor - 1];
 };
 /* eslint-enable flowtype/no-weak-types */
-const seq = (n) => (new Array(n)).fill(true)
-    .map((_, i) => i);
+/*******
+ *
+ *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
+ *
+ *  ```typescript
+ *  import { seq } from './jssm';
+ *
+ *  seq(5);  // [0, 1, 2, 3, 4]
+ *  seq(0);  // []
+ *  ```
+ *
+ */
+function seq(n) {
+    if (!(Number.isInteger(n))) {
+        throw new TypeError('seq/1 takes a non-negative integer n as an argument');
+    }
+    if (n < 0) {
+        throw new TypeError('seq/1 takes a non-negative integer n as an argument');
+    }
+    return (new Array(n))
+        .fill(true)
+        .map((_, i) => i);
+}
+/*******
+ *
+ *  Returns the histograph of an array as a `Map`.  Makes no attempt to cope
+ *  with deep equality; will fail for complex contents, as such.
+ *
+ *  ```typescript
+ *  import { histograph } from './jssm';
+ *
+ *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
+ *  ```
+ *
+ */
 const histograph = (ar) => // eslint-disable-line flowtype/no-weak-types
  ar.sort()
     .reduce((m, v) => // TODO FIXME eslint-disable-line flowtype/no-weak-types,no-sequences
@@ -31,6 +70,18 @@ const weighted_histo_key = (n, opts, prob_prop, extract) => // TODO FIXME no any
  histograph(weighted_sample_select(n, opts, prob_prop)
     .map((s) => s[extract] // TODO FIXME eslint-disable-line flowtype/no-weak-types
 ));
+/*******
+ *
+ *  Internal method generating names for edges for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 const hook_name = (from, to) => JSON.stringify([from, to]);
+/*******
+ *
+ *  Internal method generating names for actions for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 const named_hook_name = (from, to, action) => JSON.stringify([from, to, action]);
 export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name };

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.65.2";
+const version = "5.65.5";
 export { version };