relisp 0.9.0

data/lib/relisp/programming_types.rb

@@ -0,0 +1,293 @@
+#--
+# Copyright (C) 2009 <don@ohspite.net>
+#
+# This file is part of Relisp.
+#
+# Relisp is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#  
+# Relisp is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see
+# <http://www.gnu.org/licenses/>.
+#++
+#
+# Straight from the elisp info manual:
+#
+#   Programming Types
+#
+#   Integer Type::        Numbers without fractional parts.
+#   Floating Point Type:: Numbers with fractional parts and with a large range.
+#   Symbol Type::         A multi-use object that refers to a function,
+#                           variable, or property list, and has a unique identity.
+#   (Sequence Type)::     Both lists and arrays are classified as sequences.
+#     Cons Cell Type::    Cons cells, and lists (which are made from cons cells).
+#   (Array Type)::        Arrays include strings and vectors.
+#     String Type::       An (efficient) array of characters.
+#     Vector Type::       One-dimensional arrays.
+#   Hash Table Type::     Super-fast lookup tables.
+#
+# These are also elisp programming types, but Relisp doesn't
+# explicitly deal with them.  Characters are basically just integers,
+# and functions and macros are cons.
+#
+#   Character Type::      The representation of letters, numbers and
+#                           control characters.
+#   Function Type::       A piece of executable code you can call from elsewhere.
+#   Macro Type::          A method of expanding an expression into another
+#                             expression, more fundamental but less pretty.
+#
+# And then these elisp types are ignored completely.
+#
+#   Char-Table Type::     One-dimensional sparse arrays indexed by characters.
+#   Bool-Vector Type::    One-dimensional arrays of `t' or `nil'.
+#   Primitive Function Type::     A function written in C, callable from Lisp.
+#   Byte-Code Type::      A function written in Lisp, then compiled.
+#   Autoload Type::       A type used for automatically loading seldom-used
+#                           functions.
+#
+# Every type in the first group obviously matches a ruby class except
+# for 'Cons' and 'Vector'.  The types that have an analogous ruby
+# class are mapped directly to that class.  'Cons' and 'Vector' are
+# mapped to a corresponding subclass of Array; the only difference
+# between the two is how they are translated back to elisp.
+#
+# Every ruby class that corresponds to a elisp data type is duplicated
+# inside the Relisp module with the rubyized version of the elisp
+# name; for example, Relisp::Integer is exactly the same as Fixnum and
+# Relisp::HashTable is the same as Hash.  
+#
+# Every class needs to have a +from_elisp+ method that accepts a hash
+# with the object's string representation, variable name (in the elisp
+# process) and the Slave instance that created the object.  The method
+# returns a ruby object analogous to the elisp value.
+#
+# Every object needs a +to_elisp+ method that creates a string which
+# results in a elisp value equivalent to the ruby object when read and
+# evaluated in elisp (i.e. <tt>elisp_eval "(eval (read
+# #{obj.to_elisp}))"</tt>).  For most objects this basically amounts
+# to a variation on the +to_s+ method.  However, for objects that
+# don't have a string representation (hashes, buffers, frames, ...)
+# the +to_elisp+ method actually results in elisp code that, when run,
+# returns the appropriate object.
+
+module Relisp
+
+  Integer = 1.class
+  class Integer
+    def self.from_elisp(object)
+      object[:string].to_i
+    end
+  end
+
+
+  Float = (3.14).class
+  class Float
+    def self.from_elisp(object)
+      object[:string].to_f
+    end
+  end
+
+
+  Symbol = :flag.class
+  class Symbol
+    def self.from_elisp(object)
+      if object[:string] == 'nil'
+        nil
+      elsif object[:string] == 't'
+        true
+      else
+        object[:string].to_sym
+      end
+    end
+
+    def to_elisp
+      "'" + self.to_s
+    end
+  end
+
+
+  class Cons < Array
+    def self.from_elisp(object)
+      new(super(object))
+    end
+
+    def to_elisp
+      print_string = '(list '
+      each do |elt|
+        print_string << elt.to_elisp << ' '
+      end
+      print_string << ')'
+    end
+  end
+
+
+  String = "words, words, words".class
+  class String
+    def self.from_elisp(object)
+      new(eval(object[:string]))
+    end
+
+    def to_elisp
+      self.dump
+    end
+  end
+
+
+  class Vector < Array
+    def self.from_elisp(object)
+      new(super(object))
+    end
+
+    def to_elisp
+      print_string = '[ '
+      each do |elt|
+        print_string << elt.to_elisp << ' '
+      end
+      print_string << ']'
+    end
+  end
+
+
+  HashTable = {:money => "power"}.class
+  class HashTable
+    def self.from_elisp(object)
+      slave = object[:slave]
+      object_variable = slave.get_permanent_variable(object[:variable])
+
+      unless slave.elisp_eval("(type-of #{object_variable})") == "hash-table".to_sym
+        raise ArgumentError, "#{object_variable} isn't a hash-table"
+      end
+      keys_var = slave.new_elisp_variable
+      vals_var = slave.new_elisp_variable
+      slave.elisp_execute( "(setq #{keys_var} nil)" )
+      slave.elisp_execute( "(setq #{vals_var} nil)" )
+      slave.elisp_execute( "(maphash (lambda (key val)
+                              (setq #{keys_var} (append #{keys_var} (list key)))
+                              (setq #{vals_var} (append #{vals_var} (list val)))) #{object_variable})" )
+      keys = slave.elisp_eval( keys_var )
+      vals = slave.elisp_eval( vals_var )
+      keys ||= []
+      hash = Hash.new
+      keys.each_index do |i|
+        hash[keys[i]] = vals[i]
+      end
+
+      slave.makunbound(object_variable)
+      slave.makunbound(keys_var)
+      slave.makunbound(vals_var)
+
+      return hash
+    end
+
+    def to_elisp
+      lisp =  "(progn \n"
+      lisp << "  (let ((--temp--relisp--variable (make-hash-table))) \n"
+      each_pair do |key, val|
+        lisp << "    (puthash #{key.to_elisp} #{val.to_elisp} --temp--relisp--variable) \n"
+      end
+      lisp << "--temp--relisp--variable))"
+    end
+  end
+
+end
+
+
+# Every object is given a default +to_elisp+ method, and classes get a
+# dummy +from_elisp+ method.
+#
+class Object
+  def to_elisp
+    self.to_s
+  end
+
+  def self.from_elisp(*args)
+    nil
+  end
+end
+
+class Class
+  # Convert classes to the symbol form of their name
+  def to_elisp
+    self.to_s.to_sym.to_elisp
+  end
+end
+
+class NilClass
+  def to_elisp
+    "nil"
+  end
+end
+
+
+class TrueClass
+  def to_elisp
+    "t"
+  end
+end
+
+
+class FalseClass
+  # Falseness in elisp is represented by 'nil'.
+  def to_elisp
+    nil.to_elisp
+  end
+end
+
+
+# The normal Array class is modified so that an array can be converted
+# to either Relisp::Cons or Relisp::Vector.
+#
+class Array
+  @@default_elisp_type = Relisp::Cons
+
+  # Converts either a 'cons' or 'vector' to a ruby array.
+  def self.from_elisp(object)
+    object_variable = object[:slave].get_permanent_variable(object[:variable])
+    size = object[:slave].elisp_eval( "(length #{object_variable})" )
+    object_array = new
+    size.times do |i|
+      object_array << object[:slave].elisp_eval( "(elt #{object_variable} #{i.to_elisp})" )
+    end
+
+    object[:slave].elisp_execute( "(makunbound #{object_variable.to_elisp})" )
+    return object_array
+  end
+
+  # Set the elisp type that ruby arrays are converted to by default.
+  def self.default_elisp_type=(type)
+    unless type.ancestors.include?(Array)
+      raise ArgumentError, "#{type} is not a kind of Array" 
+    end
+
+    @@default_elisp_type = type
+  end
+
+  def self.default_elisp_type
+    @@default_elisp_type
+  end
+
+  # The elisp type that this array will be converted to by to_elisp.
+  def elisp_type
+    @elisp_type = nil unless defined?(@elisp_type) #to avoid uninitialized warning
+    @elisp_type || @@default_elisp_type
+  end
+
+  def elisp_type=(type)
+    unless type.ancestors.include?(Array)
+      raise ArgumentError, "#{type} is not a kind of Array" 
+    end
+
+    @elisp_type = type
+  end
+
+  def to_elisp
+    elisp_type.new(self).to_elisp
+  end
+end

data/lib/relisp/slaves.rb

@@ -0,0 +1,365 @@
+#--
+# Copyright (C) 2009 <don@ohspite.net>
+#
+# This file is part of Relisp.
+#
+# Relisp is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#  
+# Relisp is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see
+# <http://www.gnu.org/licenses/>.
+#++
+#
+# TODO:
+# * maybe catch Errno::EPIPE to see if slave died
+
+module Relisp
+
+  @default_slave = nil
+  
+  def self.default_slave
+    @default_slave
+  end
+
+  def self.default_slave=(slave)
+    unless slave.kind_of?(Slave)
+      raise ArgumentError, "#{slave} is not a Slave"
+    end
+    @default_slave = slave
+  end
+
+  # This is the base class for RubySlave and ElispSlave--the Slave
+  # class isn't meant to be used itself.
+  #
+  class Slave
+
+    # Ruby and elisp use these strings to terminate messages sent to
+    # each other.  This ruby library and the elisp code are tied to
+    # one another so closely that I don't know if it matters, but it
+    # still seemed like a bad idea to hard code the constants in both
+    # places.
+    ANSWER_CODE            = '___FORTYTWO___'
+    QUESTION_CODE          = '___TOBEORNOTTOBE___'
+    ERROR_CODE             = '___NO_THATSNOTTRUE_THATSIMPOSSIBLE___'
+    ENDOFMESSAGE_REGEXP   = Regexp.new(ANSWER_CODE + '|' + QUESTION_CODE + '|' + ERROR_CODE)
+    # Every time ruby asks elisp to evaluate an expression, the result
+    # is saved in this variable so ruby can access it if necessary.
+    PREVIOUS_ELISP_RESULT = :"--relisp--previous--result"
+    # A prefix for elisp variables created by ruby.
+    VARIABLE_PREFIX        = '--relisp--variable--'
+
+    def initialize
+      # Whenever ruby calls 'eval' on some code at the request of
+      # elisp it is in a context where any new variables set will drop
+      # out of scope immediately.  The @local_binding is a way of
+      # allowing these variables to persist through multiple calls.
+      @local_binding = nil
+      @current_elisp_variable_num = '0'
+      @debug = nil
+      Relisp.default_slave = self
+    end
+
+    # Return a symbol which corresponds to an unused variable in
+    # elisp.
+    #
+    def new_elisp_variable
+      (VARIABLE_PREFIX + @current_elisp_variable_num.succ!).to_sym
+    end
+
+    # Return a symbol corresponding to a new elisp variable which hold
+    # the same information as _old_variable_. Intended primarily for
+    # use in the +from_elisp+ method in various classes.
+    #
+    def get_permanent_variable(old_variable)
+      permanent_variable = new_elisp_variable
+      elisp_execute( "(setq #{permanent_variable} #{old_variable})" )
+      return permanent_variable
+    end
+
+    # Run _code_ in the elisp process.
+    #
+    def elisp_execute(code)
+      code = code.to_s # maybe code is a symbol or something
+      write_to_emacs code
+      write_to_emacs QUESTION_CODE
+
+      output = ''
+      output_line = read_from_emacs
+      until output_line.strip == ANSWER_CODE
+        if output_line.strip == QUESTION_CODE
+          write_to_emacs((eval(output, @local_binding)).to_elisp)
+          write_to_emacs ANSWER_CODE
+          output = ''
+        elsif output_line.strip == ERROR_CODE
+          raise Relisp::ElispError, (eval output)
+        else
+          output << output_line
+        end
+      output_line = read_from_emacs
+      end
+
+      output.gsub!(/\n\z/, '')
+      return output
+    end
+    
+    # Run _code_ in the elisp process and return the result as the
+    # corresponding ruby object.  If the ruby object is not going to
+    # be used, use elisp_execute instead.
+    #
+    def elisp_eval(code)
+      result_string = elisp_execute(code)
+      to_ruby(result_string)
+    end
+
+    private 
+
+    # Pass an elisp evaluation result to the appropriate Relisp class
+    # for translation.  The first line of _result_string_ is the
+    # 'type-of' the elisp object.  The line(s) after that are the text
+    # version of the object.  In case the string representation isn't
+    # enough information to translate the object, the result needs to
+    # be kept (in emacs) in the variable +PREVIOUS_ELISP_RESULT+.
+    #
+    def to_ruby(result_string)
+      result_string = result_string.split("\n")
+      elisp_type    = result_string.reverse!.pop
+      object_string = result_string.reverse!.join("\n")
+
+      object_info = {
+        :string   => object_string,
+        :variable => PREVIOUS_ELISP_RESULT,
+        :slave    => self, 
+      }
+
+      # Just one more reason to love Ruby.  Call the Relisp class
+      # formed by rubyizing the 'type-of' the result (i.e., hash-table
+      # becomes HashTable).
+      ruby_type = (eval elisp_type.split("-").map { |a| a.capitalize }.join)
+      unless ruby_type.kind_of? Class
+        raise "#{ruby_type} not implemented" 
+      end
+      ruby_type.from_elisp(object_info)
+    end
+
+    # Send the constants that ruby and elisp need to share.
+    #
+    def pass_constants
+      [ANSWER_CODE, QUESTION_CODE, ERROR_CODE, PREVIOUS_ELISP_RESULT].each do |constant|
+        read_from_emacs
+        write_to_emacs constant
+      end
+    end
+
+    # Forward any missing method to elisp, writing the function and
+    # arguments in prefix notation (calling the +to_elisp+ method of
+    # each of the _args_).  
+    #
+    # This automatically allows access to a large portion of elisp
+    # functions a rubyish way.  
+    #
+    def method_missing(function, *args) # :doc:
+      function = function.to_s.gsub('_', '-')
+      unless elisp_eval("(functionp '#{function})")
+        raise NameError, "#{function} is not an elisp function"
+      end
+
+      elisp_eval('(' + 
+                 function + ' ' + 
+                 args.map{|a| a.to_elisp}.join(' ') +
+                 ')')
+    end
+    
+    public
+    
+    # Creates a method in the slave that is a reference to the
+    # variable given by _symbol_ in the scope of _binding_. This is
+    # probably only useful when calling elisp in ruby where the elisp
+    # code itself calls ruby again. When the elisp process calls
+    # +ruby_eval+ the code is executed inside the loop of the slave
+    # object, so the variables in the scope of the original call to
+    # elisp aren't normally available.
+    #
+    #    emacs = Relisp::ElispSlave.new
+    #    number = 5
+    #    emacs.elisp_eval('(ruby-eval "number")')  #  => [error]
+    #
+    #    emacs = Relisp::ElispSlave.new
+    #    number = 5
+    #    local_binding = binding
+    #    emacs.provide(:number, local_binding)
+    #    emacs.elisp_eval('(ruby-eval "number")')  #  => 5
+    #
+    def provide(symbol, binding)
+      eval "@__#{symbol.to_s}__binding = binding"
+
+      instance_eval <<-endstr
+        def #{symbol.to_s}
+          eval("#{symbol.to_s}", @__#{symbol.to_s}__binding)
+        end
+      endstr
+    end
+  end
+     
+
+  # This class dedicates the ruby process to responding to queries
+  # from the emacs process that started it.  See Relisp::Slave.
+  #
+  class RubySlave < Slave
+
+    # Can be provided with a block, in which case the block is run in
+    # the context of the slave and then the slave is automatically
+    # started.  This makes slave methods available to the block
+    # without specifying an explicit receiver, and variables and
+    # functions defined in the block are in scope when requests from
+    # elisp are evaluated.
+    #
+    def initialize
+      super
+      pass_constants
+
+      if block_given?
+        yield self
+        start
+      end
+
+    end
+
+    # Begin the main listening loop.
+    #
+    def start
+      begin
+        @local_binding = binding
+        
+        loop do
+          code = ''
+          input = read_from_emacs
+          until input.strip == QUESTION_CODE
+            code << input
+            input = read_from_emacs
+          end
+          code.gsub!(/\n\z/, '')
+          
+          write_to_emacs((eval code, @local_binding).to_elisp)
+          write_to_emacs ANSWER_CODE
+        end
+      rescue => dag_yo
+        write_to_emacs dag_yo
+        write_to_emacs ERROR_CODE
+        retry
+      end
+    end
+    
+    private
+    
+    # Emacs sends ruby's stdout to the filter function designated for
+    # the ruby process.
+    #
+    def write_to_emacs(code)
+      puts code
+    end
+    
+    # Messages appear on ruby's stdin after emacs sends them to ruby
+    # process.
+    #
+    def read_from_emacs
+      gets
+    end
+  end
+  
+  # Provides an interface to an instance of emacs started as an IO
+  # object.  See Relisp::Slave.
+  #
+  class ElispSlave < Slave
+    alias do elisp_eval
+
+    # Start an emacs process, load the relisp library, and force the
+    # process to become a slave to ruby's bidding.  The string
+    # _cli_options_ specifies arguments to pass to emacs on the
+    # command line, and _load_files_ is array of files to load (with
+    # the '-l' command line option) after the relisp.el library.
+    #
+    def initialize(cli_options = "--no-site-file --no-init-file", load_files = [])
+      super()
+      # load relisp.elc if available
+      elisp_path = File.expand_path(File.join(File.dirname(__FILE__), '../../src/relisp'))
+
+      @local_binding = binding
+
+      emacs_command = if RUBY_PLATFORM.downcase.include?('mswin')
+                        "start emacs --batch "
+                      else
+                        "emacs --batch "
+                      end
+      emacs_command << cli_options
+      emacs_command << " -l #{elisp_path}"
+      load_files.each do |file|
+        emacs_command << " -l #{file}"
+      end
+      emacs_command << " --eval '(relisp-become-slave)'"
+      # In batch mode, emacs sends its normal output to stderr for
+      # some reason.  I'm sure it's a good one...
+      emacs_command << " 2>&1"
+      @emacs_pipe = IO.popen(emacs_command, "w+")
+
+      # gobble whatever output until emacs reports for duty
+      until read_from_emacs.strip == "SEND CONSTANTS"; end
+      pass_constants
+    end
+
+    attr_accessor :debug
+
+    # When given a block, runs the block with debugging turned on and
+    # then restores the former status of debug messages.  Otherwise,
+    # toggles the status of debug messages. 
+    #
+    def debugging
+      if block_given?
+        debug_original_val = @debug
+        begin
+          @debug = true
+          puts
+          puts "-----------------"
+          yield
+        ensure
+          @debug = debug_original_val
+          puts "-----------------"
+        end
+      else
+        @debug = ! @debug
+      end
+    end
+
+    private
+
+    # Emacs reads from stdin and makes the input available to the
+    # mini-buffer.
+    #
+    def write_to_emacs(code)
+      if @debug
+        puts "ruby> " + code.to_s unless code =~ ENDOFMESSAGE_REGEXP
+      end
+      @emacs_pipe.puts code
+    end
+    
+    # Emacs sends whatever it outputs by way of 'message' to stderr,
+    # which is redirected to stdout when the emacs process is started
+    # in initialize.
+    #
+    def read_from_emacs
+      output = @emacs_pipe.gets
+      if @debug
+        puts "lisp> " + output unless output =~ ENDOFMESSAGE_REGEXP
+      end
+      return output
+    end
+  end
+
+end

data/lib/relisp.rb

@@ -0,0 +1,30 @@
+#--
+# Copyright (C) 2009 <don@ohspite.net>
+#
+# This file is part of Relisp.
+#
+# Relisp is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#  
+# Relisp is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see
+# <http://www.gnu.org/licenses/>.
+#++
+
+module Relisp
+  VERSION = '0.9.0'
+
+  class ElispError < RuntimeError; end
+end
+
+require 'relisp/slaves'
+require 'relisp/programming_types'
+require 'relisp/editing_types'
+