Yadriggy

Yadriggy (mistletoe in English) is a library for building a
domain-specific language (DSL) embedded in Ruby. It was developed for
a particular kind of embedded DSLs.
These DSLs borrow the syntax from the host language, Ruby, and the
code written in the DSLs is embedded in normal Ruby code. However,
the execution of the DSL code is independent of Ruby. Its semantics
can be totally different from Ruby and the code can be run out of the
Ruby VM. These DSLs look like Ruby but they are different
languages except their syntax.
They are embedded in Ruby by borrowing the syntax but their embedding is
outward; their execution engines are their own.

For details, the documentation is available from Wiki.

An example

Computation offloading from Ruby is a typical example of the DSLs
implemented by Yadriggy.
For example, Yadriggy provides a simple DSL to offload
from Ruby to native C language.

require 'yadriggy/c'
include Yadriggy::C::CType
def fib(n) ! Integer
  typedecl n: Integer
  if n > 1
    return fib(n - 1) + fib(n - 2)
  else
    return n
  end
end
puts Yadriggy::C.run { return fib(32) }

When this code is run, the block given to Yadriggy::C.run is
translated into C code with the definition of fib method.
Then the C code is compiled into a dynamic library, loaded the
library through ruby-ffi, and executed. Since the block given to
run calls fib, the definition of fib is also translated
into C.

An external variable is accessible from the compiled block:

n = 32
puts Yadriggy::C.run { return fib(n) }

The argument to fib is take from the variable n that exists
outside of the block. n is passed to the compiled block by copying.
It is not passed by reference. Thus, when a new value is assigned to
n within the compiled block, it is not visible from the Ruby code.
The variable n in the Ruby code keeps the old value.

Note that the definition of fib contains type declarations
since this DSL is not Ruby.
This DSL looks like Ruby but it is a different language.
! Integer following def fib(n) specifies the return type.
typedecl specifies the types of the parameters (and local variables
if any). In this DSL, most types have to be statically given
although the DSL performs simple type inference and some types
can be omitted.

Library

Yadriggy provides a method for obtaining the abstract syntax tree (AST)
of the given method, lambda, or Proc.
It also provides a syntax checker that determines whether or not an AST
satisfies the syntax described in the BNF-like language, which is
a DSL embedded in Ruby by Yadriggy.

You can even obtain the AST of a piece of source code:

require 'yadriggy'
ast = Yadriggy.reify {|a| a + 1 }

reify returns the AST of the given block {|a| a + 1 }.
It takes not only a block but also a Method or Proc object.

Yadriggy works with Pry and IRuby unless a syntax error occurs.

The idea of reify was proposed in the following paper:

• Shigeru Chiba, YungYu Zhuang, Maximilian Scherr, “Deeply Reifying Running Code for Constructing a Domain-Specific Language”, PPPJ’16, Article No. 1, ACM, August 2016.

Yadriggy-Py was presented in the following paper:

• Shigeru Chiba, Foreign language interfaces by code migration, Proc. of the 18th ACM SIGPLAN International Conference on Generative Programming: Concepts and Experiences (GPCE 2019), pp. 1-13, ACM, 2019.

Installation

To install, run:

$ gem install yadriggy

or, download this repository and run:

$ bundle exec rake install

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/csg-tokyo/yadriggy.

License

The gem is available as open source under the terms of the MIT License.