rlang 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2faf9d24b118829cdd2317c26e88bd720a97ccd04844469798640596284aad82
-  data.tar.gz: 2e1cd589da638a7711022e08a6f4c7070ce26e36c0dd7dcaef4520e404f12cc4
+  metadata.gz: f0e1f5809295de94b29d997b98d712156654bc60621394d0476b5fc048ee70c0
+  data.tar.gz: d35a2adf54dc40514dfa2f966b1ff9d992a11495c3c2c13f927e380be7616fda
 SHA512:
-  metadata.gz: e050812a81279acc76f15e191d40510e575e4f0dd935883b3292a3a2ca14b497b82b0d0185feccc79b4250f8e510c73c4c44c788a904e3083c28a5f14a213920
-  data.tar.gz: c689cfb6e10ec680592629f7e4c71ec44d4abd1b4e8723284633676765d189e29d5c8dd3c81ee71bcfd02597173798550b87b9ec0a7d15623a7bc53c0493eeca
+  metadata.gz: fcb55360cc77db0bf05466a419f876274f210f3af0ce66af88210f08899e9f45b473efde8657914ea8eb0c1fc32e8816e3c0849b282b22807fce7b297319e5d0
+  data.tar.gz: 9021a72e563ba1608d3fd5208929d619f4324b5274d8506e42e7a8a29d397178dd58254ba78b096fc29b0c16d4acb0ff92343e6e2e49e16c617c959298104080

data/.gitignore

@@ -9,4 +9,5 @@
 # added for rlang
 *.gem
 *~
-.rake_tasks
+.rake_tasks
+*.wasm

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.4.0
+* Object instances, instance methods and instance variables now supported
+* Test suite using parser directly
+* Code coverage is enabled in test suite
+
 ## 0.3.1
 * Add ruby parser as runtime dependency in gemspec
 * DAta directive documented in Rlang manual

data/Gemfile.lock

@@ -1,18 +1,23 @@
 PATH
   remote: .
   specs:
-    rlang (0.3.0)
+    rlang (0.4.0)
       parser
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.0)
+    docile (1.3.2)
     minitest (5.14.0)
     parser (2.7.0.2)
       ast (~> 2.4.0)
     rake (12.3.3)
     rutie (0.0.4)
+    simplecov (0.18.1)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11.0)
+    simplecov-html (0.11.0)
     wasmer (0.3.0)
       rutie (~> 0.0.3)
 
@@ -24,6 +29,7 @@ DEPENDENCIES
   minitest (~> 5.0)
   rake (~> 12.0)
   rlang!
+  simplecov (~> 0.18)
   wasmer (~> 0.3)
 
 BUNDLED WITH

data/README.md

@@ -23,11 +23,31 @@ $ gem install rlang
 Alternatively, if you clone this git repo and play with the Rlang source code you can generate your own local gem and install it like this:
 
 ```
+$ bundle install
 $ gem build rlang.gemspec
 $ gem install --local rlang-x.y.z.gem
 ```
 
-To check that the installation went well, run `rlang --help` and see if the help message displays correctly
+To check that the installation went well, run `rlang --help` and see if the help message displays correctly.
+
+## A Quick example
+An example is always worth a thousand words, so here is a quick one that'll show you how to compile some Rang code and run it from your browser. Since Chrome, Chromium, Firefox and Safari all natively embed a WebAssembly runtime it is the easiest way to test compiled Rlang code.
+
+Navigate to the Fibonacci directory in [examples/fib](https://github.com/ljulliar/rlang/blob/master/examples/fib/) and download the three files from this directory: fib.rb, index.html, server.rb. Alternatively you can git clone the repo and go directly in that directory.
+
+Open [fib.rb](https://github.com/ljulliar/rlang/blob/master/examples/fib/fib.rb) with your favorite editor and see for yourself that it really looks like Ruby code :-). Then from a shell session:
+
+```shell
+# Compile the fib.rb file to Wasm bytecode
+$ rlang --wasm -o ./fib.wasm ./fib.rb
+# Launch the mini http server
+$ ruby server.rb
+
+```
+Point your browser to [http://localhost:8080](http://localhost:8080), a simple page should display inviting you to type an integer value then click run to obtain the corresponding fibonacci term.
+
+That was easy, right ?
+
 
 ## The Rlang language
 Ruby features supported by Rlang are detailed in the [Rlang Manual](https://github.com/ljulliar/rlang/blob/master/docs/RlangManual.md)

data/bin/rlang

@@ -14,31 +14,11 @@
 require 'optparse'
 require 'fileutils'
 require 'rlang'
+require 'builder'
 
 include Log
 logger.level = Logger::INFO
 
-# WAT source frame
-WAT_FRAME = %q{
-;; Generated by Rlang compiler version %{version} on %{time}\n"
-(module %{module}
-  (memory $0 %{memory_min} %{memory_max})
-
-  ;; ======= EXPORTS =======
-  (export "memory" (memory $0))
-  %{exports}
-
-  ;; ======= GLOBAL VARIABLES =======
-  %{globals}
-
-  ;; ======= STATIC DATA =======
-  %{data}
-
-  ;; ======= CODE =======
-  %{code}
-)
-}
-
 options = {}
 OptionParser.new do |opts|
   opts.banner = %q{Usage: rlang [options] filename
@@ -59,8 +39,8 @@ options:
 }
 
   opts.on("-I DIR", "--load_path DIRECTORY", "specify $LOAD_PATH directory (may be used more than once)") do |dir|
-    options[:load_path] ||= []
-    options[:load_path] << dir
+    options[:LOAD_PATH] ||= []
+    options[:LOAD_PATH] << dir
   end
 
   opts.on("-M", "--module NAME", "WASM module name") do |name|
@@ -92,8 +72,8 @@ options:
   end
 
   opts.on("-v", "--verbose [LEVEL]", "Verbosity level (fatal, error, warn, info, debug)") do |level|
-    options[:level] = level || 'INFO'
-    logger.level = Kernel.const_get("Logger::#{options[:level].upcase}")
+    options[:log_level] = level || 'INFO'
+    logger.level = Kernel.const_get("Logger::#{options[:log_level].upcase}")
   end
 
   opts.on("-V", "--version", "Displays Rlang version") do |v|
@@ -109,7 +89,7 @@ end.parse!(ARGV)
 
 options[:module] ||= ''
 options[:memory_min] ||= 4
-options[:load_path] ||= []
+options[:LOAD_PATH] ||= []
 
 fh_out = options[:output] ? File.open(options[:output], 'w') : STDOUT
 
@@ -124,38 +104,23 @@ if options[:ast]
 end
 
 if options[:wat] || options[:wasm]
-  parser = Rlang::Parser::Parser.new(nil)
-  parser.config[:LOAD_PATH] = options[:load_path]
-  parser.config[:__FILE__] = File.expand_path(ARGV[0])
-  parser.config[:export_all] = options[:export_all]
-  wg = Rlang::Parser::WGenerator.new(parser)
-  parser.wgenerator = wg
-  parser.parse_file(File.expand_path(ARGV[0]))
-
-  # Write generated WAT code in a temp file
-  # Do not delete temp file when closing
-  tf = Tempfile.new([File.basename(ARGV[0]), '.wat'])
-  tf.persist!
-  tf << WAT_FRAME % {version: Rlang::VERSION,
-                     time: Time.now,
-                     module: options[:module], 
-                     memory_min: options[:memory_min],
-                     memory_max: options[:memory_max],
-                     exports: Rlang::Parser::Export.transpile,
-                     globals: Rlang::Parser::Global.transpile,
-                     data: Rlang::Parser::DAta.transpile,
-                     code: wg.root.transpile
-                    }
-  tf.close
-
+  # Compile the Rlang file into a WAT file
+  source = File.expand_path(ARGV[0])
+  compiler = Builder::Rlang::Compiler.new(source, nil, options)
+  if compiler.compile
+    wat_path = compiler.target
+  else
+    exit 1
+  end
+  # Compile the WAt file to Wasm byte code
   if options[:wasm]
-    builder = Builder::Wat::Builder.new(tf.path, options[:output], options[:load_path])
+    builder = Builder::Wat::Builder.new(wat_path, options[:output])
     builder.compile
   elsif options[:wat]
     if options[:output]
-      FileUtils.mv(tf.path, options[:output])
+      FileUtils.mv(wat_path, options[:output])
     else
-      STDOUT.write(File.read(tf.path))
+      STDOUT.write(File.read(wat_path))
     end
   end
 end

data/docs/RlangManual.md

@@ -8,15 +8,13 @@ Still, to make this Ruby to WebAssembly compilation possible a number of trade-o
 
 ## The Rlang object model
 
-In Rlang you can define classes and those classes can be instantiated but *only* statically not dynamically. Supporting dynamic object allocation would more or less mean that Rlang becomes a Ruby virtual machine and this is not the intent. What the intent is with Rlang is to provide you with a language that can assist you in developing such a Virtual Machine for instance ;-)
-
-One of the consequence of this for instance is that you can statically instantiate a new object in the body of a class not in a method. In other words objects can be instantiated at compile time not at runtime (note: this may change in a future version)
+In Rlang you can define classes and those classes can be instantiated either statically at compile time or  dynamically at runtime. There is no inheritance mechanism today between classes in the current version. Classes cannot be nested.
 
 ## What Rlang does
 
 Rlang provides:
 * Classes, class attributes and class variables
-* Object instantiation (only at compile time)
+* Object instantiation, attribute accessors and instance variables
 * Method definition and method calls
 * Integers and booleans 
 * Constants
@@ -48,9 +46,9 @@ calling that method later in your code is as simple as invoking `Math.fib(20)`
 ## Classes
 Classes are core constructs of Rlang and are very similar to Ruby classes.
 
-Within a class you define methods and class variables. Actually all methods must be defined within a class. In other words you can not define a method at the top level of your Rlang code (not a very good practice anyway, even in plain Ruby). Also there is no inheritance mechanism in Rlang in the current version.
+In Rlang, all methods must be defined within the scope of a class. In other words you can not define a method at the top level of your Rlang code (not a very good practice anyway, even in plain Ruby). Also there is no inheritance mechanism in Rlang in the current version.
 
-Here is an example of a class definition and the initialization and use of a class variable written in Rlang:
+Here is an example of a class definition and the initialization and use of a class variable written in Rlang (note: this example uses only class methods on purpose. Instance methods are covered later in this document):
 
 ```ruby
 class MyClass
@@ -68,18 +66,16 @@ end
 ```
 
 This short piece of code shows several interesting points:
-1. A class variable can be statically initialized at the class level. Concretely this means that at compile time the memory location corresponding to the `@@cvar` class variable initially receives the value 100.
+1. A class variable can be statically initialized at the class level. Concretely this means that at compile time the memory location corresponding to the `@@cvar` class variable is statically initialized at 100.
 1. Methods in this example are class methods, hence the use of `self.take_one` and `self.refill` in method definitions but instance methods are also supported (more on this later)
 1. In `MyClass::take_one` you can see that Rlang also supports convenient syntactic sugar like `if` as a modifier or combined operation and assignment as in Ruby (here the `-=` operator)
 
-### Class attributes
-Since objects cannot be instantiated at runtime in Rlang, there is no such thing as instance variable. Rlang uses a special directive `wattr` to do 4 things at once: 
-1. Define the attributes of a class (see that as its instance variables somehow)
-2. Define the type of the attributes (remember, Rlang is a compiler...)
-2. Define the corresponding accessors both getter and setter (like `attr_accessor` does in Ruby)
-3. Compute the memory footprint needed when objects of this class are instantiated.
+### Class attributes and instance variables
+Rlang support both the use of class attributes and instance variables. Class attribute declaration is happening through the `wattr` directive. I actually defines a couple of things for you:
+1. Define the corresponding accessors both getter and setter (like `attr_accessor` does in Ruby)
+2. Define the corresponding instance variable
 
-That's a lot with a single statement and it makes your code easy to read. Here is an example
+Here is an example showing the definition of a single attribute
 ```ruby
 class Square
   wattr :side
@@ -102,7 +98,7 @@ class Test
 end
 ```
 
-The code is pretty straightforward: a new square instance is created, its side is set to 10 and as you would expect the call to the Square#area method would return 100.
+The code is pretty straightforward: a new square instance is created (here it is created statically at compile time), its side attribute is set to 10 and, as you would expect, the call to the Square#area method returns 100.
 
 ### Class attribute type
 In the example above the `side` attribute is implicitely using the `:I32` (long integer) WebAssembly type. It's the default Rlang type. Assuming you want to manage big squares, you'd have to use `:I64` (double integer) like this for the `side` attribute and also instruct Rlang that the return value of area is also `:I64` (more on this later).
@@ -120,19 +116,55 @@ end
 ```
 
 ## Object instantiation
-In the current version of Rlang objects can only be instantiated at compile time not at runtime. As a result of this, all object instantiation must happen in the body of a class not in the body of a method. You have already seen an example of such an object instantiation in the previous example with `Square.new` being instantiated and stored in the class variable `@@cvar`.
+Starting with version 0.4.0, Rlang is equipped with a dynamic memory allocator (see [Rlang library](#the-rlang-library) section). It is therefore capable of allocating objects in a dynamic way at *runtime*. Prior versions were only capable of allocating objects statically at *compile* time.
+
+### Static objects
+You have already seen how to perform static objects allocation in one of our previous example. A statement like `@@square = Square.new` appearing in the body of a class definition result in a portion of the WebAssembly memory being statically allocated and initialized at compile time by Rlang and the `@@square` variable points to that particular memory location. Similarly you can also statically instantiate and store an object in a global variable or in a constant like this:
+
+```ruby
+SQUARE = Square.new
+$SQUARE = Square.new
+```
+
+### Dynamic objects
+At any point in the body of method you can dynamically instantiate a new object. Here is an exemple:
+
+```ruby
+class Cube
+  wattr :x, :y, :z
+
+  def initialize(x, y, z)
+   @x = x; @y = y; @z = z
+  end
 
-Similarly you can also instantiate and store an object in a global variable.
+  def volume
+    @x * @y * @z
+  end
+end
+
+class Main
+  def self.run
+    cube = Cube.new(10, 20, 30)
+    v = cube.volume # would be 6000
+    # ... Do what eveer you have to do...
+    Object.free(cube)
+  end
+end
+```
+In this example the `Cube` method uses 3 instance variables `@x, @y, @z`. Those instance variables can be accessed through the usual attribute accessors like `Cube#x` and `Cube#x=`. In your code you can also use the `_size_` class method to know how much bytes an object consumes in meory. Here a call to `Cube._size_` would return 12 as each instance variable is an `I32` using 4 bytes each.
+
+### (Lack of) Garbage collection
+In its current version, Rlang doesn't come with a garbage collector. So all dynamically allocated objects must be eventually free'd explicitely using the `Object.free` method in your code when objects are no longer needed.
 
 ## Methods
-Methods in Rlang are defined as you would normally do in Ruby by using. They can be either class or instance methods.
+Methods in Rlang are defined as you would normally do in Ruby by using the `def` reserved keyword. They can be either class or instance methods.
 
 ### Method arguments
 Rlang method definition supports fixed name arguments in any number. The  *args and **args notation are not supported.
 
 By default all arguments in Rlang are considered as being type `:I32` (a 32 bit integer). See the Type section below for more details. If your argument is of a different type you **must** explicitely state it. 
 ```ruby
-def self.m_two_args(arg1, arg2, arg3)
+def m_three_args(arg1, arg2, arg3)
   arg arg1: :Square, arg2: :I64
   # your code here...
 end
@@ -151,18 +183,18 @@ def self.m_no_return_value(arg1, arg2)
   return
 end
 ```
-Similarly you can use `return :I64` if your method is to return a double integer value or `return :Square` if you method returns an object.
+Similarly you can use `result :I64` if your method is to return a double integer value or `return :Square` if you method returns an object.
 
-With a few exceptions (see the Conditional and Iteration Structures sections below), each Rlang statements evaluate to a value. In the absence of an explicit `return some_expression` statement, a method returns the value of the last evaluated statement. In the example above the method `MyClass::take_one` returns the value of `@@cvar` after decreasing it by one and `MyClass::refill` returns 100.
+With a few exceptions (see the Conditional and Iteration Structures sections below), each Rlang statements evaluate to a value. In the absence of an explicit `return` statement, a method returns the value of the last evaluated statement. In the example above defining the `MyClass` class, the method `MyClass.take_one` returns the value of `@@cvar` after decreasing it by one and `MyClass.refill` returns 100.
 
-Rlang also gives you the ability to declare the return type of a method like this 
+Rlang also gives you the ability to declare the return type of a method like this anywhere in your code.
 ```ruby
-result :class_name, :method_name, :wasm_type
+result :class_name, :method_name, :your_type_here
 ```
 
-This result directive must be used to instruct the compiler about the return type of a method if it has not seen it yet (e.g. the method definition is coming later in your source code). But keep in mind that this is only needed if the method returns something different than the default type (`:I32`).
+This result directive must be used to instruct the compiler about the return type of a method if it has not seen it yet (e.g. the method definition is coming later in your source code) or when calling a method from another class defined in a different file not yet compiled. But keep in mind that this is only needed if the method returns something different than the default type (`:I32`).
 
-If `:method_name` symbol starts with a `#` it refers to an instance method. Without it it refers to a class method.
+Note: in this directive `:method_name` symbol starts with a `#` characters if it refers to an instance method. Without it it refers to a class method.
 
 For an example see the [test_def_result_type_declaration.rb](https://github.com/ljulliar/rlang/blob/master/test/rlang_test_files/test_def_result_type_declaration.rb), a Rlang file that is part of the Rlang test suite.
 
@@ -410,8 +442,14 @@ Rlang comes with a library that provides a number of pre-defined classes and met
 require 'rlang/lib'
 ```
 
-For now, the Rlang library is very modest and only contains basic WebAssembly memory management functions like `Memory::size` and `Memory::grow` to mirror the WebAssembly functions of the same name.
+For now, the Rlang library is very modest and containoffers the following classes and methods
+
+* **Memory** class: provides Rlang methods like `Memory::size` and `Memory::grow` mapping directly to the WebAssembly functions of the same name (see WebAssembly specficiations)
+* **Malloc** class: provides a dynamic memory manager. It is used by Rlang to instantiate new objects but you can also use it in your own code if need be.
+  * Malloc.malloc(nbytes) : dynamically allocates nbytes of memory and return address of the allocated memory space or -1 if it fails
+  * Malloc.free(address) : frees the block of memory at the given address
+* **Object** class: provides a couple of object management method. Use `Object.free` to free an object.
 
-A basic dynamic memory allocator is also provided. It is shamelessly adapted from example provided in the famous Kernigan & Richie C book. Take a look at the [C version](https://github.com/ljulliar/rlang/blob/master/lib/rlang/lib/malloc.c) and see how easy it is to adapt  [Malloc in Rlang](https://github.com/ljulliar/rlang/blob/master/lib/rlang/lib/malloc.rb).
+As a side note, the dynamic memory allocator provided with Rlang is quite simple. It is shamelessly adapted from example provided in the famous Kernigan & Richie C book 2nd edition. Take a look at the [C version](https://github.com/ljulliar/rlang/blob/master/lib/rlang/lib/malloc.c) and see how easy it is to rewrite it in [Rlang](https://github.com/ljulliar/rlang/blob/master/lib/rlang/lib/malloc.rb).
 
 That's it! Enjoy Rlang and, as always, feedback and contributions are welcome.

data/examples/fib/fib.rb

@@ -0,0 +1,11 @@
+class Math
+  export
+  def self.fib(n)
+    if n <= 1
+      f = n
+    else
+      f = self.fib(n-1) + self.fib(n-2)
+    end
+    return f
+  end
+end

data/examples/fib/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+
+<html>
+<head>
+  <script>
+    var importObject = {
+      host: {
+        print: function(arg) {
+          console.log(arg);
+        }
+      }
+    };
+    // Load the module using the newest Streaming API
+    WebAssembly.instantiateStreaming(fetch('/fib.wasm'), importObject)
+    .then(obj => {
+        // Add a listener to the button to execute the 
+        // Wasm function when the button is pressed.
+        var button = document.getElementById('run');
+        button.addEventListener('click', function() {
+          var n = +document.getElementById('n').value;
+          console.log(n);
+          var fib_n = obj.instance.exports.math_c_fib(n);
+          console.log(fib_n);
+          document.getElementById('fib_n').innerHTML = fib_n;
+        }, false);
+      }
+    );
+  </script>
+</head>
+<body>
+  <h1>Rlang test</h1>
+
+  <p>Fibonacci terms</p>
+  n = <input type="text" size=6 id="n" value=16>
+  <input type="button" id="run" value="Run"/>
+  <p id="fib_n">-</p>
+</body>
+</html>

data/examples/fib/server.rb

@@ -0,0 +1,16 @@
+require 'rack'
+
+Rack::Mime::MIME_TYPES.merge!({
+  ".wasm"     => "application/wasm",
+})
+
+builder = Rack::Builder.new do
+  map "/" do
+    use Rack::Static, urls: [""],
+                      root: File.expand_path('./'),
+                      index: 'index.html'
+    run lambda {}
+  end
+end
+
+Rack::Handler::WEBrick.run builder

data/lib/builder/rlang.rb

@@ -1,2 +1,2 @@
-
+require_relative 'rlang/compiler'
 require_relative 'rlang/builder'

data/lib/builder/rlang/builder.rb

@@ -1,8 +1,15 @@
 # Rubinius WebAssembly VM
 # Copyright (c) 2019, Laurent Julliard and contributors
 # All rights reserved.
+#
+# Turns an Rlang source file into a Wasm file
+# either by executing the rlang command or by
+# running the parser/compiler from within this
+# class
 
 require_relative '../ext/tempfile'
+require_relative '../wat'
+require_relative './compiler'
 
 module Builder::Rlang
   class Builder
@@ -11,21 +18,46 @@ module Builder::Rlang
     RLANG = File.expand_path('../../../../bin/rlang', __FILE__)
 
     attr_reader :source, :target, :wat_path
+    attr_accessor :use_rlang_command
 
-    def initialize
-      @wat_path = nil
-      @target = nil
-    end
-
-    def compile(source, target, options='')
-      @source = source # Path to Rlang file
+    # source: Path to Rlang file (.rb)
+    # target: Path to Wasm file (.wasm)
+    # options: Rlang parser options (parser.config)
+    #
+    # options is either a string when using rlang compiler
+    # or a hash of parser options when using the parser
+    def initialize(source, target, options=nil)
+      @source = source
       @target = target
       @options = options
-      system("ruby -I#{LIB_DIR} -- #{RLANG} #{@options} --wasm -o #{target} #{@source}")
+      @use_rlang_command = false
+    end
+
+    def use_rlang_command!
+      @use_rlang_command = true
+    end
+
+    # return true if everything went well, false otherwise
+    def compile
+      if @use_rlang_command
+        system("ruby -I#{LIB_DIR} -- #{RLANG} #{@options || ''} --wasm -o #{target} #{@source}")
+      else
+        # Compile the Rlang file into a WAT file
+        @compiler = Compiler.new(@source, nil, @options)
+        if @compiler.compile
+          tf_path = @compiler.target
+        else
+          return false
+        end
+        # turn the WAT file into Web Assembly code
+        wat_builder = ::Builder::Wat::Builder.new(tf_path, @target)
+        @target ||= wat_builder.target
+        return wat_builder.compile
+      end
     end
 
     def cleanup
-      File.unlink(@target) if @target
+      @compiler.cleanup
     end
   end
 end