nudge 0.2.6 → 0.2.7

data/lib/instructions/exec/exec_if.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:exec+ stack, and one +:bool+;
+# returns the top +:exec+ item if the +:bool+ is +false+, the second one if +true+
+#
+# *needs:* 2 +:exec+, 1 +:bool+
+#
+# *pushes:* 1 +:exec+
+#
+
 class ExecIfInstruction < Instruction
   
   include IfInstruction

data/lib/instructions/exec/exec_k.rb

@@ -1,3 +1,7 @@
+# Implements the K Combinator on the +:exec+ stack:
+# deletes the second item (replacing the top one).
+#
+
 class ExecKInstruction < Instruction
   def preconditions?
     needs :exec, 2

data/lib/instructions/exec/exec_pop.rb

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

data/lib/instructions/exec/exec_rotate.rb

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

data/lib/instructions/exec/exec_s.rb

@@ -1,3 +1,14 @@
+# Implements the S Combinator on the +:exec+ stack:
+# if the top three items on the stack are A, B, C (in top-to-bottom order), this pushes
+# 1. a CodeBlock containing B and C (in that order)
+# 2. C
+# 3. A
+#
+# *needs:* 3 +:exec+ items
+#
+# *pushes:* 3 +:exec+ items 
+#
+
 class ExecSInstruction < Instruction
   def preconditions?
     needs :exec, 3

data/lib/instructions/exec/exec_shove.rb

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

data/lib/instructions/exec/exec_swap.rb

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

data/lib/instructions/exec/exec_y.rb

@@ -1,3 +1,21 @@
+# Implements the Y Combinator on the +:exec+ stack:
+# pops the top item from the +:exec+ stack, then
+# pushes:
+# * a CodeBlockPoint with the following macro:
+#   block {
+#     do exec_y
+#     popped_item
+#   }
+# * the +popped_item+ (again)
+# 
+# The result is an (arguably infinite) recursive call of the +popped_item+; it will run once, then
+# the macro will be encountered and the process will repeat.
+#
+# *needs:* 1 +:exec+ item
+#
+# *pushes:* 2 +:exec+ items
+
+
 class ExecYInstruction < Instruction
   def preconditions?
     needs :exec, 1

data/lib/instructions/exec/exec_yank.rb

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

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

data/lib/instructions/float/float_abs.rb

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

data/lib/instructions/float/float_add.rb

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

data/lib/instructions/float/float_cosine.rb

@@ -1,3 +1,11 @@
+# pops the top item of the +:float+ stack;
+# pushes a ValuePoint with its cosine onto the +:float+ stack
+#
+# *needs:* 1 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatCosineInstruction < Instruction
   def preconditions?
     needs :float, 1

data/lib/instructions/float/float_define.rb

@@ -1,3 +1,12 @@
+# pops the top item of the +:float+ 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 +:float+ ValuePoint
+#
+# *needs:* 1 +:float+, 1 +:name+
+#
+# *pushes:* nothing
+#
+
 class FloatDefineInstruction < Instruction
   include DefineInstruction
   def initialize(context)

data/lib/instructions/float/float_depth.rb

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

data/lib/instructions/float/float_divide.rb

@@ -1,3 +1,15 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a ValuePoint with their (floating point) quotient onto the +:float+ stack
+#
+# note: the top item is the denominator, the second item is the numerator
+#
+# note: will push an +:error+ ValuePoint instead of an +:int+ if the numerator is 0.0
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatDivideInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_duplicate.rb

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

data/lib/instructions/float/float_equal_q.rb

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

data/lib/instructions/float/float_flush.rb

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

data/lib/instructions/float/float_greater_than_q.rb

@@ -1,3 +1,12 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a new ValuePoint onto the +:bool+ stack,
+# with value +true+ if the second one is strictly greater than the top one
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:bool+
+#
+
 class FloatGreaterThanQInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_if.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:float+ stack, and one +:bool+;
+# returns the top +:float+ item if the +:bool+ is +false+, the second one if +true+
+#
+# *needs:* 2 +:float+, 1 +:bool+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatIfInstruction < Instruction
   
   include IfInstruction

data/lib/instructions/float/float_less_than_q.rb

@@ -1,3 +1,12 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a new ValuePoint onto the +:bool+ stack,
+# with value +true+ if the second one is strictly less than the top one
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:bool+
+#
+
 class FloatLessThanQInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_max.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a new ValuePoint onto the +:float+ stack with the largest of the two values
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatMaxInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_min.rb

@@ -1,3 +1,11 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a new ValuePoint onto the +:float+ stack with the smallest of the two values
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatMinInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_modulo.rb

@@ -1,3 +1,15 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a ValuePoint with the remainder after dividing the second into the first onto the +:float+ stack
+#
+# note: the top item is the denominator, the second item is the numerator
+#
+# note: will push an +:error+ ValuePoint instead of a +:float+ if the numerator is 0.0
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatModuloInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_multiply.rb

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

data/lib/instructions/float/float_negative.rb

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

data/lib/instructions/float/float_pop.rb

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

data/lib/instructions/float/float_power.rb

@@ -1,3 +1,15 @@
+# pops the top 2 items of the +:float+ stack;
+# pushes a ValuePoint with value x**y, where x is the second stack item, y the top one
+#
+# note: the top item is the exponent, the second item is the base
+#
+# note: will push an +:error+ ValuePoint instead of a +:float+ if the operation doesn't return a float
+#
+# *needs:* 2 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatPowerInstruction < Instruction
   def preconditions?
     needs :float, 2

data/lib/instructions/float/float_random.rb

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

data/lib/instructions/float/float_rotate.rb

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

data/lib/instructions/float/float_shove.rb

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

data/lib/instructions/float/float_sine.rb

@@ -1,3 +1,11 @@
+# pops the top item of the +:float+ stack;
+# pushes a ValuePoint with its sine onto the +:float+ stack
+#
+# *needs:* 1 +:float+
+#
+# *pushes:* 1 +:float+
+#
+
 class FloatSineInstruction < Instruction
   def preconditions?
     needs :float, 1