root/v6/v6-KindaPerl6/docs/ruby_backend.txt

kp6 ruby backend

MISSION

As of January 2008, kp6 is the most-advanced actively-developed
non-parrot perl6 implementation.  It is written in a subset of
perl6, and runs on the more limited, but faster, mp6.

kp6 is designed to be capable of running on itself.  But the
performance of kp6 on kp6 is currently too slow to be usable.
By a couple of orders of magnitude.

This performance obstacle has severely hampered using bootstrapped
kp6 as a development path towards the implementation of perl6.

The objective of this kp6 ruby backend is to provide sufficient
performance for bootstrapped kp6 to be usable, thus unblocking
the development path.


DEVELOPMENT TIPS

 perl script/kp6 -Cruby -e 'say 3'  # show the emitted ruby code
 perl script/kp6 -Bruby -e 'say 3'  # run the emitted ruby code

 perl script/kp6 -Cast -e 'say 3'   # show the AST
 perl script/kp6 -Cperl5 -e 'say 3' # show the emitted perl5

 ./script/run_tests.pl --backend=ruby


If you change Emit/Ruby.pm,
  # get svn file timestamps correct
  rm -rf v6-KindaPerl6/compiled
  svn up
  # make
  perl Makefile.PL
  make kp6_mp6

make kp6_mp6 runs
 perl script/mp6.pl \
  -o compiled/perl5-kp6-mp6/lib/KindaPerl6/Visitor/Emit/Ruby.pm \
  src/KindaPerl6/Visitor/Emit/Ruby.pm


Files:
 docs/ruby_backend.txt
 src/KindaPerl6/Visitor/Emit/Ruby.pm
 compiled/ruby-kp6-mp6/kp6_runtime.rb
 compiled/ruby-kp6-mp6
 src/KindaPerl6/Runtime/Ruby


SCOPE OF OBJECTIVES

Performance.  Obj: kp6 on kp6 should run with at least the speed of
kp6 on mp6, and ideally of pugs.  Non-obj: performance on anything
other than kp6, eg, numerics.

Ability to run kp6 without significant mofication.

Simplicity.  Obj: simplicity for reducing development cost and risk.
Non-obj: simplicity for elegance, long-term maintainability, or
anything else.

Correctness.  Just enough correctness to make kp6 happy, and support
it's near term further development.  While stronger correctness will
likely exist, it's not a project objective.
Non-obj: Unneeded p6 spec-wise correctness, either short or long term.

Readable emitted ruby code.  Obj: easily readable for debugging.
Non-obj: easily hand writiable.  No hairy ruby games.


DESIGN

Calling convention:
 ->(cap){
   ->(the,formal,arguments) {
     ...inline argment processing...
     ...body...
   }.(nil,nil,nil)
 }
 cap is a Ruddy::Capture.

Name encoding
 base type - a prefix.  $x -> s_x, @%& -> a_ h_ c_
 characters - follow kp6.
 categories - follow kp6?
   but kp6's including <> in the encoding of infix:<x> seems unfortunate.

Variables
 Lookup is done using normal ruby lookup on zero-ary accessors which
 return p6 Containers.

 $x
 $x = v
 $x := v
 s_x
 s_x._(v)
 s_x = v       # for binding lexical variables
 self.s_x = v  # for binding package variables

 f(...)
 c_f.(...)

Lexical vars
 ->(x1,x2){...}.(v1,v2)  === (let ((x1 v1) (x2 v2)) ...)
 The absence of a real lambda in ruby 1.8 is what forces us to use 1.9.

Package vars
 Done with class vars.

 our $.x
 ===
 our :s_x
 ==>
 def s_x; @@x ||= ...; end  where ... is the optional default, or undef.
 def s_x=(v); @@x = v; end  

OO
 p6 classes are similarly named ruby classes.
 p6 modules and packages are ruby modules.(?)
 methods:

   $o.m()
   s_o.c_m.(...)

   current_class.def_pkg_var(:c_m, ...)
   where ... is
     ->(c){
       ->(s_self,...){
         ...
       }  
     }



Examples:
 my sub f(x) { 42 * x }
 ==>
 ->(c_f){
   c_f =
     ->(cap){
       ->(s_x){
         cap.mumble(1)
         s_x._(cap.frotz(0))
         42 * s_x
       }.(Scalar.new)
     }
   }.()
 }.(nil)

 sub g() { 42 }
 ==>
 our :c_g, ->(c){
   ...
   }



DESIGN DISCUSSION

A high-level alternate approach would be to more closely mimic the
perl5 backend.  Just do a transliteration.  Speedup would come from
running more or less directly on fast ruby oo, instead of the p5
backend's running on an oo layer (Moose) sitting on top of slow p5 oo.
This approach would in some ways be simpler.  And the performance gain
may well be sufficient to achieve a usably fast bootstrapped kp6.  I
didn't take this path because it required greater understanding of the
perl5 backend, and the assorted libraries it uses.  Which seemed a
higher cost and risk approach, for me, than reusing the architecture
from redsix.  Someone else might pursue it, if the current approach
bogs down, of if keeping the ruby and p5 backends synced becomes
burdensome at some future time.

Regards signature architecture.  The p6 signature language is, even
more so than usual, a non-trivial language.  Options:
(1) pass to the runtime, a p6 sig string '$x,$y', then parse in the
runtime.  Even if the parse/emit was used to cannonicallize the form,
there's still such richness as would be a pain to duplicate.
(2) pass to the runtime, an ast instead.
(2a) an ast composed of runtime objects, which are not p6 objects.
(2b) an ast composed of p6 objects.  Facilitates p6 reflection.
(3) at compile-time, generate inline code for parameter processing.
Currently the backend is using (3), but there is unfinished code for (2a).

Here's the unused (2a) convention:
 sig = Ruddy::Signature.new(...)
 ->(cap){
   ->(the,formal,arguments) {
     sig.bind(cap,binding)
     ...body...
   }.(nil,nil,nil)
 }
 cap may be an array (positional args only), a hash (named args only),
 or a Ruddy::Capture.

 my sub f(x) { 42 * x }
 ==>
 ->(c_f){
   c_f = ->(){
     sig = Ruddy::Signature.new(...)
     ->(cap){
       ->(s_x){
         sig.bind(cap,binding)
         42 * s_x
       }.(nil)
     }
   }.()
 }.(nil)




Note to self: don't forget Method .receiver and .owner. :)


TODO:
- continue to work through failing tests
- try compilation of kp6 p6 files

- start creating mp6_runtime.rb.

- flesh out todos

OLD FUZZY TODO LIST:
- walk though Emit/Ruby.pm, deciding, creating, and documenting runtime apis.
- do Runtime/Ruby.  Should be much simpler and smaller than Runtime/Perl5/.

LATER:
- create script/kp6.pl? a p6 version of the p5 script/kp6.
- rename ruby backend to ruddy (after acceptance).