statifier 0.0.1 → 0.1.0

data/lib/statifier/datamodel/data_binding.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # The `<data>` binding, as the reference binds (the specification's
+    # sections 5.3.2 and 5.3.3 and B.2.2; its appendix gives no procedure
+    # body).
+    #
+    # When the chart starts every `<data>` id is created, as undefined, and
+    # what binds then binds: every `<data>` under early binding, the root's
+    # own under late binding. A root `<data>` whose id the host's datamodel
+    # already held keeps the host's value. Under late binding a state's own
+    # `<data>` binds when the state is first entered; the caller decides
+    # that it is the first entry.
+    #
+    # One context serves a whole pass, since no `<data>` may read another in
+    # the same pass. A value that fails (an `expr` that did not compile, a
+    # `src`, which nothing here fetches, or an evaluation that fails) leaves
+    # the id undefined and answers a {Failure}, which the interpreter raises
+    # as `error.execution` with the origin `{kind: :data, d_index:}`.
+    #
+    # @api private
+    module DataBinding
+      # What a binding pass answers: `data`, the datamodel it leaves;
+      # `changes`, a {Change} per `<data>` that bound; and `failures`, a
+      # {Failure} per `<data>` that did not; both in `d_index` order.
+      Bound = ::Data.define(:data, :changes, :failures)
+
+      # One `<data>` bound: its `d_index` and `id`, the value the id held
+      # before (`Predicator::UNDEFINED` once seeded) and the value it holds
+      # now.
+      Change = ::Data.define(:d_index, :id, :prior_value, :new_value)
+
+      # One `<data>` that failed to bind: its `d_index` and the `reason`
+      # its `error.execution` carries.
+      Failure = ::Data.define(:d_index, :reason)
+
+      module_function
+
+      # The binding when the chart starts. `context.data` is the host's
+      # datamodel with the system variables seeded.
+      #
+      # @return [Bound]
+      def start(context)
+        bind_all(context.with(data: seed(context)), starting_indexes(context.machine, context.data.keys))
+      end
+
+      # The datamodel with every `<data>` id the host did not supply
+      # declared, as undefined: what the chart starts with before anything
+      # binds.
+      def seed(context)
+        context.machine.data_elements.reduce(context.data) do |data, element|
+          data.key?(element.id) ? data : data.merge(element.id => Predicator::UNDEFINED)
+        end.freeze
+      end
+
+      # The `<data>` that bind when the chart starts: every one under early
+      # binding, the root's own under late, less the root's whose id the
+      # host supplied.
+      def starting_indexes(machine, host_ids)
+        root_data = machine.state(0).data
+        indexes = machine.binding == :early ? machine.data_elements.map(&:d_index) : root_data
+        indexes.reject { root_data.include?(_1) && host_ids.include?(machine.data_elements[_1].id) }
+      end
+
+      # The binding of `state_index`'s own `<data>` on its first entry:
+      # nothing under early binding, and nothing for the root, whose own
+      # bound when the chart started (binding it again would overwrite a
+      # value the host supplied).
+      #
+      # @return [Bound]
+      def enter_state(context, state_index)
+        machine = context.machine
+        return unbound(context) if machine.binding == :early || state_index.zero?
+
+        bind_all(context, machine.state(state_index).data)
+      end
+
+      # A pass that binds nothing.
+      def unbound(context) = Bound.new(data: context.data, changes: [].freeze, failures: [].freeze)
+
+      # Each of `indexes` bound in ascending order against the one context.
+      def bind_all(context, indexes)
+        data, changes, failures = indexes.sort.reduce([context.data, [], []]) do |bound, index|
+          bind_one(context, bound, index)
+        end
+        Bound.new(data: data.freeze, changes: changes.freeze, failures: failures.freeze)
+      end
+
+      # The pass so far, `[data, changes, failures]`, with the `<data>` at
+      # `d_index` bound, or its failure recorded.
+      def bind_one(context, (data, changes, failures), d_index)
+        element = context.machine.data_elements[d_index]
+        evaluated = value_of(context, element.value)
+        return [data, changes, failures + [Failure.new(d_index:, reason: evaluated.error)]] unless evaluated.ok?
+
+        [data.merge(element.id => evaluated.value), changes + [change(data, element, evaluated.value)], failures]
+      end
+
+      # The {Change} binding `element` to `value` makes over `data`.
+      def change(data, element, value)
+        Change.new(d_index: element.d_index, id: element.id, prior_value: data.fetch(element.id, Predicator::UNDEFINED),
+                   new_value: value)
+      end
+
+      # A `<data>` value evaluated; a `src` fails, as nothing here fetches it.
+      def value_of(context, value)
+        return Evaluated.new(value: nil, error: SrcValue.new(src: value.src)) if value.is_a?(Machine::Src)
+
+        Datamodel.evaluate(context, value)
+      end
+    end
+  end
+end

data/lib/statifier/datamodel/delay.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # A `<send>` delay in whole milliseconds, read through predicator's own
+    # duration parser (`Predicator.parse_duration`), as the reference reads
+    # it through its expression language's: one duration vocabulary, so the
+    # units are predicator's eight (`y`, `mo`, `w`, `d`, `h`, `m`, `s`,
+    # `ms`), a superset of the five the SCXML schema names.
+    #
+    # The one rewrite is the reference's: the schema admits a bare leading
+    # dot (`.5s`) and the parser does not, so a leading `.` becomes `0.`.
+    # The sum is the reference's expression language's conversion: a month
+    # is thirty days and a year three hundred and sixty five.
+    #
+    # @api private
+    module Delay
+      # Each unit's worth in milliseconds.
+      WEIGHTS = {
+        years: 31_536_000_000, months: 2_592_000_000, weeks: 604_800_000, days: 86_400_000,
+        hours: 3_600_000, minutes: 60_000, seconds: 1_000, milliseconds: 1
+      }.freeze
+
+      module_function
+
+      # `value` (a delay's text, or what a `delayexpr` evaluated to) in
+      # milliseconds. Text is parsed; a `Predicator::Duration` is summed. A
+      # map, a date or an instant is 0, as the reference reads any map, which
+      # carries none of its duration keys; anything else, and text the parser
+      # refuses, is an {InvalidDelay} carrying the value as given.
+      #
+      # @return [Evaluated] the milliseconds, or the refusal
+      def milliseconds(value)
+        case value
+        when String then parsed(value)
+        when Predicator::Duration then Evaluated.new(value: total(value), error: nil)
+        when Hash, Predicator::Date, Predicator::DateTime then Evaluated.new(value: 0, error: nil)
+        else Evaluated.new(value: nil, error: InvalidDelay.new(value:))
+        end
+      end
+
+      # Delay text parsed after the leading-dot rewrite.
+      def parsed(text)
+        parsed = Predicator.parse_duration(text.start_with?(".") ? "0#{text}" : text)
+        return Evaluated.new(value: nil, error: InvalidDelay.new(value: text)) unless parsed.ok?
+
+        Evaluated.new(value: total(parsed.value), error: nil)
+      end
+
+      # A duration's milliseconds.
+      def total(duration) = WEIGHTS.sum { |unit, weight| duration.public_send(unit) * weight }
+    end
+  end
+end

data/lib/statifier/datamodel/location.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # A write of a value at a location, as an `<assign>` makes one, in the
+    # reference's order: the location resolves to a path; a root that begins
+    # with an underscore is refused; a root the datamodel does not hold is
+    # refused; the value the path holds is read; then the value is written
+    # at the path. A write never declares a root, and creates only what lies
+    # between the root and the leaf, as predicator's store does.
+    #
+    # The published predicator has no location surface of its own, so the
+    # location is read through its compiler: the text compiled as the
+    # program `location = null` is one assignment whose target segments are
+    # the instructions between the root's `lit` and the value's. Text that
+    # is not exactly one assignment target is refused as an
+    # {InvalidLocation}. A bracket key is taken only in the forms the
+    # reference's location reader takes (a string literal, an integer
+    # literal, a negative integer literal, an identifier); any other key is
+    # refused as a {ComputedKey}, as the reference refuses it.
+    #
+    # @api private
+    module Location
+      module_function
+
+      # Writes `value` at `location` (its text) in `context`'s datamodel.
+      #
+      # @return [Written] the context with the written root bound, the path
+      #   and the value it held before, or the reason the write was refused
+      def write(context, location, value)
+        target = target(location)
+        return target if target.is_a?(Written)
+
+        resolved = Predicator.evaluate(target, context.data, **context.options)
+        return refused(EvaluatorError.new(source: location, error: resolved.error)) unless resolved.ok?
+
+        checked(context, location, resolved.value, value)
+      end
+
+      # The instructions that push the location's path as one list, or the
+      # refusal of text that is not one assignment target.
+      def target(location)
+        compiled = Predicator.compile_program("#{location} = null")
+        return refused(EvaluatorError.new(source: location, error: compiled.error)) unless compiled.ok?
+
+        shape_refusal(compiled.value, location) || (compiled.value[0...-2] + [["make_list", compiled.value.last[1]]])
+      end
+
+      # The refusal of compiled `location = null` instructions that are not
+      # one assignment target, or whose target has a computed key; nil when
+      # they are neither.
+      def shape_refusal(instructions, location)
+        return refused(InvalidLocation.new(location:)) unless one_target?(instructions)
+
+        refused(ComputedKey.new(location:)) unless plain_keys?(instructions[1...-2])
+      end
+
+      # Whether `instructions` are one store of null whose root is the first
+      # instruction and stays on the stack to the store, so nothing but the
+      # target runs.
+      def one_target?(instructions)
+        return false unless Stores.readable?(instructions)
+
+        depths = Stores.depths(instructions)
+        instructions.one? { _1.first == "store" } && instructions.last.first == "store" &&
+          instructions[-2] == ["lit", nil] && !Stores.root_name(instructions, 0).nil? &&
+          depths[1...-1].all? { _1&.positive? }
+      end
+
+      # Whether every segment after the root is one the reference takes as a
+      # key: a name or a string literal (one `lit` of a String), an integer
+      # literal (one `lit` of an Integer), a negative one (that `lit` and
+      # `unary_minus`), or an identifier (one `load`), whose value the write
+      # then takes. Any other key is computed, and the reference refuses it.
+      def plain_keys?(segments)
+        until segments.empty?
+          taken = key_size(segments)
+          return false if taken.zero?
+
+          segments = segments.drop(taken)
+        end
+        true
+      end
+
+      # How many instructions the key at the head of `segments` takes, 0 when
+      # the head is not a key the reference takes.
+      def key_size(segments)
+        (opcode, operand), following = segments
+        case opcode
+        when "load" then 1
+        when "lit" then lit_key_size(operand, following)
+        else 0
+        end
+      end
+
+      # How many instructions a `lit` of `operand` followed by `following`
+      # takes as a key: 2 for a negative integer literal, 1 for a String or
+      # an Integer, 0 for any other literal.
+      def lit_key_size(operand, following)
+        return 0 unless operand.is_a?(String) || operand.is_a?(Integer)
+
+        operand.is_a?(Integer) && following == ["unary_minus"] ? 2 : 1
+      end
+
+      # The write of `value` at `path`, after the reference's two root checks.
+      def checked(context, location, path, value)
+        root = path.first
+        return refused(SystemVariable.new(root:)) if Datamodel.system_root?(root)
+        return refused(UnboundLocation.new(location:)) unless context.data.key?(root)
+
+        stored(context, location, path, value)
+      end
+
+      # The write itself: `value` stored at `path` in the root's value, as
+      # predicator's store writes it, or predicator's refusal.
+      def stored(context, location, path, value)
+        root = path.first
+        result = Predicator.execute(store_of(path, value), { root => context.data[root] })
+        return refused(EvaluatorError.new(source: location, error: result.error)) unless result.ok?
+
+        Written.new(context: context.bind(root, result.value[root]), path: path.freeze,
+                    prior_value: read(context.data, path), error: nil)
+      end
+
+      # The instructions that store `value` at `path`.
+      def store_of(path, value) = path.map { ["lit", _1] } + [["lit", value], ["store", path.size]]
+
+      # The value at `path` before the write: a String key against a map, an
+      # Integer index against a list (a negative one from the end, as the
+      # reference reads it), and undefined on any miss or any step through
+      # something else.
+      def read(data, path)
+        path.reduce(data) do |container, segment|
+          case [container, segment]
+          in [Hash, String] | [Array, Integer] then container.fetch(segment) { return Predicator::UNDEFINED }
+          else return Predicator::UNDEFINED
+          end
+        end
+      end
+
+      # A refused write.
+      def refused(reason) = Written.new(context: nil, path: nil, prior_value: nil, error: reason)
+    end
+  end
+end

data/lib/statifier/datamodel/program.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # A `<script>` program's run, with the reference's outcome.
+    #
+    # The reference runs a program with every underscore-prefixed root the
+    # datamodel already holds protected: a store into one fails at the
+    # attempt, so no later statement runs and none reads the value. The
+    # writes made before a failure (that one or any other) are kept. A
+    # system root the program creates fresh is not on that list; its write
+    # lands, the run goes on, and the change found after the run is never
+    # kept and fails the run, naming the first such root in sort order.
+    #
+    # The published predicator offers no protected roots and answers no
+    # context for a run that stops, so the program runs rewritten
+    # ({Stores.guarded}): a store into a protected root becomes a call of a
+    # host function that refuses, which stops the run at that statement as
+    # the reference's refusal does; every other store reports its root's
+    # new value to a host function that records it, so the writes made
+    # before any stop are known. Both host functions live only for the run,
+    # and the datamodel the run leaves is the one it started with plus the
+    # recorded roots that are not system roots: exactly the roots the
+    # reference finds changed, with the same values. A store whose root the
+    # rewrite cannot read fails the run rather than write unguarded.
+    #
+    # Each noted store hands the host function a copy of its root's whole
+    # value, so a loop that grows one root costs more per store than the
+    # reference's store does; the loop budget bounds it.
+    #
+    # @api private
+    module Program
+      # What a host function raises to stop a run at a protected store.
+      class Refused < StandardError; end
+
+      module_function
+
+      # Runs `program` (a {Machine::Program}) against `context`.
+      #
+      # @return [Executed] the datamodel the run leaves and the reason it
+      #   failed, if it did: {SystemVariable} for a system root written,
+      #   else {EvaluatorError} for predicator's refusal
+      def run(context, program)
+        before = context.data
+        halted = []
+        written = {}
+        protected_roots = before.keys.select { Datamodel.system_root?(_1) }
+        result = Predicator.execute(Stores.guarded(program.instructions, protected_roots), before,
+                                    **context.options, functions: functions(context, halted, written))
+        outcome(before, written, failure(program, result, halted.first))
+      end
+
+      # The context's functions and the run's two: {Stores::GUARD} records
+      # the root it refuses in `halted`, {Stores::NOTE} each root's latest
+      # value in `written`.
+      def functions(context, halted, written)
+        context.options[:functions].merge(
+          Stores::GUARD => ->(root) { raise Refused, halted.push(root).first },
+          Stores::NOTE => ->(root, value) { written.store(root, value).then { nil } },
+          Stores::UNREAD => -> { raise Refused, "a store whose root cannot be read" }
+        )
+      end
+
+      # The reason a run stopped, or nil: a protected root's refusal names
+      # its root; any other failure is predicator's.
+      def failure(program, result, halted)
+        return SystemVariable.new(root: halted) if halted
+        return nil if result.ok?
+
+        EvaluatorError.new(source: program.source, error: result.error)
+      end
+
+      # The datamodel the run leaves and its failure: a system root the run
+      # created fails it when nothing else did.
+      def outcome(before, written, failure)
+        system, other = written.partition { |root, _value| Datamodel.system_root?(root) }
+        failure ||= SystemVariable.new(root: system.map(&:first).min) unless system.empty?
+        Executed.new(data: before.merge(other.to_h).freeze, error: failure)
+      end
+    end
+  end
+end

data/lib/statifier/datamodel/reason_value.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # A failure as the predicator value its `error.*` event carries as data,
+    # so a chart can read `_event.data` and every evaluation that reads
+    # `_event` stays a predicator evaluation. The reference carries its
+    # failure terms as they are; predicator refuses a context holding a
+    # value that is not its own, so here a reason becomes a Hash.
+    #
+    # @api private
+    module ReasonValue
+      # The predicator values a reason may carry, kept as they are.
+      VALUE_TYPES = [Predicator::Duration, Predicator::Date, Predicator::DateTime].freeze
+
+      module_function
+
+      # `reason` as a predicator value: a reason becomes a Hash of its fields
+      # under String keys, with `"kind"` its name in snake case (an
+      # `InvalidTarget` is `{"kind" => "invalid_target", "target" => ...}`),
+      # applied all the way down; a Symbol becomes its String; a predicator
+      # value stays as it is.
+      def of(reason)
+        case reason
+        when ::Data then VALUE_TYPES.include?(reason.class) ? reason : fields(reason)
+        when Symbol then reason.to_s
+        when Hash then reason.to_h { |key, value| [of(key), of(value)] }
+        when Array then reason.map { of(_1) }
+        else reason
+        end
+      end
+
+      # A reason's fields with its kind first.
+      def fields(reason)
+        { "kind" => kind(reason.class) }.merge(reason.to_h.to_h { |key, value| [key.to_s, of(value)] })
+      end
+
+      # A reason class's name in snake case.
+      def kind(klass) = klass.name.split("::").last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+  end
+end

data/lib/statifier/datamodel/reasons.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Statifier
+  module Datamodel
+    # What an evaluation answered: `value`, or, as `error`, the reason it
+    # failed. Read `ok?`, not the value: nil is predicator's null.
+    #
+    # @api private
+    Evaluated = ::Data.define(:value, :error) do
+      # @return [Boolean] whether the evaluation succeeded
+      def ok? = error.nil?
+    end
+
+    # What a program run answered: `data`, the datamodel it leaves (the
+    # writes made before a failure included), and `error`, the reason it
+    # failed, nil when it did not.
+    #
+    # @api private
+    Executed = ::Data.define(:data, :error) do
+      # @return [Boolean] whether the run succeeded
+      def ok? = error.nil?
+    end
+
+    # What a write to a location answered: the `context` it leaves, the
+    # `path` the location resolved to and the `prior_value` that path held
+    # before the write, or, as `error`, the reason it was refused (and the
+    # other fields nil).
+    #
+    # @api private
+    Written = ::Data.define(:context, :path, :prior_value, :error) do
+      # @return [Boolean] whether the write was made
+      def ok? = error.nil?
+    end
+
+    # The reasons a failure carries, each the data of the `error.execution`
+    # it raises. A deferred compile refusal is carried as the
+    # {Compiler::Error} itself, as the reference carries its compiler's.
+
+    # Predicator refused: `source` is the expression's or the location's
+    # text and `error` predicator's own error value, unwrapped.
+    #
+    # @api private
+    EvaluatorError = ::Data.define(:source, :error)
+
+    # A condition answered something other than true or false.
+    #
+    # @api private
+    NonBooleanCond = ::Data.define(:value)
+
+    # A write reached `root`, a system variable's root (underscore-prefixed).
+    #
+    # @api private
+    SystemVariable = ::Data.define(:root)
+
+    # A write named a location whose root the datamodel does not hold; a
+    # write never declares a root.
+    #
+    # @api private
+    UnboundLocation = ::Data.define(:location)
+
+    # A location's text is not one assignment target.
+    #
+    # @api private
+    InvalidLocation = ::Data.define(:location)
+
+    # A location's bracket key is a computed expression, which the
+    # reference refuses as an assignment target key; `message` is the
+    # reference's.
+    #
+    # @api private
+    ComputedKey = ::Data.define(:location) do
+      # @return [String] the reference's message for the refusal
+      def message = "Cannot use computed expression as assignment target key"
+    end
+
+    # A delay that is not one: text predicator's duration parser refuses, or
+    # a value that is neither text nor a duration.
+    #
+    # @api private
+    InvalidDelay = ::Data.define(:value)
+
+    # A `<data>` value is a `src`, which the host resolves and nothing here
+    # fetches.
+    #
+    # @api private
+    SrcValue = ::Data.define(:src)
+  end
+end