vissen-parameterized 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61c1d3168e0c9c1b157fa61e1a45106cb6ecfe2d988855b4f15bd3716e4f979b
+  data.tar.gz: 2ecddf87812abfab49b494b70917e126cbd1dd3e6ad6fdceb91c8e00dcdf4840
+SHA512:
+  metadata.gz: 3e5dcb1be70060630f47d467f494b2c94650fd6e95098fb75b3451113d73c81f524728e1d4bf8de2d53046af7394e51668dd1c37d98bb68bd255db2ac086980c
+  data.tar.gz: a0f02adc5b6d9a43772ea46a0c4ea7e6a06ad1bde65f5185c8c3c48500e6108cc6433dc5cd91c4856c9186e114b6c98a07b50c501450b3ab73d046aec4755c62

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,67 @@
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+  TargetRubyVersion: 2.5
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Layout/ClassStructure:
+  Enabled: true
+  Categories:
+    module_inclusion:
+      - include
+      - prepend
+      - extend
+  ExpectedOrder:
+      - module_inclusion
+      - constants
+      - public_class_methods
+      - initializer
+      - instance_methods
+      - protected_methods
+      - private_methods
+
+Layout/IndentHeredoc:
+  EnforcedStyle: squiggly
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - 'test/**/*.rb'
+
+Lint/InterpolationCheck:
+  Exclude:
+    - 'test/**/*.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'Rakefile'
+    - '**/*.rake'
+    - 'test/**/*.rb'
+    - '*.gemspec'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'test/**/*.rb'
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    - "_"
+    - a
+    - b
+    - x
+    - y
+    - i
+    - p
+    - n
+    - t
+    - r
+    - g
+    - to

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.0
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in vissen-parameterized.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,48 @@
+PATH
+  remote: .
+  specs:
+    vissen-parameterized (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    docile (1.3.0)
+    json (2.1.0)
+    minitest (5.11.3)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.1)
+    rainbow (3.0.0)
+    rake (10.5.0)
+    rubocop (0.55.0)
+      parallel (~> 1.10)
+      parser (>= 2.5)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.9.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    unicode-display_width (1.3.2)
+    yard (0.9.12)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  minitest (~> 5.0)
+  rake (~> 10.0)
+  rubocop (~> 0.52)
+  simplecov (~> 0.16)
+  vissen-parameterized!
+  yard (~> 0.9)
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Sebastian Lindberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# 🥀 Vissen Parameterized
+
+[![Gem Version](https://badge.fury.io/rb/vissen-parameterized.svg)](https://badge.fury.io/rb/vissen-parameterized)
+[![Build Status](https://travis-ci.org/midi-visualizer/vissen-parameterized.svg?branch=master)](https://travis-ci.org/midi-visualizer/vissen-parameterized)
+[![Inline docs](http://inch-ci.org/github/midi-visualizer/vissen-parameterized.svg?branch=master)](http://inch-ci.org/github/midi-visualizer/vissen-parameterized)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/vissen-parameterized/)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'vissen-parameterized'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install vissen-parameterized
+
+## Usage
+
+```ruby
+class Doubler
+  include Parameterized
+  extend  Parameterized::DSL
+  
+  param input: Value::Real
+  output Value::Real
+  
+  def call(params)
+    params.input * 2
+  end
+end
+
+external_value = Value::Real.new 21
+
+doubler = Doubler.new
+doubler.bind :input, external_value
+
+# A tainted check is needed before reading the value
+doubler.tainted? # => true
+doubler.value # => 42.0
+
+# Make sure untaint! is called before any value is changed
+doubler.untaint!
+
+external_value.set 4.5
+
+# Before the taint check the old value is returned
+doubler.value # => 42.0
+doubler.tainted? # => true
+doubler.value # => 9.0
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/midi-visualizer/vissen-parameterized.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new(:rubocop)
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.stats_options = %w[--list-undoc]
+end
+
+desc 'Generate Ruby documentation'
+task doc: %w[yard]
+
+task default: %w[test rubocop:auto_correct]
+
+task pre_release: %i[default doc] do
+  sh 'bundle'
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'vissen/parameterized'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/vissen/parameterized/accessor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # Simple proxy object for the parameter hash stored in Parameterized
+    # objects. It allows access to parameters that looks like `params.input`
+    # instead of `params[:input].value`.
+    class Accessor
+      protected
+
+      # @param  parameters [Hash<Symbol, Parameter>] the parameters to provide
+      #   access to.
+      def initialize(parameters)
+        parameters.each do |key, param|
+          define_singleton_method(key) { param.value }
+        end
+
+        freeze
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/conditional.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The conditional is just a specialized form of a parameterized object. It
+    # takes just one input and, through a given block, transforms it to a
+    # boolean value. The aliased method `#met?` is nothing more than syntactic
+    # suger for and equivalent to calling `#value`.
+    #
+    # === Usage
+    # The following exable sets up a conditional, binds it to a value and checks
+    # if the condition is met for two different values. The update proceedure is
+    # the same as with other parameterized objects.
+    #
+    #   less_than_two = Conditional.new { |value| value < 2 }
+    #   value = Value::Real.new 1
+    #   less_than_two.bind :input, value
+    #
+    #   less_than_two.tainted? # => true
+    #   less_than_two.met? # => true
+    #   less_than_two.untaint!
+    #
+    #   value.write 3
+    #   less_than_two.tainted? # => true
+    #   less_than_two.met? # => false
+    #
+    class Conditional
+      include Parameterized
+
+      # @!method met?
+      # @return [true, false] the state of the conditional.
+      alias met? value
+
+      # @param  input_klass [Class] the value class of the input parameter.
+      # @param  opts (see Parameterized)
+      def initialize(input_klass = Value::Real, **opts)
+        super(parameters: { input: Parameter.new(input_klass) },
+              output: Value::Bool.new,
+              **opts)
+
+        define_singleton_method :call do |params|
+          yield params.input
+        end
+      end
+
+      # Forces the state of the output to the given value. The input is unbound
+      # and untainted to prevent it from affecting the output further.
+      #
+      # @param  value [true, false] the value to force.
+      # @return [true] if the output was changed.
+      # @return [false] otherwise.
+      def force!(value = true)
+        input = @_params[:input]
+        input.unbind unless input.constant?
+        input.untaint!
+
+        @_value.write value
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/dsl.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # This module provides a DSL for defining input parameters and output values
+    # for parameterized objects.
+    #
+    # == Usage
+    #
+    #   class Example
+    #     extend DSL
+    #
+    #     param input:  Value::Vec,
+    #           offset: Value::Real
+    #   end
+    #
+    module DSL
+      # @param  key [Symbol] the parameter to add.
+      # @param  value_klass [Class] the value type of the parameter.
+      # @param  default [Object] the default value of the parameter.
+      # @return [nil]
+      def param(key, value_klass, default: nil)
+        @_params = {} unless defined? @_params
+        @_params[key] = [value_klass, default].freeze
+        nil
+      end
+
+      # @param  value_klass [Class] the value class to use.
+      # @return [nil]
+      def output(value_klass)
+        @_output = value_klass
+        nil
+      end
+
+      # @return [Hash<Symbol, Parameter>] a new hash containing one parameter
+      #   object for each parameter key.
+      def class_parameters
+        return {}.freeze unless defined? @_params
+
+        @_params.each_with_object({}) { |(k, v), h| h[k] = Parameter.new(*v) }
+                .freeze
+      end
+
+      # @raise  [RuntimeError] if no output class has been defined.
+      #
+      # @return [Value, nil] a new instance of the value class defined using
+      #   `#output`, or nil if nothing was defined.
+      def class_output
+        return nil unless defined? @_output
+        @_output.new
+      end
+
+      # Dynamically adds a `.new` method to the extending module (or class), if
+      # it is a descendent of Parameterized, that initializes the input
+      # parameters and the output value.
+      #
+      # @param  mod [Module] the module that extended the DSL.
+      def self.extended(mod)
+        define_param_types mod
+        return unless mod <= Parameterized
+
+        mod.define_singleton_method :new do |*args, **opts|
+          super(*args,
+                parameters: class_parameters,
+                output: class_output,
+                **opts)
+        end
+      end
+
+      private_class_method :extended
+
+      # Defines custom param methods for each class that includes the `Value`
+      # module.
+      #
+      # @param  mod [Module] the module to define the types on.
+      def self.define_param_types(mod)
+        Value.types.each do |klass|
+          # Skip unless the type is native to the library
+          next unless klass.name.start_with? 'Vissen::Parameterized::Value'
+
+          name = class_to_sym klass
+          mod.define_singleton_method name do |key, **opts|
+            param(key, klass, **opts)
+          end
+        end
+      end
+
+      private_class_method :define_param_types
+
+      # Converts a class name to a symbol.
+      #
+      #   Vissen::Parameterized::Value::Real -> :real
+      #
+      # @param  klass [Class] the class to symbolize.
+      # @return [Symbol] a symbolized version of the class name.
+      def self.class_to_sym(klass)
+        Value.canonicalize(klass).to_sym
+      end
+
+      private_class_method :class_to_sym
+    end
+  end
+end

data/lib/vissen/parameterized/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # This is the top level output error class and should be subclassed by all
+    # other custom error classes used in this library.
+    class Error < StandardError
+    end
+  end
+end

data/lib/vissen/parameterized/global_scope.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The global scope is by definition a singleton and exists as the top level
+    # parent of all other scopes.
+    class GlobalScope < Scope
+      include Singleton
+
+      # The global scope can never die.
+      #
+      # @return [false]
+      def dead?
+        false
+      end
+
+      # @see dead?
+      #
+      # @return [true]
+      def alive?
+        true
+      end
+
+      # @raise [RuntimeError]
+      def kill!
+        raise 'The global scope cannot be killed'
+      end
+
+      # The only scope that is included in the global scope is the global scope
+      # itself.
+      #
+      # @param  scope [Object] the scope to check.
+      # @return [true] if the given scope is the global scope.
+      # @return [false] otherwise.
+      def include_scope?(scope)
+        equal?(scope)
+      end
+
+      # @raise [StopIteration]
+      def parent
+        raise StopIteration
+      end
+
+      private
+
+      def initialize; end
+    end
+  end
+end

data/lib/vissen/parameterized/graph.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # The graph implements a mechanism for updating and untainting a set of
+    # interconnected paramaeterized objects.
+    class Graph
+      # @raise  [ScopeError] if any of the end nodes are not included in the
+      #   scope.
+      #
+      # @param  end_nodes [Array<Parameterized>] the top level parameterized
+      #   objects.
+      # @param  scope [Scope] the scope in which the graph (and the end nodes)
+      #   exists.
+      def initialize(end_nodes, scope: GlobalScope.instance)
+        end_nodes.each do |node|
+          raise ScopeError unless scope.include? node
+        end
+
+        @end_nodes = end_nodes
+
+        freeze
+      end
+
+      # Updates the entire graph.
+      def update!
+        @end_nodes.each(&:tainted?)
+        @end_nodes.each(&:untaint!)
+
+        @end_nodes.each { |node| yield node.value } if block_given?
+      end
+    end
+  end
+end

data/lib/vissen/parameterized/parameter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Vissen
+  module Parameterized
+    # Parameter respond to #value and can either return a locally stored
+    # constant or the value of a target object.
+    #
+    # === Usage
+    #
+    #   parameter = Parameter.new Value::Real
+    #   parameter.set 42
+    #   parameter.value # => 42
+    #
+    #   target = Value::Real.new 4.2
+    #   parameter.bind target
+    #   parameter.value # => 4.2
+    #
+    class Parameter
+      extend Forwardable
+
+      INSPECT_FORMAT = '#<%<name>s:0x%016<object_id>x %<type>s:%<value>s>'
+      private_constant :INSPECT_FORMAT
+
+      def_delegators :@target, :value, :tainted?, :untaint!, :scope
+
+      # @param  value_klass [Class] the value type supported by the parameter.
+      # @param  default_value [Object] the default constant value. It defaults
+      #   to the default of the given value class.
+      def initialize(value_klass, default_value = nil)
+        @default  = default_value.nil? ? value_klass::DEFAULT : default_value
+        @constant = value_klass.new @default
+        @target   = @constant
+      end
+
+      # Unbinds the parameter and resets the value of the to the default of the
+      #   value class.
+      #
+      # @return [self]
+      def clear!
+        set @default
+      end
+
+      # @return [false] if the parameter is bound to a value object.
+      # @return [true] otherwise.
+      def constant?
+        @constant.equal? @target
+      end
+
+      # @raise  [RuntimeError] if the parameter is constant.
+      #
+      # @return [#value] the value target.
+      def target
+        raise RuntimeError if constant?
+        @target
+      end
+
+      # Writes a constant value to the parameter.
+      #
+      # @param  value [Object] the value to set.
+      # @return [self]
+      def set(value)
+        @constant.write value
+        @target = @constant
+        self
+      end
+
+      # TODO: validate the value type
+      #
+      # @param  obj [#value] the value object to bind to.
+      # @return [self]
+      def bind(obj)
+        raise TypeError unless obj.respond_to?(:value)
+        @target = obj
+        self
+      end
+
+      # Copies the value of the target to the internal constant and unbinds from
+      # the target.
+      def unbind
+        raise 'cannot unbind constant' if constant?
+        set @target.value
+      end
+
+      # @return [Value] the value class of the parameter.
+      def type
+        @constant.class
+      end
+
+      # @return [String] the parameter value formated as a string wrapped either
+      #   in `()` or `{}` depending on if the value is constant or bound.
+      def to_s
+        base = @target.to_s
+        constant? ? "(#{base})" : "{#{base}}"
+      end
+
+      # Produces a readable string representation of the parameter object.
+      #
+      # @return [String] a string representation.
+      def inspect
+        format INSPECT_FORMAT, name: self.class.name,
+                               object_id: object_id,
+                               type: Value.canonicalize(type),
+                               value: to_s
+      end
+    end
+  end
+end