statifier 0.0.1 → 0.1.0

data/lib/statifier/interpreter/entering.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # The pseudocode's three `computeEntrySet` out-parameters, one value:
+    # `states_to_enter`; `states_for_default_entry`, the compound states
+    # among them entered by default rather than as a target; and
+    # `default_history_content`, by a history's parent, the `t_index` of the
+    # history's default transition, whose content runs because the history
+    # had recorded nothing. The two sets are frozen ascending Arrays and the
+    # map a frozen Hash.
+    #
+    # @api private
+    EntrySet = ::Data.define(:states_to_enter, :states_for_default_entry, :default_history_content) do
+      # The entry set with `index` added to `states_to_enter`.
+      def add(index) = with(states_to_enter: put(states_to_enter, index))
+
+      # The entry set with `index` added to `states_for_default_entry`.
+      def flag_default_entry(index) = with(states_for_default_entry: put(states_for_default_entry, index))
+
+      # The entry set with `t_index` registered as `parent`'s default
+      # history content.
+      def register_history_content(parent, t_index)
+        with(default_history_content: default_history_content.merge(parent => t_index).freeze)
+      end
+
+      private
+
+      def put(set, index) = set.include?(index) ? set : (set + [index]).sort.freeze
+    end
+
+    class EntrySet
+      # An entry set with nothing in it.
+      EMPTY = new(states_to_enter: [].freeze, states_for_default_entry: [].freeze,
+                  default_history_content: {}.freeze)
+    end
+
+    # The entry set, ported function for function from the pseudocode as
+    # the reference ports it: what a set of transitions enters. Each
+    # function threads an {EntrySet} through and answers the one it leaves,
+    # where the pseudocode writes into its out-parameters.
+    #
+    # @api private
+    module Entering
+      module_function
+
+      # `computeEntrySet`: what `transitions` enter. For each, every written
+      # target enters with its descendants, then every effective target (a
+      # history resolved to what it stands for) enters its ancestors up to
+      # the transition's domain.
+      #
+      # @return [EntrySet]
+      def compute_entry_set(snapshot, transitions)
+        transitions.reduce(EntrySet::EMPTY) do |entry_set, transition|
+          entry_set = transition.targets.reduce(entry_set) do |set, target|
+            add_descendant_states_to_enter(snapshot, target, set)
+          end
+          domain = Selection.get_transition_domain(snapshot, transition)
+          Selection.get_effective_target_states(snapshot, transition).reduce(entry_set) do |set, target|
+            add_ancestor_states_to_enter(snapshot, target, domain, set)
+          end
+        end
+      end
+
+      # `addDescendantStatesToEnter`: `index` and what enters with it, added
+      # to `entry_set`. A history restores its recorded value or, having
+      # recorded nothing, follows its default transition and registers that
+      # transition's content on its parent. A compound state is marked as
+      # entered by default and enters its initial targets. A parallel enters
+      # every region no state already in the set lies inside. Any other state
+      # enters alone.
+      #
+      # @return [EntrySet]
+      def add_descendant_states_to_enter(snapshot, index, entry_set)
+        machine = snapshot.machine
+        return enter_history_target(snapshot, index, entry_set) if machine.history?(index)
+
+        entry_set = entry_set.add(index)
+        if machine.compound?(index)
+          enter_targets(snapshot, initial_targets(machine, index), index, entry_set.flag_default_entry(index))
+        elsif machine.parallel?(index)
+          enter_uncovered_regions(snapshot, index, entry_set)
+        else
+          entry_set
+        end
+      end
+
+      # `addAncestorStatesToEnter`: every proper ancestor of `index` up to
+      # but not including `ancestor` enters, each parallel among them with
+      # its regions not yet covered. A nil `ancestor` bounds nothing.
+      #
+      # @return [EntrySet]
+      def add_ancestor_states_to_enter(snapshot, index, ancestor, entry_set)
+        machine = snapshot.machine
+        machine.proper_ancestors(index).take_while { _1 != ancestor }.reduce(entry_set) do |set, anc|
+          set = set.add(anc)
+          machine.parallel?(anc) ? enter_uncovered_regions(snapshot, anc, set) : set
+        end
+      end
+
+      # The history arm: the recorded value when there is one, else the
+      # default transition's targets with its content registered on the
+      # history's parent; either way the targets enter up to that parent.
+      def enter_history_target(snapshot, history_index, entry_set)
+        history = snapshot.machine.state(history_index)
+        recorded = snapshot.history[history_index]
+        return enter_targets(snapshot, recorded, history.parent, entry_set) unless recorded.nil?
+
+        default = history.history_default
+        targets = snapshot.machine.transitions.fetch(default).targets
+        enter_targets(snapshot, targets, history.parent, entry_set.register_history_content(history.parent, default))
+      end
+
+      # Every target's descendants, then every target's ancestors up to
+      # `ancestor`.
+      def enter_targets(snapshot, targets, ancestor, entry_set)
+        entry_set = targets.reduce(entry_set) { |set, target| add_descendant_states_to_enter(snapshot, target, set) }
+        targets.reduce(entry_set) { |set, target| add_ancestor_states_to_enter(snapshot, target, ancestor, set) }
+      end
+
+      # A compound state's default-entry targets: its `<initial>`
+      # transition's when the document wrote one, else the default the
+      # compiler resolved from the `initial` attribute or the first child.
+      def initial_targets(machine, index)
+        t_index = machine.state(index).initial_transition
+        t_index.nil? ? machine.state(index).initial : machine.transitions.fetch(t_index).targets
+      end
+
+      # Every region of the parallel `index` that no state already in the
+      # set lies inside enters with its descendants. A history child is
+      # never a region.
+      def enter_uncovered_regions(snapshot, index, entry_set)
+        machine = snapshot.machine
+        machine.child_states(index).reduce(entry_set) do |set, region|
+          covered = set.states_to_enter.any? { machine.descendant?(_1, region) }
+          covered ? set : add_descendant_states_to_enter(snapshot, region, set)
+        end
+      end
+    end
+  end
+end

data/lib/statifier/interpreter/exit_entry.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # Exit and entry, ported function for function from the pseudocode as
+    # the reference ports it; each function names the one it ports. Which
+    # transitions fire and which states each one leaves is {Selection}'s,
+    # and the entry set is {Entering}'s; this module answers, for a set of
+    # transitions that fire, what leaving and entering states means: the
+    # states to exit in exit order with the history recorded before any of
+    # them leaves, and the states to enter in entry order with, for each,
+    # the default-entry and history content to run and the completion events
+    # its entry raises.
+    #
+    # It runs no executable content. The pseudocode's `exitStates` and
+    # `enterStates` interleave the configuration's moves with content; here
+    # {exit_states} and {enter_states} answer the moves as values ({Exit},
+    # {Entry}), and the step that calls them runs each state's `<onexit>`,
+    # `<onentry>` and transition content, evaluates a final state's
+    # `<donedata>` and queues the completion events, state by state, in the
+    # order given. No content moves the configuration, so the answers do not
+    # depend on what the content does.
+    #
+    # Exit order is descending index and entry order ascending, which is
+    # document order: a descendant leaves before its ancestors and enters
+    # after them, and a parallel's regions leave in reverse document order
+    # and enter in document order.
+    #
+    # @api private
+    module ExitEntry
+      # What {exit_states} answered: `states`, the states to exit in exit
+      # order, each to run its `<onexit>` blocks and leave; `history`, the
+      # recorded history with every history child of an exiting state
+      # recorded from the configuration as it stood before any state left;
+      # and `configuration`, the configuration once they have all left.
+      Exit = ::Data.define(:states, :history, :configuration)
+
+      # A completion event an entry raises: `name`, `done.state.` and the
+      # completed state's id; `final`, the index of the final state whose
+      # entry raised it (the event's origin); and `donedata`, true when the
+      # event carries that final state's `<donedata>` (the parent's event)
+      # and false when it carries no data (a parallel's).
+      Completion = ::Data.define(:name, :final, :donedata)
+
+      # One state's entry, as {enter_states} answers it: `index`, the state;
+      # `initial_content`, the `t_index` of its `<initial>` transition when
+      # it was entered by default and its document wrote one, else nil;
+      # `history_content`, the `t_index` of the default transition a history
+      # child registered on it, else nil; `completions`, the {Completion}s
+      # its entry raises, in the order they are raised; and `stops`, true
+      # for a final state whose parent is the root, whose entry ends the
+      # execution and raises nothing.
+      Arrival = ::Data.define(:index, :initial_content, :history_content, :completions, :stops)
+
+      # What {enter_states} answered: `states`, an {Arrival} per state to
+      # enter in entry order, each to join the configuration and run, in
+      # order, its `<onentry>` blocks, its initial content, its history
+      # content and then its completions; and `configuration`, the
+      # configuration once they have all entered.
+      Entry = ::Data.define(:states, :configuration)
+
+      module_function
+
+      # `exitStates`, its moves: the exit set ({Selection.compute_exit_set})
+      # in exit order, and the history recorded over it.
+      #
+      # @return [Exit]
+      def exit_states(snapshot, transitions)
+        exit_set = Selection.compute_exit_set(snapshot, transitions)
+        states = exit_set.reverse.freeze
+        Exit.new(states:, history: record_history_values(snapshot, states),
+                 configuration: (snapshot.configuration - exit_set).freeze)
+      end
+
+      # `exitStates`' history-recording loop: for every history child of
+      # every state in `states_to_exit`, in that order, its value, each
+      # overwriting what the history had recorded. A shallow history records
+      # the state's active children, a deep one its active atomic
+      # descendants, both read from the snapshot's configuration.
+      def record_history_values(snapshot, states_to_exit)
+        machine = snapshot.machine
+        recorded = states_to_exit.each_with_object(snapshot.history.dup) do |index, history|
+          machine.state(index).history_children.each { history[_1] = recorded_value(snapshot, index, _1) }
+        end
+        recorded.freeze
+      end
+
+      # The value one history child `history_index` of `index` records.
+      def recorded_value(snapshot, index, history_index)
+        machine = snapshot.machine
+        deep = machine.state(history_index).history_type == :deep
+        snapshot.configuration.select do |active|
+          deep ? machine.atomic?(active) && machine.descendant?(active, index) : machine.state(active).parent == index
+        end.freeze
+      end
+
+      # `enterStates`, its moves: the entry set
+      # ({Entering.compute_entry_set}) in entry order, each state with the
+      # content its entry runs and the completion events it raises, read
+      # against the configuration as the states before it have joined it.
+      # `snapshot` is the one the exit left: its configuration and history
+      # after {exit_states}.
+      #
+      # @return [Entry]
+      def enter_states(snapshot, transitions)
+        entry_set = Entering.compute_entry_set(snapshot, transitions)
+        arrivals = []
+        configuration = entry_set.states_to_enter.reduce(snapshot.configuration) do |config, index|
+          entered = snapshot.with(configuration: (config | [index]).sort.freeze)
+          arrivals << arrival(entered, index, entry_set)
+          entered.configuration
+        end
+        Entry.new(states: arrivals.freeze, configuration:)
+      end
+
+      # One state's entry, read with `index` in the configuration.
+      def arrival(snapshot, index, entry_set)
+        machine = snapshot.machine
+        default_entry = entry_set.states_for_default_entry.include?(index)
+        stops = machine.final?(index) && machine.state(index).parent.zero?
+        Arrival.new(index:, initial_content: default_entry ? machine.state(index).initial_transition : nil,
+                    history_content: entry_set.default_history_content[index],
+                    completions: stops ? [].freeze : completion_events(snapshot, index), stops:)
+      end
+
+      # A final state's completion events: `done.state.` and its parent's
+      # id, carrying its `<donedata>`, then, when the parent's own parent is
+      # a parallel every region of which is now in a final state,
+      # `done.state.` and that parallel's id, carrying no data. A parent with
+      # no id raises nothing, its parallel's event included; a parallel with
+      # no id raises nothing for itself.
+      def completion_events(snapshot, index)
+        machine = snapshot.machine
+        return [].freeze unless machine.final?(index)
+
+        parent = machine.state(index).parent
+        return [].freeze unless named?(machine, parent)
+
+        parent_event = Completion.new(name: "done.state.#{machine.state(parent).id}", final: index, donedata: true)
+        [parent_event, *parallel_completion(snapshot, index, machine.state(parent).parent)].freeze
+      end
+
+      # The parallel's event, when `grandparent` is a parallel with an id
+      # every region of which is in a final state.
+      def parallel_completion(snapshot, index, grandparent)
+        machine = snapshot.machine
+        return [] unless !grandparent.nil? && machine.parallel?(grandparent) && named?(machine, grandparent)
+        return [] unless machine.child_states(grandparent).all? { in_final_state?(snapshot, _1) }
+
+        [Completion.new(name: "done.state.#{machine.state(grandparent).id}", final: index, donedata: false)]
+      end
+
+      # Whether the state has a non-empty id.
+      def named?(machine, index)
+        id = machine.state(index).id
+        !id.nil? && !id.empty?
+      end
+
+      # `isInFinalState`: a compound state is in a final state when an
+      # active child is a final; a parallel when every region is,
+      # recursively. Anything else, a final itself included, is not.
+      def in_final_state?(snapshot, index)
+        machine = snapshot.machine
+        if machine.compound?(index)
+          machine.child_states(index).any? { snapshot.active?(_1) && machine.final?(_1) }
+        elsif machine.parallel?(index)
+          machine.child_states(index).all? { in_final_state?(snapshot, _1) }
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/statifier/interpreter/foreach.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    # `<foreach>`, as the reference's foreach node runs it
+    # (`Statifier.Machine.Content.Foreach` in statifier-ex), for
+    # {Content}'s block runner: the names are checked before anything else,
+    # and a failure there, or of `array`, keeps nothing.
+    #
+    # @api private
+    module Foreach
+      # A `<foreach>` `item` that is not a bare variable name.
+      IllegalItemName = ::Data.define(:name)
+
+      # A `<foreach>` `index` that is not a bare variable name.
+      IllegalIndexName = ::Data.define(:name)
+
+      # A `<foreach>` `array` that evaluated to something other than a list.
+      NotIterable = ::Data.define(:value)
+
+      # A bare variable name, the one shape a `<foreach>` `item` and `index`
+      # take.
+      NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      module_function
+
+      # `<foreach>`: the names checked, `array` evaluated once (the list is
+      # a value, so the body cannot change what is iterated), the item and
+      # index declared undefined when the datamodel does not hold them, and
+      # the body run once per element with the item and the zero-based index
+      # bound. Unlike an `<assign>`, it may bind a name the datamodel does not
+      # yet hold. A body failure keeps what earlier iterations wrote.
+      def execute(run, node, stamp)
+        collection = iterated(run.context, node)
+        return [run, collection] unless collection.is_a?(Array)
+
+        collection.each_with_index.reduce([run.with(context: declare(run.context, node)), nil]) do |(at, _), (value, i)|
+          after, reason = Content.nested(at.with(context: bind_iteration(at.context, node, value, i)), node.content,
+                                         stamp)
+          break [after, reason] unless reason.nil?
+
+          [after, nil]
+        end
+      end
+
+      # The context with one iteration's item and index bound.
+      def bind_iteration(context, node, value, position)
+        context = context.bind(node.item, value)
+        node.index.nil? ? context : context.bind(node.index, position)
+      end
+
+      # The list a `<foreach>` iterates, or the reason it cannot: an illegal
+      # item, then an illegal index, then a failed `array`, then a value that
+      # is not a list.
+      def iterated(context, node)
+        illegal = illegal_name(node.item, IllegalItemName) || (node.index && illegal_name(node.index, IllegalIndexName))
+        return illegal if illegal
+
+        evaluated = Datamodel.evaluate(context, node.array)
+        return evaluated.error unless evaluated.ok?
+
+        evaluated.value.is_a?(Array) ? evaluated.value : NotIterable.new(value: evaluated.value)
+      end
+
+      # Why `name` cannot be bound, or nil: a system variable's root, or not a
+      # bare name.
+      def illegal_name(name, illegal)
+        return Datamodel::SystemVariable.new(root: name) if name.start_with?("_")
+
+        NAME.match?(name) ? nil : illegal.new(name:)
+      end
+
+      # The context with the item and the index (when written) each declared
+      # undefined unless the datamodel holds it, so both are bound even when
+      # the list is empty.
+      def declare(context, node)
+        [node.item, node.index].compact.reduce(context) do |declared, name|
+          declared.data.key?(name) ? declared : declared.bind(name, Predicator::UNDEFINED)
+        end
+      end
+    end
+  end
+end

data/lib/statifier/interpreter/invoke/arguments.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    module Invoke
+      # An `<invoke>`'s arguments resolved against one context, in the
+      # reference's order (`invoke_one`'s `with` in `Statifier.Interpreter`,
+      # statifier-ex): the type, the source, the `namelist` and `<param>`
+      # values in document order, then `<content>`. The first failure
+      # abandons the whole element, unlike a `<donedata>` param, which fails
+      # alone.
+      #
+      # @api private
+      module Arguments
+        module_function
+
+        # The resolved `type:`, `src:`, `params:` and `content:` as a Hash,
+        # or the reason the first that failed carries.
+        def resolve(context, invoke)
+          resolved = {}
+          { type: invoke.type, src: invoke.src }.each do |key, expr|
+            evaluated = expr.nil? ? Send::NONE : Datamodel.evaluate(context, expr)
+            return evaluated.error unless evaluated.ok?
+
+            resolved[key] = evaluated.value
+          end
+          rest(context, invoke, resolved)
+        end
+
+        # The params and the content, after the type and the source.
+        def rest(context, invoke, resolved)
+          pairs = Send.resolve_params(context, invoke.namelist + invoke.params)
+          return pairs.error unless pairs.ok?
+
+          content = content(context, invoke.content)
+          return content.error unless content.ok?
+
+          resolved.merge(params: Send.params_data(pairs.value), content: content.value)
+        end
+
+        # The `<content>` child's data: nil for none, its body read as a
+        # `<send>`'s is ({Send.text_data}), or its `expr`'s value.
+        def content(context, content)
+          return Send::NONE if content.nil?
+          return Send.value(Send.text_data(content.value)) if content.is_a?(Machine::Static)
+
+          Datamodel.evaluate(context, content)
+        end
+      end
+    end
+  end
+end

data/lib/statifier/interpreter/invoke/passes.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Interpreter
+    module Invoke
+      # The finalize and autoforward pass and the cancel on exit, as
+      # {Invoke} says.
+      #
+      # @api private
+      module Passes
+        module_function
+
+        # `for state in configuration: for inv in state.invoke: if
+        # inv.invokeid == externalEvent.invokeid: applyFinalize(inv,
+        # externalEvent); if inv.autoforward: send(inv.id, externalEvent)`,
+        # run after `_event` is set and before selection, with its
+        # {Effect::Trace::FinalizeAutoforward} last. The configuration is
+        # walked in document order and each state's invocations in document
+        # order; one that is not live is passed over. The two tests are
+        # independent: a live invocation that matches and forwards does
+        # both, its `<finalize>` first.
+        #
+        # @return [Array] `[state, effects]`
+        def finalize_autoforward(state, event)
+          return [state, trace(state, event, [], [])] if state.active_invocations.empty?
+
+          passed, effects = state.configuration.reduce([state, []]) do |acc, index|
+            state.machine.state(index).invoke.reduce(acc) { |inner, invoke| pass_one(inner, index, invoke, event) }
+          end
+          [passed, effects + trace(passed, event, finalized(state, event), forwarded(effects))]
+        end
+
+        # The live invocations whose id the event carries.
+        def finalized(state, event) = state.active_invocations.values.select { _1 == event.invokeid }.uniq
+
+        # The invocations the pass forwarded the event to, in order.
+        def forwarded(effects) = effects.grep(Effect::Autoforward).map(&:invoke_id)
+
+        # The pass's trace.
+        def trace(state, event, finalized, forwarded)
+          Blocks.traced(state, Effect::Trace::FinalizeAutoforward, event:, finalized:, forwarded:)
+        end
+
+        # One `<invoke>`'s body of the pass.
+        def pass_one((state, effects), index, invoke, event)
+          invoke_id = state.active_invocations[[index, invoke.index]]
+          return [state, effects] if invoke_id.nil?
+
+          stepped = invoke_id == event.invokeid ? finalize(state, index, invoke, event) : none(state)
+          [stepped.state, effects + stepped.effects + forward(stepped.state, index, invoke, invoke_id, event)]
+        end
+
+        # A step that changes nothing.
+        def none(state) = Stepped.new(state:, effects: [])
+
+        # The {Effect::Autoforward} of an invocation that sets
+        # `autoforward`.
+        def forward(state, index, invoke, invoke_id, event)
+          return [] unless invoke.autoforward
+
+          [Effect::Autoforward.new(invoke_id:, state_index: index, event:, **state.counters)]
+        end
+
+        # `applyFinalize`: no `<finalize>` does nothing; an empty one writes
+        # the returned values back ({auto_assign}); any other runs as a block
+        # owned by `{kind: :finalize, state_index:, invoke_index:}`.
+        #
+        # @return [Stepped]
+        def finalize(state, index, invoke, event)
+          block = invoke.finalize
+          return none(state) if block.nil?
+          return auto_assign(state, index, invoke, event.data) if block.content.empty?
+
+          Blocks.run_block(state, { kind: :finalize, state_index: index, invoke_index: invoke.index }, block.content)
+        end
+
+        # An empty `<finalize>`: each `namelist` entry and each `<param
+        # location>` whose name the event's data, a map, carries is written
+        # as by `<assign>` with that value, each write answering an
+        # {Effect::DatamodelChange} in the order written. A write that fails
+        # raises `error.execution` (origin `{kind: :finalize, state_index:,
+        # invoke_index:}`) and leaves the other writes standing.
+        #
+        # @return [Stepped]
+        def auto_assign(state, index, invoke, data)
+          return none(state) unless data.is_a?(Hash)
+
+          owner = { kind: :finalize, state_index: index, invoke_index: invoke.index }
+          targets(invoke).select { data.key?(_1.name) }.reduce(none(state)) do |acc, param|
+            acc.then_step(write(acc.state, param.expr.source, data[param.name], owner))
+          end
+        end
+
+        # The `namelist` entries and `<param location>`s an empty
+        # `<finalize>` may write, the ones that compiled.
+        def targets(invoke)
+          (invoke.namelist + invoke.params).select { _1.kind == :location && _1.expr.is_a?(Machine::Compiled) }
+        end
+
+        # One write of an empty `<finalize>`.
+        #
+        # @return [Stepped]
+        def write(state, source, value, owner)
+          written = Datamodel::Location.write(state.context, source, value)
+          return none(state.raise_failure(owner, written.error)) unless written.ok?
+
+          after = state.with(datamodel: Ractor.make_shareable(written.context.data))
+          Stepped.new(state: after, effects: [Invoke.change(after, written, source, value, owner)])
+        end
+
+        # `for inv in s.invoke: cancelInvoke(inv)`: an {Effect::CancelInvoke}
+        # per live invocation of the state at `index`, in document order,
+        # each no longer live after it. Run after the state's `<onexit>`
+        # blocks and before it leaves the configuration.
+        #
+        # @return [Stepped]
+        def cancel_invocations(state, index)
+          state.machine.state(index).invoke.reduce(none(state)) do |acc, invoke|
+            acc.then_step(cancel_one(acc.state, index, invoke.index))
+          end
+        end
+
+        # One invocation's `cancelInvoke(inv)`, nothing when it is not live.
+        #
+        # @return [Stepped]
+        def cancel_one(state, index, invoke_index)
+          key = [index, invoke_index]
+          invoke_id = state.active_invocations[key]
+          return none(state) if invoke_id.nil?
+
+          after = state.with(active_invocations: state.active_invocations.except(key).freeze)
+          Stepped.new(state: after, effects: [cancel_effect(after, invoke_id, index)])
+        end
+
+        # The {Effect::CancelInvoke}.
+        def cancel_effect(state, invoke_id, index)
+          Frozen.copy(Effect::CancelInvoke.new(invoke_id:, state_index: index, **state.counters,
+                                               caller_context: state.caller_context))
+        end
+      end
+    end
+  end
+end