nudge 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. data/VERSION +1 -1
  2. data/lib/instructions/bool/bool_and.rb +8 -0
  3. data/lib/instructions/bool/bool_define.rb +9 -0
  4. data/lib/instructions/bool/bool_depth.rb +5 -0
  5. data/lib/instructions/bool/bool_duplicate.rb +7 -0
  6. data/lib/instructions/bool/bool_equal_q.rb +8 -0
  7. data/lib/instructions/bool/bool_flush.rb +3 -0
  8. data/lib/instructions/bool/bool_not.rb +8 -0
  9. data/lib/instructions/bool/bool_or.rb +8 -0
  10. data/lib/instructions/bool/bool_pop.rb +3 -0
  11. data/lib/instructions/bool/bool_random.rb +3 -0
  12. data/lib/instructions/bool/bool_rotate.rb +11 -0
  13. data/lib/instructions/bool/bool_shove.rb +14 -0
  14. data/lib/instructions/bool/bool_swap.rb +3 -0
  15. data/lib/instructions/bool/bool_xor.rb +8 -0
  16. data/lib/instructions/bool/bool_yank.rb +12 -0
  17. data/lib/instructions/bool/bool_yankdup.rb +12 -0
  18. data/lib/instructions/code/code_atom_q.rb +9 -0
  19. data/lib/instructions/code/code_backbone_points.rb +17 -0
  20. data/lib/instructions/code/code_car.rb +15 -0
  21. data/lib/instructions/code/code_cdr.rb +13 -1
  22. data/lib/instructions/code/code_concatenate.rb +20 -0
  23. data/lib/instructions/code/code_cons.rb +22 -1
  24. data/lib/instructions/code/code_container.rb +21 -2
  25. data/lib/instructions/code/code_contains_q.rb +11 -0
  26. data/lib/instructions/code/code_define.rb +9 -0
  27. data/lib/instructions/code/code_depth.rb +5 -0
  28. data/lib/instructions/code/code_discrepancy.rb +13 -7
  29. data/lib/instructions/code/code_do_count.rb +21 -1
  30. data/lib/instructions/code/code_do_range.rb +44 -3
  31. data/lib/instructions/code/code_do_times.rb +39 -1
  32. data/lib/instructions/code/code_duplicate.rb +7 -0
  33. data/lib/instructions/code/code_equal_q.rb +9 -0
  34. data/lib/instructions/code/code_execute.rb +7 -0
  35. data/lib/instructions/code/code_execute_then_pop.rb +9 -0
  36. data/lib/instructions/code/code_flush.rb +3 -0
  37. data/lib/instructions/code/code_gsub.rb +11 -3
  38. data/lib/instructions/code/code_if.rb +8 -0
  39. data/lib/instructions/code/code_instructions.rb +12 -0
  40. data/lib/instructions/code/code_list.rb +10 -0
  41. data/lib/instructions/code/code_member_q.rb +14 -0
  42. data/lib/instructions/code/code_name_lookup.rb +10 -0
  43. data/lib/instructions/code/code_noop.rb +3 -0
  44. data/lib/instructions/code/code_nth.rb +12 -0
  45. data/lib/instructions/code/code_nth_cdr.rb +14 -2
  46. data/lib/instructions/code/code_nth_point.rb +15 -0
  47. data/lib/instructions/code/code_null_q.rb +11 -0
  48. data/lib/instructions/code/code_parses_q.rb +8 -0
  49. data/lib/instructions/code/code_points.rb +8 -0
  50. data/lib/instructions/code/code_pop.rb +3 -0
  51. data/lib/instructions/code/code_position.rb +11 -0
  52. data/lib/instructions/code/code_quote.rb +11 -0
  53. data/lib/instructions/code/code_replace_nth_point.rb +11 -0
  54. data/lib/instructions/code/code_rotate.rb +11 -0
  55. data/lib/instructions/code/code_shove.rb +14 -0
  56. data/lib/instructions/code/code_swap.rb +3 -0
  57. data/lib/instructions/code/code_yank.rb +12 -0
  58. data/lib/instructions/code/code_yankdup.rb +12 -0
  59. data/lib/instructions/conversion/bool_from_float.rb +9 -0
  60. data/lib/instructions/conversion/bool_from_int.rb +9 -0
  61. data/lib/instructions/conversion/code_from_bool.rb +9 -1
  62. data/lib/instructions/conversion/code_from_float.rb +10 -1
  63. data/lib/instructions/conversion/code_from_int.rb +10 -1
  64. data/lib/instructions/conversion/code_from_name.rb +10 -1
  65. data/lib/instructions/conversion/float_from_bool.rb +9 -0
  66. data/lib/instructions/conversion/float_from_int.rb +9 -0
  67. data/lib/instructions/conversion/int_from_bool.rb +9 -0
  68. data/lib/instructions/conversion/int_from_float.rb +9 -0
  69. data/lib/instructions/exec/exec_define.rb +9 -0
  70. data/lib/instructions/exec/exec_depth.rb +5 -0
  71. data/lib/instructions/exec/exec_do_count.rb +22 -0
  72. data/lib/instructions/exec/exec_do_range.rb +43 -0
  73. data/lib/instructions/exec/exec_do_times.rb +40 -0
  74. data/lib/instructions/exec/exec_duplicate.rb +7 -0
  75. data/lib/instructions/exec/exec_equal_q.rb +9 -0
  76. data/lib/instructions/exec/exec_flush.rb +5 -0
  77. data/lib/instructions/exec/exec_if.rb +8 -0
  78. data/lib/instructions/exec/exec_k.rb +4 -0
  79. data/lib/instructions/exec/exec_pop.rb +3 -0
  80. data/lib/instructions/exec/exec_rotate.rb +11 -0
  81. data/lib/instructions/exec/exec_s.rb +11 -0
  82. data/lib/instructions/exec/exec_shove.rb +14 -0
  83. data/lib/instructions/exec/exec_swap.rb +3 -0
  84. data/lib/instructions/exec/exec_y.rb +18 -0
  85. data/lib/instructions/exec/exec_yank.rb +12 -0
  86. data/lib/instructions/exec/exec_yankdup.rb +12 -0
  87. data/lib/instructions/float/float_abs.rb +8 -0
  88. data/lib/instructions/float/float_add.rb +8 -0
  89. data/lib/instructions/float/float_cosine.rb +8 -0
  90. data/lib/instructions/float/float_define.rb +9 -0
  91. data/lib/instructions/float/float_depth.rb +5 -0
  92. data/lib/instructions/float/float_divide.rb +12 -0
  93. data/lib/instructions/float/float_duplicate.rb +7 -0
  94. data/lib/instructions/float/float_equal_q.rb +8 -0
  95. data/lib/instructions/float/float_flush.rb +3 -0
  96. data/lib/instructions/float/float_greater_than_q.rb +9 -0
  97. data/lib/instructions/float/float_if.rb +8 -0
  98. data/lib/instructions/float/float_less_than_q.rb +9 -0
  99. data/lib/instructions/float/float_max.rb +8 -0
  100. data/lib/instructions/float/float_min.rb +8 -0
  101. data/lib/instructions/float/float_modulo.rb +12 -0
  102. data/lib/instructions/float/float_multiply.rb +8 -0
  103. data/lib/instructions/float/float_negative.rb +8 -0
  104. data/lib/instructions/float/float_pop.rb +3 -0
  105. data/lib/instructions/float/float_power.rb +12 -0
  106. data/lib/instructions/float/float_random.rb +3 -0
  107. data/lib/instructions/float/float_rotate.rb +11 -0
  108. data/lib/instructions/float/float_shove.rb +14 -0
  109. data/lib/instructions/float/float_sine.rb +8 -0
  110. data/lib/instructions/float/float_sqrt.rb +10 -0
  111. data/lib/instructions/float/float_subtract.rb +10 -0
  112. data/lib/instructions/float/float_swap.rb +3 -0
  113. data/lib/instructions/float/float_tangent.rb +8 -0
  114. data/lib/instructions/float/float_yank.rb +12 -0
  115. data/lib/instructions/float/float_yankdup.rb +12 -0
  116. data/lib/instructions/int/int_abs.rb +9 -1
  117. data/lib/instructions/int/int_add.rb +8 -0
  118. data/lib/instructions/int/int_define.rb +10 -1
  119. data/lib/instructions/int/int_depth.rb +5 -0
  120. data/lib/instructions/int/int_divide.rb +12 -0
  121. data/lib/instructions/int/int_duplicate.rb +7 -0
  122. data/lib/instructions/int/int_equal_q.rb +8 -0
  123. data/lib/instructions/int/int_flush.rb +3 -0
  124. data/lib/instructions/int/int_greater_than_q.rb +9 -0
  125. data/lib/instructions/int/int_if.rb +8 -0
  126. data/lib/instructions/int/int_less_than_q.rb +9 -0
  127. data/lib/instructions/int/int_max.rb +8 -0
  128. data/lib/instructions/int/int_min.rb +8 -0
  129. data/lib/instructions/int/int_modulo.rb +12 -0
  130. data/lib/instructions/int/int_multiply.rb +8 -0
  131. data/lib/instructions/int/int_negative.rb +8 -0
  132. data/lib/instructions/int/int_pop.rb +3 -0
  133. data/lib/instructions/int/int_power.rb +12 -0
  134. data/lib/instructions/int/int_random.rb +3 -0
  135. data/lib/instructions/int/int_rotate.rb +11 -0
  136. data/lib/instructions/int/int_shove.rb +14 -0
  137. data/lib/instructions/int/int_subtract.rb +10 -0
  138. data/lib/instructions/int/int_swap.rb +3 -0
  139. data/lib/instructions/int/int_yank.rb +14 -0
  140. data/lib/instructions/int/int_yankdup.rb +14 -0
  141. data/lib/instructions/name/name_depth.rb +5 -0
  142. data/lib/instructions/name/name_disable_lookup.rb +11 -0
  143. data/lib/instructions/name/name_duplicate.rb +7 -0
  144. data/lib/instructions/name/name_equal_q.rb +8 -0
  145. data/lib/instructions/name/name_flush.rb +3 -0
  146. data/lib/instructions/name/name_next.rb +7 -0
  147. data/lib/instructions/name/name_pop.rb +3 -0
  148. data/lib/instructions/name/name_random_bound.rb +9 -0
  149. data/lib/instructions/name/name_rotate.rb +11 -0
  150. data/lib/instructions/name/name_shove.rb +14 -0
  151. data/lib/instructions/name/name_swap.rb +3 -0
  152. data/lib/instructions/name/name_unbind.rb +7 -0
  153. data/lib/instructions/name/name_yank.rb +12 -0
  154. data/lib/instructions/name/name_yankdup.rb +12 -0
  155. data/spec/instructions/code/code_nth_cdr_spec.rb +10 -2
  156. metadata +3 -3
@@ -1,13 +1,24 @@
1
+ # pops the top +:exec+ item;
2
+ # pushes a new +:code+ item that has that value
3
+ #
4
+ # *needs:* 1 +:exec+
5
+ #
6
+ # *pushes:* 1 +:code+
7
+
8
+
1
9
  class CodeQuoteInstruction < Instruction
2
10
  def preconditions?
3
11
  needs :exec, 1
4
12
  end
13
+
5
14
  def setup
6
15
  @arg = @context.pop(:exec).blueprint
7
16
  end
17
+
8
18
  def derive
9
19
  @result = ValuePoint.new("code", @arg)
10
20
  end
21
+
11
22
  def cleanup
12
23
  pushes :code, @result
13
24
  end
@@ -1,3 +1,14 @@
1
+ # pops the top two +:code+ items ("host" and "target"), and one +:int+ item (the "index");
2
+ # pushes a new +:code+ item, which is the +index+th program point of the +host+
3
+ # is replaced by the +target+ (as a subtree)
4
+ #
5
+ # note: order of arguments is important; the top +:code+ item is the "target" argument
6
+ #
7
+ # *needs:* 2 +:code+, 1 +:int+
8
+ #
9
+ # *pushes:* 1 +:code+
10
+ #
11
+
1
12
  class CodeReplaceNthPointInstruction < Instruction # was CODE.INSERT in Push3
2
13
  def preconditions?
3
14
  needs :int, 1
@@ -1,3 +1,14 @@
1
+ # pops the top 3 items of the +:code+ stack;
2
+ # pushes them back in _rotated_ order
3
+ #
4
+ # If they were A, B and C (with C originally at the top of the stack)
5
+ # the result will be B, C, A (with A at the top)
6
+ #
7
+ # *needs:* 3 +:code+
8
+ #
9
+ # *pushes:* 3 +:code+
10
+ #
11
+
1
12
  class CodeRotateInstruction < Instruction
2
13
  include RotateInstruction
3
14
  def initialize(context)
@@ -1,3 +1,17 @@
1
+ # pops the top items of the +:code+ and +:int+ stacks;
2
+ # pushes the +:code+ down "into" the stack, at a level determined by the +:int+ "destination" value.
3
+ #
4
+ # If the destination value is negative or 0, the item stays on top;
5
+ # if the destination value is greater than or equal to the depth of the stack, the item goes to the bottom;
6
+ # otherwise, the item is inserted farther from the stack's top as the destination value increases.
7
+ #
8
+ # note: the destination depth is calculated after the items have been popped
9
+ #
10
+ # *needs:* 1 +:code+, 1 +:int+
11
+ #
12
+ # *pushes:* 1 +:code+ (sortof)
13
+ #
14
+
1
15
  class CodeShoveInstruction < Instruction
2
16
  include ShoveInstruction
3
17
  def initialize(context)
@@ -1,3 +1,6 @@
1
+ # exchanges the position of the top 2 items on the +:code+ stack
2
+ #
3
+
1
4
  class CodeSwapInstruction < Instruction
2
5
  include SwapInstruction
3
6
  def initialize(context)
@@ -1,3 +1,15 @@
1
+ # pops the top item of the +:int+ stack (the "index");
2
+ # then repositions an item from down "inside" the +:code+ stack to its top.
3
+ #
4
+ # If the index value is negative or 0, the bottom item on the stack is moved;
5
+ # if the index value is greater than or equal to the depth of the stack, there is no change;
6
+ # otherwise, the index value refers to the bottom-to-top order of stack items.
7
+ #
8
+ # *needs:* 1 +:int+, 1 +:code+
9
+ #
10
+ # *pushes:* 1 +:code+ (sortof)
11
+ #
12
+
1
13
  class CodeYankInstruction < Instruction
2
14
  include YankInstruction
3
15
  def initialize(context)
@@ -1,3 +1,15 @@
1
+ # pops the top item of the +:int+ stack (the "index");
2
+ # pushes a duplicate of an item from down "inside" the +:code+ stack to its top.
3
+ #
4
+ # If the index value is negative or 0, the bottom item on the stack is copied;
5
+ # if the index value is greater than or equal to the depth of the stack, the top item is copied;
6
+ # otherwise, the index value refers to the bottom-to-top order of stack items.
7
+ #
8
+ # *needs:* 1 +:int+, 1 +:code+
9
+ #
10
+ # *pushes:* 1 +:code+ (sortof)
11
+ #
12
+
1
13
  class CodeYankdupInstruction < Instruction
2
14
  include YankdupInstruction
3
15
  def initialize(context)
@@ -1,3 +1,12 @@
1
+ # pops the top +:float+ item;
2
+ # pushes a new +:bool+ item,
3
+ # with value +false+ when the +:float+ is 0.0, otherwise +true+
4
+ #
5
+ # *needs:* 1 +:float+
6
+ #
7
+ # *pushes:* 1 +:bool+
8
+ #
9
+
1
10
  class BoolFromFloatInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :float, 1
@@ -1,3 +1,12 @@
1
+ # pops the top +:int+ item;
2
+ # pushes a new +:bool+ item,
3
+ # with value +false+ when the +:int+ is 0, otherwise +true
4
+ #
5
+ # *needs:* 1 +:int+
6
+ #
7
+ # *pushes:* 1 +:bool+
8
+ #
9
+
1
10
  class BoolFromIntInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :int, 1
@@ -1,4 +1,12 @@
1
- #encoding: utf-8
1
+ # encoding: utf-8
2
+ # pops the top +:bool+ item;
3
+ # pushes a new +:code+ item,
4
+ # with value equal to the +:bool+ item's blueprint
5
+ #
6
+ # *needs:* 1 +:bool+
7
+ #
8
+ # *pushes:* 1 +:code+
9
+ #
2
10
 
3
11
  class CodeFromBoolInstruction < Instruction
4
12
  def preconditions?
@@ -1,4 +1,13 @@
1
- #encoding: utf-8
1
+ # encoding: utf-8
2
+
3
+ # pops the top +:float+ item;
4
+ # pushes a new +:code+ item,
5
+ # with value equal to the +:float+ item's blueprint
6
+ #
7
+ # *needs:* 1 +:float+
8
+ #
9
+ # *pushes:* 1 +:code+
10
+ #
2
11
 
3
12
  class CodeFromFloatInstruction < Instruction
4
13
  def preconditions?
@@ -1,4 +1,13 @@
1
- #encoding: utf-8
1
+ # encoding: utf-8
2
+
3
+ # pops the top +:int+ item;
4
+ # pushes a new +:code+ item,
5
+ # with value equal to the +:int+ item's blueprint
6
+ #
7
+ # *needs:* 1 +:int+
8
+ #
9
+ # *pushes:* 1 +:code+
10
+ #
2
11
 
3
12
 
4
13
  class CodeFromIntInstruction < Instruction
@@ -1,4 +1,13 @@
1
- #encoding: utf-8
1
+ # encoding: utf-8
2
+
3
+ # pops the top +:name+ item;
4
+ # pushes a new +:code+ item,
5
+ # with value equal to the +:name+ item's blueprint
6
+ #
7
+ # *needs:* 1 +:name+
8
+ #
9
+ # *pushes:* 1 +:code+
10
+ #
2
11
 
3
12
  class CodeFromNameInstruction < Instruction
4
13
  def preconditions?
@@ -1,3 +1,12 @@
1
+ # pops the top +:bool+ item;
2
+ # pushes a new +:float+ item,
3
+ # with value 0.0 when the +:bool+ is +false+, otherwise 1.0
4
+ #
5
+ # *needs:* 1 +:bool+
6
+ #
7
+ # *pushes:* 1 +:float+
8
+ #
9
+
1
10
  class FloatFromBoolInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :bool, 1
@@ -1,3 +1,12 @@
1
+ # pops the top +:int+ item;
2
+ # pushes a new +:float+ item,
3
+ # with value obtained by applying #to_f to the value
4
+ #
5
+ # *needs:* 1 +:int+
6
+ #
7
+ # *pushes:* 1 +:float+
8
+ #
9
+
1
10
  class FloatFromIntInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :int, 1
@@ -1,3 +1,12 @@
1
+ # pops the top +:bool+ item;
2
+ # pushes a new +:int+ item,
3
+ # with value 0 when the +:bool+ is +false+, otherwise 1
4
+ #
5
+ # *needs:* 1 +:bool+
6
+ #
7
+ # *pushes:* 1 +:int+
8
+ #
9
+
1
10
  class IntFromBoolInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :bool, 1
@@ -1,3 +1,12 @@
1
+ # pops the top +:float+ item;
2
+ # pushes a new +:int+ item,
3
+ # with value obtained by applying #to_i to the value
4
+ #
5
+ # *needs:* 1 +:float+
6
+ #
7
+ # *pushes:* 1 +:int+
8
+ #
9
+
1
10
  class IntFromFloatInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :float, 1
@@ -1,3 +1,12 @@
1
+ # pops the top item of the +:exec+ stack and the +:name+ stack;
2
+ # if the name string is not a bound variable (as opposed to a local name),
3
+ # it binds the name to a new ValuePoint with type +:code+ and value derived from the +:exec+ item.
4
+ #
5
+ # *needs:* 1 +:exec+, 1 +:name+
6
+ #
7
+ # *pushes:* nothing
8
+ #
9
+
1
10
  class ExecDefineInstruction < Instruction
2
11
  include DefineInstruction
3
12
  def initialize(context)
@@ -1,3 +1,8 @@
1
+ # pushes a ValuePoint with the number of items in the +:exec+ stack onto the +:int+ stack
2
+ #
3
+ # *pushes:* 1 +:int+
4
+ #
5
+
1
6
  class ExecDepthInstruction < Instruction
2
7
  include DepthInstruction
3
8
  def initialize(context)
@@ -1,3 +1,25 @@
1
+ # Pops one "count" item from the +:int+ stack, and one item from the +:exec+ stack.
2
+ # The net effect of the instruction (unless interfered with by another operation)
3
+ # is to evaluate the +:exec+ item "count" times.
4
+ #
5
+ # If the count is negative, an +:error+ item will be pushed to the +:error+ stack. Otherwise,
6
+ # a ValuePoint containing the following "macro" is created and pushed onto the +:exec+ stack:
7
+ # block {
8
+ # value «int»
9
+ # value «int»
10
+ # do exec_do_range
11
+ # popped item
12
+ # }
13
+ # «int» 0
14
+ # «int» count - 1
15
+ # where +popped_item+ is the code from the +:exec+ stack, and +count - 1+ is a decrement of
16
+ # the "count" value.
17
+ #
18
+ # *needs:* ExecDoRangeInstruction must be active in the context for this to work; needs 1 +:int+ and 1 +:exec+ item
19
+ #
20
+ # *pushes:* it's complicated...
21
+ #
22
+
1
23
  class ExecDoCountInstruction < Instruction
2
24
  def preconditions?
3
25
  needs ExecDoRangeInstruction
@@ -1,3 +1,46 @@
1
+ # Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:exec+ stack.
2
+ # The net effect of the instruction (unless interfered with by another operation)
3
+ # is to evaluate the +:exec+ item once for every integer in the range (inclusive), and
4
+ # at the same time push the counter integer onto the +:int+ stack.
5
+ #
6
+ # note: the first integer popped is the "destination", the second one the "counter"
7
+ # (regardless of their values or signs)
8
+ #
9
+ # note: unlike the ExecDoTimes instruction, the counter is pushed
10
+ #
11
+ # <b>If the counter and destination have the same value</b>, then a new +:int+ is pushed with that value,
12
+ # and the +:exec+ item is pushed onto the +:exec+ stack.
13
+ #
14
+ # <b>If the counter and destination have different values</b>, then a "new_counter" value
15
+ # is calculated that is *one step closer to the destination*.
16
+ #
17
+ # A ValuePoint containing the following "macro" is created:
18
+ # block {
19
+ # value «int»
20
+ # value «int»
21
+ # do exec_do_range
22
+ # popped item
23
+ # }
24
+ # «int» new_counter
25
+ # «int» destination
26
+ # where +popped_item+ is the code from the +:exec+ stack, and +new_counter+ and +destination+ are the numeric values that were derived above.
27
+ #
28
+ # Finally,
29
+ # 1. a new ValuePoint whose value is +new_counter+ is pushed to the +:int+ stack;
30
+ # 2. the macro is pushed onto the +:exec+ stack
31
+ # 3. another copy of the +popped_item+ is pushed onto the +:exec+ stack (on top of the macro)
32
+ #
33
+ # The consequence is that the original item will be executed,
34
+ # the counter will be pushed onto the +:int+ stack,
35
+ # the macro will be encountered, and this process will repeat.
36
+ #
37
+ # note: if the +popped_item+ itself manipulates the +:exec+ stack, "complicated behavior" may arise
38
+ #
39
+ # *needs:* 2 +:int+ items, 1 +:exec+ item
40
+ #
41
+ # *pushes:* well, it's complicated...
42
+ #
43
+
1
44
  class ExecDoRangeInstruction < Instruction
2
45
  def preconditions?
3
46
  needs :exec, 1
@@ -1,3 +1,43 @@
1
+ # Pops two values from the +:int+ stack ("destination" and "counter"), and one item from the +:exec+ stack.
2
+ # The net effect of the instruction (unless interfered with by another operation)
3
+ # is to evaluate the +:exec+ item once for every integer in the range (inclusive).
4
+ #
5
+ # note: the top integer is the "destination", the second one the "counter"
6
+ # (regardless of their values or signs)
7
+ #
8
+ # note: unlike the ExecDoRange instruction, the counter is not pushed
9
+ #
10
+ # <b>If the counter and destination have the same value</b>, then a copy of the +:exec+ item is
11
+ # pushed onto the +:exec+ stack.
12
+ #
13
+ # <b>If the counter and destination have different values</b>, then a "new_counter" value
14
+ # is calculated that is *one step closer to the destination*.
15
+ #
16
+ # A ValuePoint containing the following "macro" is created:
17
+ # block {
18
+ # value «int»
19
+ # value «int»
20
+ # do exec_do_times
21
+ # popped item
22
+ # }
23
+ # «int» new_counter
24
+ # «int» destination
25
+ # where +popped_item+ is the code from the +:exec+ stack, and +new_counter+ and +destination+ are the numeric values that were derived above.
26
+ #
27
+ # Finally,
28
+ # 1. the macro is pushed onto the +:exec+ stack
29
+ # 2. another copy of the +popped_item+ is pushed onto the +:exec+ stack (on top of the macro)
30
+ #
31
+ # The consequence is that the original item will be executed,
32
+ # then the macro will be encountered, and this process will repeat.
33
+ #
34
+ # note: if the +popped_item+ itself manipulates the +:exec+ stack, "complicated behavior" may arise
35
+ #
36
+ # *needs:* 2 +:int+ items, 1 +:exec+ item
37
+ #
38
+ # *pushes:* well, it's complicated...
39
+ #
40
+
1
41
  class ExecDoTimesInstruction < Instruction
2
42
  def preconditions?
3
43
  needs :exec, 1
@@ -1,3 +1,10 @@
1
+ # makes and pushes a clone of the top item on the +:exec+ stack
2
+ #
3
+ # *needs:* 1 +:exec+
4
+ #
5
+ # *pushes:* 1 +:exec+
6
+ #
7
+
1
8
  class ExecDuplicateInstruction < Instruction
2
9
  include DuplicateInstruction
3
10
  def initialize(context)
@@ -1,3 +1,12 @@
1
+ # pops the top 2 items of the +:exec+ stack;
2
+ # pushes a new ValuePoint onto the +:bool+ stack, with value +true+ if the
3
+ # two items' blueprint strings are identical
4
+ #
5
+ # *needs:* 2 +:exec+
6
+ #
7
+ # *pushes:* 1 +:bool+
8
+ #
9
+
1
10
  class ExecEqualQInstruction < Instruction
2
11
  def preconditions?
3
12
  needs :exec, 2
@@ -1,3 +1,8 @@
1
+ # deletes all items from the +:exec+ stack
2
+ #
3
+ # note: this is the equivalent of a "BREAK" statement in many other languages
4
+ #
5
+
1
6
  class ExecFlushInstruction < Instruction
2
7
  include FlushInstruction
3
8
  def initialize(context)