reduxco 1.0.0

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2012, WhitePages, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  * Neither the name of the company nor the
+    names of its contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL WHITEPAGES, INC. BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,126 @@
+= Overview
+
+Reduxco is a general purpose graph reduction calculation engine for those
+non-linear dependency flows that normal pipelines and Rack Middleware-like
+architectures can't do cleanly.
+
+Conceptually, it is similar to using Rack Middleware with named keys to store
+intermediate calculations that have to be reused later, but unlike Rack Middleware,
+Reduxco is self organizing based on the dependencies used by each piece.
+
+It's primary public facing class is Reduxco::Context.
+
+= Examples
+
+== Basic Context Use
+
+In practice, one can build one ore more tables of callable objects (e.g. Procs or
+custom class instances), and register them with a Reduxco::Context.  Callables can then
+used their Reduco::Context handle to refer to the callables they can depend on.
+
+For example, the addition of two numbers could be done as follows:
+
+  map = {
+    sum: ->(c){ c[:x] + c[:y] },
+      x: ->(c){ 3 },
+      y: ->(c){ 5 }
+  }
+
+  sum = Reduxco::Reduxer.new(map).reduce(:sum)
+  sum.should == 8
+
+Note that the symbol <code>:app</code> is the default root node of Reduxco::Context#reduce,
+so if <code>:sum</code> were renamed to <code>:app</code> above, the last line could
+be slightly simplified as:
+
+  sum = Reduxco::Context.new(map).reduce
+
+Of course, any object responding to <code>call</code> can be used as the values in
+the map, so one could just as easily define a class with an instance method of
+<code>call</code> on it instead of using Proc objects.
+
+== Overriding and Super
+
+If multiple maps of callables are given, and the keys (referred to as names from
+here on) are duplicated in the maps, the last map given wins, shadowing the previous map.
+For example:
+
+  map1 = {
+    message: ->(c){ 'Hello From Map 1' }
+  }
+
+  map2 = {
+    message: ->(c){ 'Hello From Map 2' }
+  }
+
+  msg = Reduxco::Reduxer.new(map1, map2).reduce(:message)
+  msg.should == 'Hello From Map 2'
+
+If one wishes to refer to previous (shadowed) callables, one can do that using
+Context#super.  For example:
+
+  map1 = {
+    message: ->(c){ 'Hello From Map 1' }
+  }
+
+  map2 = {
+    message: ->(c){ c.super + ' and Hello From Map 2' }
+  }
+
+  msg = Reduxco::Context.new(map1, map2).reduce(:message)
+  msg.should == 'Hello From Map 1 and Hello From Map 2'
+
+== Introspection
+
+There are several introspection methods for making assertions about the
+Reduxco::Context.  These are usually used by callables to inspect their
+environment before proceeding.
+
+[Reduxco::Context#include?] Allows you to inspect if the Reduxco::Context
+                            can resolve a given refname if called.
+[Reduxco::Context#completed?] Allows you to inspect if the callable associated
+                              with a given block name has already been called;
+                              useful for assertions about weak dependencies.
+[Reduxco::Context#assert_completed] Like <code>computed?</code>, but it raises
+                                    an exception if it fails.
+
+== Before, After, and Inside
+
+= Contact
+
+Jeff Reinecke <jreinecke@whitepages.com>
+
+= Roadmap
+
+TBD
+
+= History
+
+[1.0.0 - 2013-Apr-??] Initial Release.
+
+= License
+
+  Copyright (c) 2012, WhitePages, Inc.
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+      * Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+      * Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in the
+        documentation and/or other materials provided with the distribution.
+      * Neither the name of the company nor the
+        names of its contributors may be used to endorse or promote products
+        derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL WHITEPAGES, INC. BE LIABLE FOR ANY
+  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../Gemfile", Pathname.new(__FILE__).realpath)
+require 'rubygems'
+require 'bundler/setup'
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ['--backtrace']
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.add "lib/**/*.rb", "README.rdoc"
+  rdoc.options << "--all"
+  #rdoc.options << "--coverage-report" # Useful for finding something undocumented, but won't generate output when this is selected!
+end

data/lib/reduxco.rb

@@ -0,0 +1,10 @@
+require 'reduxco/version'
+
+require 'reduxco/callable_ref'
+require 'reduxco/context'
+require 'reduxco/reduxer'
+
+# See README.rdoc or Reduxco::Reduxer
+module Reduxco
+  # Only declared here for RDoc documentation purposes of the module.
+end

data/lib/reduxco/callable_ref.rb

@@ -0,0 +1,142 @@
+module Reduxco
+  # An immutable class that represents a referrence to a callable in a
+  # CallableTable; this class is rarely used directly by clients.
+  class CallableRef
+    include Comparable
+
+    # The minimum depth number allowed.
+    MIN_DEPTH = 1
+
+    # For string representations (typically used in debugging), this is
+    # used as the separator between name and depth (if depth is given).
+    STR_SEPARATOR = ':'
+
+    # For string representations, what is the opening bracket string.
+    STR_LEFT_BRACKET = '<'
+
+    # For string representations, what is the opening bracket string.
+    STR_RIGHT_BRACKET = '>'
+
+    # [name] Typically the name is a symbol, but systems are free to use other
+    #        objects as types are not coerced into other types at any point.
+    #        If the name is a CallableRef, then this acts as a copy constructor.
+    #
+    # [depth] The depth is normally not given when used, can be specified for
+    #         referencing specific shadowed callables when callables are flattend
+    #         into a CallableTable; this is important for calls to super.
+    def initialize(name, depth=nil)
+      case name
+      when self.class
+        @name = name.name
+        @depth = (depth && depth.to_i) || name.depth
+      else
+        @name = name
+        @depth = depth && depth.to_i
+      end
+
+      raise IndexError, "Depth must be greater than zero", caller if depth && depth<MIN_DEPTH
+    end
+
+    # Returns the name of the refernce.
+    attr_reader :name
+
+    # Returns the depth of the reference, or nil if the reference is dynamic.
+    attr_reader :depth
+
+    # Is true valued when the reference will dynamically bind to an entry
+    # in the CallableTable instead of to an entry at a specific depth.
+    def dynamic?
+      return depth.nil?
+    end
+
+    # Negation of dynamic?
+    def static?
+      return !dynamic?
+    end
+
+    # Returns a CallableRef with the same name, but one depth deeper.
+    def succ
+      if( dynamic? )
+        raise RuntimeError, "Dynamic references cannot undergo relative movement."
+      else
+        self.class.new(name, depth.succ)
+      end
+    end
+    alias_method :next, :succ
+
+    # Returns a CallableRef with the same name, but one depth higher.
+    def pred
+      if( dynamic? )
+        raise RuntimeError, "Dynamic references cannot undergo relative movement."
+      else
+        self.class.new(name, depth.pred)
+      end
+    end
+
+    # Returns a unique hash value; useful resolving Hash entries.
+    def hash
+      @hash ||= self.to_a.hash
+    end
+
+    # Returns true if the passed ref is 
+    #
+    # This method raises an exception when compared to anything that does not
+    # ducktype as a reference.
+    def include?(other)
+      other.name == self.name && (dynamic? ? true : other.depth == self.depth)
+    end
+
+    # Returns true if the refs are equivalent.
+    def eql?(other)
+      if( other.kind_of?(CallableRef) || (other.respond_to?(:name) && other.respond_to?(:depth)) )
+        other.name == self.name && other.depth == self.depth
+      else
+        false
+      end
+    end
+    alias_method :==, :eql?
+    alias_method :===, :==
+
+    # Returns the sort order of the reference.  This is primarily useed
+    # for sorting references in CallableTable so that shadowed callables
+    # are called properly.
+    #
+    # Static references are sorted by the following rule: For all sets of static
+    # refs with equal names, sort by depth.  For all sets of static refs with
+    # equal depths, only sort if the names are sortable.  This means that
+    # there is no requirement for sort order to group by name or by depth, and
+    # so no software should be written around an assumption of which comes first.
+    #
+    # Refuses to sort dynamic references, as they are not ordered compared to
+    # static references.
+    def <=>(other)
+      if( dynamic? != other.dynamic? )
+        nil
+      else
+        depth_eql = depth <=> other.depth
+        (depth_eql==0 ? (name <=> other.name) : nil) || depth_eql
+      end
+    end
+
+    # Returns an array form of this CallableReference.
+    def to_a
+      @array ||= [name, depth]
+    end
+
+    # Returns a hash form of this CallableReference.
+    def to_h
+      @hash ||= {name:name, depth:depth}
+    end
+
+    # Returns a human readable string form of this CallableReference.
+    def to_s
+      @string ||= STR_LEFT_BRACKET + self.to_a.compact.map {|prop| prop.to_s}.join(STR_SEPARATOR) + STR_RIGHT_BRACKET
+    end
+
+    # Returns a human readable string form of this CallableReference.
+    def inspect
+      to_s
+    end
+
+  end
+end

data/lib/reduxco/context.rb

@@ -0,0 +1,243 @@
+require_relative 'callable_ref'
+require_relative 'context/callable_table'
+require_relative 'context/callstack'
+
+module Reduxco
+  # Context is the client facing object for Reduxco.
+  #
+  # Typically, one instantiates a Context with one or more maps of callables
+  # by name, and then calls Contxt#reduce to calculate all dependent nodes and return
+  # a result.
+  #
+  # Maps may be any object that, when iterated with each, gives name/callable
+  # pairs. Names may be any object that can serve as a hash key. Callables can
+  # be any object that responds to the call method.
+  #
+  # == Overview
+  #
+  # Context orchestrates the reduction calculation.  It is primarily used
+  # by callables invoked during computation to get access to their environment.
+  #
+  # Instantiators of a Context typically only use the Context#reduce method.
+  #
+  # Users of Reduxco should use Reduxco::Reduxer rather than directly consume
+  # Context directly.
+  #
+  # == Callable Helper Functions
+  #
+  # Callables (objects that respond to call) are the meat of the Context.
+  # When their call method is invoked, it is passed a reference to the Context.
+  # Callables can use this reference to access a range of methods, including
+  # the following:
+  #
+  # [Context#call] Given a refname, run the associated callable and returns
+  #                its value. Usually invoked as Context#[]
+  # [Context#include?] Introspects if a refname is available.
+  # [Context#completed?] Instrospects if a callable has been called and returned.
+  # [Context#after] Given a refname and a block, runs the contents of the block
+  #                 after the given refname, but returns the value of the callable
+  #                 accociated with the refname.
+  # [Context#inside] Given a refname and a block, runs the callable associated
+  #                  with the refname, giving it access to running the block
+  #                  inside of it and getting its value.
+  class Context
+
+    # Special error type for halting due to a cyclic graph.
+    class CyclicalError < StandardError; end
+
+    # Special error type for when the callable provided has no call method.
+    class NotCallableError < NoMethodError; end
+
+    # A namespaced NameError for when the callref cannot be resolved.
+    class NameError < ::NameError; end
+
+    # Special error type when Context assert methods fail. See +assert_computed+.
+    class AssertError < StandardError; end
+
+    # A namespaced LocalJumpError for when no block is given but a yield is called.
+    class LocalJumpError < ::LocalJumpError; end
+
+    # Instantiate a Context with the one or more callalbe maps (e.g. hashes
+    # whose keys are names and values are callable) for calculations.
+    #
+    # The further to the right in the arguments that a map is, the higher
+    # the precedence of itsdefinition.
+    def initialize(*callable_maps)
+      @callable_maps = callable_maps
+      @calltable = CallableTable.new(@callable_maps)
+
+      @callstack = Callstack.new
+      @cache = {}
+
+      @block_association_cache = {}
+    end
+
+    # Given a refname, call it for this context and return the result.
+    #
+    # This can also take CallableRef instances directly, however if you find
+    # yourself passing in static references, this is likely because of design
+    # flaw in your callable map hierarchy.
+    #
+    # Call results are cached so that their values can be re-used.  If callables
+    # have side-effects their side-effects are only invoked the first time
+    # they are run.
+    #
+    # Given a block, Context#yield may be used by the callable to invoke the
+    # block.  Depending on the purpose of the block, Context#inside may be
+    # the preferrable alias.
+    def call(refname=:app, &block)
+      # First, we resolve the callref and invoke it.
+      frame, callable = @calltable.resolve( CallableRef.new(refname) )
+
+      # If the ref is nil then we couldn't resolve, otherwise invoke.
+      if( frame.nil? )
+        raise NameError, "No reference for name #{refname.inspect}", caller
+      else
+        invoke(frame, callable, &block)
+      end
+    end
+    alias_method :reduce, :call
+
+    # Shorthand for call, [] is the most frequently used form of the call method
+    # due to its abbreviated form..
+    alias_method :[], :call
+
+    # Inside is preferred to call when call is given a block and the intent
+    # is to manage flow control.  Compare to Context#before and Context#after.
+    alias_method :inside, :call
+
+    # When invoked, finds the next callable in the CallableTable up the chain
+    # from the current frame, calls it, and returns the result.
+    #
+    # This is primarily used to reference shadowed callables in their overrides.
+    #
+    # Like Context#call, it may take a block that is yielded to with
+    # Context#yield.  If no block is given but the current scope has a block,
+    # its block will be automatically forwarded.
+    def super(&block)
+      # First, we resolve the super ref.
+      frame, callable = @calltable.resolve_super( current_frame )
+
+      # If the ref is nil then we couldn't resolve, otherwise invoke.
+      if( frame.nil? )
+        raise NameError, "No super found for #{current_frame}", caller
+      else
+        block = block_for_frame(current_frame) if block.nil?
+        invoke(frame, callable, &block)
+      end
+    end
+
+    # Yields to the block given to a #Context.call
+    def yield(*args)
+      block = block_for_frame(current_frame)
+      if( block.nil? )
+        raise LocalJumpError, "No block given to yield to.", caller
+      else
+        block.yield(*args)
+      end
+    end
+
+    # Returns a copy of the current callstack.
+    def callstack
+      @callstack.dup
+    end
+
+    # Returns the top frame of the callstack.
+    def current_frame
+      @callstack.top
+    end
+
+    # Returns a true value if the given refname is defined in this context.
+    #
+    # If given a CallableRef, it returns a true value if the reference is
+    # resolvable.
+    def include?(refname)
+      @calltable.resolve( CallableRef.new(refname) ) != CallableTable::RESOLUTION_FAILURE
+    end
+
+    # Returns a true value if the given refname has been computed.
+    #
+    # If the given CallableRef, it returns a true if the reference has already
+    # been computed.
+    def completed?(refname)
+      callref = CallableRef.new(refname)
+      key = callref.dynamic? ? @calltable.resolve(callref).first : callref
+      @cache.include?(key)
+    end
+
+    # Raises an exception if +completed?+ is false.  Useful for asserting weak
+    # dependencies (those which you do not need the return value of) have
+    # been met.
+    def assert_completed(refname)
+      raise AssertError, "Assertion that #{refname} has completed failed.", caller unless completed?(refname)
+    end
+
+    # Runs the passed block before calling the passed refname.  Returns the
+    # value of the call to refname.
+    def before(refname)
+      yield if block_given?
+      call(refname)
+    end
+
+    # Runs the passed block after calling the passed refname.  Returns the
+    # value of the call to refname.
+    def after(refname)
+      result = call(refname)
+      yield if block_given?
+      result
+    end
+
+    # Duplication of Contexts are dangerous because of all the deeply
+    # nested structures.  That being said, it is very tempting to try
+    # to use a well-constructed Context rather than save and reuse the
+    # callable maps used for instantiation.
+    #
+    # To remedy this concern, dup acts as a copy constructor, making a new
+    # Context instance with the same callable maps, but is otherwise
+    # freshly constructed.
+    def dup
+      self.class.new(*@callable_maps)
+    end
+
+    private
+
+    # Invoke is the root method for all invocation of callables.
+    #
+    # It is given the frame to put on the stack (typically just a CallableRef),
+    # and the callable to invoke.
+    #
+    # It is up to the callers of this method to resolve the callable that must
+    # be called, or give a Reduxco::Context::NameError if it cannot be found.
+    def invoke(frame, callable, &block)
+      #Push the frame onto the callstack.
+      @callstack.push(frame)
+
+      # Once we've added the frame to the callstack, we MUST do all work in
+      # a begub/ensure so that exception handling callables get a consistent
+      # callstack!
+      begin
+        # If the ref is already in the stack, then we have a cyclical dependency.
+        if( @callstack.rest.include?(frame) )
+          raise CyclicalError, "Cyclical dependency on #{frame.inspect} in #{@callstack.rest.top.inspect}", callstack.to_caller(caller[1])
+        end
+
+        # Recall from cache, or build if necessary.
+        unless( @cache.include?(frame) )
+          @block_association_cache[frame] = block
+          @cache[frame] = callable.respond_to?(:call) ? callable.call(self) : raise(NotCallableError, "#{frame} does not resolve to a callable.", caller[1..-1])
+        end
+        @cache[frame]
+      ensure
+        # No matter what crashes happened, we must ensure we pop the frame off the stack.
+        popped = @callstack.pop
+      end
+    end
+
+    # Returns the block argument given to the Context#call for the given frame,
+    # or nil if no block was given.
+    def block_for_frame(frame)
+      @block_association_cache[frame]
+    end
+
+  end
+end