erlectricity 0.2.1 → 1.0.0

data/History.txt

@@ -1 +1,14 @@
-
+==
+  * Backward Incompatible Changes
+    * Implicit array call for f.when(:echo, String) must now be called as
+      f.when([:echo, String]) to eliminate ambiguity
+    * Implicit array call for f.send!(:ok, "foo") must now be called as
+      f.send!([:ok, "foo"]) to eliminate ambiguity
+    * The receive loop now defaults to using file descriptors 3 and 3
+      instead of STDIN and STDOUT. This prevents inadvertent output
+      statements from silently corrupting the transfer protocol.
+    * Erlang atoms 'true' and 'false' are now converted into Ruby booleans
+    * Erlectricity::Decoder.read_any_from -> Erlectricity::Decoder.decode
+  * Major Enhancements
+    * Calling `rake` now runs tests (with and without compiled C extensions)
+    * Package management is now done by Jeweler

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Scott Fleckenstein and Tom Preston-Werner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+Erlectricity
+============
+
+http://github.com/mojombo/erlectricity
+
+By Scott Fleckenstein, Tom Preston-Werner
+
+Development Status: Production/Stable
+
+
+Description
+-----------
+
+Erlectricity allows a Ruby program to receive and respond to Erlang messages
+sent over the Erlang binary protocol.
+
+
+Install
+-------
+
+$ gem install erlectricity
+
+-or-
+
+$ gem install mojombo-erlectricity -s http://gems.github.com
+
+
+The Simplest Example
+--------------------
+
+### Ruby side (echo.rb)
+
+    require 'rubygems'
+    require 'erlectricity'
+
+    receive do |f|
+      f.when([:echo, String]) do |text|
+        f.send!([:result, "You said: #{text}"])
+        f.receive_loop
+      end
+    end
+
+### Erlang side (echo.erl)
+
+    -module(echo).
+    -export([test/0]).
+
+    test() ->
+      Cmd = "ruby echo.rb",
+      Port = open_port({spawn, Cmd}, [{packet, 4}, nouse_stdio, exit_status, binary]),
+      Payload = term_to_binary({echo, <<"hello world!">>}),
+      port_command(Port, Payload),
+      receive
+        {Port, {data, Data}} ->
+          {result, Text} = binary_to_term(Data),
+          io:format("~p~n", [Text])
+      end.
+
+
+Data Type Conversions and Matching
+----------------------------------
+
+    % Port is the port opened via open_port({spawn, Cmd}, [{packet, 4}, ...])
+    % Message is the Erlang term to encode and send to the port
+    send(Port, Message) ->
+      port_command(Port, term_to_binary(Message)).
+
+    # Each triplet below represents:
+    # (line 1) the Erlang call
+    # (line 2) the Ruby matcher
+    # (line 3) the Ruby output
+
+    send(Port, test).
+    f.when(:test) { p :ok }
+    # :ok
+
+    send(Port, {atom, symbol}).
+    f.when([:atom, Symbol]) { |sym| p sym }
+    # :symbol
+
+    send(Port, {number, 1}).
+    f.when([:number, Fixnum]) { |num| p num }
+    # 1
+
+    send(Port, {string, <<"foo">>}).
+    f.when([:string, String]) { |str| p str }
+    # "foo"
+
+    send(Port, {array, [1,2,3]}).
+    f.when([:array, Array]) { |arr| p arr }
+    # [1, 2, 3]
+
+    send(Port, {array, [<<"abc">>, <<"def">>]}).
+    f.when([:array, Array]) { |arr| p arr }
+    # ["abc", "def"]
+
+    send(Port, {hash, [{key,val}]}).
+    f.when([:hash, Erl.hash]) { |hash| p hash }
+    # {:key=>:val}
+
+    send(Port, {object, {1,{2},3,<<"four">>}}).
+    f.when([:object, Any]) { |any| p any }
+    # [1, [2], 3, "four"]
+
+
+Contribute
+----------
+
+If you'd like to hack on Erlectricity, start by forking my repo on GitHub:
+
+http://github.com/mojombo/erlectricity
+
+To get all of the dependencies, install the gem first. The best way to get
+your changes merged back into core is as follows:
+
+1. Clone down your fork
+1. Create a topic branch to contain your change
+1. Hack away
+1. Add tests and make sure everything still passes by running `rake`
+1. If you are adding new functionality, document it in the README.md
+1. Do not change the version number, I will do that on my end
+1. If necessary, rebase your commits into logical chunks, without errors
+1. Push the branch up to GitHub
+1. Send me (mojombo) a pull request for your branch
+
+
+Copyright
+---------
+
+Copyright (c) 2009 Scott Fleckenstein and Tom Preston-Werner. See LICENSE for details.

data/Rakefile

@@ -1,71 +1,74 @@
 require 'rubygems'
 require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'rake/contrib/rubyforgepublisher'
-require 'fileutils'
-require 'hoe'
-include FileUtils
-require File.join(File.dirname(__FILE__), 'lib', 'erlectricity', 'version')
-
-AUTHOR = 'Scott Fleckenstein'  # can also be an array of Authors
-EMAIL = "nullstyle@gmail.com"
-DESCRIPTION = "A library to interface erlang and ruby through the erlang port system"
-GEM_NAME = 'erlectricity' # what ppl will type to install your gem
-RUBYFORGE_PROJECT = 'erlectricity' # The unix name for your project
-HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
-DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
 
-NAME = "erlectricity"
-REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
-VERS = Erlectricity::VERSION::STRING + (REV ? ".#{REV}" : "")
-CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
-RDOC_OPTS = ['--quiet', '--title', 'erlectricity documentation',
-    "--opname", "index.html",
-    "--line-numbers", 
-    "--main", "README",
-    "--inline-source"]
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "erlectricity"
+    gem.rubyforge_project = "erlectricity"
+    gem.summary = "A library to interface erlang and ruby through the erlang port system"
+    gem.email = "tom@mojombo.com"
+    gem.homepage = "http://github.com/mojombo/erlectricity"
+    gem.authors = ["Scott Fleckenstein", "Tom Preston-Werner"]
+    gem.require_paths = ["lib", "ext"]
+    gem.files.include("ext")
+    gem.extensions << 'ext/extconf.rb'
 
-class Hoe
-  def extra_deps 
-    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
-  end 
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
 
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-hoe = Hoe.new(GEM_NAME, VERS) do |p|
-  p.author = AUTHOR 
-  p.description = DESCRIPTION
-  p.email = EMAIL
-  p.summary = DESCRIPTION
-  p.url = HOMEPATH
-  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
-  p.test_globs = ["test/**/test_*.rb"]
-  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
-  
-  # == Optional
-  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  p.extra_deps = [
-    ['concurrent', '0.2.2'],
-  ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
-  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
-  p.spec_extras = {:extensions => ['ext/extconf.rb']}
-end
+task :test do
+  require 'open3'
+  require 'fileutils'
 
-desc 'Release the website and new gem version'
-task :deploy => [:check_version, :release]
+  puts "\nCleaning extension build files and running all specs in native ruby mode..."
+  `rm -f ext/*.bundle` && puts("rm -f ext/*.bundle")
+  `rm -f ext/*.o` && puts("rm -f ext/*.o")
+  Open3.popen3("ruby test/spec_suite.rb") do |stdin, stdout, stderr|
+    while !stdout.eof?
+      print stdout.read(1)
+    end
+  end
+
+  puts "\nRunning `make` to build extensions and rerunning decoder specs..."
+  Dir.chdir('ext') { `make` }
+  Open3.popen3("ruby test/decode_spec.rb") do |stdin, stdout, stderr|
+    while !stdout.eof?
+      print stdout.read(1)
+    end
+  end
+end
 
-task :check_version do
-  unless ENV['VERSION']
-    puts 'Must pass a VERSION=x.y.z release version'
-    exit
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
   end
-  unless ENV['VERSION'] == VERS
-    puts "Please update your version.rb to match the release version, currently #{VERS}"
-    exit
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
   end
 end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "erlectricity #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 0
+:patch: 0

data/examples/echo/README.md

@@ -0,0 +1,12 @@
+This is a simple echo server example showing off basic Erlectricity usage.
+
+    $ cd examples/echo
+    $ erl
+    Erlang (BEAM) emulator version 5.6.4 [source] [smp:2] [async-threads:0] [kernel-poll:false]
+
+    Eshell V5.6.4  (abort with ^G)
+    1> c(echo).
+    {ok,echo}
+    2> echo:test().
+    <<"You said: hello world!">>
+    ok

data/examples/echo/echo.erl

@@ -0,0 +1,13 @@
+-module(echo).
+-export([test/0]).
+
+test() ->
+  Cmd = "ruby echo.rb",
+  Port = open_port({spawn, Cmd}, [{packet, 4}, nouse_stdio, exit_status, binary]), 
+  Payload = term_to_binary({echo, <<"hello world!">>}),
+  port_command(Port, Payload),
+  receive
+    {Port, {data, Data}} ->
+      {result, Text} = binary_to_term(Data),
+      io:format("~p~n", [Text])
+  end.

data/examples/echo/echo.rb

@@ -0,0 +1,11 @@
+$:.unshift File.join(File.dirname(__FILE__), *%w[../../lib])
+
+require 'rubygems'
+require 'erlectricity'
+
+receive do |f|
+  f.when([:echo, String]) do |text|
+    f.send!([:result, "You said: #{text}"])
+    f.receive_loop
+  end
+end

data/examples/gruff/gruff.erl

@@ -1,18 +1,18 @@
 -module(gruff).
 -export([start/0, stop/0, plot/4]).
 
-start() -> 
-  spawn(fun() -> 
-    register(gruff, self()), 
-    process_flag(trap_exit, true), 
+start() ->
+  spawn(fun() ->
+    register(gruff, self()),
+    process_flag(trap_exit, true),
     Cmd = "ruby ./gruff_provider.rb",
-    Port = open_port({spawn, Cmd}, [{packet, 4}, use_stdio, exit_status, binary]), 
-    port_loop(Port) 
-  end). 
+    Port = open_port({spawn, Cmd}, [{packet, 4}, nouse_stdio, exit_status, binary]),
+    port_loop(Port)
+  end).
 
-stop() -> gruff ! stop. 
+stop() -> gruff ! stop.
 
-plot(Name, Font, Data, Labels) -> 
+plot(Name, Font, Data, Labels) ->
   gruff ! {plot, self(), Name, Font, Data, Labels},
   receive
     {result, Bin} -> Bin
@@ -28,7 +28,6 @@ send_labels(Port, Labels) ->
   Data = {labels, Labels},
   Port ! {self(), {command, term_to_binary(Data)}}.
 
-
 port_loop(Port) ->
   receive
     {plot, Caller, Name, Font, Data, Labels} ->
@@ -37,18 +36,18 @@ port_loop(Port) ->
 
       send_data(Port, Data),
       send_labels(Port, Labels),
-      
+
       EndData = term_to_binary('end'),
       Port ! {self(), {command, EndData}},
       Result = get_result(Port),
       Caller ! {result, Result },
-      
+
       port_loop(Port);
-        
-    stop -> 
-      Port ! {self(), close}, 
-      receive 
-        {Port, closed} -> exit(normal) 
+
+    stop ->
+      Port ! {self(), close},
+      receive
+        {Port, closed} -> exit(normal)
       end
   end.
 
@@ -57,6 +56,6 @@ get_result(Port) ->
     {Port, {data, Data}} ->
       {result, Bin} = binary_to_term(Data),
       Bin;
-    {'EXIT', Port, Reason} ->  
+    {'EXIT', Port, Reason} ->
       exit({port_terminated,Reason})
     end.

data/examples/gruff/gruff_provider.rb

@@ -1,38 +1,31 @@
-$:.unshift(File.dirname(__FILE__) + "/../../lib/")
+$:.unshift File.join(File.dirname(__FILE__), *%w[../../lib])
+
 require 'erlectricity'
 require 'rubygems'
 require 'gruff'
 
 receive do |f|
-  
-  
-    
-  f.when(:plot, String, Symbol, String) do |name, style, font|
+  f.when([:plot, String, Symbol, String]) do |name, style, font|
     graph = Gruff.const_get(style).new
     graph.title = name
     graph.font = font
     graph.legend_font_size = 10
-    
-    
+
     f.receive do |g|
-      g.when(:data, Symbol, Array) do |name, points|
+      g.when([:data, Symbol, Array]) do |name, points|
         graph.data name, points
         g.receive_loop
       end
-  
-      g.when(:labels, Erl.hash) do |label_data|
+
+      g.when([:labels, Erl.hash]) do |label_data|
         graph.labels = label_data
         g.receive_loop
       end
-  
-      g.when(:end){ :ok }
+
+      g.when(:end) { :ok }
     end
-    
-    
-    f.send! :result, graph.to_blob
+
+    f.send!([:result, graph.to_blob])
     f.receive_loop
   end
-    
-end
-
-
+end