nudge 0.2.6 → 0.2.7

data/lib/instructions/code/code_quote.rb

@@ -1,13 +1,24 @@
+# pops the top +:exec+ item;
+# pushes a new +:code+ item that has that value
+#
+# *needs:* 1 +:exec+
+#
+# *pushes:* 1 +:code+
+
+
 class CodeQuoteInstruction < Instruction
   def preconditions?
     needs :exec, 1
   end
+  
   def setup
     @arg = @context.pop(:exec).blueprint
   end
+  
   def derive
     @result = ValuePoint.new("code", @arg)
   end
+  
   def cleanup
     pushes :code, @result
   end

data/lib/instructions/code/code_replace_nth_point.rb

@@ -1,3 +1,14 @@
+# pops the top two +:code+ items ("host" and "target"), and one +:int+ item (the "index");
+# pushes a new +:code+ item, which is the +index+th program point of the +host+
+# is replaced by the +target+ (as a subtree)
+#
+# note: order of arguments is important; the top +:code+ item is the "target" argument
+#
+# *needs:* 2 +:code+, 1 +:int+
+#
+# *pushes:* 1 +:code+
+#
+
 class CodeReplaceNthPointInstruction < Instruction # was CODE.INSERT in Push3
   def preconditions?
     needs :int, 1

data/lib/instructions/code/code_rotate.rb

@@ -1,3 +1,14 @@
+# pops the top 3 items of the +:code+ 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 +:code+
+#
+# *pushes:* 3 +:code+
+#
+
 class CodeRotateInstruction < Instruction
   include RotateInstruction
   def initialize(context)

data/lib/instructions/code/code_shove.rb

@@ -1,3 +1,17 @@
+# pops the top items of the +:code+ and +:int+ stacks;
+# pushes the +:code+ 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 +:code+, 1 +:int+
+#
+# *pushes:* 1 +:code+ (sortof)
+#
+
 class CodeShoveInstruction < Instruction
   include ShoveInstruction
   def initialize(context)

data/lib/instructions/code/code_swap.rb

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

data/lib/instructions/code/code_yank.rb

@@ -1,3 +1,15 @@
+# pops the top item of the +:int+ stack (the "index");
+# then repositions an item from down "inside" the +:code+ 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 +:code+
+#
+# *pushes:* 1 +:code+ (sortof)
+#
+
 class CodeYankInstruction < Instruction
   include YankInstruction
   def initialize(context)

data/lib/instructions/code/code_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 +:code+ 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 +:code+
+#
+# *pushes:* 1 +:code+ (sortof)
+#
+
 class CodeYankdupInstruction < Instruction
   include YankdupInstruction
   def initialize(context)

data/lib/instructions/conversion/bool_from_float.rb

@@ -1,3 +1,12 @@
+# pops the top +:float+ item;
+# pushes a new +:bool+ item,
+# with value +false+ when the +:float+ is 0.0, otherwise +true+
+#
+# *needs:* 1 +:float+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolFromFloatInstruction < Instruction
   def preconditions?
     needs :float, 1

data/lib/instructions/conversion/bool_from_int.rb

@@ -1,3 +1,12 @@
+# pops the top +:int+ item;
+# pushes a new +:bool+ item,
+# with value +false+ when the +:int+ is 0, otherwise +true
+#
+# *needs:* 1 +:int+
+#
+# *pushes:* 1 +:bool+
+#
+
 class BoolFromIntInstruction < Instruction
   def preconditions?
     needs :int, 1

data/lib/instructions/conversion/code_from_bool.rb

@@ -1,4 +1,12 @@
-#encoding: utf-8
+# encoding: utf-8
+# pops the top +:bool+ item;
+# pushes a new +:code+ item,
+# with value equal to the +:bool+ item's blueprint
+#
+# *needs:* 1 +:bool+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeFromBoolInstruction < Instruction
   def preconditions?

data/lib/instructions/conversion/code_from_float.rb

@@ -1,4 +1,13 @@
-#encoding: utf-8
+# encoding: utf-8
+
+# pops the top +:float+ item;
+# pushes a new +:code+ item,
+# with value equal to the +:float+ item's blueprint
+#
+# *needs:* 1 +:float+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeFromFloatInstruction < Instruction
   def preconditions?

data/lib/instructions/conversion/code_from_int.rb

@@ -1,4 +1,13 @@
-#encoding: utf-8
+# encoding: utf-8
+
+# pops the top +:int+ item;
+# pushes a new +:code+ item,
+# with value equal to the +:int+ item's blueprint
+#
+# *needs:* 1 +:int+
+#
+# *pushes:* 1 +:code+
+#
 
 
 class CodeFromIntInstruction < Instruction

data/lib/instructions/conversion/code_from_name.rb

@@ -1,4 +1,13 @@
-#encoding: utf-8
+# encoding: utf-8
+
+# pops the top +:name+ item;
+# pushes a new +:code+ item,
+# with value equal to the +:name+ item's blueprint
+#
+# *needs:* 1 +:name+
+#
+# *pushes:* 1 +:code+
+#
 
 class CodeFromNameInstruction < Instruction
   def preconditions?

data/lib/instructions/conversion/float_from_bool.rb

@@ -1,3 +1,12 @@
+# pops the top +:bool+ item;
+# pushes a new +:float+ item,
+# with value 0.0 when the +:bool+ is +false+, otherwise 1.0
+#
+# *needs:* 1 +:bool+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatFromBoolInstruction < Instruction
   def preconditions?
     needs :bool, 1

data/lib/instructions/conversion/float_from_int.rb

@@ -1,3 +1,12 @@
+# pops the top +:int+ item;
+# pushes a new +:float+ item,
+# with value obtained by applying #to_f to the value
+#
+# *needs:* 1 +:int+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatFromIntInstruction < Instruction
   def preconditions?
     needs :int, 1

data/lib/instructions/conversion/int_from_bool.rb

@@ -1,3 +1,12 @@
+# pops the top +:bool+ item;
+# pushes a new +:int+ item,
+# with value 0 when the +:bool+ is +false+, otherwise 1
+#
+# *needs:* 1 +:bool+
+#
+# *pushes:* 1 +:int+
+#
+
 class IntFromBoolInstruction < Instruction
   def preconditions?
     needs :bool, 1

data/lib/instructions/conversion/int_from_float.rb

@@ -1,3 +1,12 @@
+# pops the top +:float+ item;
+# pushes a new +:int+ item,
+# with value obtained by applying #to_i to the value
+#
+# *needs:* 1 +:float+
+#
+# *pushes:* 1 +:int+
+#
+
 class IntFromFloatInstruction < Instruction
   def preconditions?
     needs :float, 1

data/lib/instructions/exec/exec_define.rb

@@ -1,3 +1,12 @@
+# pops the top item of the +:exec+ 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 with type +:code+ and value derived from the +:exec+ item.
+#
+# *needs:* 1 +:exec+, 1 +:name+
+#
+# *pushes:* nothing
+#
+
 class ExecDefineInstruction < Instruction
   include DefineInstruction
   def initialize(context)

data/lib/instructions/exec/exec_depth.rb

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

data/lib/instructions/exec/exec_do_count.rb

@@ -1,3 +1,25 @@
+# Pops one "count" item from the +:int+ stack, and one item from the +:exec+ stack.
+# The net effect of the instruction (unless interfered with by another operation)
+# is to evaluate the +:exec+ 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 +:exec+ 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 +:exec+ item
+#
+# *pushes:* it's complicated...
+#
+
 class ExecDoCountInstruction < Instruction
   def preconditions?
     needs ExecDoRangeInstruction

data/lib/instructions/exec/exec_do_range.rb

@@ -1,3 +1,46 @@
+# Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:exec+ 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), and
+# at the same time push the counter integer onto the +:int+ stack.
+#
+# note: the first integer popped is the "destination", the second one the "counter"
+# (regardless of their values or signs)
+#
+# note: unlike the ExecDoTimes 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 +:exec+ 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 +:exec+ 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 item will be executed,
+# the counter will be pushed onto the +:int+ stack,
+# 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:* 2 +:int+ items, 1 +:exec+ item
+#
+# *pushes:* well, it's complicated...
+#
+
 class ExecDoRangeInstruction < Instruction
   def preconditions?
     needs :exec, 1

data/lib/instructions/exec/exec_do_times.rb

@@ -1,3 +1,43 @@
+# Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:exec+ 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 ExecDoRange instruction, the counter is not pushed
+#
+# <b>If the counter and destination have the same value</b>, then a copy of the +:exec+ 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 +:exec+ 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:* 2 +:int+ items, 1 +:exec+ item
+#
+# *pushes:* well, it's complicated...
+#
+
 class ExecDoTimesInstruction < Instruction
   def preconditions?
     needs :exec, 1

data/lib/instructions/exec/exec_duplicate.rb

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

data/lib/instructions/exec/exec_equal_q.rb

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

data/lib/instructions/exec/exec_flush.rb

@@ -1,3 +1,8 @@
+# deletes all items from the +:exec+ stack
+#
+# note: this is the equivalent of a "BREAK" statement in many other languages
+# 
+
 class ExecFlushInstruction < Instruction
   include FlushInstruction
   def initialize(context)