vissen-parameterized 0.1.0

data/lib/vissen/parameterized/scope.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The scope exists to protect parameterized objects from being bound to
+    # parameters with a different lifetime than their own.
+    #
+    # Each scope is bound to a `Conditional` and as long as it, as well as the
+    # conditionals of all the parents return false, the scope is considered to
+    # be alive.
+    #
+    # By checking that one scope is included in another, it is possible to
+    # guarantee that values belonging to the first scope are safe to use.
+    class Scope
+      # @return [Scope] the parent of this scope.
+      attr_reader :parent
+
+      # A scope is considered dead once its conditional returns true, or if the
+      # parent scope is also dead.
+      #
+      # @return [true] if the conditional is met.
+      # @return [false] otherwise.
+      def dead?
+        @conditional.met? || parent.dead?
+      end
+
+      # The inverse of `#dead?`
+      #
+      # @see dead?
+      #
+      # @return [false] if the conditional is met.
+      # @return [true] otherwise.
+      def alive?
+        !dead?
+      end
+
+      # Forces the conditional to return true, irregardless of its actual state.
+      #
+      # @return [nil]
+      def kill!
+        @conditional.force!
+      end
+
+      # Checks if the given object is included, either in this scope or in any
+      # of the parent scopes.
+      #
+      # @param  obj [#scope] the object to scope check.
+      # @return [true] if the object either shares this scope or a parent scope.
+      # @return [false] otherwise.
+      def include?(obj)
+        include_scope? obj.scope
+      end
+
+      alias === include?
+
+      # Creates a new scope that is a direct descendent of this one.
+      #
+      # @param  conditional [Conditional] the conditional to use for the new
+      #   scope.
+      # @return [Scope] a new child scope.
+      def create_scope(conditional)
+        Scope.new self, conditional
+      end
+
+      # Checks if the given scope is included in the scope hierarchy of this
+      # one.
+      #
+      # @param  other [Scope, Object] the scope to check.
+      # @return [true] if the given scope is equal to this one, or one of the
+      #   parents.
+      def include_scope?(other)
+        equal?(other) || @parent.include_scope?(other)
+      end
+
+      protected
+
+      # Creates a new scope. This method is protected to avoid erroneous parent
+      # structures and new top level scopes should instead be created using
+      # `GlobalScope.instance.create_scope`.
+      #
+      # @raise  [TypeError] if the conditional does not respond to `#met?`.
+      # @raise  [ScopeError] if the conditional is out of scope.
+      def initialize(parent, conditional)
+        raise TypeError unless conditional.respond_to? :met?
+        @parent = parent
+
+        raise ScopeError unless include? conditional
+        @conditional = conditional
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/scope_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The scope error signals that a parameter was bound out of scope.
+    class ScopeError < Error
+    end
+  end
+end

data/lib/vissen/parameterized/value/bool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    module Value
+      # Bool values are stored as booleans internally.
+      #
+      # === Usage
+      #
+      #   bool = Bool.new true
+      #   bool.value # => true
+      #
+      class Bool
+        include Value
+
+        # @return [true, false] see Value
+        DEFAULT = false
+
+        # @param  new_value [Object] the new value.
+        # @return see Value#write
+        def write(new_value)
+          super new_value ? true : false
+        end
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/value/int.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    module Value
+      # Int values are stored as Fixnums internally.
+      #
+      # === Usage
+      #
+      #   int = Int.new 42
+      #   int.value # => 42
+      #
+      class Int
+        include Value
+
+        # @return [Fixnum] see Value
+        DEFAULT = 0
+
+        # @raise  [TypeError] if the given object cannot be coerced into an
+        #   integer.
+        #
+        # @param  new_value [#to_i] the new value.
+        # @return see Value#write
+        def write(new_value)
+          super Integer(new_value)
+        end
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/value/real.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    module Value
+      # Real values are stored as floats internally.
+      #
+      # === Usage
+      #
+      #   real = Real.new 42
+      #   real.value # => 42.0
+      #
+      class Real
+        include Value
+
+        # @return [Float] see Value
+        DEFAULT = 0.0
+
+        # @raise  [TypeError] if the given object cannot be coerced into a
+        #   float.
+        #
+        # @param  new_value [#to_f] the new value.
+        # @return see Value#write
+        def write(new_value)
+          super Float(new_value)
+        end
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/value/vec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    module Value
+      # Vector type values are stored internally as arrays of floats.
+      #
+      # === Usage
+      #
+      #   vec = Vec[1, 0.2]
+      #   vec.value # => [1.0, 0.2]
+      #
+      class Vec
+        include Value
+
+        # @return [Array<Float>] the default value that will be used when `.new`
+        #   is called without arguments, or with nil.
+        DEFAULT = [0.0, 0.0].freeze
+
+        # @param  initial_value [Array<#to_f>] the initial value to use.
+        def initialize(initial_value = nil)
+          @value = DEFAULT.dup
+          taint!
+
+          write initial_value if initial_value
+        end
+
+        # @raise  [TypeError] if the given value does not respond to `#[]`.
+        # @raise  [TypeError] if the elements of the given value does not cannot
+        #   be coerced into floats.
+        #
+        # @param  new_value [Array<#to_f>] the new values to write.
+        # @return [nil]
+        def write(new_value)
+          return if @value == new_value
+
+          @value[0] = Float(new_value[0])
+          @value[1] = Float(new_value[1])
+          taint!
+          nil
+        rescue NoMethodError
+          raise TypeError, 'The given object must support #[]'
+        end
+
+        class << self
+          # @param  a [#to_f] the first vector component.
+          # @param  b [#to_f] the second vector component.
+          # @return [Vec] a new Vec instance.
+          def [](a, b)
+            new [a, b]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/value.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The Value module implements the basic functionallity of a value type.
+    # Class implementations are encouraged to override #write to provide type
+    # checking or coercion.
+    #
+    # === Usage
+    # The following example implements an integer type by calling #to_i on
+    # objects before they are written.
+    #
+    #   class Int
+    #     include Value
+    #     DEFAULT = 0
+    #
+    #     def write(new_value)
+    #       super new_value.to_i
+    #     end
+    #   end
+    #
+    module Value
+      # @return [Object] the internal value object.
+      attr_reader :value
+
+      # @return [Object] the default value that will be used when `.new` is
+      #   called without arguments, or with nil.
+      DEFAULT = nil
+
+      # @param  value [Object] the initial value to use. Ignored if nil.
+      def initialize(value = nil)
+        @value   = nil
+        @tainted = true
+
+        write(value.nil? ? self.class::DEFAULT : value)
+      end
+
+      # Updates the internally stored value. The object will be marked as
+      # tainted if the new value differs from the previous.
+      #
+      # @param  new_value [Object] the new value to write.
+      # @return [true] if the value was changed.
+      # @return [false] otherwise.
+      def write(new_value)
+        return false if new_value == @value
+        @value = new_value
+        taint!
+        true
+      end
+
+      # @return [true] if the value has been written to since the last call to
+      #   `#untaint!`.
+      # @return [false] otherwise.
+      def tainted?
+        @tainted
+      end
+
+      # Marks the value as untainted.
+      #
+      # @return [false]
+      def untaint!
+        @tainted = false
+      end
+
+      # Values are always considered part of the global scope.
+      #
+      # @return [Scope] the scope of the value.
+      def scope
+        GlobalScope.instance
+      end
+
+      # @return [Array<Module>] an array of the modules and classes that include
+      #   the `Value` module.
+      def self.types
+        @types
+      end
+
+      # Converts a class name to a string.
+      #
+      #   Vissen::Parameterized::Value::Real -> "real"
+      #
+      # @param  klass [Class] the class to canonicalize.
+      # @return [String] a string version of the class name.
+      def self.canonicalize(klass)
+        klass.name
+             .split('::').last
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .downcase
+      end
+
+      # @return [String] the value formated as a string, with an appended '*' if
+      #   the value is tainted.
+      def to_s
+        base = @value.to_s
+        tainted? ? base + '*' : base
+      end
+
+      protected
+
+      def taint!
+        @tainted = true
+      end
+
+      # @param  mod [Module]
+      def self.included(mod)
+        (@types ||= []) << mod
+      end
+
+      private_class_method :included
+    end
+  end
+end

data/lib/vissen/parameterized/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The version number of the Parameterized library.
+    #
+    # @return [String] a semantic version number.
+    VERSION = '0.1.0'
+  end
+end

data/lib/vissen/parameterized.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'singleton'
+
+require 'vissen/parameterized/version'
+require 'vissen/parameterized/error'
+require 'vissen/parameterized/scope_error'
+require 'vissen/parameterized/accessor'
+require 'vissen/parameterized/scope'
+require 'vissen/parameterized/global_scope'
+require 'vissen/parameterized/value'
+require 'vissen/parameterized/value/bool'
+require 'vissen/parameterized/value/int'
+require 'vissen/parameterized/value/real'
+require 'vissen/parameterized/value/vec'
+require 'vissen/parameterized/parameter'
+require 'vissen/parameterized/dsl'
+require 'vissen/parameterized/graph'
+
+module Vissen
+  # A parameterized object should have
+  # - a set of parameters,
+  # - a (possibly expensive) function that transforms the parameters to an
+  #   output, and
+  # - an output value.
+  module Parameterized
+    extend Forwardable
+
+    INSPECT_FORMAT = '#<%<name>s:0x%016<object_id>x (%<params>s) -> %<type>s>'
+    private_constant :INSPECT_FORMAT
+
+    # @!method value
+    # @return [Object] the output value.
+    def_delegators :@_value, :value, :to_s
+
+    # @!method returns_a?(value_klass)
+    # Checks if the parameterized object returns a value of the given value
+    # class.
+    #
+    # @param  value_klass [Class] the class to test.
+    # @return [true] if the output value is of the given class.
+    # @return [false] otherwise.
+    def_delegator :@_value, :is_a?, :returns_a?
+
+    # Forwards all arguments to super.
+    #
+    # @param  args [Array<Object>] the arguments to forward to super.
+    # @param  parameters [Hash<Symbol, Parameter>] the input parameters.
+    # @param  output [Value] the output value object.
+    # @param  scope [Scope] the scope of the object.
+    # @param  setup [Hash<Symbol, Object>] the initial setup.
+    def initialize(*args,
+                   parameters:,
+                   output:,
+                   scope: GlobalScope.instance,
+                   setup: {})
+      @_accessor = Accessor.new parameters
+      @_params   = parameters
+      @_scope    = scope
+      @_value    = output
+      @_checked  = false
+
+      load_initial setup
+
+      super(*args)
+    end
+
+    # @raise  [NotImplementedError] if not implemented by descendent.
+    #
+    # @param  _parameters [Accessor] the parameters of the parameterized object.
+    # @return [Object] an object compatible with the output value type should be
+    #   returned.
+    def call(_parameters)
+      raise NotImplementedError
+    end
+
+    # Marks the output value and all input parameters as untainted.
+    #
+    # @return [false]
+    def untaint!
+      # ASUMPTION: if the value has not been taint checked
+      #            there should be no untainted values in
+      #            this part of the graph. This does not
+      #            hold initially.
+      return unless @_checked
+      @_checked = false
+
+      @_params.each { |_, param| param.untaint! }
+      @_value.untaint!
+    end
+
+    # Checks if the output value of the parameterized object has changed. If any
+    # of the input parameters have changed since last calling `#untaint!` the
+    # `#call` method will be evaluated in order to determine the state of the
+    # output value.
+    #
+    # Note that `#call` is only evaluated once after the object has been
+    # untainted. Subsequent calls to `#tainted?` will refer to the result of the
+    # first operation.
+    #
+    # @return [true] if the output value has changed since last calling
+    #   `#untaint!`.
+    # @return [false] otherwise.
+    def tainted?
+      return @_value.tainted? if @_checked
+      @_checked = true
+
+      params_tainted =
+        @_params.reduce(false) do |a, (_, param)|
+          param.tainted? || a
+        end
+
+      return false unless params_tainted
+
+      @_value.write call(@_accessor)
+    end
+
+    # @return [true] if the parameterized object has the given parameter.
+    # @return [false] otherwise.
+    def parameter?(key)
+      @_params.key? key
+    end
+
+    # Binds a parameter to a target value.
+    #
+    # @see    Parameter#bind
+    # @raise  [KeyError] if the parameter is not found.
+    # @raise  [ScopeError] if the parameter is out of scope.
+    #
+    # @param  param [Symbol] the parameter to bind.
+    # @param  target [#value] the value object to bind to.
+    # @return [Parameter] the parameter that was bound.
+    def bind(param, target)
+      raise ScopeError unless scope.include? target
+      @_params.fetch(param).bind target
+    end
+
+    # Sets the constant value of a parameter.
+    #
+    # @see    Parameter#set
+    # @raise  [KeyError] if the parameter is not found.
+    #
+    # @param  param [Symbol] the parameter to bind.
+    # @param  value [Object] the value to set.
+    # @return [Parameter] the parameter that was set.
+    def set(param, value)
+      @_params.fetch(param).set value
+    end
+
+    # @return [Accessor] a proxy object that provides access to parameters via
+    #   method calls instead of hash lookups.
+    def parameters
+      @_accessor
+    end
+
+    alias params parameters
+
+    # @return [Scope] the scope to which the parameterized object belongs.
+    def scope
+      @_scope
+    end
+
+    # Produces a readable string representation of the parameterized object.
+    #
+    # @return [String] a string representation.
+    def inspect
+      format INSPECT_FORMAT, name: self.class.name,
+                             object_id: object_id,
+                             params: params_with_types,
+                             type: Value.canonicalize(@_value.class)
+    end
+
+    # Iterates over the parameterized objects currently bound to the parameters.
+    #
+    # @return [Enumerable] if no block is given.
+    def each_parameterized
+      return to_enum(__callee__) unless block_given?
+      @_params.each do |_, param|
+        next if param.constant?
+        target = param.target
+        yield target if target.is_a? Parameterized
+      end
+    end
+
+    private
+
+    def load_initial(setup)
+      setup.each do |key, value|
+        @_params.fetch(key)
+                .send(value.respond_to?(:value) ? :bind : :set, value)
+      end
+    end
+
+    def params_with_types
+      @_params.map { |k, v| "#{k}:#{Value.canonicalize(v.type)}" }.join(', ')
+    end
+  end
+end
+
+require 'vissen/parameterized/conditional'

data/vissen-parameterized.gemspec

@@ -0,0 +1,39 @@
+
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'vissen/parameterized/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'vissen-parameterized'
+  spec.version       = Vissen::Parameterized::VERSION
+  spec.authors       = ['Sebastian Lindberg']
+  spec.email         = ['seb.lindberg@gmail.com']
+
+  spec.summary       = 'Parameterized creates a dependency graph for pure ' \
+                       'functions.'
+  spec.description   = 'This utility library gives objects the ability to ' \
+                       'declare input dependencies, a transformation of ' \
+                       'those inputs and an output value. Forcing ' \
+                       'dependencies to be acyclic, the library can always ' \
+                       'find a valid update order of all the transformations.'
+  spec.homepage      = 'https://github.com/midi-visualizer/vissen-parameterized'
+  spec.license       = 'MIT'
+
+  spec.metadata['yard.run'] = 'yri'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '~> 0.52'
+  spec.add_development_dependency 'simplecov', '~> 0.16'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end