From 75f33ebba2446c48990e268a8a8e5f28bdd62efb Mon Sep 17 00:00:00 2001 From: John Haugeland Date: Sun, 22 May 2022 14:44:19 -0700 Subject: [PATCH] Document is_final and state_is_final, fixes StoneCypher/fsl#796, fixes StoneCypher/fsl#797 --- benchmark/results/general.chart.html | 14 +-- benchmark/results/general.json | 126 +++++++++++++-------------- dist/es6/jssm.d.ts | 36 ++++++++ dist/es6/jssm.js | 36 ++++++++ dist/es6/version.js | 2 +- dist/jssm.es5.cjs.js | 2 +- dist/jssm.es5.cjs.nonmin.js | 38 +++++++- dist/jssm.es5.iife.js | 2 +- dist/jssm.es5.iife.nonmin.js | 38 +++++++- docs/docs/assets/custom.css | 5 +- docs/docs/classes/Machine.html | 20 ++++- docs/docs/modules.html | 22 ++--- docs/typedoc-addon.css | 5 +- jssm.d.ts | 36 ++++++++ package.json | 2 +- src/site/typedoc-addon.css | 5 +- src/ts/jssm.ts | 53 +++++++++++ src/ts/version.ts | 2 +- 18 files changed, 346 insertions(+), 98 deletions(-) diff --git a/benchmark/results/general.chart.html b/benchmark/results/general.chart.html index 0761867b..f4a04906 100644 --- a/benchmark/results/general.chart.html +++ b/benchmark/results/general.chart.html @@ -28,7 +28,7 @@
- +
Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Machine<mDT>

Type parameters

  • mDT

Hierarchy

  • Machine

Index

Constructors

Properties

Methods

Constructors

constructor

  • new Machine<mDT>(__namedParameters: JssmGenericConfig<mDT>): Machine<mDT>

  • Type parameters

    • mDT

    Parameters

    • __namedParameters: JssmGenericConfig<mDT>

    Returns Machine<mDT>

Properties

_actions

_actions: Map<string, Map<string, number>>

_any_action_hook

_any_action_hook: Function

_any_transition_hook

_any_transition_hook: Function

_arrange_declaration

_arrange_declaration: string[][]

_arrange_end_declaration

_arrange_end_declaration: string[][]

_arrange_start_declaration

_arrange_start_declaration: string[][]

_dot_preamble

_dot_preamble: string

_edge_map

_edge_map: Map<string, Map<string, number>>

_edges

_edges: JssmTransition<mDT>[]

_entry_hooks

_entry_hooks: Map<string, Function>

_exit_hooks

_exit_hooks: Map<string, Function>

_flow

_flow: FslDirection

_forced_transition_hook

_forced_transition_hook: Function

Optional _fsl_version

_fsl_version?: string

_global_action_hooks

_global_action_hooks: Map<string, Function>

_graph_layout

_graph_layout: JssmLayout

_has_basic_hooks

_has_basic_hooks: boolean

_has_entry_hooks

_has_entry_hooks: boolean

_has_exit_hooks

_has_exit_hooks: boolean

_has_global_action_hooks

_has_global_action_hooks: boolean

_has_hooks

_has_hooks: boolean

_has_named_hooks

_has_named_hooks: boolean

_has_transition_hooks

_has_transition_hooks: boolean

_hooks

_hooks: Map<string, Function>

_instance_name

_instance_name: string

Optional _machine_author

_machine_author?: string[]

Optional _machine_comment

_machine_comment?: string

Optional _machine_contributor

_machine_contributor?: string[]

Optional _machine_definition

_machine_definition?: string

Optional _machine_language

_machine_language?: string

Optional _machine_license

_machine_license?: string

Optional _machine_name

_machine_name?: string

Optional _machine_version

_machine_version?: string

_main_transition_hook

_main_transition_hook: Function

_named_hooks

_named_hooks: Map<string, Function>

_named_transitions

_named_transitions: Map<string, number>

Optional _raw_state_declaration

_raw_state_declaration?: Object[]

_reverse_action_targets

_reverse_action_targets: Map<string, Map<string, number>>

_reverse_actions

_reverse_actions: Map<string, Map<string, number>>

_standard_transition_hook

_standard_transition_hook: Function

_state

_state: string

_state_declarations

_state_declarations: Map<string, JssmStateDeclaration>

_states

_states: Map<string, JssmGenericState>

_theme

_theme: FslTheme

Methods

_new_state

  • _new_state(state_config: JssmGenericState): string

  • Parameters

    • state_config: JssmGenericState

    Returns string

action

  • action(actionName: string, newData?: mDT): boolean

  • Parameters

    • actionName: string
    • Optional newData: mDT

    Returns boolean

actions

  • actions(whichState?: string): string[]

  • Parameters

    • whichState: string = ...

    Returns string[]

current_action_edge_for

  • current_action_edge_for(action: string): JssmTransition<mDT>

  • Parameters

    • action: string

    Returns JssmTransition<mDT>

current_action_for

  • current_action_for(action: string): number

  • Parameters

    • action: string

    Returns number

dot_preamble

  • dot_preamble(): string

edges_between

  • edges_between(from: string, to: string): JssmTransition<mDT>[]

  • Parameters

    • from: string
    • to: string

    Returns JssmTransition<mDT>[]

flow

  • flow(): FslDirection

force_transition

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

  • Parameters

    • newState: string
    • Optional newData: mDT

    Returns boolean

fsl_version

  • fsl_version(): string

get_transition_by_state_names

  • get_transition_by_state_names(from: string, to: string): number

  • Parameters

    • from: string
    • to: string

    Returns number

graph_layout

  • graph_layout(): string

has_completes

  • has_completes(): boolean

has_state

  • has_state(whichState: string): boolean

theme

  • theme(): FslTheme

transition

  • transition(newState: string, newData?: mDT): boolean

  • Parameters

    • newState: string
    • Optional newData: mDT

    Returns boolean

transition_impl

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

  • Parameters

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

    Returns boolean

valid_action

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

  • Parameters

    • action: string
    • Optional _newData: mDT

    Returns boolean

valid_force_transition

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

  • Parameters

    • newState: string
    • Optional _newData: mDT

    Returns boolean

valid_transition

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

  • Parameters

    • newState: string
    • Optional _newData: mDT

    Returns boolean

Generated using TypeDoc

\ No newline at end of file diff --git a/docs/docs/modules.html b/docs/docs/modules.html index ec287cb2..f8ffa794 100644 --- a/docs/docs/modules.html +++ b/docs/docs/modules.html @@ -1,21 +1,21 @@ -jssm
Options
All
  • Public
  • Public/Protected
  • All
Menu

jssm

Index

Classes

Variables

Functions

Variables

Const gviz_shapes

gviz_shapes: string[] = ...

Const histograph

histograph: Function = ...
+jssm
Options
All
  • Public
  • Public/Protected
  • All
Menu

jssm

Index

Classes

Variables

Functions

Variables

Const gviz_shapes

gviz_shapes: string[] = ...

Const histograph

histograph: Function = ...

Returns the histograph of an array as a Map. Makes no attempt to cope with deep equality; will fail for complex contents, as such.

import { histograph } from './jssm';

histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
-

Const named_colors

named_colors: string[] = ...

Const shapes

shapes: string[] = gviz_shapes

Const version

version: string = "5.65.8"

Const weighted_histo_key

weighted_histo_key: Function = ...

Const weighted_rand_select

weighted_rand_select: Function = ...

Const weighted_sample_select

weighted_sample_select: Function = ...

Functions

arrow_direction

  • arrow_direction(arrow: JssmArrow): JssmArrowDirection

Const named_colors

named_colors: string[] = ...

Const shapes

shapes: string[] = gviz_shapes

Const version

version: string = "5.65.9"

Const weighted_histo_key

weighted_histo_key: Function = ...

Const weighted_rand_select

weighted_rand_select: Function = ...

Const weighted_sample_select

weighted_sample_select: Function = ...

Functions

arrow_direction

  • arrow_direction(arrow: JssmArrow): JssmArrowDirection

  • Return the direction of an arrow - right, left, or both.

    import { arrow_direction } from './jssm';

    arrow_direction('->');    // 'right'
    arrow_direction('<~=>');  // 'both'
    -

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowDirection

arrow_left_kind

  • arrow_left_kind(arrow: JssmArrow): JssmArrowKind
  • +

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowDirection

arrow_left_kind

  • arrow_left_kind(arrow: JssmArrow): JssmArrowKind

  • Return the direction of an arrow - right, left, or both.

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

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowKind

arrow_right_kind

  • arrow_right_kind(arrow: JssmArrow): JssmArrowKind
  • +

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowKind

arrow_right_kind

  • arrow_right_kind(arrow: JssmArrow): JssmArrowKind

  • Return the direction of an arrow - right, left, or both.

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

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowKind

compile

  • compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>
  • +

    Parameters

    • arrow: JssmArrow

    Returns JssmArrowKind

compile

  • compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>

  • 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 @@ -38,7 +38,7 @@

    Hey!

    Method {@link from}:

    import * as jssm from './jssm';

    const toggle = jssm.from('up <=> down;');
    -

    Type parameters

    • mDT

    Parameters

    • tree: JssmParseTree

    Returns JssmGenericConfig<mDT>

from

  • from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>>): Machine<mDT>
  • +

    Type parameters

    • mDT

    Parameters

    • tree: JssmParseTree

    Returns JssmGenericConfig<mDT>

from

  • from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>>): Machine<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 @@ -46,11 +46,11 @@

    Hey!

    template expression.

    import * as jssm from './jssm';

    const switch = jssm.from('on <=> off;');
    -

    Type parameters

    • mDT

    Parameters

    • MachineAsString: string
    • Optional ExtraConstructorFields: Partial<JssmGenericConfig<mDT>>

    Returns Machine<mDT>

make

  • make<mDT>(plan: string): JssmGenericConfig<mDT>
  • +

    Type parameters

    • mDT

    Parameters

    • MachineAsString: string
    • Optional ExtraConstructorFields: Partial<JssmGenericConfig<mDT>>

    Returns Machine<mDT>

make

  • make<mDT>(plan: string): JssmGenericConfig<mDT>

  • An internal convenience wrapper for parsing then compiling a machine string. Not generally meant for external use. Please see compile or sm.

    -

    Type parameters

    • mDT

    Parameters

    • plan: string

    Returns JssmGenericConfig<mDT>

parse

  • parse(input: string, options?: Object): any
  • +

    Type parameters

    • mDT

    Parameters

    • plan: string

    Returns JssmGenericConfig<mDT>

parse

  • parse(input: string, options?: Object): any

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

    @@ -77,11 +77,11 @@

    Hey!

    wrap_parse itself is an internal convenience method for alting out an object as the options call. Not generally meant for external use.

    -

    Parameters

    • input: string
    • Optional options: Object

    Returns any

seq

  • seq(n: number): number[]
  • +

    Parameters

    • input: string
    • Optional options: Object

    Returns any

seq

  • seq(n: number): number[]

  • Returns, for a non-negative integer argument n, the series [0 .. n].

    import { seq } from './jssm';

    seq(5);  // [0, 1, 2, 3, 4]
    seq(0);  // []
    -

    Parameters

    • n: number

    Returns number[]

sm

  • sm<mDT>(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>
  • +

    Parameters

    • n: number

    Returns number[]

sm

  • sm<mDT>(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 @@ -89,7 +89,7 @@

    Hey!

    dynamic strings.

    import * as jssm from './jssm';

    const switch = jssm.from('on <=> off;');
    -

    Type parameters

    • mDT

    Parameters

    • template_strings: TemplateStringsArray
    • Rest ...remainder: any[]

    Returns Machine<mDT>

transfer_state_properties

  • transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration
  • +

    Type parameters

    • mDT

    Parameters

    • template_strings: TemplateStringsArray
    • Rest ...remainder: any[]

    Returns Machine<mDT>

transfer_state_properties

  • transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration

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

    diff --git a/docs/typedoc-addon.css b/docs/typedoc-addon.css index 5b934f71..6e0f9953 100644 --- a/docs/typedoc-addon.css +++ b/docs/typedoc-addon.css @@ -1,5 +1,6 @@ :root { --color-background: #def; } -body .tsd-page-title { background-color: #bdf; } -body .tsd-page-toolbar { background-color: #acf; border-bottom-color: #9be; } +body .tsd-page-title { background-color: #bdf; } +body .tsd-page-toolbar { background-color: #acf; border-bottom-color: #9be; } +body .with-border-bottom { background-color: #acf; border-color: #9be; } diff --git a/jssm.d.ts b/jssm.d.ts index 957d2b07..bec8f3bc 100644 --- a/jssm.d.ts +++ b/jssm.d.ts @@ -213,6 +213,11 @@ declare class Machine { _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); + /******** + * + * Internal method for fabricating states. Not meant for external use. + * + */ _new_state(state_config: JssmGenericState): StateType; /********* * @@ -230,7 +235,38 @@ declare class Machine { * */ 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; diff --git a/package.json b/package.json index 77bb7f83..6cafe3a5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "jssm", - "version": "5.65.8", + "version": "5.65.9", "engines": { "node": ">=10.0.0" }, diff --git a/src/site/typedoc-addon.css b/src/site/typedoc-addon.css index 5b934f71..6e0f9953 100644 --- a/src/site/typedoc-addon.css +++ b/src/site/typedoc-addon.css @@ -1,5 +1,6 @@ :root { --color-background: #def; } -body .tsd-page-title { background-color: #bdf; } -body .tsd-page-toolbar { background-color: #acf; border-bottom-color: #9be; } +body .tsd-page-title { background-color: #bdf; } +body .tsd-page-toolbar { background-color: #acf; border-bottom-color: #9be; } +body .with-border-bottom { background-color: #acf; border-color: #9be; } diff --git a/src/ts/jssm.ts b/src/ts/jssm.ts index 5f0ddeba..75f4df9f 100644 --- a/src/ts/jssm.ts +++ b/src/ts/jssm.ts @@ -903,6 +903,16 @@ class Machine { } + + + + + /******** + * + * Internal method for fabricating states. Not meant for external use. + * + */ + _new_state(state_config: JssmGenericState): StateType { if (this._states.has(state_config.name)) { @@ -947,15 +957,58 @@ class Machine { */ + + + /******** + * + * 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 { 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(): boolean { // return ((!this.is_changing()) && this.state_is_final(this.state())); return this.state_is_final(this.state()); } + + + + graph_layout(): string { return this._graph_layout; } diff --git a/src/ts/version.ts b/src/ts/version.ts index b8e00f57..e9eb429e 100644 --- a/src/ts/version.ts +++ b/src/ts/version.ts @@ -1,3 +1,3 @@ -const version: string = "5.65.8"; +const version: string = "5.65.9"; export { version };