fOOrth 0.5.0

data/lib/fOOrth/core.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+
+require_relative 'compiler/word_specs'
+require_relative 'core/object'
+require_relative 'core/class'
+require_relative 'core/virtual_machine'
+
+#* core.rb - The fOOrth language OO core.
+module XfOOrth
+
+  $FOORTH_GLOBALS = Hash.new
+  Object.create_foorth_proxy
+  Class.create_foorth_proxy
+  VirtualMachine.create_foorth_proxy('VirtualMachine')
+
+  #Predefine the default implementation of the .init method. This method must
+  #exist at this point in order to proceed further.
+  name = '.init'
+  sym = SymbolMap.add_entry(name, :foorth_init)
+  Object.create_shared_method(name, TosSpec, [], &lambda {|vm| })
+
+  #Create a virtual machine instance for the main thread. The constructor
+  #connects the new instance to a thread variable so we don't need to do
+  #anything with it here.
+  VirtualMachine.new('Main')
+
+end

data/lib/fOOrth/core/class.rb

@@ -0,0 +1,116 @@
+# coding: utf-8
+
+#* The additions to the Ruby Class class required to support fOOrth.
+class Class
+
+  #Get the foorth name of this class.
+  #<br>Decree!
+  #* These are to be the only references to @_private_foorth_name!
+  def foorth_name
+    @_private_foorth_name ||= name
+  end
+
+  #Set the foorth name of this class.
+  #<br>Decree!
+  #* These are to be the only references to @_private_foorth_name!
+  def foorth_name=(new_name)
+    @_private_foorth_name = new_name
+  end
+
+  #Access/create the class's shared fOOrth dictionary.
+  #<br>Decree!
+  #* This is to be the only reference to @_private_foorth_shared!
+  def foorth_shared
+    @_private_foorth_shared ||= Hash.new
+  end
+
+  #Create a shared method on this fOOrth class.
+  #<br>Parameters:
+  #* name - The name of the method to create.
+  #* spec_class - The specification class to use.
+  #* options - An array of options.
+  #* block - A block to associate with the name.
+  #<br>Returns
+  #* The spec created for the shared method.
+  def create_shared_method(name, spec_class, options, &block)
+    sym = XfOOrth::SymbolMap.add_entry(name)
+    spec = spec_class.new(name, sym, options, &block)
+
+    unless self == Object && options.include?(:stub)
+      define_method(sym, &spec.does)
+    end
+
+    foorth_shared[sym] = spec
+  end
+
+  #Map the symbol to a specification or nil if there is no mapping.
+  def map_foorth_shared(symbol)
+    foorth_shared[symbol] || ((sc = superclass) && sc.map_foorth_shared(symbol))
+  end
+
+  #Create an instance of this fOOrth class.
+  #<br>Parameters:
+  #* vm - The current fOOrth virtual machine.
+  def create_foorth_instance(vm)
+    (obj = self.new).foorth_init(vm)
+    obj
+  end
+
+  #Create a new fOOrth subclass of this class.
+  #<br>Parameters:
+  #* foorth_name - The foorth_name of the new sub-class.
+  #<br>Returns:
+  #* The spec of the subclass.
+  #<br>Note:
+  #* If a sub-class with the given name already exists, an exception is raised.
+  def create_foorth_subclass(foorth_name)
+    if $FOORTH_GLOBALS[XfOOrth::SymbolMap.map(foorth_name)]
+      error "F10: The class #{foorth_name} already exists."
+    end
+
+    validate_class_name(foorth_name)
+
+    new_class = Class.new(self) {self.foorth_name = foorth_name}
+
+    XfOOrth.const_set('XfOOrth_' + foorth_name, new_class)
+    install_foorth_class(foorth_name, new_class)
+  end
+
+  #Add this class as a proxy class in the foorth class system.
+  #<br>Parameters:
+  #* proxy_name - the optional name of the proxy. Defaults to the Ruby name.
+  #<br>Returns:
+  #* The spec of the proxy class.
+  def create_foorth_proxy(proxy_name = nil)
+    if proxy_name
+      self.foorth_name = proxy_name
+    end
+
+    validate_class_name(foorth_name)
+
+    error "F10: The class #{foorth_name} already exists." if $FOORTH_GLOBALS[foorth_name]
+
+    install_foorth_class(foorth_name, self)
+  end
+
+  private
+
+  #Connect the class named foorth_name to the foorth system.
+  #<br>Returns:
+  #* The newly created spec object.
+  #<br> Endemic Code Smells
+  #* :reek:UtilityFunction
+  def install_foorth_class(new_name, new_class)
+    fail "Bad name" unless new_name
+    symbol = XfOOrth::SymbolMap.add_entry(new_name)
+    $FOORTH_GLOBALS[symbol] = XfOOrth::ClassSpec.new(new_class, nil, [:class])
+  end
+
+  #Is this a valid class name?
+  def validate_class_name(name)
+    unless /^[A-Z][A-Za-z0-9]+$/ =~ name
+      error "F10: Invalid class name #{name}"
+    end
+  end
+
+end

data/lib/fOOrth/core/object.rb

@@ -0,0 +1,78 @@
+# coding: utf-8
+
+#* The additions to the Ruby Object class required to support fOOrth.
+class Object
+
+  #Get the foorth name of this object.
+  def foorth_name
+    "#{self.class.foorth_name} instance"
+  end
+
+  #Access/create the object's exclusive fOOrth dictionary.
+  #<br>Decree!
+  #* These are to be the only reference to @_private_foorth_exclusive!
+  def foorth_exclusive
+    @_private_foorth_exclusive ||= Hash.new
+  end
+
+  #Does this object have exclusive methods defined on it?
+  #<br>Decree!
+  #* These are to be the only reference to @_private_foorth_exclusive!
+  def foorth_has_exclusive?
+    instance_variable_defined?(:@_private_foorth_exclusive)
+  end
+
+  #Create an exclusive method on this fOOrth object.
+  #<br>Parameters:
+  #* name - The name of the method to create.
+  #* spec_class - The specification class to use.
+  #* options - An array of options.
+  #* block - A block to associate with the name.
+  #<br>Returns
+  #* The spec created for the shared method.
+  def create_exclusive_method(name, spec_class, options, &block)
+    sym = XfOOrth::SymbolMap.add_entry(name)
+    spec = spec_class.new(name, sym, options, &block)
+    cache_exclusive_method(sym, &spec.does)
+    foorth_exclusive[sym] = spec
+  end
+
+  #Load the new exclusive method into the object.
+  def cache_exclusive_method(symbol, &block)
+    define_singleton_method(symbol, &block)
+  rescue TypeError
+    error "F13: Exclusive methods not allowed for type: #{self.class.foorth_name}"
+  end
+
+  #Map the symbol to a specification or nil if there is no mapping.
+  def map_foorth_exclusive(symbol)
+    (foorth_has_exclusive? && foorth_exclusive[symbol]) ||
+    self.class.map_foorth_shared(symbol)
+  end
+
+  #The default foorth_init method does nothing.
+  def foorth_init(_vm)
+  end
+
+  #The \method_missing hook is used to provide meaningful error messages
+  #when problems are encountered.
+  #<br>Parameters:
+  #* symbol - The symbol of the missing method.
+  #* args - Any arguments that were passed to that method.
+  #* block - Any block that might have passed to the method.
+  #<br>Note:
+  #* Since stubs for Object class do not create methods, an attempt is made
+  #  to execute the stub if the symbol maps and is in the Object class.
+  def method_missing(symbol, *args, &block)
+    if (name = XfOOrth::SymbolMap.unmap(symbol))
+      if (stub_spec = Object.foorth_shared[symbol])
+        self.instance_exec(*args, &stub_spec.does)
+      else
+        error "F20: A #{self.foorth_name} does not understand #{name} (#{symbol})."
+      end
+    else
+      super
+    end
+  end
+
+end

data/lib/fOOrth/core/virtual_machine.rb

@@ -0,0 +1,28 @@
+# coding: utf-8
+
+#* core/virtual_machine.rb - The core connection to the virtual machine.
+module XfOOrth
+
+  #* core/virtual_machine.rb - The core connection to the virtual machine.
+  class VirtualMachine
+
+    #The name of the virtual machine instance
+    def foorth_name
+      "#{self.class.foorth_name} instance <#{@name}>"
+    end
+
+    #The currently active fiber, if any.
+    attr_accessor :fiber
+
+    class << self
+
+      #Create a new fOOrth subclass of this class. This is not allowed for the
+      #VirtualMachine class so this stub merely raises an exception.
+      def create_foorth_subclass(_name)
+        error "F13: Forbidden operation: (VirtualMachine.create_foorth_subclass)."
+      end
+
+    end
+
+  end
+end

data/lib/fOOrth/debug.rb

@@ -0,0 +1,13 @@
+# coding: utf-8
+
+require_relative 'debug/display_abort'
+require_relative 'debug/dbg_puts'
+require_relative 'debug/context_dump'
+require_relative 'debug/vm_dump'
+
+#Set up the default debug conduit.
+$foorth_dbg = $stdout
+
+#* debug.rb - Internal debug support.
+module XfOOrth
+end

data/lib/fOOrth/debug/context_dump.rb

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+#* debug/context_dump.rb - Debug support for the compiler context.
+module XfOOrth
+
+  #* debug/context_dump.rb - Debug support for the compiler context.
+  class Context
+
+    #Dump the context chain to the console for debug.
+    #<br>Parameters
+    #* vm - The current virtual machine for this thread.
+    def debug_dump(vm)
+      puts "\nContext level #{self.depth}"
+
+      @data.each do |key, value|
+        if key == :vm
+          puts "virtual machine => #{value.foorth_name}"
+        else
+          if (name = SymbolMap.unmap(key))
+            key = name.inspect
+          end
+
+          puts "#{key} => #{value}"
+        end
+      end
+
+      (prev = self.previous) && prev.debug_dump(vm)
+    end
+  end
+
+end

data/lib/fOOrth/debug/dbg_puts.rb

@@ -0,0 +1,17 @@
+# coding: utf-8
+
+#* debug/dbg_puts.rb - Display diagnostic/debug information if enabled.
+module XfOOrth
+
+  #* debug/dbg_puts.rb - Display diagnostic/debug information if enabled.
+  class VirtualMachine
+
+    #Send out debug info to the fOOrth debug port if debug is enabled.
+    def dbg_puts(*args)
+      $foorth_dbg.puts(*args) if debug
+    end
+
+  end
+
+end
+

data/lib/fOOrth/debug/display_abort.rb

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+#* debug/display_abort.rb - Display diagnostic information on an error.
+module XfOOrth
+
+  #* debug/display_abort.rb - Display diagnostic information on an error.
+  class VirtualMachine
+
+    #Display the diagnostic data required for a language abort error.
+    #<br>Parameters:
+    #* exception - The exception object that required the system abort or a
+    #  string describing the error that was encountered.
+    def display_abort(exception)
+      puts "\n#{exception.foorth_message}"
+
+      if debug
+        puts "Data Stack Contents: #{data_stack.inspect}"
+
+        if @context
+          @context.debug_dump(self)
+        else
+          puts "Error: No context is available!"
+        end
+
+        puts "\nInternal Backtrace Dump:"
+        puts
+        puts exception.backtrace
+        puts
+      end
+
+      reset
+    end
+
+  end
+
+end
+

data/lib/fOOrth/debug/vm_dump.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+
+#* debug/vm_dump.rb - Debug support for the virtual machine.
+module XfOOrth
+
+  #* debug/vm_dump.rb - Debug support for the virtual machine.
+  class VirtualMachine
+
+    #Dump the virtual machine to the console for debug.
+    def debug_dump
+      source = @parser && @parser.source
+
+      puts "\n#{self.foorth_name}"                \
+           "\n  Ruby    = #{self.to_s}"           \
+           "\n  Stack   = #{@data_stack.inspect}" \
+           "\n  Nesting = #{@context.depth}"      \
+           "\n  Quotes  = #{@quotes}"             \
+           "\n  Debug   = #{@debug}"              \
+           "\n  Show    = #{@show_stack}"         \
+           "\n  Force   = #{@force}"              \
+           "\n  Start   = #{@start_time}"         \
+           "\n  Source  = #{source && source.source_name}"  \
+           "\n  Buffer  = #{source && source.read_buffer.inspect}"
+    end
+  end
+
+end

data/lib/fOOrth/initialize.rb

@@ -0,0 +1,83 @@
+# coding: utf-8
+
+#* initialize.rb - The initialize method for the virtual machine
+module XfOOrth
+
+  #* initialize.rb - The initialize method for the virtual machine
+  class VirtualMachine
+
+    #Get or create a virtual machine for this thread.
+    #<br>Paramters:
+    #* name - The name of the virtual machine, if one is created. If a virtual
+    #  machine already exists for this thread, this parameter is ignored.
+    #<br>Note: Non-intuitive code.
+    #* VitualMachine.new connects to the thread, setting up
+    #  \Thread.current[:vm] as a side-effect. Thus it is not done here.
+    def self.vm(name='-')
+      Thread.current[:vm] || VirtualMachine.new(name)
+    end
+
+    #Set true for verbose compiler play-by-plays and detailed error reports.
+    attr_accessor :debug
+
+    #Set true to print out the data stack after every interactive line is processed.
+    attr_accessor :show_stack
+
+    #The descriptive name of this virtual machine.
+    attr_reader :name
+
+    #The thread data associated with this virtual machine.
+    attr_reader :data
+
+    #Create an new instance of a fOOrth virtual machine
+    #<br>Parameters:
+    #* name - An optional string that describes this virtual machine instance.
+    #<br>Note
+    #* A XfOOrthError will be raised if an attempt is made to create more than
+    #  one virtual machine on a thread.
+    def initialize(name='-')
+      @name, @debug, @show_stack, @data = name, false, false, {}
+
+      #Bring the major sub-systems to a known state.
+      self.reset.connect_vm_to_thread
+    end
+
+    #Create a copy of a donor vm instance.
+    #<br>Parameters:
+    #* name - An optional string that describes this virtual machine instance.
+    def foorth_copy(name)
+      copy = self.clone
+      copy.reinitialize(name)
+      copy
+    end
+
+    #Get the vm ready for operation
+    #<br>Parameters:
+    #* name - A string that describes this virtual machine instance.
+    def reinitialize(name)
+      @data_stack = @data_stack.clone
+      @name       = name
+      @data       = @data.full_clone
+    end
+
+    #Reset the interpreter and the compiler.
+    def reset
+      interpreter_reset
+      compiler_reset
+    end
+
+    #Connect the vm to a thread variable.
+    def connect_vm_to_thread
+      #Check for duplicates.
+      current = Thread.current
+      error "F91: Only one virtual machine allowed per thread" if current[:vm]
+
+      #This virtual machine is associated with this thread.
+      current[:vm] = self
+      @start_time  = Time.now
+
+      self
+    end
+  end
+
+end