relisp 0.9.0

data/Manifest

@@ -0,0 +1,18 @@
+CHANGELOG
+COPYING
+Manifest
+README
+Rakefile
+examples/elisp_master/elisp_master.el
+examples/elisp_master/ruby_slave
+examples/ruby_master/ruby_master_example
+lib/relisp.rb
+lib/relisp/editing_types.rb
+lib/relisp/programming_types.rb
+lib/relisp/slaves.rb
+setup.rb
+src/relisp.el
+src/relisp.elc
+test/test_editing_types.rb
+test/test_programming_types.rb
+test/test_slaves.rb

data/README

@@ -0,0 +1,171 @@
+= Relisp
+
+== Synopsis
+
+Emacs is great.  So is Ruby.  This purpose of this library is to:
+* call Ruby from Emacs
+* call Elisp from Ruby
+* manipulate Emacs without using Elisp to some extent (Ruby wrappers
+  around some Elisp functions and objects)
+* reduce the number of blog entries titled "Is Ruby an acceptable
+  lisp?" and flame wars under the title "ruby vs. lisp vs. scheme
+  vs. haskell vs. ..."
+
+== Install
+
+   [sudo] gem install sundae
+
+Then the library is installed, and you can call elisp from ruby.  But
+if you want to call ruby from emacs (and you do, right?) you need to
+go into the +src+ directory and copy <tt>relisp.el</tt> and/or
+<tt>relisp.elc</tt> to your elisp folder (probably <tt>~/.elisp</tt>).
+Then you might want to add the line <tt>(require 'relisp)</tt> to your
+emacs initialization file (probably <tt>~/.emacs'</tt>).
+
+If you don't know where to find the files for this gem, run the
+command <tt>gem env gemdir</tt>.  Or you can download the tarball for
+this gem and get the files there.
+
+== Usage
+
+The stuff below is all in the +examples+ directory if you want to try
+running it.
+
+=== Emacs calling Ruby
+
+==== With a generic slave
+
+Start up a ruby process:
+
+  (relisp-start-slave)
+
+Then make calls to ruby with <tt>ruby_eval</tt>:
+  
+  (ruby-eval "1 + 2 + 3") 
+      => 6
+  (ruby-eval "'ruby string'.reverse")
+      => "gnirts ybur"
+  (type-of (ruby-eval "{:name => 'john'}"))	
+      => hash-table
+
+If you need to use an elisp variable or expression in the middle of
+the command, <tt>relisp-to-ruby</tt> will provide a string that, when
+evaluated by ruby, is equal to the original elisp object.  For example:
+
+  (setq vect [1 2 3 4 5 6])
+  (ruby-eval (concat (relisp-to-ruby vect) ".class"))
+     => Relisp::Vector
+  (ruby-eval (concat (relisp-to-ruby vect) ".kind_of?(Array)"))
+     => t
+  (ruby-eval (concat (relisp-to-ruby vect) ".reverse"))
+     => [6 5 4 3 2 1]
+  (type-of (ruby-eval (concat (relisp-to-ruby vect) ".reverse")))
+     => vector
+
+Note that the data types/classes are correct in both languages.  The
+results are converted--it's not just strings getting passed back and
+forth.
+
+Elisp can ask Ruby to evaluate code which in turn will call elisp:
+
+  (ruby-eval "elisp_eval('(+ 1 2)')")
+  (ruby-eval "elisp_eval('(ruby-eval \"1 + 2\")')")
+
+The state of the slave persists from one call to the next:
+
+  (ruby-eval "a = 5")
+  (ruby-eval "a + 1")
+     => 6
+
+==== Specifying a slave file
+
+The ruby slave file should look something like this:
+
+  require 'relisp'
+
+  slave = Relisp::RubySlave.new
+
+  def sample_ruby_method
+    Relisp::Buffer.new("ruby-created-buffer")
+  end
+
+  slave.start
+
+The call to <tt>slave.start</tt> should probably be the last line of
+the file since it starts an infinite loop.  The elisp code just
+needs to specify the ruby slave file before calling
+<tt>relisp-start-slave</tt>:
+
+  (setq relisp-ruby-slave-path "ruby_slave")
+  (relisp-start-slave)
+  (ruby-eval "sample_ruby_method")
+
+For debugging and curiousity, all of the messages between emacs and
+ruby are recorded in the buffer <tt>\*Relisp\*</tt>.
+
+=== Ruby calling Emacs
+
+The Emacs process is managed by <tt>Relisp::ElispSlave</tt>.
+
+  require 'relisp'
+  emacs = Relisp::ElispSlave.new
+
+Calls are made calling <tt>elisp_eval</tt> and <tt>elisp_execute</tt>
+on the ElispSlave object.
+
+  emacs.elisp_eval "(+ 1 2)"
+     => 3
+  emacs.elisp_eval '(concat "two " "words")'
+     => "two words"
+  emacs.elisp_eval( "(setq new-var 23)")
+  emacs.elisp_eval( "(+ 1 new-var)")
+     => 24
+  
+The usual <tt>method_missing</tt> magic provides access to elisp
+functions:
+
+  emacs.concat("two", " words")        # (concat "two" "words")
+  emacs.*(5,2)                         # (* 5 2)
+  emacs.create_file_buffer("blah.txt") # (create-file-buffer "blah.txt")
+
+Emacs editing types have (or will have) proxy classes:
+
+  buffer =  Relisp::Buffer.new("ruby-created-buffer")
+     => #<Relisp::Buffer:0xb7c4784c>
+  buffer.name
+     => "ruby-created-buffer"
+
+To print debug information showing messages between ruby and emacs,
+use the <tt>ElispSlave#debugging</tt> method:
+
+  emacs.debugging do
+    emacs.elisp_eval "(+ 1 2)"    
+  end 
+
+== To Do
+
+* finish implementing emacs editting types (buffers, frames, etc.)
+* fix Windows bug(s)
+
+== Author
+
+<don@ohspite.net>
+
+== Copyright
+
+Copyright (C) 2009 <don@ohspite.net>.
+Licensed under the GNU General Public License.
+
+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/>.

data/Rakefile

@@ -0,0 +1,50 @@
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'relisp'
+
+task :default => 'test'
+
+PROJ.name           = 'relisp'
+PROJ.authors        = 'Don'
+PROJ.email          = 'don@ohspite.net'
+PROJ.url            = 'relisp.rubyforge.org'
+PROJ.summary        = 'Call ruby from emacs and call elisp from ruby. If you never did you should. These things are fun and fun is good.'
+PROJ.description    = 'Call ruby from emacs and call elisp from ruby. If you never did you should. These things are fun and fun is good.'
+PROJ.version        = Relisp::VERSION
+PROJ.rubyforge.name = 'relisp'
+PROJ.history_file   = 'CHANGELOG'
+PROJ.manifest_file  = 'Manifest'
+PROJ.readme_file    = 'README'
+PROJ.rdoc.main      = 'README'
+PROJ.exclude        = %w(tmp$ bak$ ~$ CVS \.svn/ \.git/ \.bzr/ \.bzrignore ^pkg/)
+PROJ.rdoc.include   = %w(README ^lib/ ^bin/ ^ext/ \.txt$ \.rdoc$)
+
+PROJ.gem.extras[:post_install_message] = <<-MSG
+---------------------------
+Wait! You're not finished!
+
+The gem is installed, and you can now call elisp from ruby.  But if
+you want to call ruby from emacs (and you do, right?) you need to go
+into the 'src' directory of this gem and copy 'relisp.el' and/or
+'relisp.elc' to your elisp folder (probably '~/.elisp').  Then you
+might want to add the line "(require 'relisp)" to your emacs
+initialization file (probably '~/.emacs').
+
+If you don't know where to find the files for this gem, run the
+command "gem env gemdir".  Or you can download the tarball for this
+gem and get the files there.
+---------------------------
+MSG
+
+PROJ.spec.opts << '--color'
+

data/examples/elisp_master/elisp_master.el

@@ -0,0 +1,54 @@
+;; How to specify a file when running the slave.  The next few
+;; `ruby-eval's call methods defined in the ruby slave file.
+
+(progn
+  (relisp-stop-slave)
+  (setq relisp-ruby-slave-path "ruby_slave")
+  (relisp-start-slave))
+
+(ruby-eval "sample_ruby_method1")
+(ruby-eval "sample_ruby_method2")
+
+(member "ruby-created-buffer" (mapcar (lambda (a) (buffer-name a)) (buffer-list)))
+(ruby-eval "sample_ruby_method3")
+(member "ruby-created-buffer" (mapcar (lambda (a) (buffer-name a)) (buffer-list)))
+
+;; How to start the ruby slave without a file. The rest of the
+;; commands will work fine with a slave started either way.
+
+(progn
+  (relisp-stop-slave)
+  (makunbound 'relisp-ruby-slave-path)
+  (relisp-start-slave))
+
+;; Basic functionality--note that return values are not strings but
+;; actual elisp data types:
+(ruby-eval "1 + 2 + 3")
+(ruby-eval "'ruby string'.reverse")
+
+(setq vect [1 2 3 4 5 6])
+(ruby-eval (concat (relisp-to-ruby vect) ".class"))
+(ruby-eval (concat (relisp-to-ruby vect) ".kind_of?(Array)"))
+(ruby-eval (concat (relisp-to-ruby vect) ".reverse"))
+(type-of (ruby-eval (concat (relisp-to-ruby vect) ".reverse")))
+
+(setq list '(3 5 2 6 4 1))
+(ruby-eval (concat (relisp-to-ruby list) ".sort"))
+(type-of (ruby-eval (concat (relisp-to-ruby list) ".sort")))
+
+(setq str "a couple of words")
+(ruby-eval (concat (relisp-to-ruby str) ".split"))
+
+(type-of (ruby-eval "{:name => 'john'}"))
+
+;; Recursive calls:
+(ruby-eval "elisp_eval('(+ 1 2)')")
+(ruby-eval "elisp_eval('(ruby-eval \"1 + 2\")')")
+
+;; Variable persistence between calls:
+(ruby-eval "a = 5")
+(ruby-eval "a + 1")
+
+
+
+

data/examples/elisp_master/ruby_slave

@@ -0,0 +1,19 @@
+$:.unshift File.join(File.dirname(__FILE__), "../../lib") 
+
+require 'relisp'
+
+slave = Relisp::RubySlave.new
+
+def sample_ruby_method1
+  elisp_eval("(+ 1 5)")
+end
+
+def sample_ruby_method2
+  elisp_eval('(ruby-eval "(1 + 5)")')
+end   
+
+def sample_ruby_method3
+  Relisp::Buffer.new("ruby-created-buffer")
+end
+
+slave.start

data/examples/ruby_master/ruby_master_example

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), "../../lib") 
+
+require 'relisp'
+
+emacs = Relisp::ElispSlave.new
+
+# basic functionality
+puts emacs.elisp_eval("(+ 1 2)")
+puts (emacs.elisp_eval '(concat "two " "words")')
+puts emacs.concat("two", " words")
+puts emacs.*(5,2)
+puts emacs.create_file_buffer("blah.txt")
+
+# variable persistence between calls
+emacs.elisp_eval( "(setq new-var 23)")
+puts emacs.elisp_eval( "(+ 1 new-var)")
+
+# recursive calls
+puts emacs.elisp_eval( '(ruby-eval "1 + 3")')
+
+# wrappers around elisp editing data types
+buffer =  Relisp::Buffer.new("ruby-created-buffer")
+puts buffer
+puts buffer.name
+

data/lib/relisp/editing_types.rb

@@ -0,0 +1,86 @@
+#--
+# 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/>.
+#++
+#
+# See the documentation in <tt>programming_types.rb</tt>.
+#
+# Elisp editing types as described in the elisp info manual:
+#
+#   Editing Types
+#
+#   Buffer Type::         The basic object of editing.
+#   Marker Type::         A position in a buffer.
+#   Window Type::         Buffers are displayed in windows.
+#   Frame Type::	    Windows subdivide frames.
+#   Window Configuration Type::   Recording the way a frame is subdivided.
+#   Frame Configuration Type::    Recording the status of all frames.
+#   Process Type::        A process running on the underlying OS.
+#   Stream Type::         Receive or send characters.
+#   Keymap Type::         What function a keystroke invokes.
+#   Overlay Type::        How an overlay is represented.  
+#
+# Unlike with elisp programming data types, ruby does not translate
+# the editing data types to an equivalent ruby object; instead, the
+# class corresponding to each data type is just a proxy that acts on
+# the original object in elisp.
+
+module Relisp
+
+  # A Buffer object just holds onto the Emacs buffer in an elisp
+  # variable and acts as a proxy.
+  #
+  class Buffer
+    def self.from_elisp(object)
+      new(object[:variable], object[:slave])
+    end
+
+    # When _var_or_name_ is a symbol it is considered to be the name
+    # of a pre-existing buffer in the _slave_ process.  If
+    # _var_or_name_ is a string, a new buffer is created with a name
+    # based on that string. 
+    def initialize(var_or_name, slave = Relisp.default_slave)
+      @slave = slave
+
+      if var_or_name.kind_of?( Symbol )
+        @elisp_variable = @slave.get_permanent_variable(var_or_name)
+
+        unless @slave.elisp_eval("(type-of #{@elisp_variable})") == :buffer
+          raise ArgumentError, "#{@elisp_variable} isn't a buffer"
+        end
+      elsif var_or_name.kind_of?( String )
+        @slave.elisp_execute("(generate-new-buffer #{var_or_name.to_elisp})")
+        @elisp_variable = @slave.get_permanent_variable(Relisp::Slave::PREVIOUS_ELISP_RESULT)
+      else
+        raise ArgumentError
+      end
+    end
+
+    def to_elisp
+      @elisp_variable
+    end
+
+    # Return the name of the buffer.
+    #
+    def name
+      @slave.elisp_eval "(buffer-name #{@elisp_variable})"
+    end
+  end
+
+end
+