statifier 0.0.1 → 0.1.0

data/lib/statifier/datamodel/stores.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # Reads the stores of a compiled statement program and rewrites them,
+    # the mechanism {Program} uses to give a `<script>` the reference's
+    # outcome on a published predicator that offers no protected roots and
+    # answers no context for a run that stops.
+    #
+    # The instruction list is predicator's public, versioned shape (the
+    # instruction set `Predicator.isa_version` names). A `store n` pops a
+    # value and a path of `n` segments, and the path's first segment, its
+    # root, is pushed by a `lit` of the root's name, since an assignment's
+    # target begins with a name. The stack depth before every instruction is
+    # computed by following every jump, so the instruction that pushed a
+    # store's root is the last one before the store at the depth the root
+    # sits at: everything between keeps the root on the stack.
+    #
+    # @api private
+    module Stores
+      # The host function a store into a protected root becomes: it refuses,
+      # so the run stops at the attempt. No source can call it: a name in
+      # source never holds a colon.
+      GUARD = "statifier:protected"
+
+      # The host function each other store reports its root's new value to.
+      NOTE = "statifier:wrote"
+
+      # The host function a reachable store whose root cannot be read
+      # becomes: it refuses, so such a store never writes unguarded. None of
+      # predicator's compiled programs has one.
+      UNREAD = "statifier:unread"
+
+      # The jumps, and whether each counts backward.
+      JUMPS = { "jump" => false, "pop_jump_if_falsy" => false, "jump_if_falsy_or_pop" => false,
+                "jump_if_true_or_pop" => false, "jump_backward" => true }.freeze
+
+      # The instruction-set version the tables here were written for. On any
+      # other version no store is read: every store becomes {UNREAD}.
+      ISA_VERSION = 6
+
+      # The stack effect of each instruction of that version whose effect is
+      # fixed, the ones that leave the depth as it is listed too.
+      EFFECTS = {
+        "lit" => 1, "load" => 1, "object_new" => 1, "duration" => 1, "pop" => -1,
+        "compare" => -1, "add" => -1, "subtract" => -1, "multiply" => -1, "divide" => -1, "modulo" => -1,
+        "bracket_access" => -1, "in" => -1, "contains" => -1, "object_set" => -1,
+        "not" => 0, "unary_bang" => 0, "unary_minus" => 0, "access" => 0, "relative_date" => 0, "cast" => 0
+      }.freeze
+
+      # The instructions whose effect is read from an operand.
+      COUNTED = %w[make_list call store].freeze
+
+      # Every instruction of that version the depths are computed over. A
+      # program holding any other (a retired one or a later version's) has no
+      # store read: every store becomes {UNREAD}.
+      OPCODES = (EFFECTS.keys + COUNTED + JUMPS.keys).freeze
+
+      module_function
+
+      # `instructions` with every store into one of `protected_roots` made a
+      # call of {GUARD} with its root, a store whose root cannot be read a
+      # call of {UNREAD}, and every other store followed by a call of {NOTE}
+      # with its root's name and value; every jump moved so it lands where it
+      # landed before.
+      def guarded(instructions, protected_roots)
+        roots = roots(instructions)
+        pieces = instructions.each_with_index.map { |instruction, at| piece(instruction, at, roots, protected_roots) }
+        starts = pieces.each_with_object([0]) { |piece, acc| acc << (acc.last + piece.size) }
+        pieces.each_with_index.flat_map { |piece, at| relocated(piece, at, starts) }
+      end
+
+      # The root each reachable store writes, by the store's index: the
+      # name, or nil for a store whose root is not a named `lit` (none of
+      # predicator's compiled programs has one), and nil for every store of
+      # a program whose stores cannot be read ({readable?}).
+      def roots(instructions)
+        return unread(instructions) unless readable?(instructions)
+
+        depths = depths(instructions)
+        instructions.each_with_index.filter_map do |(opcode, count), at|
+          next unless opcode == "store" && depths[at]
+
+          [at, root_name(instructions, pusher(depths, at, depths[at] - count - 1))]
+        end.to_h
+      end
+
+      # Whether the stores of `instructions` can be read: the instruction set
+      # is the version the tables were written for and every instruction is
+      # one of {OPCODES}.
+      def readable?(instructions)
+        Predicator.isa_version == ISA_VERSION && instructions.all? { OPCODES.include?(_1.first) }
+      end
+
+      # Every store of `instructions`, none read.
+      def unread(instructions)
+        instructions.each_index.select { instructions[_1].first == "store" }.to_h { [_1, nil] }
+      end
+
+      # The last instruction before `at` that a path reaches at `depth` or
+      # below: the one that pushed the slot at `depth`.
+      def pusher(depths, at, depth) = (at - 1).downto(0).find { depths[_1] && depths[_1] <= depth }
+
+      # The name the `lit` at `at` pushes, or nil.
+      def root_name(instructions, at)
+        opcode, name = at && instructions[at]
+        name if opcode == "lit" && name.is_a?(String)
+      end
+
+      # The stack depth before each instruction, nil for one no path reaches.
+      def depths(instructions)
+        depths = Array.new(instructions.size)
+        pending = [[0, 0]]
+        until pending.empty?
+          at, depth = pending.pop
+          next if at.negative? || at >= instructions.size || depths[at]
+
+          depths[at] = depth
+          pending.concat(successors(instructions[at], at, depth))
+        end
+        depths
+      end
+
+      # Where control goes after the instruction at `at`, each with the depth
+      # it arrives at.
+      def successors((opcode, operand, count), at, depth)
+        case opcode
+        when "jump" then [[at + operand, depth]]
+        when "jump_backward" then [[at - operand, depth]]
+        when "pop_jump_if_falsy" then [[at + 1, depth - 1], [at + operand, depth - 1]]
+        when "jump_if_falsy_or_pop", "jump_if_true_or_pop" then [[at + 1, depth - 1], [at + operand, depth]]
+        else [[at + 1, depth + effect(opcode, operand, count)]]
+        end
+      end
+
+      # How an instruction moves the depth.
+      def effect(opcode, operand, count)
+        case opcode
+        when "make_list" then 1 - operand
+        when "call" then 1 - count
+        when "store" then -1 - operand
+        else EFFECTS.fetch(opcode)
+        end
+      end
+
+      # What the instruction at `at` becomes, `roots` the stores read.
+      def piece(instruction, at, roots, protected_roots)
+        return [instruction] unless roots.key?(at)
+
+        root = roots[at]
+        return [["call", UNREAD, 0]] if root.nil?
+        return [["lit", root], ["call", GUARD, 1]] if protected_roots.include?(root)
+
+        [instruction, ["lit", root], ["load", root], ["call", NOTE, 2], ["pop"]]
+      end
+
+      # A piece with its jump moved to the new index of its old target; a
+      # target past the end stays past the end.
+      def relocated(piece, at, starts)
+        opcode, offset = piece.first
+        return piece unless JUMPS.key?(opcode)
+
+        backward = JUMPS.fetch(opcode)
+        target = (backward ? at - offset : at + offset).clamp(0, starts.size - 1)
+        [[opcode, backward ? starts[at] - starts[target] : starts[target] - starts[at]]]
+      end
+    end
+  end
+end

data/lib/statifier/datamodel/system_variables.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # The specification's system variables (section 5.10) as datamodel
+    # values, as the reference writes them. A field with no value is
+    # `Predicator::UNDEFINED`, never nil, which is predicator's null.
+    #
+    # @api private
+    module SystemVariables
+      # The SCXML Event I/O Processor's type URI, the key of its
+      # `_ioprocessors` entry.
+      SCXML_EVENT_PROCESSOR = "http://www.w3.org/TR/scxml/#SCXMLEventProcessor"
+
+      module_function
+
+      # The address a session is reached at through the SCXML Event I/O
+      # Processor.
+      def scxml_location(session_id) = "#_scxml_#{session_id}"
+
+      # The four system variables before any event. `_sessionid` is the id
+      # the host minted; `_name` the chart's name, undefined when it has
+      # none; `_event` declared with no value, so a read before the first
+      # event answers undefined rather than failing; `_ioprocessors` an entry
+      # per registered send type (`entries`, by type) and the SCXML Event I/O
+      # Processor's, which a registered type of the same spelling never
+      # replaces.
+      def initial(session_id:, name:, entries: {})
+        {
+          "_sessionid" => session_id,
+          "_name" => name.nil? ? Predicator::UNDEFINED : name,
+          "_event" => Predicator::UNDEFINED,
+          "_ioprocessors" => entries.merge(SCXML_EVENT_PROCESSOR => { "location" => scxml_location(session_id) })
+        }.freeze
+      end
+
+      # A session's starting datamodel: the host's roots with the system
+      # variables over them, so a host value under a system variable's name
+      # never survives.
+      def seed(host, session_id:, name:, entries: {}) = host.merge(initial(session_id:, name:, entries:)).freeze
+
+      # The fields of `_event` an event may not carry.
+      OPTIONAL_FIELDS = %i[sendid origin origintype invokeid].freeze
+
+      # `_event`'s value for an event: its name, its type (`:internal`,
+      # `:external` or `:platform`) as text, each of {OPTIONAL_FIELDS}
+      # (keywords in `optional`) undefined when the event has none, and its
+      # data as it is.
+      #
+      # @raise [ArgumentError] for a keyword that names no field of `_event`
+      def event(name:, type:, data:, **optional)
+        unknown = optional.keys - OPTIONAL_FIELDS
+        raise ArgumentError, "unknown _event fields: #{unknown.inspect}" unless unknown.empty?
+
+        fields = OPTIONAL_FIELDS.to_h { [_1.to_s, absent(optional[_1])] }
+        { "name" => name, "type" => type.to_s, **fields, "data" => data }.freeze
+      end
+
+      # `_event`'s value for `event`, a {Statifier::Event} ({event}).
+      def of_event(event) = event(**event.to_h.slice(:name, :type, :data, *OPTIONAL_FIELDS))
+
+      # The datamodel with `_event` set to `event_value` ({event}).
+      def put_event(data, event_value) = data.merge("_event" => event_value).freeze
+
+      # nil, a field the event does not carry, as undefined.
+      def absent(value) = value.nil? ? Predicator::UNDEFINED : value
+    end
+  end
+end

data/lib/statifier/datamodel.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "predicator"
+
+require_relative "machine"
+require_relative "datamodel/reasons"
+require_relative "datamodel/reason_value"
+require_relative "datamodel/system_variables"
+require_relative "datamodel/stores"
+require_relative "datamodel/program"
+require_relative "datamodel/location"
+require_relative "datamodel/data_binding"
+require_relative "datamodel/delay"
+
+module Statifier
+  # The datamodel binding: how a chart's expressions reach predicator, the
+  # one expression language, as they reach it in the reference.
+  #
+  # The datamodel is a Hash of String root to predicator value. Every
+  # evaluation runs through `Predicator.evaluate` (a condition, a value) or
+  # `Predicator.execute` (a `<script>` program) against a {Context}: the
+  # datamodel, `In()` as a host function over the configuration the context
+  # was built with, the unbound policy {UNBOUND} and the clock the host
+  # passed for the call. A context is built per evaluation site and is never
+  # kept: `In()` reads a configuration that moves at every microstep, and
+  # `_event` is rewritten for every event.
+  #
+  # Nothing here raises on a failed evaluation. A failure is answered as a
+  # value carrying its reason, and the interpreter turns it into the
+  # `error.execution` platform event the reference raises (an {Event});
+  # the `<data>` binding ({DataBinding}) answers its failures the same way.
+  #
+  # @api private
+  module Datamodel
+    # The unbound policy every evaluation passes: a load of a root the
+    # datamodel does not hold fails at the load, as the reference evaluates.
+    # A declared root with no value holds `Predicator::UNDEFINED` instead,
+    # and reads as undefined.
+    UNBOUND = :error
+
+    # One evaluation site's view: `data`, the datamodel; `machine` and
+    # `configuration` (the indexes of the active states), which `In()`
+    # reads; and `clock`, the host's clock for the call, nil for
+    # predicator's own.
+    Context = ::Data.define(:data, :machine, :configuration, :clock) do
+      # The context with `root` bound to `value`, everything else carried
+      # over: safe only inside the evaluation site that built this context.
+      def bind(root, value) = with(data: data.merge(root => value).freeze)
+
+      # The options an evaluation of this context passes to predicator.
+      def options = { functions: { "In" => Datamodel.in_state(machine, configuration) }, on_unbound: UNBOUND, clock: }
+    end
+
+    module_function
+
+    # The context one evaluation site runs against.
+    def context(data, machine, configuration, clock: nil) = Context.new(data:, machine:, configuration:, clock:)
+
+    # `In(stateId)` over `configuration`: true when the id names a state of
+    # `machine` that is active, false for an inactive state and for an id
+    # the chart never declared, as the reference answers. It takes exactly
+    # one argument.
+    def in_state(machine, configuration)
+      lambda do |state_id|
+        index = machine.id_to_index[state_id]
+        !index.nil? && configuration.include?(index)
+      end
+    end
+
+    # Evaluates `expr` (a {Machine::Compiled}, a {Machine::Static} or a
+    # {Machine::Invalid}) against `context`. A static value comes back
+    # untouched; a compiled one runs through `Predicator.evaluate`; an
+    # invalid one answers the compile refusal it carries, the deferral the
+    # reference raises when the node runs.
+    #
+    # @return [Evaluated] the value, or the reason it failed
+    def evaluate(context, expr)
+      case expr
+      when Machine::Static then Evaluated.new(value: expr.value, error: nil)
+      when Machine::Invalid then Evaluated.new(value: nil, error: expr.error)
+      else
+        result = Predicator.evaluate(expr.instructions, context.data, **context.options)
+        error = EvaluatorError.new(source: expr.source, error: result.error) unless result.ok?
+        Evaluated.new(value: result.value, error:)
+      end
+    end
+
+    # Evaluates a transition's condition: nil (none written) is true. A
+    # condition that fails, or answers anything but true or false, answers
+    # the failure; the specification treats both as false and requires
+    # `error.execution` for both.
+    #
+    # @return [Evaluated] true or false, or the reason it failed
+    def evaluate_cond(context, cond)
+      return Evaluated.new(value: true, error: nil) if cond.nil?
+
+      evaluated = evaluate(context, cond)
+      return evaluated if !evaluated.ok? || [true, false].include?(evaluated.value)
+
+      Evaluated.new(value: nil, error: NonBooleanCond.new(value: evaluated.value))
+    end
+
+    # Runs a `<script>` program against `context` ({Program.run}); an
+    # {Machine::Invalid} program answers its compile refusal and writes
+    # nothing.
+    #
+    # @return [Executed] the datamodel the program leaves, and the reason it
+    #   failed, if it did
+    def execute(context, program)
+      return Executed.new(data: context.data, error: program.error) if program.is_a?(Machine::Invalid)
+
+      Program.run(context, program)
+    end
+
+    # Whether `root` is a system variable's: the rule is the underscore
+    # prefix, as the reference's, so it covers the four seeded variables and
+    # any other root spelled that way.
+    def system_root?(root) = root.is_a?(String) && root.start_with?("_")
+  end
+end

data/lib/statifier/document/data.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Document
+    # A `<datamodel>`: its `<data>` children.
+    #
+    # @api private
+    Datamodel = ::Data.define(:location, :data)
+
+    # A `<data>`: `id`, `expr` and `src` as written (`expr` and `src` nil
+    # when absent), and `text`, the element's own character data as
+    # written.
+    #
+    # @api private
+    Data = ::Data.define(:location, :id, :expr, :src, :text, :attribute_locations)
+
+    # A `<donedata>`: its `<content>` child or nil, and its `<param>`
+    # children.
+    #
+    # @api private
+    Donedata = ::Data.define(:location, :content, :params)
+
+    # A `<param>`: `name` as written, `expr` or nil, and `param_location`,
+    # its `location` attribute or nil.
+    #
+    # @api private
+    Param = ::Data.define(:location, :name, :expr, :param_location, :attribute_locations)
+
+    # A `<content>`: `expr` or nil; `text`, the element's own character data
+    # as written; and `markup` and `markup_location`, as an {Assign} has
+    # them.
+    #
+    # @api private
+    Content = ::Data.define(:location, :expr, :text, :markup, :markup_location, :attribute_locations)
+  end
+end

data/lib/statifier/document/executable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Document
+    # A `<raise>`: `event` is the attribute as written, one string, not
+    # split.
+    #
+    # @api private
+    Raise = ::Data.define(:location, :event, :attribute_locations)
+
+    # A `<log>`: `label` and `expr` as written, or nil.
+    #
+    # @api private
+    Log = ::Data.define(:location, :label, :expr, :attribute_locations)
+
+    # An `<assign>`. `location` is its `location` attribute, the path
+    # assigned to; the element's span is `node_location`. `expr` is the
+    # attribute or nil. `text` is the element's own character data, as
+    # written. `markup` is the source of its element children, from the
+    # first child that is not blank text to the last, sliced from the
+    # document with its line breaks as they are there, and
+    # `markup_location` its span; both are nil when it has no element child.
+    #
+    # @api private
+    Assign = ::Data.define(:location, :node_location, :expr, :text, :markup, :markup_location, :attribute_locations)
+
+    # An `<if>`: one {Branch} for the `<if>` itself, then one per `<elseif>`
+    # and `<else>`, each holding the executable content up to the next.
+    #
+    # @api private
+    If = ::Data.define(:location, :branches)
+
+    class If
+      # One partition of an `<if>`. `location` is the span of the element
+      # that opened it (the `<if>`, an `<elseif>` or an `<else>`); `cond` is
+      # that element's condition source, nil for an `<else>`.
+      #
+      # @api private
+      Branch = ::Data.define(:location, :cond, :content, :attribute_locations)
+    end
+
+    # A `<foreach>`: `array`, `item` and `index` as written (`index` nil
+    # when absent), and its executable content.
+    #
+    # @api private
+    Foreach = ::Data.define(:location, :array, :item, :index, :content, :attribute_locations)
+
+    # A `<script>`: `text` is its program, the element's own character data
+    # as written. A script with `src` does not lower, so `src` is always nil
+    # and `attribute_locations` empty.
+    #
+    # @api private
+    Script = ::Data.define(:location, :text, :src, :attribute_locations)
+
+    # A `<send>`: each attribute as written, or nil, except `namelist`,
+    # split on whitespace; its `<param>` children and its `<content>` child.
+    #
+    # @api private
+    Send = ::Data.define(
+      :location, :event, :eventexpr, :target, :targetexpr, :type, :typeexpr, :id,
+      :idlocation, :delay, :delayexpr, :namelist, :params, :content, :attribute_locations
+    )
+
+    # A `<cancel>`: `sendid` and `sendidexpr` as written, or nil.
+    #
+    # @api private
+    Cancel = ::Data.define(:location, :sendid, :sendidexpr, :attribute_locations)
+  end
+end

data/lib/statifier/document/invoke.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Document
+    # An `<invoke>`: each attribute as written, or nil, except `namelist`,
+    # split on whitespace, and `autoforward`, true only when written
+    # `"true"`; its `<param>` children, its `<content>` child or nil, and its
+    # `<finalize>` block or nil (a written empty `<finalize/>` is an empty
+    # {Block}, so absent and empty differ).
+    #
+    # @api private
+    Invoke = ::Data.define(
+      :location, :type, :typeexpr, :src, :srcexpr, :id, :idlocation, :namelist,
+      :autoforward, :params, :content, :finalize, :attribute_locations
+    )
+  end
+end

data/lib/statifier/document/states.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Statifier
+  class Document
+    # A `<state>`, `<parallel>`, `<final>` or `<history>`: one node for the
+    # four, `kind` naming which (`:state`, `:parallel`, `:final`,
+    # `:history`), the slots a kind does not use left empty. `id` is the
+    # attribute or nil; `initial` is the attribute split on whitespace;
+    # `history_type` is `:shallow` or `:deep` on a history (`:shallow` when
+    # absent or neither) and nil on every other kind. `onentry` and `onexit`
+    # hold one {Block} per element, never flattened.
+    #
+    # @api private
+    State = ::Data.define(
+      :kind, :location, :id, :initial, :initial_element, :states, :transitions,
+      :onentry, :onexit, :history_type, :donedata, :datamodel_element, :invoke,
+      :attribute_locations
+    )
+
+    # An `<initial>`: however many transitions were written, none and two
+    # included.
+    #
+    # @api private
+    Initial = ::Data.define(:location, :transitions)
+
+    # A `<transition>`. `event` and `target` are the attributes split on
+    # whitespace, `cond` the condition's source or nil, `type` `:external`
+    # or `:internal` (`:external` when absent or neither). `content` holds
+    # its executable content directly: a transition has no block element.
+    #
+    # @api private
+    Transition = ::Data.define(:location, :event, :target, :cond, :type, :content, :attribute_locations)
+
+    # The executable content of one `<onentry>`, `<onexit>` or `<finalize>`
+    # element. A written empty element is an empty block.
+    #
+    # @api private
+    Block = ::Data.define(:location, :content)
+  end
+end

data/lib/statifier/document.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Statifier
+  # The typed chart: what lowering makes of the reader's element tree, one
+  # immutable node per SCXML element, and what the compiler reads. The node
+  # for `<scxml>` itself is this class; the nodes for the elements under it
+  # are the classes nested in it.
+  #
+  # Three things hold for every node:
+  #
+  # - Expressions are source. `cond`, `expr`, `array`, `location` and every
+  #   other attribute a datamodel evaluates are the text the author wrote,
+  #   uncompiled.
+  # - The tree is not yet validated. It holds what was written, including
+  #   shapes the specification forbids (a `<send>` with both `event` and
+  #   `eventexpr`, an `<initial>` with two transitions), for a later check to
+  #   report.
+  # - `attribute_locations` records only what was written: a frozen Hash
+  #   from an attribute's name, as a Symbol, to the span of its value (the
+  #   text inside the quotes), holding a key exactly when the author wrote
+  #   that attribute. A field's value alone cannot say whether it was
+  #   written, because lowering applies the defaults (`binding` is `:early`,
+  #   a transition's `type` is `:external`, a history's `type` is
+  #   `:shallow`).
+  #
+  # Every node carries the span of the element it was made from
+  # (`location`, or `node_location` on an {Assign}, whose `location` is its
+  # attribute) as an {XML::Location}. Every list is frozen and in document
+  # order. A field for one child element (`datamodel_element`,
+  # `initial_element`, `donedata`, `content`, `finalize`) holds the last such
+  # child written.
+  #
+  # The root fields: `name`, `version`, `datamodel` and `xmlns` are the
+  # attributes as written, or nil; `namespace` is the namespace the root's
+  # name resolves to (it differs from `xmlns` for a prefixed root); `binding`
+  # is `:early` or `:late`, `:early` when absent or neither; `initial` is the
+  # attribute split on whitespace; `states` holds the `<state>`,
+  # `<parallel>` and `<final>` children, `datamodel_element` the
+  # `<datamodel>` child or nil, and `scripts` every `<script>` child.
+  #
+  # @api private
+  Document = ::Data.define(
+    :location, :name, :version, :xmlns, :namespace, :datamodel, :binding,
+    :initial, :states, :datamodel_element, :scripts, :attribute_locations
+  )
+end
+
+require_relative "document/states"
+require_relative "document/executable"
+require_relative "document/data"
+require_relative "document/invoke"