spnet 0.1.4 → 0.1.5

data/README.rdoc

@@ -1,8 +1,9 @@
 = spnet
 
 * {Homepage}[https://rubygems.org/gems/spnet]
+* {Source Code}[https://github.com/jamestunnell/spnet]
 * {Documentation}[http://rubydoc.info/gems/spnet/frames]
-* {Email}[mailto:jamestunnell at lavabit.com]
+* {Email}[mailto:jamestunnell@lavabit.com]
 
 == Description
 
@@ -12,9 +13,11 @@ Provide infrastructure for forming processing networks.
 
 Signal ports: Used to pass a stream of data through a block.
 
-Value ports: Used to get/set a value within a block (usually to control a parameter), with optional range limiting.
+Param ports: Used to get/set a value within a block (usually to control a parameter).
 
-Command ports: Used to trigger the execution a command within a block, with optional data as well.
+Command ports: Used to trigger the execution a command within a block, with optional data.
+
+Limiters: Control the limits on values that can be sent into signal or param ports.
 
 == Examples
 

data/lib/spnet.rb

@@ -1,11 +1,29 @@
+require 'hashmake'
+
 require 'spnet/version'
-require 'spnet/in_port'
-require 'spnet/out_port'
-require 'spnet/block'
+
+require 'spnet/core/in_port'
+require 'spnet/core/out_port'
+require 'spnet/core/limiter'
+
+require 'spnet/limiters/no_limiter'
+require 'spnet/limiters/lower_limiter'
+require 'spnet/limiters/upper_limiter'
+require 'spnet/limiters/range_limiter'
+require 'spnet/limiters/enum_limiter'
 
 require 'spnet/ports/signal_in_port'
 require 'spnet/ports/signal_out_port'
-require 'spnet/ports/value_in_port'
-require 'spnet/ports/value_out_port'
+require 'spnet/ports/param_in_port'
+require 'spnet/ports/param_out_port'
 require 'spnet/ports/command_in_port'
 require 'spnet/ports/command_out_port'
+
+require 'spnet/core/block'
+require 'spnet/core/link'
+require 'spnet/core/network'
+
+require 'spnet/storage/port_locater.rb'
+require 'spnet/storage/link_state.rb'
+require 'spnet/storage/block_state.rb'
+require 'spnet/storage/network_state.rb'

data/lib/spnet/core/block.rb

@@ -0,0 +1,46 @@
+module SPNet
+
+# Base class for encapsulating processing functionality. Connects to
+# other blocks via input and output ports.
+#
+# @author James Tunnell
+class Block
+  include Hashmake::HashMakeable
+  
+  attr_reader :in_ports, :out_ports, :sample_rate
+  
+  # Define ArgSpec's to use in processing hashed arguments during #initialize.
+  ARG_SPECS = {
+    :sample_rate => arg_spec(:reqd => true, :type => Numeric, :validator => ->(a){ a > 0 }),
+    :algorithm => arg_spec(:reqd => true, :type => Proc, :validator => ->(p){ p.arity == 1 }),
+    :in_ports => arg_spec_hash(:reqd => false, :type => InPort),
+    :out_ports => arg_spec_hash(:reqd => false, :type => OutPort),
+  }
+  
+  # A new instance of Block.
+  # @param [Hash] args Hashed arguments for initialization. See Block::ARG_SPECS
+  #                    for details of which keys are required.
+  def initialize args = {}
+    hash_make Block::ARG_SPECS, args
+  end
+  
+  # Execute the block algorithm.
+  # @param [Fixnum] count The number of steps to execute. Passed on to the algorithm Proc.
+  def step count
+    @algorithm.call count
+  end
+  
+  # Produces a BlockState object based on this Block object.
+  # @return [BlockState]
+  def export_state
+    port_params = {}
+    @in_ports.each do |name, port|
+      if port.is_a?(ParamInPort)
+        port_params[name] = port.get_value
+      end
+    end
+    
+    BlockState.new(:class_sym => self.class.to_s.to_sym, :port_params => port_params)
+  end
+end
+end

data/lib/spnet/core/in_port.rb

@@ -0,0 +1,41 @@
+module SPNet
+
+# A port that exposes some functionality in a block.
+#
+# @author James Tunnell
+class InPort
+  include Hashmake::HashMakeable
+
+  # Define ArgSpec's to use in processing hashed arguments during #initialize.  
+  ARG_SPECS = {
+    :matching_class => arg_spec(:reqd => true, :type => Class),
+  }
+
+  attr_reader :link, :matching_class
+  
+  # A new instance of InPort.
+  # @param [Hash] args Hashed arguments for initialization. See InPort::ARG_SPECS
+  #                    for details.
+  def initialize args
+    hash_make InPort::ARG_SPECS, args
+    @link = nil
+  end
+
+  # Set @link to the given Link object.
+  def set_link link
+    raise ArgumentError, "link 'to' port is not self" unless link.to == self
+    @link = link
+  end
+
+  # Set @link to nil.
+  def clear_link
+    @link = nil
+  end
+
+  # Return true if @link is not nil.
+  def linked?
+    !link.nil?
+  end
+end
+
+end

data/lib/spnet/core/limiter.rb

@@ -0,0 +1,30 @@
+module SPNet
+
+# Defines a limit, where a value should not be above (for upper limit) or below
+# (for lower limit). If inclusive is set to true, the limit indicates that values
+# at the limit are OK.
+#
+# @author James Tunnell
+class Limit
+  attr_reader :value, :inclusive
+  
+  def inclusive?
+    return @inclusive
+  end
+  
+  def initialize value, inclusive
+    @value = value
+    @inclusive = inclusive
+  end
+end
+
+# Base class for limiting values. Does nothing on it's own.
+#
+# @author James Tunnell
+class Limiter
+  def apply_limit value, current_value
+    raise NotImplementedError
+  end
+end
+
+end

data/lib/spnet/core/link.rb

@@ -0,0 +1,70 @@
+module SPNet
+
+# Form a connection between an OutPort and an InPort.
+#
+# @author James Tunnell
+class Link
+  include Hashmake::HashMakeable
+  
+  # Define arg specs to use in processing hashed arguments during #initialize.
+  ARG_SPECS = {
+    :from => arg_spec(:reqd => true, :type => OutPort),
+    :to => arg_spec(:reqd => true, :type => InPort)
+  }
+  
+  attr_reader :to, :from
+  
+  # A new instance of Link. Link is not active by default (does not set
+  # from.link and to.link to self).
+  # @param [Hash] args Hashed arguments for initialization. See Link::ARG_SPECS
+  #                    for details of which keys are required.
+  def initialize args = {}
+    hash_make Link::ARG_SPECS, args
+    
+    raise ArgumentError, "from port class #{@from.class} is not a #{@to.matching_class}" unless @from.is_a?(@to.matching_class)
+    raise ArgumentError, "to port class #{@to.class} is not a #{@from.matching_class}" unless @to.is_a?(@from.matching_class)
+  end
+  
+  # Make the link active by setting from.link and to.link to self.
+  def activate
+    @from.set_link self
+    @to.set_link self
+  end
+  
+  # Make the link inactive by setting from.link and to.link to nil.
+  def deactivate
+    @from.clear_link
+    @to.clear_link
+  end
+  
+  # Return true if the link is active (from.link and to.link are set to to self).
+  def active?
+    (@from.link == self) && (@to.link == self)
+  end
+
+  # Produce a LinkState object from the current Link object.
+  def export_state blocks
+    from, to = nil, nil
+    
+    blocks.each do |block_name, block|
+      block.out_ports.each do |port_name, port|
+        if port == @from
+          from = PortLocater.new(:block_name => block_name, :port_name => port_name)
+          break
+        end
+      end
+      
+      block.in_ports.each do |port_name, port|
+        if port == @to
+          to = PortLocater.new(:block_name => block_name, :port_name => port_name)
+          break
+        end
+      end
+    end
+    
+    raise "could not find from port" if from.nil?
+    raise "could not find to port" if to.nil?
+    return LinkState.new(:from => from, :to => to)
+  end
+end
+end

data/lib/spnet/core/network.rb

@@ -0,0 +1,54 @@
+module SPNet
+
+# A signal processing network, formed by connecting Block objects with Link objects.
+#
+# @author James Tunnell
+class Network
+  include Hashmake::HashMakeable
+
+  # Define arg specs to use in processing hashed arguments during #initialize.
+  ARG_SPECS = {
+    :sample_rate => arg_spec(:reqd => true, :type => Numeric, :validator => ->(a){a > 0.0}),
+    :name => arg_spec(:reqd => false, :type => String, :default => ""),
+    :blocks => arg_spec_hash(:reqd => false, :type => Block),
+    :links => arg_spec_array(:reqd => false, :type => Link),
+  }
+  
+  attr_reader :sample_rate, :name, :blocks, :links
+  
+  # A new instance of Network. Changes all block sample rates (if necessary) to
+  # match the given sample rate. Activates links.
+  # @param [Hash] args Hashed arguments for initialization. See Network::ARG_SPECS
+  #                    for details of which keys are required.
+  def initialize args = {}
+    hash_make Network::ARG_SPECS, args
+    
+    # ensure that all sample rates match given rate
+    @blocks.each do |block_name, block|
+      if block.sample_rate != @sample_rate
+        raise ArgumentError, "block sample rate #{block.sample_rate} does not match network sample rate #{@sample_rate}"
+      end
+    end
+    
+    @links.each do |link|
+      link.activate
+    end
+  end
+  
+  # Produce a NetworkState object from the current Network object.
+  def export_state
+    block_states = {}
+    @blocks.each do |block_name, block|
+      block_states[block_name] = block.export_state
+    end
+    
+    link_states = []
+    @links.each do |link|
+      link_states.push link.export_state(@blocks)
+    end
+    
+    return NetworkState.new(:name => @name, :block_states => block_states, :link_states => link_states)
+  end
+  
+end
+end

data/lib/spnet/core/out_port.rb

@@ -0,0 +1,41 @@
+module SPNet
+
+# A port that is used to exercise some functionality exposed by an InPort.
+#
+# @author James Tunnell
+class OutPort
+  include Hashmake::HashMakeable
+  
+  # Define ArgSpec's to use in processing hashed arguments during #initialize.
+  ARG_SPECS = {
+    :matching_class => arg_spec(:reqd => true, :type => Class),
+  }
+
+  attr_reader :name, :link, :matching_class
+
+  # A new instance of OutPort.
+  # @param [Hash] args Hashed arguments for initialization. See OutPort::ARG_SPECS
+  #                    for details.  
+  def initialize args
+    hash_make OutPort::ARG_SPECS, args
+    @link = nil
+  end
+
+  # Set @link to the given Link object.
+  def set_link link
+    raise ArgumentError, "link 'from' port is not self" unless link.from == self
+    @link = link
+  end
+
+  # Set @link to nil.
+  def clear_link
+    @link = nil
+  end
+  
+  # Return true if @link is not nil.
+  def linked?
+    !link.nil?
+  end
+end
+
+end

data/lib/spnet/limiters/enum_limiter.rb

@@ -0,0 +1,24 @@
+module SPNet
+# Keeps values to those found in the given Enumerable object.
+#
+# @author James Tunnell
+class EnumLimiter < Limiter
+  attr_reader :values
+  
+  def initialize values
+    raise ArgumentError, "values is not an Enumerable" unless values.is_a?(Enumerable)
+    @values = values
+  end
+  
+  # Limit the given value to those given by @values. If the given value is not
+  # found, return the current value.
+  def apply_limit value, current_value
+    if @values.include? value
+      return value
+    else
+      return current_value
+    end
+  end
+end
+
+end

data/lib/spnet/limiters/lower_limiter.rb

@@ -0,0 +1,31 @@
+module SPNet
+# Keeps values at or above the given Limit.
+#
+# @author James Tunnell
+class LowerLimiter < Limiter
+  attr_reader :limit, :inclusive
+  
+  def initialize limit, inclusive
+    @limit = limit
+    @inclusive = inclusive
+  end
+
+  # Limit the given value to be at or above @limit. Ignores the current_value parameter.
+  def apply_limit value, current_value = nil
+    if inclusive
+      if value >= @limit
+        return value
+      else
+        return @limit
+      end
+    else
+      if value > @limit
+        return value
+      else
+        return @limit + Float::EPSILON
+      end
+    end
+  end
+end
+
+end

data/lib/spnet/limiters/no_limiter.rb

@@ -0,0 +1,11 @@
+module SPNet
+# Does not limit values at all.
+#
+# @author James Tunnell
+class NoLimiter < Limiter
+  # Does not limit at all. Return the given value.
+  def apply_limit value, current_value = nil
+    return value
+  end
+end
+end

data/lib/spnet/limiters/range_limiter.rb

@@ -0,0 +1,24 @@
+module SPNet
+# Keeps values between the given Limit objects.
+#
+# @author James Tunnell
+class RangeLimiter < Limiter
+  attr_reader :lower, :upper
+  
+  def initialize lower_limit, lower_inclusive, upper_limit, upper_inclusive
+    @lower = LowerLimiter.new(lower_limit, lower_inclusive)
+    @upper = UpperLimiter.new(upper_limit, upper_inclusive)
+  end
+
+  # Limit the given value to be between lower and upper limits. Ignores the current_value parameter.  
+  def apply_limit value, current_value = nil
+    new_value = @lower.apply_limit value
+    if(new_value == value)
+      # value is OK so far. Make sure the right (upper) limit is OK too.
+      new_value = @upper.apply_limit value
+    end
+    return new_value
+  end
+end
+
+end