From 915482bf57474c05cb0b8722e89d782eda4ea61c Mon Sep 17 00:00:00 2001 From: John Haugeland Date: Thu, 28 Jul 2022 15:19:37 -0700 Subject: [PATCH 1/2] Adds `machina`, `finity`, `fsm-iterator`, `fsm-as-promised` to feature comparison table, fixes StoneCypher/fsl#1114, fixes StoneCypher/fsl#1115, fixes StoneCypher/fsl#1116, fixes StoneCypher/fsl#1117 --- docs/docs/classes/jssm.Machine.html | 58 +-- docs/docs/classes/jssm_error.JssmError.html | 2 +- docs/docs/modules/jssm.html | 18 +- docs/docs/modules/jssm_constants.html | 2 +- docs/docs/modules/jssm_types._internal_.html | 2 +- docs/docs/modules/jssm_types.html | 4 +- docs/docs/modules/jssm_util.html | 18 +- docs/docs/modules/version.html | 2 +- docs/docs/pages/FeatureComparison.html | 519 +++++++++--------- src/doc_md/FeatureComparison.md | 521 ++++++++++--------- 10 files changed, 574 insertions(+), 572 deletions(-) diff --git a/docs/docs/classes/jssm.Machine.html b/docs/docs/classes/jssm.Machine.html index 9b1b17e8..bc8ba7c2 100644 --- a/docs/docs/classes/jssm.Machine.html +++ b/docs/docs/classes/jssm.Machine.html @@ -1,4 +1,4 @@ -Machine | JSSM, a JavaScript state machine - the FSM for FSL
Options
All
  • Public
  • Public/Protected
  • All
Menu

Type Parameters

  • mDT

Hierarchy

  • Machine

Index

Constructors

Properties

Accessors

Methods

Constructors

Properties

_actions: Map<string, Map<string, number>>
_any_action_hook: HookHandler<mDT>
_any_transition_hook: HookHandler<mDT>
_arrange_declaration: string[][]
_arrange_end_declaration: string[][]
_arrange_start_declaration: string[][]
_data?: mDT
_default_properties: Map<string, any>
_dot_preamble: string
_edge_map: Map<string, Map<string, number>>
_edges: JssmTransition<mDT>[]
_entry_hooks: Map<string, HookHandler<mDT>>
_exit_hooks: Map<string, HookHandler<mDT>>
_forced_transition_hook: HookHandler<mDT>
_fsl_version?: string
_global_action_hooks: Map<string, HookHandler<mDT>>
_graph_layout: JssmLayout
_has_basic_hooks: boolean
_has_entry_hooks: boolean
_has_exit_hooks: boolean
_has_global_action_hooks: boolean
_has_hooks: boolean
_has_named_hooks: boolean
_has_post_basic_hooks: boolean
_has_post_entry_hooks: boolean
_has_post_exit_hooks: boolean
_has_post_global_action_hooks: boolean
_has_post_hooks: boolean
_has_post_named_hooks: boolean
_has_post_transition_hooks: boolean
_has_transition_hooks: boolean
_history: JssmHistory<mDT>
_history_length: number
_hooks: Map<string, HookHandler<mDT>>
_instance_name: string
_machine_author?: string[]
_machine_comment?: string
_machine_contributor?: string[]
_machine_definition?: string
_machine_language?: string
_machine_license?: string
_machine_name?: string
_machine_version?: string
_main_transition_hook: HookHandler<mDT>
_named_hooks: Map<string, HookHandler<mDT>>
_named_transitions: Map<string, number>
_post_any_action_hook: HookHandler<mDT>
_post_any_transition_hook: HookHandler<mDT>
_post_entry_hooks: Map<string, HookHandler<mDT>>
_post_exit_hooks: Map<string, HookHandler<mDT>>
_post_forced_transition_hook: HookHandler<mDT>
_post_global_action_hooks: Map<string, HookHandler<mDT>>
_post_hooks: Map<string, HookHandler<mDT>>
_post_main_transition_hook: HookHandler<mDT>
_post_named_hooks: Map<string, HookHandler<mDT>>
_post_standard_transition_hook: HookHandler<mDT>
_property_keys: Set<string>
_raw_state_declaration?: <internal>.Object[]
_required_properties: Set<string>
_reverse_action_targets: Map<string, Map<string, number>>
_reverse_actions: Map<string, Map<string, number>>
_standard_transition_hook: HookHandler<mDT>
_state: string
_state_declarations: Map<string, JssmStateDeclaration>
_state_properties: Map<string, any>
_states: Map<string, JssmGenericState>
_theme: FslTheme

Accessors

  • get history(): [string, mDT][]
  • actions(whichState?: string): string[]

Returns boolean

  • actions(whichState?: string): string[]
  • List all actions available from this state. Please note that the order of the actions is not guaranteed.

    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']

    Parameters

    • whichState: string = ...

      The state whose actions to have listed

      -

    Returns string[]

  • current_action_for(action: string): number
  • data(): mDT

Returns string[]

  • current_action_for(action: string): number
  • data(): mDT
  • Get the current data of a machine.

    import * as jssm from 'jssm';

    const switch = jssm.from('on <=> off;', {data: 1});
    console.log( switch.data() ); // 1
    -

    Returns mDT

  • do(actionName: string, newData?: mDT): boolean
  • do(actionName: string, newData?: mDT): boolean
  • Instruct the machine to complete an action. Synonym for action.

    const light = sm`
    off 'start' -> red;
    red 'next' -> green 'next' -> yellow 'next' -> red;
    [red yellow green] 'shutdown' ~> off;
    `;

    light.state(); // 'off'
    light.do('start'); // true
    light.state(); // 'red'
    light.do('next'); // true
    light.state(); // 'green'
    light.do('next'); // true
    light.state(); // 'yellow'
    light.do('dance'); // !! false - no such action
    light.state(); // 'yellow'
    light.do('start'); // !! false - yellow does not have the action start
    light.state(); // 'yellow'
    @@ -58,7 +58,7 @@

    The action to engage

  • Optional newData: mDT

    The data change to insert during the action

    -

Returns boolean

  • dot_preamble(): string
  • force_transition(newState: string, newData?: mDT): boolean

Returns boolean

  • dot_preamble(): string
  • force_transition(newState: string, newData?: mDT): boolean
  • Instruct the machine to complete a forced transition (which will reject if called with a normal transition call.)

    const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;

    light.state(); // 'red'
    light.transition('off'); // false
    light.state(); // 'red'
    light.force_transition('off'); // true
    light.state(); // 'off' @@ -67,7 +67,7 @@

    The state to switch to

  • Optional newData: mDT

    The data change to insert during the transition

    -

Returns boolean

  • fsl_version(): string
  • get_transition_by_state_names(from: string, to: string): number
  • go(newState: string, newData?: mDT): boolean

Returns boolean

  • fsl_version(): string
  • get_transition_by_state_names(from: string, to: string): number
  • go(newState: string, newData?: mDT): boolean
  • Instruct the machine to complete a transition. Synonym for transition.

    const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;

    light.state(); // 'red'
    light.go('green'); // true
    light.state(); // 'green'
    @@ -75,55 +75,55 @@

    The state to switch to

  • Optional newData: mDT

    The data change to insert during the transition

    -

Returns boolean

  • graph_layout(): string
  • has_completes(): boolean
  • has_state(whichState: string): boolean

Returns boolean

  • graph_layout(): string
  • has_completes(): boolean
  • has_state(whichState: string): boolean
  • Check whether the machine knows a given state.

    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

    Parameters

    • whichState: string

      The state to be checked for extance

      -

    Returns boolean

  • has_terminals(): boolean
  • has_unenterables(): boolean
  • hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>
  • instance_name(): string
  • is_complete(): boolean
  • is_final(): boolean

Returns boolean

  • has_terminals(): boolean
  • has_unenterables(): boolean
  • hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>
  • instance_name(): string
  • is_complete(): boolean
  • is_final(): boolean
  • Check whether the current state is final (either has no exits or is marked complete.)

    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
    -

    Returns boolean

  • is_terminal(): boolean
  • is_unenterable(whichState: string): boolean
  • known_prop(prop_name: string): boolean
  • is_terminal(): boolean
  • is_unenterable(whichState: string): boolean
  • known_prop(prop_name: string): boolean
  • Check whether a given string is a known property's name.

    const example = sm`property foo default 1; a->b;`;

    example.known_prop('foo'); // true
    example.known_prop('bar'); // false

    Parameters

    • prop_name: string

      The relevant property name to look up

      -

    Returns boolean

  • known_props(): string[]

Returns boolean

  • known_props(): string[]
  • List all known property names. If you'd also like values, use props instead. The order of the properties is not defined, and the properties generally will not be sorted.

    
     
    -

    Returns string[]

  • list_actions(): string[]
  • list_actions(): string[]
  • Lists all edges of a machine.

    import { sm } from 'jssm';

    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'
    }
    ]
    -

    Returns JssmTransition<mDT>[]

  • list_entrances(whichState?: string): string[]
  • list_entrances(whichState?: string): string[]
  • List all entrances attached to the current state. Please note that the order of the list is not defined.

    import { sm } from 'jssm';

    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' ]

    Parameters

    • whichState: string = ...

      The state whose entrances to have listed

      -

    Returns string[]

  • list_exit_actions(whichState?: string): string[]
  • list_exits(whichState?: string): string[]

Returns string[]

  • list_exit_actions(whichState?: string): string[]
  • list_exits(whichState?: string): string[]
  • List all exits attached to the current state. Please note that the order of the list is not defined.

    import { sm } from 'jssm';

    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' ]

    Parameters

    • whichState: string = ...

      The state whose exits to have listed

      -

    Returns string[]

  • list_named_transitions(): Map<string, number>
  • list_states_having_action(whichState: string): string[]

Returns string[]

  • list_named_transitions(): Map<string, number>
  • list_states_having_action(whichState: string): string[]
  • List all states that have a specific action attached. Please note that the order of the states is not guaranteed.

    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']

    Parameters

    • whichState: string

      The action to be checked for associated states

      -

    Returns string[]

Returns string[]

  • 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.

    @@ -131,7 +131,7 @@

    Parameters

    • whichState: string = ...

      The state whose transitions to have listed

      -

    Returns JssmTransitionList

  • machine_author(): string[]
  • machine_comment(): string
  • machine_contributor(): string[]
  • machine_definition(): string
  • machine_language(): string
  • machine_license(): string
  • machine_name(): string
  • machine_version(): string
  • post_hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>
  • probabilistic_histo_walk(n: number): Map<string, number>
  • probabilistic_transition(): boolean
  • probabilistic_walk(n: number): string[]
  • probable_action_exits(whichState?: string): any[]
  • prop(name: string): any

Returns JssmTransitionList

  • machine_author(): string[]
  • machine_comment(): string
  • machine_contributor(): string[]
  • machine_definition(): string
  • machine_language(): string
  • machine_license(): string
  • machine_name(): string
  • machine_version(): string
  • post_hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>
  • probabilistic_histo_walk(n: number): Map<string, number>
  • probabilistic_transition(): boolean
  • probabilistic_walk(n: number): string[]
  • probable_action_exits(whichState?: string): any[]
  • prop(name: string): any
  • Get the current value of a given property name.

    
     
    @@ -139,35 +139,35 @@

    The relevant property name to look up

Returns any

The value behind the prop name. Because functional props are evaluated as getters, this can be anything.

-
  • props(): object
  • props(): object
  • Get the current value of every prop, as an object. If no current definition exists for a prop - that is, if the prop was defined without a default and the current state also doesn't define the prop - then that prop will be listed in the returned object with a value of undefined.

    const traffic_light = sm`

    property can_go default true;
    property hesitate default true;
    property stop_first default false;

    Off -> Red => Green => Yellow => Red;
    [Red Yellow Green] ~> [Off FlashingRed];
    FlashingRed -> Red;

    state Red: { property stop_first true; property can_go false; };
    state Off: { property stop_first true; };
    state FlashingRed: { property stop_first true; };
    state Green: { property hesitate false; };

    `;

    traffic_light.state(); // Off
    traffic_light.props(); // { can_go: true, hesitate: true, stop_first: true; }

    traffic_light.go('Red');
    traffic_light.props(); // { can_go: false, hesitate: true, stop_first: true; }

    traffic_light.go('Green');
    traffic_light.props(); // { can_go: true, hesitate: false, stop_first: false; }
    -

    Returns object

  • Serialize the current machine, including all defining state but not the machine string, to a structure. This means you will need the machine string to recreate (to not waste repeated space;) if you want the machine string embedded, call {@link serialize_with_string} instead.

    -

    Parameters

    • Optional comment: string

    Returns JssmSerialization<mDT>

  • state(): string
  • state(): string
  • Get the current state of a machine.

    import * as jssm from 'jssm';

    const switch = jssm.from('on <=> off;');
    console.log( switch.state() ); // 'on'

    switch.transition('off');
    console.log( switch.state() ); // 'off'
    -

    Returns string

  • state_is_complete(whichState: string): boolean
  • state_is_final(whichState: string): boolean
  • state_is_complete(whichState: string): boolean
  • state_is_final(whichState: string): boolean
  • Check whether a given state is final (either has no exits or is marked complete.)

    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

    Parameters

    • whichState: string

      The name of the state to check for finality

      -

    Returns boolean

  • state_is_terminal(whichState: string): boolean
  • states(): string[]

Returns boolean

  • state_is_terminal(whichState: string): boolean
  • states(): string[]
  • List all the states known by the machine. Please note that the order of these states is not guaranteed.

    import * as jssm from 'jssm';

    const switch = jssm.from('on <=> off;');
    console.log( switch.states() ); // ['on', 'off']
    -

    Returns string[]

  • strict_prop(name: string): any
  • strict_prop(name: string): any
  • Get the current value of a given property name. If missing on the state and without a global default, throw, unlike prop, which would return undefined instead.

    @@ -177,7 +177,7 @@

    The relevant property name to look up

Returns any

The value behind the prop name. Because functional props are evaluated as getters, this can be anything.

-
  • transition(newState: string, newData?: mDT): boolean
  • transition(newState: string, newData?: mDT): boolean
  • Instruct the machine to complete a transition. Synonym for go.

    const light = sm`
    off 'start' -> red;
    red 'next' -> green 'next' -> yellow 'next' -> red;
    [red yellow green] 'shutdown' ~> off;
    `;

    light.state(); // 'off'
    light.go('red'); // true
    light.state(); // 'red'
    light.go('green'); // true
    light.state(); // 'green'
    light.go('blue'); // !! false - no such state
    light.state(); // 'green'
    light.go('red'); // !! false - green may not go directly to red, only to yellow
    light.state(); // 'green'
    @@ -185,4 +185,4 @@

    The state to switch to

  • Optional newData: mDT

    The data change to insert during the transition

    -

Returns boolean

  • transition_impl(newStateOrAction: string, newData: mDT, wasForced: boolean, wasAction: boolean): boolean
  • Parameters

    • newStateOrAction: string
    • newData: mDT
    • wasForced: boolean
    • wasAction: boolean

    Returns boolean

  • valid_action(action: string, _newData?: mDT): boolean
  • valid_force_transition(newState: string, _newData?: mDT): boolean
  • valid_transition(newState: string, _newData?: mDT): boolean

Generated using TypeDoc

\ No newline at end of file +

Returns boolean

Generated using TypeDoc

\ No newline at end of file diff --git a/docs/docs/classes/jssm_error.JssmError.html b/docs/docs/classes/jssm_error.JssmError.html index 79837d92..d71d6a71 100644 --- a/docs/docs/classes/jssm_error.JssmError.html +++ b/docs/docs/classes/jssm_error.JssmError.html @@ -1,4 +1,4 @@ -JssmError | JSSM, a JavaScript state machine - the FSM for FSL
Options
All
  • Public
  • Public/Protected
  • All
Menu

Hierarchy

Index

Constructors

Properties

base_message: string
message: string
name: string
requested_state: string
stack?: string
prepareStackTrace?: ((err: <internal>.Error, stackTraces: CallSite[]) => any)

Type declaration

  • Compile a machine's JSON intermediate representation to a config object. If you're using this (probably don't,) you're probably also using parse to get the IR, and the object constructor @@ -43,7 +43,7 @@

    Hey!

    The type of the machine data member; usually omitted

Parameters

  • tree: JssmParseTree

    The parse tree to be boiled down into a machine config

    -

Returns JssmGenericConfig<mDT>

Returns JssmGenericConfig<mDT>

  • Create a state machine from an implementation string. This is one of the two main paths for working with JSSM, alongside sm.

    Use this method when you want to conveniently pull a state machine from a @@ -57,7 +57,7 @@

    Hey!

    The FSL code to evaluate

  • Optional ExtraConstructorFields: Partial<JssmGenericConfig<mDT>>

    Extra non-code configuration to pass at creation time

    -

Returns Machine<mDT>

  • is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean

Returns Machine<mDT>

  • is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean
  • An internal convenience wrapper for parsing then compiling a machine string. Not generally meant for external use. Please see compile or sm.

    @@ -65,7 +65,7 @@

    Hey!

    The type of the machine data member; usually omitted

Parameters

  • plan: string

    The FSL code to be evaluated and built into a machine config

    -

Returns JssmGenericConfig<mDT>

Returns JssmGenericConfig<mDT>

  • This method wraps the parser call that comes from the peg grammar, parse. Generally neither this nor that should be used directly unless you mean to develop plugins or extensions for the machine.

    @@ -96,7 +96,7 @@

    Hey!

    The FSL code to be evaluated

  • Optional options: <internal>.Object

    Things to control about the instance

    -

Returns any

Returns any

  • Create a state machine from a template string. This is one of the two main paths for working with JSSM, alongside from.

    Use this method when you want to work directly and conveniently with a @@ -110,7 +110,7 @@

    Hey!

    The assembled code

  • Rest ...remainder: any[]

    The mechanic for template argument insertion

    -

Returns Machine<mDT>

Returns Machine<mDT>