fOOrth 0.5.0

data/lib/fOOrth/interpreter.rb

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+require_relative 'interpreter/data_stack'
+require_relative 'interpreter/do_loop'
+require_relative 'interpreter/squash'
+require_relative 'interpreter/add_to_hash'
+
+#* interpreter.rb - The run time interpreter portion of the fOOrth language system.
+module XfOOrth
+
+  #* interpreter.rb - The run time interpreter portion of the fOOrth language system.
+  class VirtualMachine
+
+    #The fOOrth timer anchor point. Used to assist in benchmarking etc.
+    attr_accessor :start_time
+
+    #Reset the state of the fOOrth inner interpreter.
+    def interpreter_reset
+      @data_stack = Array.new
+      self
+    end
+  end
+
+end

data/lib/fOOrth/interpreter/add_to_hash.rb

@@ -0,0 +1,17 @@
+# coding: utf-8
+
+#* interpreter/add_to_hash.rb - The fOOrth language hash literal support module.
+module XfOOrth
+
+  #* interpreter/add_to_hash.rb - The fOOrth language hash literal support module.
+  class VirtualMachine
+
+    #Add the key and value to the hash being constructed.
+    def add_to_hash
+      key, value = popm(2)
+      peek(1)[key] = value
+    end
+
+  end
+
+end

data/lib/fOOrth/interpreter/data_stack.rb

@@ -0,0 +1,125 @@
+# coding: utf-8
+
+#* interpreter/data_stack.rb - The fOOrth language system data stack.
+module XfOOrth
+
+  #* interpreter/data_stack.rb - The fOOrth language system data stack.
+  class VirtualMachine
+    #The fOOrth data stack. This is the primary means used to hold data
+    #for processing.
+    attr_accessor :data_stack
+
+    #Add an entry to the data stack.
+    #<br>Parameters:
+    #* datum - The data to be added to the data stack.
+    def push(datum)
+      @data_stack << datum
+    end
+
+    #Add some entries to the data stack.
+    #<br>Parameters:
+    #* datum - An array of data to be mass added to the data stack.
+    def pushm(datum)
+      @data_stack += datum
+    end
+
+    #Remove the "top" entry from the data stack.
+    #<br>Returns:
+    #* The "top" element of the data stack.
+    #<br>Note:
+    #* If the stack is empty this will raise an XfOOrthError exception.
+    def pop
+      error "F30: Data Stack Underflow: pop" if @data_stack.empty?
+      @data_stack.pop
+    end
+
+    #Remove multiple entries from the "top" of the data stack.
+    #<br>Parameters:
+    #* count - the number of elements to be returned.
+    #<br>Returns:
+    #* An array containing the "top" count elements of the data stack.
+    #<br>Note:
+    #* Raises an XfOOrthError exception if the stack has too few data.
+    def popm(count)
+      begin
+        error "F30: Data Stack Underflow: popm" if @data_stack.length < count
+        @data_stack.pop(count)
+      rescue
+        @data_stack = []
+        raise
+      end
+    end
+
+    #Remove the "top" entry from the data stack as a boolean.
+    #<br>Returns:
+    #* The "top" element of the data stack as a boolean
+    #<br>Note:
+    #* If the stack is empty this will raise an XfOOrthError exception.
+    def pop?
+      pop.to_foorth_b
+    end
+
+    #Read an entry from the data stack without modify that stack.
+    #<br>Parameters:
+    #* index - The (optional) entry to be retrieved. 1 corresponds to the
+    #  "top" of the stack, 2 the next element, etc.
+    #  This parameter defaults to 1.
+    #<br>Returns:
+    #* The element specified from the data stack.
+    #<br>Note:
+    #* Attempting to access an element deeper than the number of elements
+    #  on the stack will fail with an XfOOrthError exception.
+    def peek(index=1)
+      unless @data_stack.length >= index && index > 0
+        error "F30: Data Stack Underflow: peek"
+      end
+
+      @data_stack[-index]
+    end
+
+    #Overwrite the TOS with the supplied data.
+    #<br>Parameters:
+    #* datum - The data to be placed in the data stack.
+    #<br>Note:
+    #* Attempting to poke an empty stack will fail with an XfOOrthError exception.
+    def poke(datum)
+      error "F30: Data Stack Underflow: poke" if @data_stack.empty?
+      @data_stack[-1] = datum
+    end
+
+    #Read an entry from the data stack as a boolean without modify that stack.
+    #<br>Parameters:
+    #* index - The (optional) entry to be retrieved. 1 corresponds to the "top"
+    #  of the stack, 2 the next element, etc. This parameter defaults to 1.
+    #<br>Returns:
+    #* The element specified from the data stack as a boolean.
+    #<br>Note:
+    #* Attempting to access an element deeper than the number of elements on
+    #  the stack will fail with an XfOOrthError exception.
+    def peek?(index=1)
+      peek(index).to_foorth_b
+    end
+
+    #A special operation to support dyadic operators. Swap then pop.
+    #<br>Returns:
+    #* The second element from the data stack.
+    #<br>Note:
+    #* If the stack has less than 2 elements, this will raise an
+    #  XfOOrthError exception.
+    def swap_pop
+      begin
+        unless @data_stack.length >= 2
+          error "F30: Data Stack Underflow: swap_pop"
+        end
+
+        nos, tos = @data_stack.pop(2)
+        @data_stack << tos
+        nos
+      rescue
+        @data_stack = []
+        raise
+      end
+    end
+
+  end
+end

data/lib/fOOrth/interpreter/do_loop.rb

@@ -0,0 +1,55 @@
+# coding: utf-8
+
+#* interpreter/do_loop.rb - The fOOrth language do loop support module.
+module XfOOrth
+
+  #* interpreter/do_loop.rb - The fOOrth language do loop support module.
+  class VirtualMachine
+
+    #The runtime implementation of the "do" word.
+    #<br>Parameters:
+    #* jloop - An optional outer loop value.
+    #* block - A block of code to be executed as the do loop body.
+    #<br>Block Parameters:
+    #* iloop - The stack frame of the current loop counter. This
+    #  corresponds to the fOOrth 'i' value.
+    #* jloop - The stack frame of any containing loop counter. This corresponds
+    #  to the fOOrth 'j' value. If there is no containing loop, this
+    #  will always be a zero frame ie: [0, 0, 0].
+    #<br>Note:
+    #* Nested loops must be in the same compiler context in order to use this
+    #  mechanism. Otherwise, loop index counters must be passed in explicitly.
+    #<br>Endemic Code Smells
+    #* :reek:FeatureEnvy  -- false positive
+    def vm_do(jloop = [0, 0, 0], &block)
+      #Pop the start and ending values from the stack.
+      start_index, end_index = popm(2)
+
+      #Construct the loop data frame.
+      iloop = [start_index, end_index - 1, start_index + end_index - 1]
+
+      #Loop until done!
+      while iloop[0] <= iloop[1]
+        #Yield to the loop.
+        yield iloop, jloop
+      end
+    end
+
+    #The runtime implementation of the "+loop" word.
+    def vm_do_increment
+      inc_raw = self.pop
+
+      unless (inc_value = inc_raw.to_foorth_n)
+        error "F40: Cannot convert a #{inc_raw.foorth_name} to a Numeric instance"
+      end
+
+      if inc_value > 0
+        inc_value
+      else
+        error "F41: Invalid loop increment value: #{inc_value}"
+      end
+    end
+
+  end
+
+end

data/lib/fOOrth/interpreter/squash.rb

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+#* interpreter/squash.rb - The fOOrth language array literal support module.
+module XfOOrth
+
+  #* interpreter/squash.rb - The fOOrth language do loop support module.
+  class VirtualMachine
+
+    #Compress the entire data stack into a single entry.
+    def squash
+      @data_stack = [@data_stack]
+    end
+
+    #Compress all the added entries into a single entry and revive the previous
+    #contents of the data stack.
+    def unsquash
+      previous = @data_stack[0]
+      data = @data_stack[1..-1]
+      @data_stack = previous
+      push(data)
+    end
+
+  end
+
+end

data/lib/fOOrth/library.rb

@@ -0,0 +1,38 @@
+# coding: utf-8
+
+require_relative 'library/stubs'
+require_relative 'library/object_library'
+require_relative 'library/class_library'
+require_relative 'library/vm_library'
+require_relative 'library/data_ref_library'
+require_relative 'library/clone_library'
+require_relative 'library/compile_library'
+require_relative 'library/ctrl_struct_library'
+require_relative 'library/stdio_library'
+require_relative 'library/numeric_library'
+require_relative 'library/integer_library'
+require_relative 'library/rational_library'
+require_relative 'library/complex_library'
+require_relative 'library/string_library'
+require_relative 'library/duration_library'
+require_relative 'library/time_library'
+require_relative 'library/array_library'
+require_relative 'library/hash_library'
+require_relative 'library/procedure_library'
+require_relative 'library/thread_library'
+require_relative 'library/fiber_library'
+require_relative 'library/bundle_library'
+require_relative 'library/sync_bundle_library'
+require_relative 'library/other_value_types_library'
+require_relative 'library/command_library'
+require_relative 'library/in_stream_library'
+require_relative 'library/out_stream_library'
+require_relative 'library/queue_library'
+require_relative 'library/stack_library'
+require_relative 'library/mutex_library'
+
+#* library.rb - The word library portion of the fOOrth language system.
+module XfOOrth
+
+end
+

data/lib/fOOrth/library/array_library.rb

@@ -0,0 +1,577 @@
+# coding: utf-8
+
+#* library/array_library.rb - Array support for the fOOrth library.
+module XfOOrth
+
+  #Connect the Array class to the fOOrth class system.
+  Array.create_foorth_proxy
+
+  # [] Array .new [[]]; create an empty array.
+  # The default implementation from Object is used for this.
+
+  # [n] Array .new_size [[0,0,...0]]; create an array of n zeros.
+  Array.create_exclusive_method('.new_size', TosSpec, [], &lambda {|vm|
+    begin
+      vm.poke(self.new(Integer.foorth_coerce(vm.peek), 0));
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [v] Array .new_value [[v]]; create an array of a single value.
+  Array.create_exclusive_method('.new_value', TosSpec, [],
+    &lambda {|vm| vm.poke(self.new(1, vm.peek)); })
+
+  # [v n] Array .new_values [[v,v,...v]]; create an array of a n values.
+  Array.create_exclusive_method('.new_values', TosSpec, [], &lambda {|vm|
+    begin
+      count = Integer.foorth_coerce(vm.pop)
+      vm.poke(self.new(count, vm.peek))
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [n] Array .new{{ ... }} [[array]]; create an array of a n computed values.
+  Array.create_exclusive_method('.new{{', NosSpec, [], &lambda {|vm|
+    block = vm.pop
+    count = Integer.foorth_coerce(vm.pop)
+
+    vm.push(Array.new(count) { |idx| block.call(vm, nil, idx); vm.pop})
+  })
+
+  # [array] .map{{ ... }} [mapped_array]
+  Array.create_shared_method('.map{{', NosSpec, [], &lambda { |vm|
+    idx, block = 0, vm.pop
+    vm.push(self.map { |val| block.call(vm, val, idx); idx += 1; vm.pop})
+  })
+
+  # [array] .select{{ ... }} [selected_array]
+  Array.create_shared_method('.select{{', NosSpec, [], &lambda { |vm|
+    idx, block = 0, vm.pop
+    vm.push(self.select { |val| block.call(vm, val, idx); idx += 1; vm.pop})
+  })
+
+  # [] [ v1 v2 ... vn ] [[v1,v2,...vn]]; an array literal value
+  VirtualMachine.create_shared_method('[', VmSpec, [:immediate], &lambda { |vm|
+    vm.nest_mode('vm.squash; ', :array_literal)
+
+    vm.context.create_local_method(']', LocalSpec, [:immediate],
+      &lambda {|vm| vm.unnest_mode('vm.unsquash; ', [:array_literal]) })
+  })
+
+  # [array] .each{{ ... }} [unspecified]
+  Array.create_shared_method('.each{{', NosSpec, [], &lambda { |vm|
+    block = vm.pop
+    self.each_with_index { |val, idx| block.call(vm, val, idx) }
+  })
+
+  # Some basic data access words.
+  # [a] @ [a[0]]
+  Array.create_shared_method('@', TosSpec, [], &lambda { |vm|
+    vm.push(self[0])
+  })
+
+  # [ v a ] ! [], a[0] = v
+  Array.create_shared_method('!', TosSpec, [], &lambda { |vm|
+    self[0] = vm.pop
+  })
+
+  # [ i a ] .[]@ [ a[i] ]
+  Array.create_shared_method('.[]@', TosSpec, [], &lambda {|vm|
+    begin
+      vm.poke(self[Integer.foorth_coerce(vm.peek)])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [ v i a ] .[]! []; a[i]=v
+  Array.create_shared_method('.[]!', TosSpec, [], &lambda {|vm|
+    value, index = vm.popm(2)
+    self[Integer.foorth_coerce(index)] = value;
+  })
+
+  # [ [ 1 2 3 ] ] .reverse [ [ 3 2 1 ] ]
+  Array.create_shared_method('.reverse', TosSpec, [],
+    &lambda {|vm| vm.push(self.reverse); })
+
+  # [ [ 3 1 2 ] ] .sort [ [ 1 2 3 ] ]
+  Array.create_shared_method('.sort', TosSpec, [],
+    &lambda {|vm| vm.push(self.sort {|va,vb| va <=> va.foorth_coerce(vb)}); })
+
+  # [ [ 1 2 3 ] ] .shuffle  [ [ x y z ] ]
+  Array.create_shared_method('.shuffle', TosSpec, [],
+    &lambda {|vm| vm.push(self.shuffle); })
+
+  # [ [ 3 1 2 ] ] .length [ 3 ]
+  Array.create_shared_method('.length', TosSpec, [],
+    &lambda {|vm| vm.push(self.length); })
+
+  # [ an_array ] .empty? [ a_boolean ]
+  Array.create_shared_method('.empty?', TosSpec, [],
+    &lambda {|vm| vm.push(self.empty?); })
+
+  # [ [ 3 1 2 ] n ] << [ [ 3 1 2 n ] ]
+  Array.create_shared_method('<<', NosSpec, [],
+    &lambda {|vm| vm.poke(self << vm.peek); })
+
+  # [[3 1 2] n] + [[3 1 2 n]]
+  Array.create_shared_method('+', NosSpec, [],
+    &lambda {|vm| vm.poke(self + vm.peek.in_array); })
+
+
+  # The LEFT group
+  # [w [ 3 1 2 ] ] .left [ [ 3 1 ] ]; assumes w = 2
+  Array.create_shared_method('.left', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .left" if width < 0
+      vm.poke(self.first(width));
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 3 1 2 ] ] .-left [ 2 ]    // Assumes w = 2
+  Array.create_shared_method('.-left', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .-left" if width < 0
+      vm.poke(self[width..-1]);
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 0 8 9 ] [ 1 2 3 4 ] ] .+left [ [ 0 8 9 3 4 ] ] // Assumes w = 2
+  Array.create_shared_method('.+left', TosSpec, [], &lambda {|vm|
+    begin
+      ins = vm.pop.in_array
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .+left" if width < 0
+      vm.poke(ins + self[width..-1])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 1 2 3 4 ] ] .^left [ [ 3 4 ] [ 1 2 ] ]; assumes w = 2
+  Array.create_shared_method('.^left', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .^left" if width < 0
+
+      vm.poke(self[width..-1])
+      vm.push(self.first(width));
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+
+  #The RIGHT group
+  # [w [ 3 1 2 ] ] .right [ [ 1 2 ] ]; assumes w = 2
+  Array.create_shared_method('.right', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .right" if width < 0
+      vm.poke(self.last(width))
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 3 1 2 ] ] .-right [ [ 3 ] ]   // Assumes w = 2
+  Array.create_shared_method('.-right', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .-right" if width < 0
+      vm.poke(self[0...(0-width)]);
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 0 8 9 ] [ 1 2 3 4 ] ] .+right [ [ 1 2 0 8 9 ] ] // Assumes w = 2
+  Array.create_shared_method('.+right', TosSpec, [], &lambda {|vm|
+    begin
+      ins = vm.pop.in_array
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .+right" if width < 0
+      vm.poke(self[0...(0-width)] + ins)
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [w [ 1 2 3 4 ] ] .^right [ [ 1 2 ] [ 3 4 ] ]; assumes w = 2
+  Array.create_shared_method('.^right', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid width: #{width} in .^right" if width < 0
+
+      vm.poke(self[0...(0-width)])
+      vm.push(self.last(width));
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+
+  # The MID group
+  # [n w [ 1 2 3 4 5 6 7 8 ] ] .mid [ [ 3 4 5 6 ] ] // Assumes n = 2, w = 4
+  Array.create_shared_method('.mid', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.pop)
+      posn = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid index: #{posn} in .mid"  if posn < 0
+      error "F41: Invalid width: #{width} in .mid" if width < 0
+      vm.poke(self[posn...(posn+width)])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [n w [ 1 2 3 4 5 6 7 8 ] ] .-mid [ [ 1 2 7 8 ] ] // Assumes n = 2, w = 4
+  Array.create_shared_method('.-mid', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.pop)
+      posn = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid index: #{posn} in .-mid"  if posn < 0
+      error "F41: Invalid width: #{width} in .-mid" if width < 0
+      vm.poke(self[0...posn] + self[(posn+width)..-1])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [n w [ 0 8 9 ] [ 1 2 3 4 5 6 7 8 ] ] .+mid [ [ 1 2 0 8 9 7 8 ] ] // Assumes n=2, w=4
+  Array.create_shared_method('.+mid', TosSpec, [], &lambda {|vm|
+    begin
+      ins = vm.pop.in_array
+      width = Integer.foorth_coerce(vm.pop)
+      posn = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid index: #{posn} in .+mid"  if posn < 0
+      error "F41: Invalid width: #{width} in .+mid" if width < 0
+      vm.poke(self[0...posn] + ins + self[(posn+width)..-1])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [n w [ 1 2 3 4 5 6 7 8 ] ] .^mid [ [ 1 2 7 8 ] [ 3 4 5 6 ] ] // For n=2, w=4
+  Array.create_shared_method('.^mid', TosSpec, [], &lambda {|vm|
+    begin
+      width = Integer.foorth_coerce(vm.pop)
+      posn = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid index: #{posn} in .^mid"  if posn < 0
+      error "F41: Invalid width: #{width} in .^mid" if width < 0
+      vm.poke(self[0...posn] + self[(posn+width)..-1])
+      vm.push(self[posn...(posn+width)])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+
+  # The MIDLR group
+  # [l r [ 1 2 3 4 5 6 7 8 ] ] .midlr [ [ 2 3 4 5 6 7 ] ] // Assumes l=1, r=1
+  Array.create_shared_method('.midlr', TosSpec, [], &lambda {|vm|
+    begin
+      right = Integer.foorth_coerce(vm.pop)
+      left  = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid left width: #{left} in .midlr"  if left < 0
+      error "F41: Invalid right width: #{right} in .midlr" if right < 0
+      vm.poke(self[left..(0-right-1)])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [l r [ 1 2 3 4 5 6 7 8 ] ] .-midlr [ [ 1 8 ] ] // Assumes l = 1, r = 1
+  Array.create_shared_method('.-midlr', TosSpec, [], &lambda {|vm|
+    begin
+      right = Integer.foorth_coerce(vm.pop)
+      left  = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid left width: #{left} in .-midlr"  if left < 0
+      error "F41: Invalid right width: #{right} in .-midlr" if right < 0
+      vm.poke(self.first(left) + self.last(right))
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [l r [ 0 8 9 ] [ 1 2 3 4 5 6 7 8 ] ] .+midlr [ [ 1 0 8 9 8 ] ] // Assumes l = 1, r = 1
+  Array.create_shared_method('.+midlr', TosSpec, [], &lambda {|vm|
+    begin
+      ins = vm.pop.in_array
+      right = Integer.foorth_coerce(vm.pop)
+      left  = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid left width: #{left} in .-midlr"  if left < 0
+      error "F41: Invalid right width: #{right} in .-midlr" if right < 0
+      vm.poke(self.first(left) + ins + self.last(right))
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+  # [l r [ 1 2 3 4 5 ] ] .midlr [ [ 1 5 ] [ 2 3 4 ] ] // Assumes l=1, r=1
+  Array.create_shared_method('.^midlr', TosSpec, [], &lambda {|vm|
+    begin
+      right = Integer.foorth_coerce(vm.pop)
+      left  = Integer.foorth_coerce(vm.peek)
+      error "F41: Invalid left width: #{left} in .midlr"  if left < 0
+      error "F41: Invalid right width: #{right} in .midlr" if right < 0
+      vm.poke(self.first(left) + self.last(right))
+      vm.push(self[left..(0-right-1)])
+    rescue
+      vm.data_stack.pop
+      raise
+    end
+  })
+
+
+  #The DEQUEUE LEFT group
+  #[ [ 1 2 3 ] ] .pop_left [ [ 2 3 ] 1 ]
+  Array.create_shared_method('.pop_left', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .pop_left" if self.empty?
+    vm.push(self[1..-1]);
+    vm.push(self.first)
+  })
+
+  #[ [ 1 2 3 ] ] .pop_left! [ 1 ]; Mutates original array.
+  Array.create_shared_method('.pop_left!', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .pop_left!" if self.empty?
+    vm.push(self.delete_at(0))
+  })
+
+  #[ 0 [ 1 2 3 ] ] .push_left [ [ 0 1 2 3 ] ]
+  Array.create_shared_method('.push_left', TosSpec, [], &lambda{|vm|
+    vm.poke([ vm.peek ] + self)
+  })
+
+  #[ 0 [ 1 2 3 ] ] .push_left! [ ]; Mutates original array.
+  Array.create_shared_method('.push_left!', TosSpec, [], &lambda{|vm|
+    self.insert(0, vm.pop)
+  })
+
+  #[ [ 1 2 3 ] ] .peek_left [ [ 1 2 3 ] 1 ]
+  Array.create_shared_method('.peek_left', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .peek_left" if self.empty?
+    vm.push(self);
+    vm.push(self.first)
+  })
+
+  #[ [ 1 2 3 ] ] .peek_left! [ 1 ]
+  Array.create_shared_method('.peek_left!', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .peek_left!" if self.empty?
+    vm.push(self.first)
+  })
+
+
+  #The DEQUEUE RIGHT group
+  #[ [ 1 2 3 ] ] .pop_right [ [ 1 2 ] 3 ]
+  Array.create_shared_method('.pop_right', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .pop_right" if self.empty?
+    vm.push(self[0...-1]);
+    vm.push(self.last)
+  })
+
+  #[ [ 1 2 3 ] ] .pop_right! [ 3 ]; Mutates original array.
+  Array.create_shared_method('.pop_right!', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .pop_right!" if self.empty?
+    vm.push(self.pop)
+  })
+
+  #[ 4 [ 1 2 3 ] ] .push_right [ [ 1 2 3 4 ] ]
+  Array.create_shared_method('.push_right', TosSpec, [], &lambda{|vm|
+    vm.poke(self + [ vm.peek ])
+  })
+
+  #[ 4 [ 1 2 3 ] ] .push_right! [ ]; Mutates original array.
+  Array.create_shared_method('.push_right!', TosSpec, [], &lambda{|vm|
+    self << vm.pop
+  })
+
+  #[ [ 1 2 3 ] ] .peek_right [ [ 1 2 3 ] 3 ]
+  Array.create_shared_method('.peek_right', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .peek_right" if self.empty?
+    vm.push(self);
+    vm.push(self.last)
+  })
+
+  #[ [ 1 2 3 ] ] .peek_right! [ [ 1 2 3 ] 3 ]
+  Array.create_shared_method('.peek_right!', TosSpec, [], &lambda{|vm|
+    error "F31: Array underflow error on .peek_right!" if self.empty?
+    vm.push(self.last)
+  })
+
+
+  # [ a ] .min [ smallest_element ]
+  Array.create_shared_method('.min', TosSpec, [], &lambda {|vm|
+    result = self[0]
+
+    self.each do |value|
+      other = result.foorth_coerce(value)
+      result = other if result > other
+    end
+
+    vm.push(result)
+  })
+
+  # [ a ] .max [ largest_element ]
+  Array.create_shared_method('.max', TosSpec, [], &lambda {|vm|
+    result = self[0]
+
+    self.each do |value|
+      other = result.foorth_coerce(value)
+      result = other if result < other
+    end
+
+    vm.push(result)
+  })
+
+  # [ array ] .split [ a0 a1 ... aN ]
+  Array.create_shared_method('.split', TosSpec, [], &lambda {|vm|
+    vm.pushm(self)
+  })
+
+  # [ a1 a2 aN N ] .join [ [ a1 a2 ... aN ] ]
+  Integer.create_shared_method('.join', TosSpec, [], &lambda {|vm|
+    error "F30: Invalid array size: .join" if self < 0
+    vm.push(vm.popm(self))
+  })
+
+  # [ array ] .to_s [ string ]
+  Array.create_shared_method('.to_s', TosSpec, [], &lambda {|vm|
+    result = "[ "
+
+    self.each do |value|
+      if value.is_a?(String)
+        result << value.inspect + " "
+      else
+        value.to_foorth_s(vm)
+        result << (vm.pop || value.inspect) + " "
+      end
+    end
+
+    vm.push(result + "]")
+  })
+
+  # [ l 2 3 ... n ] .strmax [ widest ]
+  Array.create_shared_method('.strmax', TosSpec, [], &lambda {|vm|
+    result = 0
+
+    self.each {|item|
+      item.foorth_strlen(vm)
+      temp = vm.pop
+      result = result > temp ? result : temp
+    }
+
+    vm.push(result)
+  })
+
+  #[ array ] .scatter [ a0 a1 ... aN ]
+  Array.create_shared_method('.scatter', TosSpec, [], &lambda {|vm|
+    vm.data_stack += self
+  })
+
+  #[ x0 x1 ... xN] gather [ array ]
+  VirtualMachine.create_shared_method('gather', VmSpec, [], &lambda{|vm|
+    @data_stack = [@data_stack]
+  })
+
+  #[ x0 x1 ... xN N] .gather [ array ]
+  Integer.create_shared_method('.gather', TosSpec, [], &lambda {|vm|
+    error "F30: Invalid .gather count value." unless self > 0
+    error "F30: Data stack underflow." unless self <= vm.data_stack.length
+
+    temp = vm.data_stack.pop(self)
+    vm.data_stack << temp
+  })
+
+  #[ an_array ] .to_a [ an_array ]
+  Array.create_shared_method('.to_a', TosSpec, [],
+    &lambda {|vm| vm.push(self) })
+
+  #[ an_array ] .to_h [ a_hash ]
+  Array.create_shared_method('.to_h', TosSpec, [], &lambda {|vm|
+    result = {}
+    self.each_with_index { |val, idx| result[idx] = val }
+    vm.push(result)
+  })
+
+  #[ an_array ] .values [ an_array ]
+  Array.create_shared_method('.values', TosSpec, [],
+    &lambda {|vm| vm.push(self) })
+
+  #[ an_array ] .keys [ an_array ]
+  Array.create_shared_method('.keys', TosSpec, [],
+    &lambda {|vm| vm.push((0...self.length).to_a) })
+
+
+  $fcpl = 80 #fOOrth Character Per Line
+  $flpp = 25 #fOOrth Lines Per Page
+
+  # [ l 2 3 ... n ] .pp []; pretty print the array!
+  Array.create_shared_method('.pp', TosSpec, [], &lambda {|vm|
+    self.foorth_strmax(vm)
+    width = vm.pop + 1
+    cols  = (width <= $fcpl) ? ($fcpl / width) : 1
+    full_rows = ((cols * width) % $fcpl) == 0
+    rows_left = (self.length + cols - 1) / cols
+    pages = (rows_left + $flpp - 1) / $flpp
+    page_capacity = $flpp * cols
+
+    (0...pages).each do |page|
+      offset = page * page_capacity
+      rows_this_page = (rows_left >= $flpp) ? $flpp : rows_left
+
+      (0...rows_this_page).each do |row|
+        (0...cols).each do |col|
+          self[offset + col*rows_this_page + row].to_foorth_s(vm)
+
+          if cols > 1
+            print vm.pop.ljust(width)
+          else
+            print vm.pop
+          end
+        end
+
+        puts unless full_rows
+      end
+
+      rows_left -= $flpp
+      puts "\n"
+    end
+  })
+
+  #Show the page length.
+  VirtualMachine.create_shared_method(')pl', MacroSpec,
+    [:macro, 'puts "Page Length = #{$flpp}"; '])
+
+
+  #Set/show the page length.
+  VirtualMachine.create_shared_method(')set_pl', MacroSpec,
+    [:macro, 'puts "New Page Length = #{$flpp = vm.pop.to_i}"; '])
+
+end