nudge 0.2.6 → 0.2.7

data/VERSION

@@ -1 +1 @@
-0.2.6
+0.2.7

data/lib/instructions/bool/bool_and.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:bool+ stack;
+# pushes a ValuePoint with their logical AND onto the +:bool+ stack
+#
+# *needs:* 2 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolAndInstruction < Instruction
   
   def preconditions?

data/lib/instructions/bool/bool_define.rb

@@ -1,3 +1,12 @@
+# pops the top item of the +:bool+ stack and the +:name+ stack;
+# if the name string is not a bound variable (as opposed to a local name),
+# it binds the name to the +:bool+ ValuePoint
+#
+# *needs:* 1 +:bool+, 1 +:name+
+#
+# *pushes:* nothing
+#
+
 class BoolDefineInstruction < Instruction
   include DefineInstruction
   def initialize(context)

data/lib/instructions/bool/bool_depth.rb

@@ -1,3 +1,8 @@
+# pushes a ValuePoint with the number of items in the +:bool+ stack onto the +:int+ stack
+#
+# *pushes:* 1 +:int+
+#
+
 class BoolDepthInstruction < Instruction
   include DepthInstruction
   def initialize(context)

data/lib/instructions/bool/bool_duplicate.rb

@@ -1,3 +1,10 @@
+# makes and pushes a clone of the top item on the +:bool+ stack
+#
+# *needs:* 1 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolDuplicateInstruction < Instruction
   include DuplicateInstruction
   def initialize(context)

data/lib/instructions/bool/bool_equal_q.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:bool+ stack;
+# pushes a new ValuePoint onto the +:bool+ stack, with value +true+ if the boolean values are identical
+#
+# *needs:* 2 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolEqualQInstruction < Instruction
   
   def preconditions?

data/lib/instructions/bool/bool_flush.rb

@@ -1,3 +1,6 @@
+# deletes all items from the +:bool+ stack
+#
+
 class BoolFlushInstruction < Instruction
   include FlushInstruction
   def initialize(context)

data/lib/instructions/bool/bool_not.rb

@@ -1,3 +1,11 @@
+# pops the top item of the +:bool+ stack;
+# pushes a ValuePoint with the value negated onto the +:bool+ stack
+#
+# *needs:* 1 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolNotInstruction < Instruction
   
   def preconditions?

data/lib/instructions/bool/bool_or.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:bool+ stack;
+# pushes a ValuePoint with their logical OR onto the +:bool+ stack
+#
+# *needs:* 2 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolOrInstruction < Instruction
   
   def preconditions?

data/lib/instructions/bool/bool_pop.rb

@@ -1,3 +1,6 @@
+# pops (and discards) the topmost item from the +:bool+ stack
+#
+
 class BoolPopInstruction < Instruction
   include PopInstruction
   def initialize(context)

data/lib/instructions/bool/bool_random.rb

@@ -1,3 +1,6 @@
+# pushes a new +:bool+ ValuePoint, with value determined by a call to BoolType.any_value
+#
+
 class BoolRandomInstruction < Instruction
   def preconditions?
     true # no preconditions

data/lib/instructions/bool/bool_rotate.rb

@@ -1,3 +1,14 @@
+# pops the top 3 items of the +:bool+ stack;
+# pushes them back in _rotated_ order
+# 
+# If they were A, B and C (with C originally at the top of the stack)
+# the result will be B, C, A (with A at the top)
+#
+# *needs:* 3 +:bool+
+#
+# *pushes:* 3 +:bool+
+#
+
 class BoolRotateInstruction < Instruction
   include RotateInstruction
   def initialize(context)

data/lib/instructions/bool/bool_shove.rb

@@ -1,3 +1,17 @@
+# pops the top items of the +:bool+ and +:int+ stacks;
+# pushes the +:bool+ down "into" the stack, at a level determined by the +:int+ "destination" value.
+# 
+# If the destination value is negative or 0, the item stays on top;
+# if the destination value is greater than or equal to the depth of the stack, the item goes to the bottom;
+# otherwise, the item is inserted farther from the stack's top as the destination value increases.
+# 
+# note: the destination depth is calculated after the items have been popped
+#
+# *needs:* 1 +:bool+, 1 +:int+
+#
+# *pushes:* 1 +:bool+ (sortof)
+#
+
 class BoolShoveInstruction < Instruction
   include ShoveInstruction
   def initialize(context)

data/lib/instructions/bool/bool_swap.rb

@@ -1,3 +1,6 @@
+# exchanges the position of the top 2 items on the +:bool+ stack
+#
+
 class BoolSwapInstruction < Instruction
   include SwapInstruction
   def initialize(context)

data/lib/instructions/bool/bool_xor.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:bool+ stack;
+# pushes a ValuePoint with their logical XOR onto the +:bool+ stack
+#
+# *needs:* 2 +:bool+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolXorInstruction < Instruction
   
   def preconditions?

data/lib/instructions/bool/bool_yank.rb

@@ -1,3 +1,15 @@
+# pops the top item of the +:int+ stack (the "index");
+# then repositions an item from down "inside" the +:bool+ stack to its top.
+# 
+# If the index value is negative or 0, the bottom item on the stack is moved;
+# if the index value is greater than or equal to the depth of the stack, there is no change;
+# otherwise, the index value refers to the bottom-to-top order of stack items.
+#
+# *needs:* 1 +:int+, 1 +:bool+
+#
+# *pushes:* 1 +:bool+ (sortof)
+#
+
 class BoolYankInstruction < Instruction
   include YankInstruction
   def initialize(context)

data/lib/instructions/bool/bool_yankdup.rb

@@ -1,3 +1,15 @@
+# pops the top item of the +:int+ stack (the "index");
+# pushes a duplicate of an item from down "inside" the +:bool+ stack to its top.
+# 
+# If the index value is negative or 0, the bottom item on the stack is copied;
+# if the index value is greater than or equal to the depth of the stack, the top item is copied;
+# otherwise, the index value refers to the bottom-to-top order of stack items.
+#
+# *needs:* 1 +:int+, 1 +:bool+
+#
+# *pushes:* 1 +:bool+ (sortof)
+#
+
 class BoolYankdupInstruction < Instruction
   include YankdupInstruction
   def initialize(context)

data/lib/instructions/code/code_atom_q.rb

@@ -1,3 +1,12 @@
+# pops the top item of the +:code+ stack;
+# pushes a ValuePoint onto the +:bool+ stack that is +false+ only if the +:code+ item was a CodeBlockPoint,
+# (that is, a multi-line Nudge program)
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
 class CodeAtomQInstruction < Instruction
   def preconditions?
     needs :code, 1

data/lib/instructions/code/code_backbone_points.rb

@@ -1,3 +1,20 @@
+# pops the top item from the +:code+ stack;
+# pushes an +:int+ with the number of items <i>in the root</i> of the +:code+ value
+#
+# note: if the +:code+ value does not parse, or is an atom (doesn't parse into a CodeBlockPoint),
+# the result is 0; if it is an empty block, it's also 0
+#
+# For example:
+#   [1,2,[3,4],5] -> 4 backbone points
+#   [[1,2,3,4,5]] -> 1 backbone point
+#   [] -> 0 backbone points
+#   1 -> 0 backbone points
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:int+
+#
+
 class CodeBackbonePointsInstruction < Instruction
   
   def preconditions?

data/lib/instructions/code/code_car.rb

@@ -1,10 +1,24 @@
+# pops the top item from the +:code+ stack;
+# implements a equivalent to Lisp's +car+ function, treating Nudge blocks as lists:
+#
+# If the +:code+ value has at least two points (meaning it's a block with at least 1 element),
+# the new code value is the blueprint of the first element of that block; otherwise the "new"
+# code is the original item's blueprint. A new +:code+ ValuePoint is created with this value and pushed.
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeCarInstruction < Instruction
   def preconditions?
     needs :code, 1
   end
+
   def setup
     @arg = @context.pop_value(:code)
   end
+
   def derive
     tree = NudgeProgram.new(@arg)
     if tree.linked_code.kind_of?(CodeblockPoint) && (tree.points > 2)
@@ -14,6 +28,7 @@ class CodeCarInstruction < Instruction
     end
     @result = ValuePoint.new("code", new_tree.blueprint)
   end
+
   def cleanup
     pushes :code, @result
   end

data/lib/instructions/code/code_cdr.rb

@@ -1,3 +1,15 @@
+# pops the top item from the +:code+ stack;
+# implements a equivalent to Lisp's +cdr+ function, treating Nudge blocks as lists:
+#
+# If the +:code+ value has at least 2 points (meaning it's a block with at least 1 element),
+# the new code value is this block with its first element deleted; otherwise, the result is
+# an empty block.
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeCdrInstruction < Instruction
   def preconditions?
     needs :code, 1
@@ -7,7 +19,7 @@ class CodeCdrInstruction < Instruction
   end
   def derive
     tree = NudgeProgram.new(@arg)
-    if tree.linked_code.kind_of?(CodeblockPoint) && (tree.points > 2)
+    if tree.linked_code.kind_of?(CodeblockPoint) && (tree.points > 1)
       new_tree = tree.delete_point(2)
     else
       new_tree = CodeblockPoint.new([])

data/lib/instructions/code/code_concatenate.rb

@@ -1,3 +1,23 @@
+# pops the top 2 items from the +:code+ stack;
+# pushes a new +:code+ item containing a block obtained by concatenating the other listings
+#
+# note: the top stack item (the "attachment") is concatenated _into_ the second popped item (the "receiver")
+#
+# If both items are already blocks, the new block is their concatenation;
+# if the receiver is a block and the attachment isn't, the attachment is appended to the receiver;
+# if the receiver is not a block, then a _surrounding_ block is constructed that contains both, in order.
+#
+# For example:
+#   [a, b] + [1,2,3] -> [a,b,1,2,3]
+#   [a,b] + 1 -> [a,b,1]
+#   a + [1,2,3] -> [a,[1,2,3]]
+#   a + 1 -> [a,1]
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeConcatenateInstruction < Instruction
   def preconditions?
     needs :code, 2

data/lib/instructions/code/code_cons.rb

@@ -1,4 +1,25 @@
-# This is a tricky one to translate from Push, which assumes a very Lisp-like list structure. Here we'll simply build a new block with the consed item first, and the original code second.
+# pops the top 2 items from the +:code+ stack;
+# pushes a new +:code+ item containing a block, obtained by +cons+ing the other listings, a la Lisp
+#
+# note: order matters, and the top stack item is the second argument, the second stack item is the first
+#
+# If the second argument is a block, the result is obtained by inserting the first argument
+# into that block as the new first element; if the second argument isn't a block, it's first
+# wrapped in one, and then the first argument is inserted into that block.
+#
+# For example:
+#   first_argument + second_argument -> cons result
+#   [a, b] + [1,2,3] -> [[a,b],1,2,3]
+#   [a,b] + 1 -> [[a,b],1]
+#   a + [1,2,3] -> [a,1,2,3]
+#   a + 1 -> [a,1]
+#
+# note: there are several differences between this and +code_concatenate+
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeConsInstruction < Instruction
   def preconditions?

data/lib/instructions/code/code_container.rb

@@ -1,14 +1,32 @@
-# Pushes the "container" of the second CODE stack item within the first CODE stack item onto the CODE stack. If second item contains the first anywhere (i.e. in any nested list) then the container is the smallest sub-list that contains but is not equal to the first instance. For example, if the top piece of code is "( B ( C ( A ) ) ( D ( A ) ) )" and the second piece of code is "( A )" then this pushes ( C ( A ) ). Pushes an empty list if there is no such container
-
+# pops the top 2 items from the +:code+ stack;
+# pushes a new +:code+ item containing a block, which is a copy of the first block in the first argument
+# which contains as a child an exact copy of the second argument
+#
+# note: order matters, and the top stack item is the second argument, the second stack item is the first
+#
+# For example:
+#   first_argument , second_argument -> code_container result
+#   [a, b] , z -> []
+#   [a,b] , a -> [a,b]
+#   [[a,b],c] , a -> [a,b]
+#   [a,[b,[c,d]]] , b -> [b,[c,d]]
+#   [a,b] , [a,b] -> [a,b]
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeContainerInstruction < Instruction
   def preconditions?
     needs :code, 2
   end
+  
   def setup
     @searching_in_this = @context.pop_value(:code)
     @searching_for_this = @context.pop_value(:code)
   end
+  
   def derive
     needle = NudgeProgram.new(@searching_for_this).linked_code.blueprint
     haystack_program = NudgeProgram.new(@searching_in_this)
@@ -22,6 +40,7 @@ class CodeContainerInstruction < Instruction
     end
     @result = ValuePoint.new("code", result_value)
   end
+  
   def cleanup
     pushes :code, @result
   end

data/lib/instructions/code/code_contains_q.rb

@@ -1,3 +1,14 @@
+# pops the top 2 item of the +:code+ stack;
+# pushes a new ValuePoint onto the +:bool+ stack, with value +true+ if the
+# second argument appears as a sub-block anywhere in the first argument
+#
+# note: order matters, and the top stack item is the second argument, the second stack item is the first
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
 class CodeContainsQInstruction < Instruction
   def preconditions?
     needs :code, 2

data/lib/instructions/code/code_define.rb

@@ -1,3 +1,12 @@
+# pops the top item of the +:code+ stack and the +:name+ stack;
+# if the name string is not a bound variable (as opposed to a local name),
+# it binds the name to a new ValuePoint the +:code+ value.
+#
+# *needs:* 1 +:code+, 1 +:name+
+#
+# *pushes:* nothing
+#
+
 class CodeDefineInstruction < Instruction
   def preconditions?
     needs :code, 1

data/lib/instructions/code/code_depth.rb

@@ -1,3 +1,8 @@
+# pushes a ValuePoint with the number of items in the +:code+ stack onto the +:int+ stack
+#
+# *pushes:* 1 +:int+
+#
+
 class CodeDepthInstruction < Instruction
   include DepthInstruction
   def initialize(context)

data/lib/instructions/code/code_discrepancy.rb

@@ -1,10 +1,16 @@
-# ORIGINAL DESCRIPTION in Push3:
-# Pushes a measure of the discrepancy between the top two CODE stack items onto the INTEGER stack. This will be zero if the top two items are equivalent, and will be higher the 'more different' the items are from one another. The calculation is as follows:
-# 1. Construct a list of all of the unique items in both of the lists (where uniqueness is determined by equalp). Sub-lists and atoms all count as items.
-# 2. Initialize the result to zero.
-# 3. For each unique item increment the result by the difference between the number of occurrences of the item in the two pieces of code.
-# 4. Push the result.
-
+# pops the top 2 items of the +:code+ stack;
+# and compares their values algorithmically to obtain an +:int+ value, which it pushes
+#
+# The measure of discrepancy is determined by:
+# 1. first creating a list of every program point's blueprint, for both +:code+ values
+# 2. for every item in the _union_ of these sets of blueprints, accumulate the absolute difference in the number of times the blueprint appears in each of the two items' values
+#
+# the resulting +:int+ is pushed
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:int+
+#
 
 class CodeDiscrepancyInstruction < Instruction
   def preconditions?