q-language 1.0.0

data/Rakefile

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+# 
+# Copyright © 2010-2011 Jesse Sielaff
+# 
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/methods/test_*.rb'
+end

data/lib/q-language.rb

@@ -0,0 +1,9 @@
+# encoding: UTF-8
+# 
+# Copyright © 2010-2011 Jesse Sielaff
+# 
+
+require 'number'
+
+Dir[File.expand_path("../q-language/*.rb", __FILE__)].sort.each {|f| require f }
+Dir[File.expand_path("../q-language/methods/*.rb", __FILE__)].sort.each {|f| require f }

data/lib/q-language/device.rb

@@ -0,0 +1,166 @@
+# encoding: UTF-8
+# 
+# Copyright © 2010-2011 Jesse Sielaff
+# 
+
+class Q_Device
+  def initialize (script)
+    @script = script
+    parse_script_into_nodes
+    
+    @max_nodes ||= 3000
+    @max_method_nodes ||= 3000
+    
+    @max_array_length ||= 100_000
+    @max_hash_length ||= 100_000
+    @max_string_length ||= 100_000
+  end
+  
+  attr_accessor :max_nodes, :max_method_nodes
+  attr_accessor :max_array_length, :max_hash_length, :max_string_length
+  attr_reader :script
+  
+  # • User method
+  # Removes a Node of the given target type from the Q_Device's tree, rewrites
+  # the Q script based on the new tree, then returns the removed Node. All Nodes
+  # of the given type will be targeted with equal probability. If no target type
+  # is given, Node may be of any type. If no Node of the given type is found,
+  # returns nil.
+  # 
+  def delete_node (target_type = :all)
+    parse_script_into_nodes if @nodes_need_reloading
+    
+    candidate_nodes = nodes(target_type) - [@tree]
+    return nil unless target_node = candidate_nodes.sample
+    
+    target_node.block.nodes.delete(target_node)
+    nodes.delete(target_node)
+    nodes(target_node.node_type).delete(target_node)
+    
+    rewrite_script
+    
+    target_node
+  end
+  
+  # Executes the script in a new Q_Environment with the given variables and
+  # implicit receivers, then returns the Q_Environment.
+  # 
+  def execute (variables = {}, *implicit)
+    parse_script_into_nodes if @nodes_need_reloading
+    
+    object = Class.new.new
+    object.class.send(:define_method, :to_q) { QDynamic.new(self) }
+    
+  begin
+    options = [@max_nodes, @max_method_nodes, @max_array_length, @max_hash_length, @max_string_length]
+    env = Q_Environment.new(variables, *implicit, object, options)
+    env.evaluate(@tree)
+  rescue Q_Environment::TooManyNodes
+  end
+    
+    env
+  end
+  
+  # • User method
+  # Returns a Node of the given type. All Nodes may be chosen with equal
+  # probability. If no node of the given is found, returns nil.
+  # 
+  def get_node (target_type = :all)
+    parse_script_into_nodes if @nodes_need_reloading
+    nodes(target_type).sample
+  end
+  
+  # • User method
+  # Inserts the given Node into a random position in a random block in the tree,
+  # rewrites the Q script based on the new tree, then returns the Node. All
+  # blocks in the tree will be targeted with equal probability.
+  # 
+  def insert_node (new_node)
+    parse_script_into_nodes if @nodes_need_reloading
+    
+    if new_node.is_a? String
+      new_node = Q_Parser.new(new_node).parse.first
+    end
+    
+    nodes_in_target_block = nodes(:block).sample.nodes
+    node_position = rand(nodes_in_target_block.length + 1)
+    
+    nodes_in_target_block.insert(node_position, new_node)
+    nodes.push(new_node)
+    nodes(new_node.node_type).push(new_node)
+    
+    rewrite_script
+    
+    new_node
+  end
+  
+  # • User method
+  # Executes the given block, rewrites the Q script to reflect any changes to
+  # the tree, then returns the result of the block.
+  # 
+  def modify
+    parse_script_into_nodes if @nodes_need_reloading
+    
+    result = yield
+    
+    rewrite_script
+    @nodes_need_reloading = true
+    
+    result
+  end
+  
+  # • User method
+  # Returns the Array containing all Nodes of the given type.
+  # 
+  def nodes (type = :all)
+    parse_script_into_nodes if @nodes_need_reloading
+    instance_variable_get :"@#{type}_nodes"
+  end
+  
+  # Parses the Q script, then stores the resulting tree and all its Nodes.
+  # 
+  def parse_script_into_nodes
+    @tree, @block_nodes, @literal_nodes, @method_nodes, @variable_nodes = Q_Parser.new(@script).parse
+    @all_nodes = @block_nodes + @literal_nodes + @method_nodes + @variable_nodes
+    @nodes_need_reloading = false
+  end
+  
+  # • User method
+  # Replaces a Node of the given target type from the Q_Device's tree with the
+  # given Node, rewrites the Q script based on the new tree, then returns the
+  # removed Node. All Nodes of the given type will be targeted with equal
+  # probability. If no target type is given, removed Node may be of any type. If
+  # no target Node of the given type is found, returns nil.
+  # 
+  def replace_node (new_node, target_type = :all)
+    parse_script_into_nodes if @nodes_need_reloading
+    
+    candidate_nodes = nodes(target_type) - [@tree]
+    return nil unless target_node = candidate_nodes.sample
+    
+    if new_node.is_a? String
+      new_node = Q_Parser.new(new_node).parse.first
+    end
+    
+    nodes_in_parent_block = target_node.block.nodes
+    node_position = nodes_in_parent_block.index(target_node)
+    
+    nodes_in_parent_block[node_position] = new_node
+    
+    nodes.delete(target_node)
+    nodes.push(new_node)
+    
+    nodes(target_node.node_type).delete(target_node)
+    nodes(new_node.node_type).push(new_node)
+    
+    rewrite_script
+    
+    target_node
+  end
+  
+  # Converts the tree into script form, then stores the script.
+  # 
+  def rewrite_script
+    @script = @tree.to_script
+  end
+end

data/lib/q-language/environment.rb

@@ -0,0 +1,358 @@
+# encoding: UTF-8
+# 
+# Copyright © 2010-2011 Jesse Sielaff
+# 
+
+class Q_Environment
+  def initialize (variables = {}, *implicit, object, options)
+    @successful_methods = Hash.new {|h,k| h[k] = 0 }
+    @failed_methods = Hash.new {|h,k| h[k] = 0 }
+    @discarded_objects = Hash.new {|h,k| h[k] = 0 }
+    @nodes_evaluated = Hash.new {|h,k| h[k] = 0 }
+    
+    @max_nodes = options[0]
+    @max_method_nodes = options[1]
+    
+    @max_array_length = options[2]
+    @max_hash_length = options[3]
+    @max_string_length = options[4]
+    
+    @variables = variables.to_hash
+    @implicit = implicit
+    @frame_stack = [object]
+    
+    @scope = { queue: [], method_stack: [], unassigned_variables: [], prev: nil }
+    @method_results = []
+  end
+  
+  TooManyNodes = Class.new(Exception)
+  
+  attr_accessor :max_nodes, :max_method_nodes
+  attr_accessor :max_array_length, :max_hash_length, :max_string_length
+  attr_reader :successful_methods, :failed_methods, :discarded_objects, :nodes_evaluated
+  
+  # Returns a Proc used for iterating over objects in the queue while looking
+  # for QObject method arguments. The returned Proc uses two parameters: an
+  # object from the queue, and that object's index in the queue. If the object
+  # parameter is an instance of the given QObject class and has not yet been
+  # used as the method receiver or as a method argument, the Proc adds the index
+  # parameter to the given indices Array and marks the object's index in the
+  # queue as used.
+  # 
+  def arg_search_block (q_class, indices)
+    proc do |object, i|
+      next if (i == @receiver_index) or @arg_indices.include?(i)
+      
+      if object.to_q.is_a?(q_class)
+        @arg_indices.push(i)
+        indices.push(i)
+        true
+      end
+    end
+  end
+  
+  # Stores the queue indices of the arguments required by the given
+  # method_args_hash in @arg_indices, then returns true. If the queue does not
+  # contain sufficient objects to fulfill the method argument requirements,
+  # returns false.
+  # 
+  def args? (method_args_hash)
+    left_indices = []
+    splat_indices = []
+    right_indices = []
+    queue = @scope[:queue]
+    
+    return false unless method_args_hash[:reqs_left].all? do |q_class|
+      queue.each_with_index.any? &arg_search_block(q_class, left_indices)
+    end
+    
+    return false unless method_args_hash[:reqs_right].all? do |q_class|
+      queue.each_with_index.reverse_each.any? &arg_search_block(q_class, right_indices)
+    end
+    
+    if q_class = method_args_hash[:splat]
+      queue.each_with_index &arg_search_block(q_class, splat_indices)
+    end
+    
+    @arg_indices = left_indices + splat_indices + right_indices
+    true
+  end
+  
+  # Returns a Proc object to be used when calling QObject methods with required
+  # block arguments. The returned Proc uses two optional parameters: the first
+  # is a single argument object (default is nil) that will be associated with
+  # the last unassigned variable name appearing before the block in the script;
+  # the second is the Q_Environment in which to evaluate the block Node embedded
+  # in the Proc object (default is the Q_Environment that created the Proc).
+  # 
+  def block_arg (block_node)
+    return unless block_node
+    
+    parameter_name = @scope[:unassigned_variables].pop
+    
+    lambda do |parameter_object = nil, env = self|
+      env.instance_eval do
+        if has_old_value = @variables.has_key?(parameter_name)
+          old_value = @variables[parameter_name]
+        end
+        
+        set(parameter_name, parameter_object)
+        
+        b, j = @scope[:break], @scope[:jump]
+        
+        @scope = { queue: [], method_stack: [], unassigned_variables: [], prev: @scope }
+        
+        return_value = evaluate(block_node)
+        b = @scope[:break] || b
+        j = @scope[:jump] || j
+        
+        @scope = @scope[:prev]
+        
+        @scope[:break] = b
+        @scope[:jump] = j
+        
+        has_old_value ? set(parameter_name, old_value) : unset(parameter_name)
+        
+        return_value
+      end
+    end
+  end
+  
+  # Returns true if a break flag is set in the current scope, nil otherwise.
+  # 
+  def break?
+    @scope[:break]
+  end
+  
+  # Sets a jump flag in the current scope and a break flag in the previous
+  # scope.
+  # 
+  def break!
+    jump!
+    @scope[:prev][:break] = true
+  end
+  
+  # Evaluates the Node. For a literal Node, calls queue_push with the literal
+  # object. For a method Node, calls method_push with the method name. For a
+  # variable node, calls variable_push with the variable name. For a block Node,
+  # first tries to run any pending method that would succeed with a block
+  # argument; if no method succeeds, adds a new scope level and evaluates each
+  # Node within the block in that scope. Returns the result of calling
+  # queue_push with either the method result or with the the frontmost object
+  # from the nested scope's queue.
+  # 
+  def evaluate (node)
+    raise TooManyNodes if @nodes_evaluated[:total] >= @max_nodes
+    
+    @nodes_evaluated[node.node_type] += 1
+    @nodes_evaluated[:total] += 1
+    
+    case node.node_type
+      when :literal then queue_push(node.value)
+      when :method then method_push(node.value)
+      when :variable then variable_push(node.value)
+      when :block
+        if method?(node)
+          return queue_push(@method_results.pop)
+        end
+        
+        @scope = { queue: [], method_stack: [], unassigned_variables: [], prev: @scope }
+        
+        node.value.each do |node|
+          evaluate node
+          break if @scope[:jump]
+        end
+        
+        return_value = @scope[:queue].shift
+        
+        @scope[:method_stack].each {|name| @failed_methods[name] += 1 }
+        @scope[:queue].each {|obj| @discarded_objects[obj.class] += 1 }
+        @scope = @scope[:prev]
+        
+        return queue_push(return_value)
+    end
+  end
+  
+  # Returns the result of calling the given block with the given object as the
+  # value of self.
+  # 
+  def frame (object, &block)
+    @frame_stack.push(object)
+    result = yield
+    @frame_stack.pop
+    result
+  end
+  
+  # • User method
+  # Returns the object associated with the given variable name, or nil if there
+  # is no such object.
+  # 
+  def get (name)
+    @variables[name]
+  end
+  
+  # Sets a jump flag in the current scope.
+  # 
+  def jump!
+    @scope[:jump] = true
+  end
+  
+  # Returns the name of the last variable used in the current scope that was
+  # associated with an object, or nil if no such variable exists.
+  # 
+  def last_assigned_variable
+    @scope[:last_assigned_variable]
+  end
+  
+  # Pushes the result of calling the top method in the pending methods stack
+  # using the combination of sufficient receiver and arguments found frontmost
+  # in the queue into @method_results, then returns true. If no receiver or
+  # insufficient arguments are found in the queue, returns false. If a
+  # block_node argument is given, attempts to call QObject methods requiring a
+  # block argument.
+  # 
+  def method? (block_node = nil)
+    return false unless name = @scope[:method_stack].last
+    
+    q_receiver = nil
+    potential_receivers = @scope[:queue] + @implicit + [QImplicit.new(@scope[:queue])]
+    
+    potential_receivers.each_with_index do |potential_receiver, receiver_i|
+      @receiver_index = receiver_i
+      q_potential_receiver = potential_receiver.to_q
+      
+      next unless q_potential_receiver.respond_to?(name)
+      
+      method_args_hash = q_potential_receiver.method(name).owner::MethodArguments[name]
+      
+      next if method_args_hash[:block] && !block_node
+      
+      @arg_indices = []
+      
+      if args?(method_args_hash)
+        q_receiver = q_potential_receiver
+        break
+      end
+    end
+    
+    return false unless q_receiver
+    
+    @method_results << q_send(q_receiver, block_node)
+    
+    true
+  end
+  
+  # Pops the top method name from the pending method stack, and increments that
+  # method's success count by 1.
+  # 
+  def method_pop
+    name = @scope[:method_stack].pop
+    @successful_methods[name] += 1
+    name
+  end
+  
+  # If the given method succeeds, calls queue_push with the result; otherwise,
+  # adds the given method name to the top of the pending method stack.
+  # 
+  def method_push (name)
+    @scope[:method_stack].push(name)
+    queue_push(@method_results.pop) if method?
+  end
+  
+  # • User method
+  # Returns the outermost frame object for this Q_Environment.
+  # 
+  def object
+    @frame_stack.first
+  end
+  
+  # Returns the sanitized result of calling the current method with the given
+  # q_receiver, the given block_node as its block arg, and the objects in the
+  # queue at the indices currently stored in @arg_indices as its arguments.
+  # 
+  def q_send (q_receiver, block_node)
+    arg_objects = @arg_indices.map {|i| @scope[:queue][i] }
+    indices = @arg_indices + [@receiver_index]
+    @scope[:queue].reject!.each_with_index {|x,i| indices.include? i }
+    
+    q_receiver.instance_variable_set(:@__environment__, self)
+    sanitize(q_receiver.__send__(method_pop, *arg_objects, &block_arg(block_node)))
+  end
+  
+  # Adds the given object to the end of the queue. Associates all unassigned
+  # variables with the object, then tests whether any pending methods succeed
+  # with the new object in the queue. If so, calls queue_push again with the
+  # result of the successful method; otherwise, returns the given object.
+  # 
+  def queue_push (object)
+    @scope[:queue] << object
+    @scope[:unassigned_variables].each {|v| set(v, object) }.clear
+    
+    method? ? queue_push(@method_results.pop) : object
+  end
+  
+  # Returns a new Q_Environment referencing the same variables, object, and
+  # implicit receivers as this Q_Environment, but with new runtime statistics,
+  # for use in executing methods outside the context of the original Q_Device.
+  # 
+  def replicate
+    options = [@max_nodes, @max_method_nodes, @max_array_length, @max_hash_length, @max_string_length]
+    Q_Environment.new(@variables, *@implicit, @object, options)
+  end
+  
+  # • User method
+  # Returns the return value of the outermost block.
+  # 
+  def return_value
+    @scope[:queue].first
+  end
+  
+  # If the given object is an Array, Hash, or String, returns the object
+  # shortened to the maximum length; otherwise, returns the object unchanged.
+  # 
+  def sanitize (obj)
+    case obj
+      when Array then obj.slice!(0...max_array_length) if obj.length > @max_array_length
+      when Hash then obj.pop while obj.length > @max_hash_length
+      when String then obj.slice!(0...max_string_length) if obj.length > @max_string_length
+    end
+    
+    obj
+  end
+  
+  # Returns the value of self for the current frame.
+  # 
+  def self
+    @frame_stack.last
+  end
+  
+  # • User method
+  # Associates the given variable name with the given object, then returns the
+  # object.
+  # 
+  def set (name, object)
+    return unless name
+    @variables[name] = object
+  end
+  
+  # Unsets the named variable, then returns the object previously associated
+  # with the variable.
+  # 
+  def unset (name)
+    @variables.delete(name)
+  end
+  
+  # If there is an object already associated with the given variable name, marks
+  # that variable name as the last assigned variable, and then calls queue_push
+  # with that object. Otherwise, adds the variable name to the list of
+  # unassigned variables.
+  # 
+  def variable_push (variable)
+    if object = get(variable)
+      @scope[:last_assigned_variable] = variable
+      queue_push(object)
+    else
+      @scope[:unassigned_variables].push(variable)
+    end
+  end
+end