shen-ruby 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c457075dab1a292cac646bf9148aaafb79de2457
-  data.tar.gz: b8909a0fef1f820b121110a06394366a7c01c3a4
+  metadata.gz: 2cc8006d7f3fac61a20da31b9abe918d51ccfc56
+  data.tar.gz: bb145ab8f07ab6ede1cb1eef9ff9ea5aa219d31a
 SHA512:
-  metadata.gz: 686bb28d207078c9e7e0a9ad38c058fe9ed7da9695a84adf4f51a85e58ca3870b90235ada593ae3c7ebdedfc641ac0649591dfa59ae9dc43b84b1f5607747de9
-  data.tar.gz: d767482519d1199ad6206f122fd0c1bd8211c155df994cdabbf5e9c7f2f5f6a616e7019e1d7d9886a775ffd1e72625d605c837286b6d4cd6dda6012884169092
+  metadata.gz: 9a3c09ebb9aaf85a1df12b949ea8d820f3924aa7034dad4c425af651d1e898323e2c725e067ded89e81e441abe7d7624e37a53f9e8438af52df30044f0dd3b3f
+  data.tar.gz: 57339d8ecf2d9cc0e2bcc2e452235e15eb9ce70f4d36244a880cd79cc55706ade719bcc54ef1a9ee9f064964ac77ae63e7fd1ee7da69b38c380ad3eb453e1821

data/HISTORY.md

@@ -1,5 +1,10 @@
 # ShenRuby Release History
 
+## 0.12.0 - January 31, 2014
+### Features
+- Shen -> Ruby interop
+  - See README.md for details
+
 ## 0.11.0 - January 15, 2014
 ### Features
 - KLambda implementation switched to [Klam](https://github.com/gregspurrier/klam). This has many implications, including:

data/README.md

@@ -14,7 +14,7 @@ ShenRuby 0.1.0 began to satisfy the first goal by providing a Shen REPL accessib
 ## Installation
 NOTE: ShenRuby requires Ruby 1.9 language features. It is tested with Ruby 2.0.0, 2.1.5, and 2.2.0. It has been lightly tested with JRuby 1.7.17. It is functional with Ruby 1.9.3, however its fixed stack size prevents it from passing the Shen Test Suite (see [Setting Stack Size](setting-stack-size) below).
 
-ShenRuby 0.11.0 is the current release. To install it as a gem, use the following command:
+ShenRuby 0.12.0 is the current release. To install it as a gem, use the following command:
 
     gem install shen-ruby
 
@@ -23,13 +23,13 @@ ShenRuby 0.11.0 is the current release. To install it as a gem, use the followin
 Once the gem has been installed, the Shen REPL can be launched via the `srrepl` (short for ShenRuby REPL) command. For example:
 
     % srrepl
-    Loading.... Completed in 2.18 seconds.
+    Loading.... Completed in 2.62 seconds.
 
     Shen 2010, copyright (C) 2010 Mark Tarver
     released under the Shen license
     www.shenlanguage.org, version 16
     running under Ruby, implementation: ruby 2.2.0
-    port 0.11.0 ported by Greg Spurrier
+    port 0.12.0 ported by Greg Spurrier
 
 
     (0-)
@@ -124,6 +124,65 @@ The equivalent conversion functions for vectors are `ShenRuby.vector_to_list` an
 #### Caveats
 Shen function invocation via methods on the Shen object only works for normal functions. It will not work for special forms like `define` or macros.
 
+### Invoking Ruby from Shen
+By convention, functionality for interacting with Shen's host platform is placed within a package named with the host language's file extension. Therefore the Ruby interop forms begin with `rb.`.
+
+#### Constant References
+Ruby constants, including classes and modules, are referenced by prefixing them with `rb.#` and replacing `::` with `#`. For example:
+
+    rb.#Hash
+    rb.#Math#PI
+    rb.#RUBY_VERSION
+
+### Method Invocation
+Ruby method invocation uses a syntax inspired by Clojure and looks similar to normal function application. The method name, prefixed with `rb.`, is used as the operator and the receiver is the first operand. Any additional operands are passed to the method as its arguments. For example:
+
+    (rb.reverse "hello")
+    (rb.prepend "bye" "good")
+    (rb.sqrt rb.#Math 4)
+
+The `[]` and `[]=` method names used for accessing and manipulating Ruby arrays and hashes cannot be used directly because the Shen reader interprets `[]` as an empty list. Use `rb.<-` and `rb.->` instead. These mimic Shen's `<-vector` and `vector->` operations on vectors.
+
+#### Invoking Class Methods
+The last example above invokes the `Math` module's `sqrt` class method. A shorter form is provided as a convenience:
+
+    (rb.#Math.sqrt 4)
+
+Invocations of `Kernel` class methods can be further shortened by prefixing the method's name with `rb.#`. The following are all equivalent:
+
+    (rb.require rb.#Kernel "digest/md5")
+    (rb.#Kernel.require "digest/md5")
+    (rb.#require "digest/md5")
+
+#### Hash Parameters
+Many Ruby methods take a `Hash` object as their final parameter. Ruby provides a special syntax for this which is echoed by ShenRuby. Argument triples of the form 'key `=>` value' are poured into `Hash` and passed as the method's final argument. For example:
+
+    (rb.#puts a => "hello" b => 37)
+
+As in Ruby, the key-arrow-value triples must be the final normal arguments to the method.
+
+#### Block Parameters
+In addition to normal arguments, Ruby methods may also accept blocks. A block argument in ShenRuby is denoted by `&n`--where `n` is the arity of the block expected by the method--followed by a function. Arities from 0 to 5 are supported. If the arity is one, `&` may be used instead of `&1`. The arity marker and the block function must be the last two elements of the argument list.
+
+For example, to print each character of a string on a separate line using Shen's `pr` and `nl` system functions:
+
+    (rb.each_char "hello" &1 (/. X (do (pr X) (nl))))
+
+Or, to sum the elements of a list using Ruby's `Enumerable#reduce`:
+
+    (rb.reduce [1 2 3] &2 +)
+
+This use of `reduce` is possible because Shen's list and vector types are enumerable in ShenRuby.
+
+Please note that these two examples can--and, in practice, should--be easily implemented in Shen without resorting to Ruby methods. They are here simply to demonstrate ShenRuby's syntax for block arguments.
+
+#### Type Coercion
+Shen booleans, numbers, strings, and symbols are implemented using the corresponding Ruby classes and no coercion is required.
+
+Shen's list and vector types both implement the Ruby `Enumerable` interface and may be passed directly as arguments to methods expecting instances of `Enumerable`. When an `Array` is required, they can be coerced using `rb.to_a`.
+
+ShenRuby provides two system functions for coercing Ruby `Enumerable` instances to Shen lists and vectors. These are `rb-to-l` and `rb-to-v`, respectively.
+
 ## Setting Stack Size
 Some operations in Shen, notably type checking of complicated types, require more stack space than is available by default in Ruby. If your program encounters a stack overflow, you can increase Ruby's stack size through the following methods.
 
@@ -148,7 +207,6 @@ The following resources may be helpful for those wanting to learn more about the
 
 The following features and improvements are among those planned for ShenRuby as it approaches its 1.0 release:
 
-- Ability to call Ruby methods directly from Shen
 - Support for command-line Shen scripts that under ShenRuby
 - Support for Rubinius
 - Thread-safe `ShenRuby::Shen` instances

data/lib/shen_ruby/rb.shen

@@ -0,0 +1,139 @@
+\\ Ruby Interoperability
+\\
+\\ The rb package provides interoperability with the host Ruby
+\\ environment.
+
+(package rb []
+
+\\\\ Parsing of rb.<const-or-method> symbols
+
+(defcc <ruby-extension>
+  <rb-dot> "#" <const-name> "." <method-name>
+    := [class-method <const-name> <method-name>];
+  <rb-dot> "#" <const-name> := [constant <const-name>];
+  <rb-dot> "#" <method-name> := [class-method "Kernel" <method-name>];
+  <rb-dot> <method-name> := [instance-method <method-name>];)
+
+(defcc <rb-dot> "r" "b" "." := skip;)
+
+(defcc <const-name>
+  <const-segment> "#" <const-name> := (@s <const-segment> "::" <const-name>);
+  <const-segment> := <const-segment>;)
+
+(defcc <const-segment>
+  Cap <const-segment-tail> := (cn Cap <const-segment-tail>)
+                              where (capital? Cap);)
+
+(defcc <const-segment-tail>
+  <char> <const-segment-tail> := (cn <char> <const-segment-tail>);
+  <e> := "";)
+
+(defcc <method-name>
+  "-" ">" := "[]=";
+  "<" "-" := "[]";
+  <char> <method-name> := (cn <char> <method-name>);
+  <char> := <char>;)
+
+(defcc <char>
+  C := C where (not (or (= C ".") (= C "#"))))
+
+(define capital?
+  S -> (element? S [($ ABCDEFGHIJKLMNOPQRSTUVWXYZ)]))
+
+\\\\ Parsing of method argument lists
+
+(defcc <method-invocation>
+  Receiver Method <normal-args> <block-args> :=
+    [rb-send-block Receiver Method | (append <block-args> <normal-args>)];
+  Receiver Method <normal-args> :=
+    [rb-send Receiver Method | <normal-args>];)
+
+(defcc <normal-args>
+  <kv-pairs> := [(make-hash-constructor <kv-pairs>)];
+  <arg> <normal-args> := [<arg> | <normal-args>];
+  <e> := [];)
+
+(defcc <kv-pairs>
+  <key> <arrow> <val> <kv-pairs> := [[<key> <val>] | <kv-pairs>];
+  <key> <arrow> <val> := [[<key> <val>]];)
+
+(defcc <key>
+  <arg> := <arg>;)
+
+(defcc <arrow>
+  Arrow := Arrow where (= Arrow (intern "=>"));)
+
+(defcc <val>
+  <arg> := <arg>;)
+
+(defcc <arg>
+  Sym := Sym where (not (or (= Sym (intern "=>"))
+                            (and (symbol? Sym)
+                                 (= (hdstr (str Sym)) "&"))));)
+
+(defcc <block-args>
+  <arity-marker> Expr := [<arity-marker> Expr];)
+
+(defcc <arity-marker>
+  X := 1 where (= X (intern "&"));
+  X := 0 where (= X (intern "&0"));
+  X := 1 where (= X (intern "&1"));
+  X := 2 where (= X (intern "&2"));
+  X := 3 where (= X (intern "&3"));
+  X := 4 where (= X (intern "&4"));
+  X := 5 where (= X (intern "&5"));)
+
+(define make-hash-constructor
+  Pairs -> (let Temp (gensym (protect Hash))
+             [let Temp [rb-send [rb-const "Hash"] "new"]
+               [do | (make-hash-load-exprs Pairs Temp)]]))
+
+(define make-hash-load-exprs
+  [] Hash -> [Hash]
+  [[Key Val] | Pairs] Hash -> [[rb-send Hash "[]=" Key Val] |
+                               (make-hash-load-exprs Pairs Hash)])
+
+\\\\ The macros that make the magic
+
+(define parse-ruby-extension
+  RbExt -> (trap-error (compile <ruby-extension> (explode RbExt))
+                       (/. _ (error
+                              (make-string "Invalid Ruby reference: ~A"
+                                           RbExt)))))
+
+(define compile-method-invocation
+  Receiver Method Args ->
+    (trap-error (compile <method-invocation> [Receiver Method | Args])
+                (/. _ (error
+                       (make-string
+                        "Invalid argument syntax for Ruby method '~A': ~A"
+                        Method Args)))))
+
+(define expand-method-invocation
+  [instance-method Method] [] ->
+    (error (make-string "Ruby instance method '~A' has no receiver"
+                        Method))
+  [instance-method Method] [Receiver | Args] ->
+    (compile-method-invocation Receiver Method Args)
+  [class-method Class Method] Args ->
+    (compile-method-invocation [rb-const Class] Method Args))
+
+(define expand-constant-reference
+  [constant Const] -> [rb-const Const]
+  \\ Bail out and give the instance method rules a shot
+  _ -> (fail))
+
+\\ This function is extremely performance critical because it is used in
+\\ the guard expressions of the macro below.
+(define ruby-extension?
+  RbExt -> (and (rb-send RbExt "instance_of?" (rb-const "Symbol"))
+                (rb-send (rb-send RbExt "to_s") "start_with?" "rb.")))
+
+(defmacro desugar-ruby-extensions
+  [Method | Args] -> (expand-method-invocation (parse-ruby-extension Method)
+                                               Args)
+                     where (ruby-extension? Method)
+  Const <- (expand-constant-reference (parse-ruby-extension Const))
+           where (ruby-extension? Const))
+
+)

data/lib/shen_ruby/shen_ruby.shen

@@ -0,0 +1,26 @@
+(package shen-ruby [rb-to-l rb-to-v]
+
+\\ Convert a Ruby Enumerable to a Shen vector
+(define rb-to-l
+  Enum -> (reverse (rb.reduce Enum [] &2 (/. L X (cons X L))))
+          where (rb.kind_of? Enum rb.#Enumerable)
+  X -> (error (make-string "'~A' is not a Ruby Enumerable" X)))
+
+(systemf rb-to-l)
+
+\\ Convert a Ruby Enumerable to a Shen vector
+(define rb-to-v
+  Enum -> (let Array (rb.to_a Enum)
+               Size (rb.size Array)
+               Vector (vector Size)
+               (rb-to-v-helper Array Vector Size))
+  X -> (error (make-string "'~A' is not a Ruby Enumerable" X)))
+
+(systemf rb-to-v)
+
+(define rb-to-v-helper
+  A V 0 -> V
+  A V Index -> (do (vector-> V Index (rb.<- A (- Index 1)))
+                   (rb-to-v-helper A V (- Index 1))))
+
+)

data/lib/shen_ruby/version.rb

@@ -1,3 +1,3 @@
 module ShenRuby
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/shen/lib/shen_ruby/shen.rb

@@ -125,7 +125,7 @@ module ShenRuby
       # Load the rest of the K Lambda files
       %w(sequent yacc
          reader prolog track load writer
-         macros declarations t-star types
+         macros declarations types t-star
         ).each do |kl_filename|
         ::ShenRuby::Shen.load_file(self, ::File.join(kl_root, kl_filename + ".kl"))
       end
@@ -134,6 +134,16 @@ module ShenRuby
       declare :quit, cons(:"-->", cons(:unit, nil))
       declare :eval_string, cons(:string, cons(:"-->", cons(:unit, nil)))
       declare :"eval-string", cons(:string, cons(:"-->", cons(:unit, nil)))
+
+      systemf :"rb-const"
+      systemf :"rb-send"
+      systemf :"rb-send-block"
+
+      old_hush = value(:"*hush*")
+      set :"*hush*", true
+      load ::File.expand_path('../../../../lib/shen_ruby/rb.shen', __FILE__)
+      load ::File.expand_path('../../../../lib/shen_ruby/shen_ruby.shen', __FILE__)
+      set :"*hush*", old_hush
     end
 
     class << self

data/shen-ruby.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version     = ">= 1.9.3"
 
-  s.add_runtime_dependency 'klam', '0.0.2', '0.0.2'
+  s.add_runtime_dependency 'klam', '0.0.5', '0.0.5'
 
   s.add_development_dependency 'rake', '~> 10.4.2', '>= 10.4.2'
   s.add_development_dependency 'rspec', '~> 3.1', '>= 3.1.0'

data/spec/shen_ruby/converters_spec.rb

@@ -1,18 +1,6 @@
 require 'spec_helper'
 
-describe 'Ruby <-> Shen type converters' do
-  before :all do
-    @shen = ShenRuby::Shen.new
-  end
-
-  def eval_shen(str)
-    @shen.eval_string(str)
-  end
-
-  def expect_shen(str)
-    expect(eval_shen(str))
-  end
-
+describe 'Ruby <-> Shen type converters', :type => :functional do
   describe 'ShenRuby.array_to_list' do
     it 'returns a Shen list containing the elements of the array' do
       @shen.set(:"test-list", ShenRuby.array_to_list([1, 2, 3]))

data/spec/shen_ruby/interop_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe 'Shen -> Ruby interop', :type => :functional do
+  describe 'dereferencing constants' do
+    it 'supports classes' do
+      expect_shen('rb.#String').to eq(String)
+    end
+
+    it 'supports modules' do
+      expect_shen('rb.#Math').to eq(Math)
+    end
+
+    it 'supports constants' do
+      expect_shen('rb.#RUBY_VERSION').to eq(RUBY_VERSION)
+    end
+
+    it 'supports nested lookup' do
+      expect_shen('rb.#Math#PI').to eq(Math::PI)
+    end
+  end
+
+  describe 'method invocation' do
+    describe 'instance methods' do
+      it 'invokes the named method on an object' do
+        expect_shen('(rb.reverse "abc")').to eq("cba")
+      end
+
+      it 'passes additional arguments to the method' do
+        expect_shen('(rb.prepend "bar" "foo")').to eq("foobar")
+      end
+
+      it 'supports [] and []= via rb.<- and rb.->' do
+        expect_shen(<<-EOSHEN).to eq('ruby')
+          (let Hash (rb.new rb.#Hash)
+            (do (rb.-> Hash "hello" "ruby")
+                (rb.<- Hash "hello")))
+        EOSHEN
+      end
+
+      it 'provides sugar for hash parameters in final position' do
+        expect_shen(<<-EOSHEN).to eq('hello ruby')
+          (let Hash (rb.<- rb.#Hash key1 => "hello" key2 =>"ruby")
+            (@s (rb.<- Hash key1) " " (rb.<- Hash key2)))
+        EOSHEN
+      end
+    end
+
+    describe 'class method invocation' do
+      it 'is supported by a sugared syntax' do
+        expect_shen('(rb.#Math.sqrt 4)').to eq(2)
+      end
+    end
+
+    describe 'kernel method invocation' do
+      it 'is supported by a sugared syntax' do
+        expect_shen('(rb.#sprintf "%0.3f" 0.1)').to eq('0.100')
+      end
+    end
+
+    describe 'the optional block argument' do
+      it 'accepts abstractions' do
+        expect_shen('(rb.find [1 2 3] & (/. X (> X 1)))').to eq(2)
+      end
+
+      it 'accepts naked function names' do
+        expect_shen('(rb.find [1 "abc" foo] & string?)').to eq("abc")
+      end
+
+      it 'accepts wrapped function names' do
+        expect_shen('(rb.find [1 "abc" foo] & (function string?))').to eq("abc")
+      end
+
+      it 'supports arities other than 1' do
+        expect_shen('(rb.reduce [1 2 3] &2 (/. A X (+ A X)))').to eq(6)
+        expect_shen('(rb.reduce [1 2 3] &2 +)').to eq(6)
+        expect_shen('(rb.reduce [1 2 3] &2 (function +))').to eq(6)
+      end
+    end
+  end
+
+  describe "Shen's list type" do
+    it 'implements Enumerable' do
+      expect_shen('(rb.reduce [1 2 3] &2 +)').to eq(6)
+    end
+  end
+
+  describe "Shen's vector type" do
+    it 'implements Enumerable' do
+      expect_shen('(rb.reduce (@v 1 2 3 <>) &2 +)').to eq(6)
+    end
+  end
+
+  describe "Ruby Enumerable coercion" do
+    describe 'rb-to-l' do
+      it 'coerces Enumerable instances to lists' do
+        expect_shen('(= (rb-to-l (rb.to_a [1 2 3])) [1 2 3])').to be(true)
+      end
+    end
+
+    describe 'rb-to-v' do
+      it 'coerces Enumerable instances to vectors' do
+        expect_shen('(= (rb-to-v (rb.to_a [1 2 3])) (@v 1 2 3 <>))').to be(true)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1 +1,19 @@
 require 'shen_ruby'
+
+module EvalShen
+  def eval_shen(str)
+    @shen.eval_string(str)
+  end
+
+  def expect_shen(str)
+    expect(eval_shen(str))
+  end
+end
+
+RSpec.configure do |cfg|
+  # Support eval_kl and friends in functional specs
+  cfg.include EvalShen, :type => :functional
+  cfg.before(:all, :type => :functional) do
+    @shen = ShenRuby::Shen.new
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shen-ruby
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Greg Spurrier
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-15 00:00:00.000000000 Z
+date: 2015-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: klam
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.2
+        version: 0.0.5
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +86,8 @@ files:
 - bin/srrepl
 - lib/shen_ruby.rb
 - lib/shen_ruby/converters.rb
+- lib/shen_ruby/rb.shen
+- lib/shen_ruby/shen_ruby.shen
 - lib/shen_ruby/version.rb
 - shen-ruby.gemspec
 - shen/README.txt
@@ -166,6 +168,7 @@ files:
 - shen/release/test_programs/whist.shen
 - shen/release/test_programs/yacc.shen
 - spec/shen_ruby/converters_spec.rb
+- spec/shen_ruby/interop_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/gregspurrier/shen-ruby
 licenses:
@@ -194,4 +197,5 @@ specification_version: 4
 summary: ShenRuby is a Ruby port of the Shen programming language
 test_files:
 - spec/shen_ruby/converters_spec.rb
+- spec/shen_ruby/interop_spec.rb
 - spec/spec_helper.rb