rlang 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7fd26f4ab304200f0319e23e1e8529e538ea058a58fe4571e0e3525c2c5ce14
-  data.tar.gz: 88bb4ec22b5a2571944693da8ea21d0e1379fb41b3c9ae85d91851a2f8569d9b
+  metadata.gz: 38b11b7ed747a6a72f0a46a2c498efef419039a9bf85b5ba6442b7fd8f5300fc
+  data.tar.gz: 2e1c220542d7b7356c6b963edb2d34e45cdbd0cd556dec6a718a4f663b5651b5
 SHA512:
-  metadata.gz: f6c92dcfec61a4df573d2c911882f346fb242315596220e25aa547998f137b8578f18ca62467c77af2b75e92ea73d87a21cbc37eae1bd56e89038bc62fca2264
-  data.tar.gz: b9e09724905b3175904258174c834b8d52b9f7ae99c7046e81e13f97e699d94b53f110b70763283992e71c7d6a2f3d0eb9d9cba60a30a1ef319338f1ec580919
+  metadata.gz: 71fc2a6a83c414edbc2dbfca1b1e465a1d265ba80350101e4536178e1959ccf4a823478c7c139acde6d3e88d56d25d0a2fd9d4a781b2c1da919b4de0f5a4268a
+  data.tar.gz: 65969682077beb48030e5f9ffff0f1d97aa2ee2ea48e2142feac74e3a687661aa5b7afcbb8db26b8b1da8936e7dbeca4d09e9a8be5108dda8dd6325fb15a3c99

data/CHANGELOG.md

@@ -1,9 +1,12 @@
+## 0.5.1
+* Imported WASM methods can now be defined
+* Preliminary version of WASI interface and IO class added to Rlang library
+
 ## 0.5.0
-* Class attributes syntac now identical to plain Ruby
-* Very preliminary version of Rlang String class
+* Class attributes syntax now identical to plain Ruby
 * Class in class definition and module supported
 * Class inheritance
-* Basic array class
+* Basic Array and String class in Rlang library
 
 ## 0.4.0
 * Object instances, instance methods and instance variables now supported

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rlang (0.5.0)
+    rlang (0.5.1)
       parser
 
 GEM

data/README.md

@@ -1,4 +1,4 @@
-# Rlang : a native Ruby to WebAssembly compiler
+# Rlang : a Ruby-like language compiled to WebAssembly
 
 Rlang is meant to generate fast and uncluttered [WebAssembly](https://webassembly.org) code from the comfort of the Ruby language.
 
@@ -6,14 +6,12 @@ Rlang is actually two things: 1) a subset of the Ruby language and 2) a **compil
 
 So in summary what Rlang does is:
 <p align="center"><b>
-Ruby source code &rarr; Rlang compiler &rarr; WebAssembly bytecode
+Rlang source code &rarr; Rlang compiler &rarr; WebAssembly bytecode
 </b></p>
 
-Rlang must not be confused with other projects claiming to "compile" Ruby to WebAssembly. What they really do is to actually compile a mruby VM written in C in Webassembly (using tools like emscripten) and then run that VM in a Webassembly runtime.
-
 Rlang can be seen as a foundational language that can help you quickly develop and debug high performance WebAssembly modules. For the rationale behind the creation of Rlang see [below](#why-rlang).
 
-This is still a young project but Rlang has already been successfully tested with some real code such as the dynamic memory allocator provided with the Rlang library. It will keep mproving over time, always with the goal of generating crisp and uncluttered WebAssembly code.
+This is still a young project but Rlang has already been successfully tested with some real code such as the dynamic memory allocator provided with the Rlang library. It will keep improving over time, always with the goal of generating crisp and uncluttered WebAssembly code.
 
 If you want to help with Rlang see [How you can help](#how-you-can-help).
 
@@ -22,6 +20,8 @@ If you want to help with Rlang see [How you can help](#how-you-can-help).
 * **WABT toolkit**: the rlang compiler can generate both WebAssembly source code (WAT file) and WebAssembly bytecode (WASM file). To generate WASM bytecode the rlang compiler uses wat2wasm. This utility is part of the [WABT toolkit](https://github.com/WebAssembly/wabt)
 * **wasmer runtime** (optional): [Wasmer](https://wasmer.io/) is a fast WebAssembly runtime. You'll need it if you want to run the test suite from the source repo. You can also use it to run the compiled WASM code generated by the rlang compiler. You can get Wasmer at  [wasmer.io](https://wasmer.io/)
 
+Rlang has also been successfully tested with the [Wasmtime](https://wasmtime.dev/) WebAssembly runtime.
+
 
 ## Installing Rlang
 Rlang is available as a gem from rubygems.org. So simply run the following command to install it:
@@ -78,7 +78,9 @@ This project was created out of the need to develop a Virtual Machine written in
 
 After a first proof of concept written directly by hand in WebAssembly (WAT source code) it became clear that writing a full fledged VM directly in WebAssembly was going to be tedious, complex and unnecessarily painful.
 
-Sure I could have written this VM in any of the language that can already be compiled directly to WebAssembly (C, C++, Rust, Go,...) but being fond of Ruby since 2000 I decided that I would go for a compiler capable of transforming a subset of the Ruby language directly into WebAssembly with a minimum overhead. So in a nutshell: the goal of Rlang is to let you develop efficient WebAssembly code with a reasonably high level of abstraction while keeping the generated WebAssembly code straightforward and human readable.
+Sure I could have written this VM in any of the language that can already be compiled directly to WebAssembly (C, C++, Rust, Go,...) but being fond of Ruby since 2000 I decided that I would go for a compiler capable of transforming a subset of the Ruby language directly into WebAssembly with a minimum overhead.
+
+So in a nutshell: the goal of Rlang is to let you develop efficient WebAssembly code with a reasonably high level of abstraction while keeping the generated WebAssembly code straightforward,  human readable and slim.
 
 ## Why the name Rlang?
 Yes I hear you: Rlang is already the name of the R language so why use that name and aren't you introducing some confusion? Well for one I couldn't resist using that name to honor software engineering history (see below) and because, after all, the intersection between the Ruby/WebAssembly community and the R language community focused on data processing and machine learning must be quite small to say the least.

data/bin/rlang

@@ -13,13 +13,16 @@
 
 require 'optparse'
 require 'fileutils'
-require 'rlang'
+require 'rlang' # setup RLANG_BASE_DIR
 require 'builder'
 
+RLANG_LIB_DIR = File.expand_path('./rlang/lib', RLANG_BASE_DIR)
+
 include Log
 logger.level = Logger::INFO
 
 options = {}
+custom_load_path = []
 OptionParser.new do |opts|
   opts.banner = %q{Usage: rlang [options] filename
   read a Rlang file, check it for errors, and convert it
@@ -39,8 +42,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
+    custom_load_path ||= []
+    custom_load_path << dir
   end
 
   opts.on("-M", "--module NAME", "WASM module name") do |name|
@@ -67,6 +70,10 @@ options:
     options[:wasm] = v
   end
 
+  opts.on("-S", "--start FUNCTION", "Function name where execution starts (default '_start')") do |function|
+    options[:start] = function
+  end
+
   opts.on("-o", "--output FILE", "Write output to file") do |file|
     options[:output] = file
   end
@@ -87,9 +94,10 @@ options:
   end
 end.parse!(ARGV)
 
-options[:module] ||= ''
+options[:module]     ||= '' 
 options[:memory_min] ||= 4
-options[:LOAD_PATH] ||= []
+options[:LOAD_PATH]  = custom_load_path << RLANG_LIB_DIR
+options[:start]      ||= '_start'
 
 fh_out = options[:output] ? File.open(options[:output], 'w') : STDOUT
 

data/docs/RlangCompiler.md

@@ -19,6 +19,7 @@ Usage: rlang [options] rlang_file.rb
     -w, --wat                        Generate WAT source file
     -a, --ast                        Generate Ruby AST file
     -s, --wasm                       Generate WASM bytecode file
+    -S, --start FUNCTION             Function name where execution starts (default '_start')
     -o, --output FILE                Write output to file
     -v, --verbose [LEVEL]            Verbosity level (fatal, error, warn, info, debug)
     -V, --version                    Displays Rlang version
@@ -30,7 +31,8 @@ Usage: rlang [options] rlang_file.rb
 * **-m, --memory MIN[,MAX]**: size of the WASM memory allocated at run time. The first argument is the initial amount of memory allocated and the second one (optional) is the maximum memory that your WASM module can allocate while running. The unit of both arguments is in number of WASM pages (4 KBytes)
 * **-w, --wat**: parse Rlang file and generate WAT source code
 * **-a, --ast**: parse Rlang file and generate the Ruby abstract syntax tree
-* **-w, --wat**: parse Rlang file, generate WAT source code and compile it to WASM bytecode
+* **-s, --wasm**: parse Rlang file, generate WAT source code and compile it to WASM bytecode
+* **-S, --start**: function to use as the execution starting point of the WASM module (default is `_start`)
 * **-o, --output FILE**: send rlang output to FILE
 * **-v, --verbose [LEVEL]**: verbosity level (fatal, error, warn, info, debug). Default is warn
 * **-V, --version**: Displays Rlang version

data/docs/RlangManual.md

@@ -6,10 +6,6 @@ Ruby programmers will feel at home with Rlang and non Ruby programmers will find
 
 Still, to make this Ruby to WebAssembly compilation possible a number of trade-offs had to be made. The goal of this document is to explain the features of Rlang are how it differs from plain Ruby.
 
-## The Rlang object model
-
-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:
@@ -84,6 +80,12 @@ end
 ```
 A Class in RLang can also inherit from another class as in Ruby. Whan a superclass is not specified, a newly defined class automatically inherits from the Object class.
 
+If you need to use a class name in your code before the class is actually processed by the compiler you can use the following empty class notation to declare that the corresponding constant is actually a class. You can later reopen the class definition and define methods.
+
+```ruby
+class String; end
+```
+
 
 ### Class attributes and instance variables
 Rlang support both the use of class attributes and instance variables. Class attribute declaration is happening through the `attr_accessor`, `attr_reader` or `attr_writer` directives as in plain Ruby. It actually defines a couple of things for you:
@@ -147,6 +149,7 @@ class Test
   # ...
 end
 ```
+The address in memory of both class variables and constants can be accessed by using the `addr` method as in `SQUARE.addr` for instance.
 
 **IMPORTANT NOTE**: in the current version of Rlang the new method call used to allocate static objects doesn't do any initialization. That's why the new method in this context (class body or top level) doesn't accept any parameter.
 
@@ -180,7 +183,7 @@ class Main
     cube = Cube.new(10, 20, 30)
     v = cube.volume
     # ... Do what ever you have to do...
-    Object.free(cube)
+    cube.free
   end
 end
 ```
@@ -246,7 +249,9 @@ end
 The `local` directive above instructs the compiler that `lvar` is of type `:I64` and the local variable mysquare is of type `Square`. Without it `lvar` would have been auto-vivified with the Wasm default type or `:I32`.
 
 ### Exporting a method
-In WebAssembly, you can make functions visible to the outside world by declaring them in the export section. To achieve a similar result in Rlang, you can use the `export` keyword right before a method definition. 
+In WebAssembly, you can make functions visible to the outside world by declaring them in the export section. To achieve a similar result in Rlang, you can use the `export` keyword right before a method definition with an optional export name of your choice.
+
+If no function name is specified, Rlang will build it for you. WASM exported functions are named after the class name (in lower case), the method type (class or instance) and the method name. As an example the exported method in the example above will be known to the WASM runtime as the `myclass_c_visible` function (where the `_c_` means it's a class function and `_i_` an instance method).
 
 ```ruby
 class MyClass
@@ -256,18 +261,40 @@ class MyClass
     # ...
   end
 
+  export :seeable
+  def self.visible_too(arg1)
+    # ...
+  end
+
   def self.not_visible
     # ...
   end
 end
 ```
 
-Note that the `export` keyword only applies to the method definition that immediately follows. In the example above `MyClass::m_visible` will be exported by the generated WASM module whereas `MyClass::m_not_visible` will not
+Note that the `export` keyword only applies to the method definition that immediately follows. In the example above `MyClass::visible` and `MyClass::visible_too` will be exported by the generated WASM module whereas `MyClass::not_visible` will not.
+
+### Importing a method
+An import statement in WebAssembly is a way to declare the signature of a method defined outside of the current WebAssembly module and then call it from your code.
+
+Rlang has an equivalent import statement as shown in the example below:
+```ruby
+import :wasi_unstable, :proc_exit
+def self.proc_exit(exitcode)
+  arg exitcode: :I32
+  result :none
+end
+```
+
+The first 2 arguments of import are the imported module name and function name as in WebAssembly and then follows a regular method definition with arguments and possibly the `arg` directive to specify argument types and a `result` directive to indicate the nature of the returned value. Two points worth highlighting here:
+1. The Rlang method name doesn't have to be the same as the function name in the import statement.
+2. As imported function are external to your Rlang module they must be declared as class methods. This is bacause defining them as instance method would automatically pass `self` as the first argument in the method call therefore changing the signature of the method.
+
+The example above is taken from the Rlang WASI class that defines the interface with [WASI (WebAssembly System Interface)](https::wasi.dev).
 
-WASM exported functions are named after the class name (in lower case) followed by an underscore and the method name. So the exported method in the example above is known to the WASM runtime as the `myclass_c_visible` function (where the `_c_` means it's a class function and `_i_` an instance method)
 
 ## Rlang types
-The types currently supported by Rlang are integers either long (`:I32`) or double (`:I64`) or a class type. Float types (:F32, :F64) may follow in a future version. By default Rlang assumes that any integer literal, variable, argument,... is of type `:I32`. If you need it to be of a different type you must state it explicitely in the method body (see above).
+The types currently supported by Rlang are integers either long (`:I32`) or double (`:I64`) or a class type. Float types (`:F32`, `:F64`) may follow in a future version. By default Rlang assumes that any integer literal, variable, argument,... is of type `:I32`. If you need it to be of a different type you must state it explicitely in the method body (see above).
 
 ### Implicit type cast
 Only in rare cases will you use the `local` directive in methods as Rlang does its best to infer the type of a variable from its first assigned value. As an example, in the code below, the fact that `arg1` is known to be an `:I64` type of argument is enough to auto-magically create lvar as in `:I64` local variable too.

data/examples/fib/fib.rb

@@ -8,4 +8,8 @@ class Math
     end
     return f
   end
-end
+end
+
+def self.main
+  Math.fib(12)
+end

data/lib/builder/rlang/compiler.rb

@@ -17,23 +17,10 @@ module Builder::Rlang
     # 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}
+%{code}
 
-  ;; ======= GLOBAL VARIABLES =======
-  %{globals}
-
-  ;; ======= STATIC DATA =======
-  %{data}
-
-  ;; ======= CODE =======
-  %{code}
-)
-    }
+}
 
     # source: Path to Rlang file (.rb)
     # target: Path to Wat file (.wat)
@@ -64,12 +51,6 @@ module Builder::Rlang
       end
       @tf.write(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: @wgenerator.root.transpile
                         })
       @tf.close

data/lib/rlang.rb

@@ -2,3 +2,6 @@ require_relative "./rlang/version"
 require_relative "./utils/log"
 require_relative "./rlang/parser"
 require_relative "./builder"
+
+# Set up path to this file
+RLANG_BASE_DIR = File.expand_path(File.dirname(__FILE__))

data/lib/rlang/lib/array/array32.rb

@@ -5,13 +5,14 @@
 # 4 bytes object array class
 require_relative '../memory'
 require_relative '../kernel'
-require_relative '../object'
-require_relative '../string'
+#require_relative '../string'
 
 
 class Array32
   attr_reader :count, :ptr
 
+  result :Kernel, :raise, :none
+
   # count: number of elements in Array
   # Array elements are native types or
   # pointers to objects
@@ -40,4 +41,10 @@ class Array32
     value
   end
 
+  def free
+    result :none
+    Object.free(@ptr)
+    Object.free(self)
+  end
+
 end

data/lib/rlang/lib/array/array64.rb

@@ -4,7 +4,6 @@
 #
 # 4 bytes object array class
 require_relative '../memory'
-require_relative '../kernel'
 require_relative '../object'
 require_relative '../string'
 
@@ -40,4 +39,10 @@ class Array64
     value
   end
 
+  def free
+    result :none
+    Object.free(@ptr)
+    Object.free(self)
+  end
+
 end

data/lib/rlang/lib/io.rb

@@ -0,0 +1,70 @@
+# Rubinius WebAssembly VM
+# Copyright (c) 2019-2020, Laurent Julliard and contributors
+# All rights reserved.
+#
+# IO class for all basic input and output operations
+
+require_relative './wasi'
+
+class IO
+  attr_accessor :fd
+
+  @@num_bytes_written = 0
+  @@num_bytes_read    = 0
+
+  def initialize(fd)
+    @fd = fd
+  end
+
+  def write(stg)
+    arg stg: :String
+    ciovec = WASI::CIOVec.new(1)
+    ciovec << stg
+    errno = WASI.fd_write(@fd, ciovec.ciovs.ptr, 1, @@num_bytes_written.addr)
+    ciovec.free
+    errno
+  end
+
+  def print(stg)
+    self.write(stg)
+  end
+
+  def puts(stg)
+    arg stg: :String
+    result :none
+    ciovec = WASI::CIOVec.new(2)
+    ciovec << stg
+    ciovec << "\n"
+    errno = WASI.fd_write(@fd, ciovec.ciovs.ptr, 2, @@num_bytes_written.addr)
+    ciovec.free
+  end   
+
+  def read
+    result :I32 #:String
+    iovec = WASI::IOVec.new(1)
+    errno = WASI.fd_read(@fd, iovec.iovs.ptr, 1, @@num_bytes_read.addr)
+    # -1 below because of \0 terminated string
+    String.new(iovec.iovs[0], @@num_bytes_read-1) 
+  end
+
+end
+
+STDIN  = IO.new
+STDOUT = IO.new
+STDERR = IO.new
+
+module Kernel
+
+  def puts(stg)
+    arg stg: :String
+    result :none
+    STDOUT.puts(stg)
+  end
+
+  def print(stg)
+    arg stg: :String
+    result :none
+    STDOUT.print(stg)
+  end
+
+end

data/lib/rlang/lib/kernel.rb

@@ -3,15 +3,20 @@
 # All rights reserved.
 #
 # Kernel methods
+#
+# Most of the Kernel methods are defined in other files
+# to avoid requiring classes that rely on Kernel methods
+# themselves.
 
-$! = 0.cast_to(:String)
+class String; end
 
 module Kernel
 
   def raise(msg)
     arg msg: :String
     result :none
-    $! = msg
+    #$! = msg
+    #STDERR.puts msg
     inline wat: '(unreachable)', wtype: :none
   end
 

data/lib/rlang/lib/malloc.rb

@@ -8,8 +8,8 @@
 # For a detailed explanation of the allocator code see
 # https://gnuchops.wordpress.com/2013/02/26/memory-allocator-for-embedded-system-k-r-ritchie-book/
 
-require 'rlang/lib/memory'
-require 'rlang/lib/unistd'
+require_relative './memory'
+require_relative './unistd'
 
 # minimum number of units to request
 $NALLOC = 1024