nudge 0.2.6 → 0.2.7

data/lib/instructions/code/code_do_count.rb

@@ -1,4 +1,24 @@
-# Again, the original description of this instruction appears to be confusing "CODE.DO*RANGE" with "EXEC.DO*RANGE"; I've made the adjustment to the code so that the behavior is as described, not the implementation.
+# Pops one "count" item from the +:int+ stack, and one item from the +:code+ stack.
+# The net effect of the instruction (unless interfered with by another operation)
+# is to evaluate the +:code+ item "count" times.
+#
+# If the count is negative, an +:error+ item will be pushed to the +:error+ stack. Otherwise,
+# a ValuePoint containing the following "macro" is created and pushed onto the +:exec+ stack:
+#   block {
+#     value «int»
+#     value «int»
+#     do exec_do_range
+#     popped item
+#   }
+#   «int» 0
+#   «int» count - 1
+# where +popped_item+ is the code from the +:code+ stack, and +count - 1+ is a decrement of
+# the "count" value.
+#
+# *needs:* ExecDoRangeInstruction must be active in the context for this to work; needs 1 +:int+ and 1 +:code+ item
+#
+# *pushes:* it's complicated...
+#
 
 class CodeDoCountInstruction < Instruction
   def preconditions?

data/lib/instructions/code/code_do_range.rb

@@ -1,6 +1,47 @@
-# ORIGINAL DESCRIPTION: An iteration instruction that executes the top item on the CODE stack a number of times that depends on the top two integers, while also pushing the loop counter onto the INTEGER stack for possible access during the execution of the body of the loop. The top integer is the "destination index" and the second integer is the "current index." First the code and the integer arguments are saved locally and popped. Then the integers are compared. If the integers are equal then the current index is pushed onto the INTEGER stack and the code (which is the "body" of the loop) is pushed onto the EXEC stack for subsequent execution. If the integers are not equal then the current index will still be pushed onto the INTEGER stack but two items will be pushed onto the EXEC stack -- first a recursive call to CODE.DO*RANGE (with the same code and destination index, but with a current index that has been either incremented or decremented by 1 to be closer to the destination index) and then the body code. Note that the range is inclusive of both endpoints; a call with integer arguments 3 and 5 will cause its body to be executed 3 times, with the loop counter having the values 3, 4, and 5. Note also that one can specify a loop that "counts down" by providing a destination index that is less than the specified current index.
-
-# That description must be flawed; "a recursive call to CODE.DO*RANGE" would not run the same code, but rather run the next piece of code from the :code stack. I'm interpreting it as a typo, and using exec_do_range instead, since that will have the desired outcome without running through all kinds of weird :code items.
+# Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:code+ stack.
+# The net effect of the instruction (unless interfered with by another operation)
+# is to evaluate the +:code+ item once for every integer in the range (inclusive), and
+# at the same time push the counter integer onto the +:int+ stack.
+#
+# note: rather than duplicating the functionality of the ExecDoRangeInstruction, that is used as a macro here
+#
+# note: the first integer popped is the "destination", the second one the "counter"
+# (regardless of their values or signs)
+#
+# note: unlike the CodeDoTimes instruction, the counter is pushed
+#
+# <b>If the counter and destination have the same value</b>, then a new +:int+ is pushed with that value,
+# and the +:code+ item is pushed onto the +:exec+ stack.
+#
+# <b>If the counter and destination have different values</b>, then a "new_counter" value
+# is calculated that is *one step closer to the destination*.
+#
+# A ValuePoint containing the following "macro" is created:
+#   block {
+#     value «int»
+#     value «int»
+#     do exec_do_range
+#     popped item
+#   }
+#   «int» new_counter
+#   «int» destination
+# where +popped_item+ is the code from the +:code+ stack, and +new_counter+ and +destination+ are the numeric values that were derived above.
+#
+# Finally,
+# 1. a new ValuePoint whose value is +new_counter+ is pushed to the +:int+ stack;
+# 2. the macro is pushed onto the +:exec+ stack
+# 3. another copy of the +popped_item+ is pushed onto the +:exec+ stack (on top of the macro)
+#
+# The consequence is that the original +:code+ item will be executed (at least once),
+# the counter will be pushed onto the +:int+ stack,
+# the macro will be encountered, and this cycle will repeat via the ExecDoRangeInstruction.
+#
+# note: if the +popped_item+ itself manipulates the +:exec+ stack, "complicated behavior" may arise 
+#
+# *needs:* 2 +:int+ items, 1 +:code+ item
+#
+# *pushes:* well, it's complicated...
+#
 
 class CodeDoRangeInstruction < Instruction
   def preconditions?

data/lib/instructions/code/code_do_times.rb

@@ -1,4 +1,42 @@
-# Again, the original description of this instruction appears to be confusing "CODE.DO*RANGE" with "EXEC.DO*RANGE"; I've made the adjustment to the code so that the behavior is as described, not the implementation.
+# Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:code+ stack.
+# The net effect of the instruction (unless interfered with by another operation)
+# is to evaluate the +:exec+ item once for every integer in the range (inclusive).
+#
+# note: the top integer is the "destination", the second one the "counter"
+# (regardless of their values or signs)
+#
+# note: unlike the CodeDoRange instruction, the counter is not pushed
+#
+# <b>If the counter and destination have the same value</b>, then a copy of the +:code+ item is
+# pushed onto the +:exec+ stack.
+#
+# <b>If the counter and destination have different values</b>, then a "new_counter" value
+# is calculated that is *one step closer to the destination*.
+#
+# A ValuePoint containing the following "macro" is created:
+#   block {
+#     value «int»
+#     value «int»
+#     do exec_do_times
+#     popped item
+#   }
+#   «int» new_counter
+#   «int» destination
+# where +popped_item+ is the code from the +:code+ stack, and +new_counter+ and +destination+ are the numeric values that were derived above.
+#
+# Finally,
+# 1. the macro is pushed onto the +:exec+ stack
+# 2. another copy of the +popped_item+ is pushed onto the +:exec+ stack (on top of the macro)
+#
+# The consequence is that the original item will be executed,
+# then the macro will be encountered, and this process will repeat.
+#
+# note: if the +popped_item+ itself manipulates the +:exec+ stack, "complicated behavior" may arise 
+#
+# *needs:* ExecDoTimesInstruction must be active; 2 +:int+ items, 1 +:exec+ item
+#
+# *pushes:* well, it's complicated...
+#
 
 class CodeDoTimesInstruction < Instruction
   def preconditions?

data/lib/instructions/code/code_duplicate.rb

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

data/lib/instructions/code/code_equal_q.rb

@@ -1,3 +1,12 @@
+# pops the top 2 items of the +:code+ stack;
+# pushes a new ValuePoint onto the +:bool+ stack, with value +true+ if the
+# two items' blueprint strings are identical
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
 class CodeEqualQInstruction < Instruction
   def preconditions?
     needs :code, 2

data/lib/instructions/code/code_execute.rb

@@ -1,3 +1,10 @@
+# pops the top item from the +:code+ stack;
+# pushes it onto the +:exec+ stack so it is executed
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:exec+
+
 class CodeExecuteInstruction < Instruction
   def preconditions?
     needs :code, 1

data/lib/instructions/code/code_execute_then_pop.rb

@@ -1,3 +1,12 @@
+# peeks at the top item from the +:code+ stack (without popping it!);
+# pushes a new block containing that code value and "do code_pop" onto the +:exec+ stack,
+# so the item is executed, then removed from the +:code+ stack
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:exec+
+#
+
 class CodeExecuteThenPopInstruction < Instruction
   def preconditions?
     needs CodePopInstruction

data/lib/instructions/code/code_flush.rb

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

data/lib/instructions/code/code_gsub.rb

@@ -1,6 +1,14 @@
-# ORIGINAL PUSH3 DESCRIPTION: Pushes the result of substituting the third item on the code stack for the second item in the first item. As of this writing this is implemented only in the Lisp implementation, within which it relies on the Lisp "subst" function. As such, there are several problematic possibilities; for example "dotted-lists" can result in certain cases with empty-list arguments. If any of these problematic possibilities occurs the stack is left unchanged.
-
-# Here, we will pop three :code items, find all occurrences of the appropriate point in the changed codeblock, and then replace them in last-to-first order (so the point counts discovered initially don't change during substitution)
+# pops three items from the +:code+ stack: the "host", the "old_subtree" and the "new_subtree";
+# pushes a new +:code+ item which contants the +host+, with every occurrence of the +old_subtree+
+# (if any) replaced by the +new_subtree+
+#
+# note: the order of arguments counts; the top +:code+ stack item is the +host+, 
+# the second is the +old_subtree+, and the third is the +new_subtree+
+#
+# *needs:* 3 +:code+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeGsubInstruction < Instruction # was CODE.SUBST in Push3
   def preconditions?

data/lib/instructions/code/code_if.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:code+ stack, and one +:bool+;
+# returns the top +:code+ item if the +:bool+ is +false+, the second one if +true+
+#
+# *needs:* 2 +:code+, 1 +:bool+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeIfInstruction < Instruction
   
   def preconditions?

data/lib/instructions/code/code_instructions.rb

@@ -1,14 +1,26 @@
+# pushes a new +:code+ item whose value is a block containing one call to every
+# Instruction active in the context
+#
+# note: the order of instructions is determined by the order they appear in the context's library
+#
+# *needs:* nothing
+#
+# *pushes:* 1 +:code+
+
 class CodeInstructionsInstruction < Instruction
   def preconditions?
     true
   end
+  
   def setup
   end
+  
   def derive
     all_instructions = @context.instructions
     list_as_block = all_instructions.inject("block {") {|b,i| b + " do #{i.to_nudgecode}"} + "}"
     @result = ValuePoint.new("code", list_as_block)
   end
+  
   def cleanup
     pushes :code, @result
   end

data/lib/instructions/code/code_list.rb

@@ -1,3 +1,13 @@
+# pops the top 2 items from the +:code+ stack;
+# pushes a new +:code+ item containing a block obtained by combining the other listings into one block
+#
+# note: the top stack item (the "attachment") is the second item of the resulting list
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeListInstruction < Instruction
   def preconditions?
     needs :code, 2

data/lib/instructions/code/code_member_q.rb

@@ -1,3 +1,17 @@
+# 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 block in the _backbone_ of the first argument
+#
+# note: order matters, and the top stack item is the second argument, the second stack item is the first
+#
+# note: compare to CodeContainsQInstruction, which checks for matches at all subtrees, not just the "root"
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
+
 class CodeMemberQInstruction < Instruction
   def preconditions?
     needs :code, 2

data/lib/instructions/code/code_name_lookup.rb

@@ -1,3 +1,13 @@
+# pops the top +:name+ item;
+# pushes a new +:code+ item that has a value equal to the current context binding
+#
+# note: if there is no binding, the resulting +:code+ value will be an empty string
+#
+# *needs:* 1 +:name+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeNameLookupInstruction < Instruction  # was Push3 CODE.DEFINITION
   def preconditions?
     needs :name, 1

data/lib/instructions/code/code_noop.rb

@@ -1,3 +1,6 @@
+# does nothing
+#
+
 class CodeNoopInstruction < Instruction
   def preconditions?
     true

data/lib/instructions/code/code_nth.rb

@@ -1,3 +1,15 @@
+# pops the top +:code+ item and +:int+ item ("N");
+# pushes a new +:code+ item containing the Nth backbone element of the +:code+, if it's a block
+#
+# If the +:code+ is not a block, it's replaced intact;
+# if the +:code+ is an empty block, an +:error+ is pushed instead of a +:code+ item;
+# otherwise, the index is chosen as +N+ modulo the length of the block's backbone.
+#
+# *needs:* 1 +:code+ and 1 +:int+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeNthInstruction < Instruction 
   def preconditions?
     needs :int, 1

data/lib/instructions/code/code_nth_cdr.rb

@@ -1,3 +1,15 @@
+# pops the top +:code+ item and +:int+ item ("N");
+# pushes a new +:code+ item, which is the result of removing the first +N+ backbone elements of the +:code+
+#
+# If the +:code+ is not a block, it is wrapped in one first;
+# if +N+ is less than 1, the original code (or newly wrapped atom) is returned;
+# otherwise, the number of items removed is actually the backbone length *modulo* +N+
+#
+# *needs:* 1 +:code+, 1 +:int+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeNthCdrInstruction < Instruction
   def preconditions?
     needs :int, 1
@@ -17,10 +29,10 @@ class CodeNthCdrInstruction < Instruction
       if b_len > 0
         new_tree = CodeblockPoint.new(backbone.contents.slice(@arg1 % b_len, b_len))
       else
-        new_tree = CodeblockPoint.new([])
+        new_tree = backbone
       end
     else
-      new_tree = @arg1 > 0 ? CodeblockPoint.new([tree.linked_code]) : CodeblockPoint.new([])
+      new_tree = @arg1 < 1 ? CodeblockPoint.new([tree.linked_code]) : CodeblockPoint.new([])
     end
     @result = ValuePoint.new("code", new_tree.blueprint)
   end

data/lib/instructions/code/code_nth_point.rb

@@ -1,12 +1,26 @@
+# pops the top +:code+ item and +:int+ item ("N");
+# pushes a new +:code+ item containing the Nth program point of the +:code+
+#
+# If the +:code+ is not a block, it's replaced intact;
+# if the +:code+ value cannot be parsed, an +:error+ is pushed instead of a +:code+ item;
+# otherwise, the index is chosen as +N+ modulo the length of the number of program points.
+#
+# *needs:* 1 +:code+ and 1 +:int+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeNthPointInstruction < Instruction # was CODE.EXTRACT in Push3
   def preconditions?
     needs :int, 1
     needs :code, 1
   end
+  
   def setup
     @arg1 = @context.pop_value(:int)
     @arg2 = @context.pop_value(:code)
   end
+  
   def derive
     tree = NudgeProgram.new(@arg2)
     tree_size = tree.points
@@ -15,6 +29,7 @@ class CodeNthPointInstruction < Instruction # was CODE.EXTRACT in Push3
     pt = tree[which]
     @result = ValuePoint.new("code", pt.blueprint)
   end
+  
   def cleanup
     pushes :code, @result
   end

data/lib/instructions/code/code_null_q.rb

@@ -1,14 +1,25 @@
+# pops the top +:code+ item;
+# pushes a new +:bool+ item with value +true+ if the +:code+ is an empty block
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
 class CodeNullQInstruction < Instruction
   def preconditions?
     needs :code, 1
   end
+  
   def setup
     arg_blueprint = @context.pop_value(:code)
     @arg1 = NudgeProgram.new(arg_blueprint).blueprint
   end
+  
   def derive
     @result = ValuePoint.new("bool", @arg1 == "block {}")
   end
+  
   def cleanup
     pushes :bool, @result
   end

data/lib/instructions/code/code_parses_q.rb

@@ -1,3 +1,11 @@
+# pops the top +:code+ item;
+# pushes a new +:bool+ with value +true+ if the +:code+ can be parsed
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:bool+
+#
+
 class CodeParsesQInstruction < Instruction
   def preconditions?
     needs :code, 1

data/lib/instructions/code/code_points.rb

@@ -1,3 +1,11 @@
+# pops the top +:code+ item;
+# pushes a new +:int+ with the number of program points in the +:code+
+#
+# *needs:* 1 +:code+
+#
+# *pushes:* 1 +:int+
+#
+
 class CodePointsInstruction < Instruction
   
   def preconditions?

data/lib/instructions/code/code_pop.rb

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

data/lib/instructions/code/code_position.rb

@@ -1,3 +1,14 @@
+# pops the top two +:code+ items;
+# pushes a new +:int+ item, with value equal to the program point number in the first argument
+# where the second argument appears as a subtree (or 0 otherwise)
+#
+# note: order of arguments is important; the top stack item is the second argument
+#
+# *needs:* 2 +:code+
+#
+# *pushes:* 1 +:int+
+#
+
 class CodePositionInstruction < Instruction
   def preconditions?
     needs :code, 2