ruby-internal 0.6.0 → 0.7.0

data/README

@@ -1,7 +1,21 @@
-This is ruby-internal, a library that provides access to the internals
-of the ruby interpreter.
+Ruby-internal is a Ruby library that provides direct access to Ruby's
+(MRI or YARV) internal data structures.
 
-See the file LICENSE for license and copyright information.
+How is ruby-internal useful? You can:
+
+* dump and load methods and procs and classes
+* inspect and pretty-print ascii charts of node trees
+* inspect and print ascii charts of class hierarchies
+* use the provided code obfuscator (nwobfusc.rb) so your code can't easily be read.
+* use it to build a just-in-time compiler (see Ludicrous).
+
+== Installation
+
+To install ruby-internal:
+
+  $ gem install ruby-internal
+
+== Building from source
 
 To build and run the tests:
   ruby setup.rb config
@@ -11,16 +25,195 @@ Or, if you are on ruby 1.9 (or another version of ruby that doesn't have
 pre-parsed ruby source included in the distribution), you'll need to
 pass a special command-line option in the config step so the build
 scripts can find ruby's source code:
+
   ruby setup.rb config --ruby-source-path=/path/to/ruby
   ruby setup.rb setup
 
 To install:
   ruby install.rb install
 
-See the generated documentation (in the doc/ directory) and the examples
-(in the directory example/) for usage.
+== Sample code
+
+This will dump the class Foo (including its instance methods, class variables,
+etc.) and re-load it:
+
+  :include: sample/dump_class.rb
+
+== Ruby-internal and irb
+
+Ruby-internal is very useful as a tool for digging into the internals of Ruby
+and figuring out what the interpreter is doing with your code. To use
+ruby-internal with irb, put the following in your .irbrc:
+
+  :include: sample/irbrc
+
+Now you can print node trees:
+
+  irb(main):001:0> pp (proc { 1 + 1 }.body)
+  NODE_NEWLINE at (irb):1
+  |-nth = 1
+  +-next = NODE_CALL at (irb):1
+    |-recv = NODE_LIT at (irb):1
+    | +-lit = 1
+    |-args = NODE_ARRAY at (irb):1
+    | |-alen = 1
+    | |-head = NODE_LIT at (irb):1
+    | | +-lit = 1
+    | +-next = false
+    +-mid = :+
+  => nil
+
+And view class hierarchies:
+
+  irb(main):004:0> puts Object.new.classtree
+  #<Object:0x40330ce8>
+  +-class = Object
+    |-class = #<Class:Object>
+    | |-class = Class
+    | | |-class = #<Class:Class>
+    | | | |-class = #<Class:Class> (*)
+    | | | +-super = #<Class:Module>
+    | | |   |-class = Class (*)
+    | | |   +-super = #<Class:Object> (*)
+    | | +-super = Module
+    | |   |-class = #<Class:Module> (*)
+    | |   +-super = Object (*)
+    | +-super = Class (*)
+    +-super = #<PP::ObjectMixin?:0x40349568>
+      +-class = PP::ObjectMixin?
+        |-class = Module (*)
+        +-super = #<Kernel:0x4033507c>
+          +-class = Kernel
+  => nil
+
+View method signatures:
+
+  irb(main):015:0> def foo(a, b, *rest, &block); end; method(:foo).signature
+  => #<MethodSig::Signature:0x4037093c @origin_class=Object, @arg_info={:b=>"b",
+  :block=>"&block", :a=>"a", :rest=>"*rest"}, @name="foo", @arg_names=[:a,
+  :b, :rest, :block]>
+  irb(main):016:0> proc { |x, y, *rest| }.signature
+  => #<Proc::Signature:0x4036cf30 @args=#<Proc::Arguments:0x4036d020 @rest_arg=2,
+  @multiple_assignment=true, @names=[:x, :y, :rest]>, @arg_info={:x=>"x", :y=>"y",
+  :rest=>"*rest"}>
+
+And reconstruct compiled methods:
+
+  irb(main):001:0> def foo(a, b, *rest, &block)
+  irb(main):002:1>   begin
+  irb(main):003:2*     if not a and not b then
+  irb(main):004:3*       raise "Need more input!"
+  irb(main):005:3>     end
+  irb(main):006:2>     return a + b
+  irb(main):007:2>   ensure
+  irb(main):008:2*     puts "In ensure block"
+  irb(main):009:2>   end
+  irb(main):010:1> end
+  => nil
+  irb(main):011:0> m = method(:foo)
+  => #<Method: Object#foo>
+  irb(main):012:0> puts m.as_code
+  def foo(a, b, *rest, &block)
+    begin
+      (raise("Need more input!")) if (not a and not b)
+      return a + b
+    ensure
+      puts("In ensure block")
+    end
+  end
+  => nil
+
+== YARV support
 
-Some notes about security:
+Yes, ruby-internal works with YARV, too. The difference when using YARV
+is that sometimes you have nodes, and sometimes you have instruction
+sequences. So whereas pre-YARV you would have a pure AST, with YARV you
+get structures that look like this:
+
+  irb(main):001:0> def foo; 1 + 1; end
+  => nil
+  irb(main):002:0> pp method(:foo).body  
+  NODE_METHOD at (irb):1
+  |-noex = PUBLIC
+  |-body = <ISeq:foo@(irb)>
+  | |-0000 trace            8
+  | |-0002 trace            1
+  | |-0004 putobject        1
+  | |-0006 putobject        1
+  | |-0008 opt_plus         
+  | |-0009 trace            16
+  | +-0011 leave            
+  +-cnt = 0
+
+You can also access the original AST with Node.compile:
+
+  irb(main):001:0> n = Node.compile_string('1+1')
+  => #>Node::SCOPE:0x40420af0>
+  irb(main):002:0> pp n
+  NODE_SCOPE at (compiled):1
+  |-rval = NODE_CALL at (compiled):1
+  | |-recv = NODE_LIT at (compiled):1
+  | | +-lit = 1
+  | |-args = NODE_ARRAY at (compiled):1
+  | | |-alen = 1
+  | | |-head = NODE_LIT at (compiled):1
+  | | | +-lit = 1
+  | | +-next = false
+  | +-mid = :+
+  |-tbl = nil
+  +-next = false
+
+compile it to a bytecode sequence:
+
+  irb(main):003:0> is = n.bytecode_compile()
+  => <ISeq:<main>@(compiled)>
+  irb(main):004:0> puts is.disasm
+  == disasm: >ISeq:>main>@(compiled)>=====================================
+  0000 trace            1                                               (   1)
+  0002 putobject        1
+  0004 putobject        1
+  0006 opt_plus         
+  0007 leave            
+  => nil
+
+iterate over the bytecode sequence:
+
+  irb(main):004:0> is.each { |i| puts "#{i.inspect} #{i.length} #{i.operand_types.inspect}" }
+  #<VM::Instruction::TRACE:0x40412324 @operands=[1]> 2 [:num]
+  #<VM::Instruction::PUTOBJECT:0x404121d0 @operands=[1]> 2 [:value]
+  #<VM::Instruction::PUTOBJECT:0x4041207c @operands=[1]> 2 [:value]
+  #<VM::Instruction::OPT_PLUS:0x40411f28 @operands=[]> 1 []
+  #<VM::Instruction::LEAVE:0x40411e24 @operands=[]> 1 []
+  => nil
+
+then decompile it:
+
+  irb(main):005:0> require 'as_expression'
+  => true
+  irb(main):006:0> is.as_expression
+  => "1 + 1"
+
+There are still a few missing features (particularly in the decompiler),
+but expect to see more exciting tools for working with bytecode in the
+future!
+
+== Other tools
+
+Ruby-internal comes with two useful tools, nwdump and nwobfusc. The
+nwdump tool works in much the same way as the older Pragmatic nodedump
+tool. If you require it from the command line:
+
+  $ ruby -rinternal/node/dump test.rb
+
+it will dump your program's syntax tree. The nwobfusc tool is similar:
+
+  $ ruby -rinternal/obfusc test.rb > test2.rb
+
+but its output is an obfuscated version of your program. The program
+must be run on the same version of both ruby-internal and the
+interpreter.
+
+== Some notes about security
 
 - Data can always be inspected.
 - Methods that could potentially cause a crash if used incorrectly are
@@ -29,3 +222,8 @@ Some notes about security:
   disallowed with $SAFE >= 4.
 - Methods that load marshalled data do taint checks with $SAFE >= 1.
 
+== Future directions
+
+* Load/dump the state of the ruby interpreter
+* Manipulate the AST/bytecode on-the-fly 
+

data/ext/cached/ruby-1.6.8/internal/binding/block.h

@@ -0,0 +1,35 @@
+#ifndef ruby_internal_block__h_
+#define ruby_internal_block__h_
+
+#include <ruby.h>
+
+#ifndef RUBY_VM
+#include "env.h"
+#endif
+
+struct BLOCKTAG {
+    struct RBasic super;
+    long dst;
+    long flags;
+};
+
+struct BLOCK {
+    NODE *var;
+    NODE *body;
+    VALUE self;
+    struct FRAME frame;
+    struct SCOPE *scope;
+    struct BLOCKTAG *tag;
+    VALUE klass;
+    int iter;
+    int vmode;
+    int flags;
+    struct RVarmap *dyna_vars;
+    VALUE orig_thread;
+    VALUE wrapper;
+    struct BLOCK *prev;
+};
+
+
+#endif
+

data/ext/cached/ruby-1.6.8/internal/method/method.h

@@ -0,0 +1,19 @@
+#ifndef ruby_internal_method__h_
+#define ruby_internal_method__h_
+
+#include <ruby.h>
+
+#include "internal/node/ruby_internal_node.h"
+
+struct METHOD {
+    VALUE klass, oklass;
+    VALUE recv;
+    ID id, oid;
+    NODE *body;
+};
+
+#define METHOD_OCLASS(m) m->klass
+#define METHOD_RCLASS(m) m->klass
+
+#endif
+

data/ext/cached/ruby-1.6.8/internal/module/classpath.c

@@ -0,0 +1,3 @@
+#include "classpath.h"
+
+

data/ext/cached/ruby-1.6.8/internal/module/classpath.h

@@ -0,0 +1,8 @@
+#ifndef CLASSPATH_H
+#define CLASSPATH_H
+
+#include "ruby.h"
+
+
+#endif
+

data/ext/cached/ruby-1.6.8/internal/node/block.h

@@ -0,0 +1,35 @@
+#ifndef ruby_internal_block__h_
+#define ruby_internal_block__h_
+
+#include <ruby.h>
+
+#ifndef RUBY_VM
+#include "env.h"
+#endif
+
+struct BLOCKTAG {
+    struct RBasic super;
+    long dst;
+    long flags;
+};
+
+struct BLOCK {
+    NODE *var;
+    NODE *body;
+    VALUE self;
+    struct FRAME frame;
+    struct SCOPE *scope;
+    struct BLOCKTAG *tag;
+    VALUE klass;
+    int iter;
+    int vmode;
+    int flags;
+    struct RVarmap *dyna_vars;
+    VALUE orig_thread;
+    VALUE wrapper;
+    struct BLOCK *prev;
+};
+
+
+#endif
+

data/ext/cached/ruby-1.6.8/internal/node/global_entry.h

@@ -0,0 +1,15 @@
+#ifndef global_entry__h_
+#define global_entry__h_
+
+struct global_entry {
+    ID id;
+    void *data;
+    VALUE (*getter)();
+    void  (*setter)();
+    void  (*marker)();
+    int block_trace;
+    struct trace_var *trace;
+};
+
+#endif
+

data/ext/cached/ruby-1.6.8/internal/node/node_type_descrip.c

@@ -0,0 +1,149 @@
+#include "node_type_descrip.h"
+#include "version.h"
+
+Node_Type_Descrip node_type_descrips_unsorted[] = {
+  { NODE_ALIAS, NEN_1ST, NEN_2ND, NEN_NONE, "ALIAS" },
+#ifdef HAVE_NODE_ALLOCA
+  { NODE_ALLOCA, NEN_CFNC, NEN_VALUE, NEN_CNT, "ALLOCA" },
+#endif
+  { NODE_AND, NEN_1ST, NEN_2ND, NEN_NONE, "AND" },
+  { NODE_ARGS, NEN_REST, NEN_OPT, NEN_CNT, "ARGS" },
+  { NODE_ARGSCAT, NEN_HEAD, NEN_BODY, NEN_NONE, "ARGSCAT" },
+  { NODE_ARGSPUSH, NEN_HEAD, NEN_BODY, NEN_NONE, "ARGSPUSH" },
+  { NODE_ARRAY, NEN_HEAD, NEN_ALEN, NEN_NEXT, "ARRAY" },
+  { NODE_ATTRSET, NEN_VID, NEN_NONE, NEN_NONE, "ATTRSET" },
+  { NODE_BACK_REF, NEN_NTH, NEN_CNT, NEN_NONE, "BACK_REF" },
+  { NODE_BEGIN, NEN_BODY, NEN_NONE, NEN_NONE, "BEGIN" },
+  { NODE_BLOCK, NEN_HEAD, NEN_NEXT, NEN_NONE, "BLOCK" },
+  { NODE_BLOCK_ARG, NEN_CNT, NEN_NONE, NEN_NONE, "BLOCK_ARG" },
+  { NODE_BLOCK_PASS, NEN_BODY, NEN_ITER, NEN_NONE, "BLOCK_PASS" },
+  { NODE_BMETHOD, NEN_CVAL, NEN_NONE, NEN_NONE, "BMETHOD" },
+  { NODE_BREAK, NEN_STTS, NEN_NONE, NEN_NONE, "BREAK" },
+  { NODE_CALL, NEN_ARGS, NEN_MID, NEN_RECV, "CALL" },
+  { NODE_CASE, NEN_HEAD, NEN_BODY, NEN_NEXT, "CASE" },
+  { NODE_CDECL, NEN_VALUE, NEN_VID, NEN_NONE, "CDECL" },
+  { NODE_CFUNC, NEN_CFNC, NEN_ARGC, NEN_NONE, "CFUNC" },
+  { NODE_CLASS, NEN_BODY, NEN_CNAME, NEN_SUPER, "CLASS" },
+  { NODE_COLON2, NEN_HEAD, NEN_MID, NEN_NONE, "COLON2" },
+  { NODE_COLON3, NEN_MID, NEN_NONE, NEN_NONE, "COLON3" },
+  { NODE_CONST, NEN_VID, NEN_NONE, NEN_NONE, "CONST" },
+  { NODE_CREF, NEN_BODY, NEN_NEXT, NEN_CLSS, "CREF" },
+  { NODE_CVAR, NEN_VID, NEN_NONE, NEN_NONE, "CVAR" },
+  { NODE_CVASGN, NEN_VALUE, NEN_VID, NEN_NONE, "CVASGN" },
+  { NODE_CVDECL, NEN_VALUE, NEN_VID, NEN_NONE, "CVDECL" },
+  { NODE_DASGN, NEN_VALUE, NEN_VID, NEN_NONE, "DASGN" },
+  { NODE_DASGN_CURR, NEN_VALUE, NEN_VID, NEN_NONE, "DASGN_CURR" },
+  { NODE_DEFINED, NEN_HEAD, NEN_NONE, NEN_NONE, "DEFINED" },
+  { NODE_DEFN, NEN_DEFN, NEN_MID, NEN_NOEX, "DEFN" },
+  { NODE_DEFS, NEN_DEFN, NEN_MID, NEN_RECV, "DEFS" },
+  { NODE_DMETHOD, NEN_CVAL, NEN_NONE, NEN_NONE, "DMETHOD" },
+  { NODE_DOT2, NEN_BEG, NEN_END, NEN_STATE, "DOT2" },
+  { NODE_DOT3, NEN_BEG, NEN_END, NEN_STATE, "DOT3" },
+  { NODE_DREGX, NEN_LIT, NEN_CFLAG, NEN_NEXT, "DREGX" },
+  { NODE_DREGX_ONCE, NEN_LIT, NEN_CFLAG, NEN_NEXT, "DREGX_ONCE" },
+  { NODE_DSTR, NEN_LIT, NEN_NEXT, NEN_NONE, "DSTR" },
+  { NODE_DVAR, NEN_VID, NEN_NONE, NEN_NONE, "DVAR" },
+  { NODE_DXSTR, NEN_LIT, NEN_NEXT, NEN_NONE, "DXSTR" },
+  { NODE_ENSURE, NEN_HEAD, NEN_ENSR, NEN_NONE, "ENSURE" },
+  { NODE_EVSTR, NEN_LIT, NEN_NONE, NEN_NONE, "EVSTR" },
+  { NODE_FALSE, NEN_NONE, NEN_NONE, NEN_NONE, "FALSE" },
+  { NODE_FBODY, NEN_HEAD, NEN_ORIG, NEN_MID, "FBODY" },
+  { NODE_FCALL, NEN_ARGS, NEN_MID, NEN_NONE, "FCALL" },
+  { NODE_FLIP2, NEN_BEG, NEN_END, NEN_CNT, "FLIP2" },
+  { NODE_FLIP3, NEN_BEG, NEN_END, NEN_CNT, "FLIP3" },
+  { NODE_FOR, NEN_BODY, NEN_ITER, NEN_VAR, "FOR" },
+  { NODE_GASGN, NEN_VALUE, NEN_VID, NEN_ENTRY, "GASGN" },
+  { NODE_GVAR, NEN_VID, NEN_ENTRY, NEN_NONE, "GVAR" },
+  { NODE_HASH, NEN_HEAD, NEN_NONE, NEN_NONE, "HASH" },
+  { NODE_IASGN, NEN_VALUE, NEN_VID, NEN_NONE, "IASGN" },
+  { NODE_IF, NEN_COND, NEN_BODY, NEN_ELSE, "IF" },
+  { NODE_IFUNC, NEN_CFNC, NEN_TVAL, NEN_STATE, "IFUNC" },
+  { NODE_ITER, NEN_BODY, NEN_ITER, NEN_VAR, "ITER" },
+  { NODE_IVAR, NEN_VID, NEN_NONE, NEN_NONE, "IVAR" },
+  { NODE_LASGN, NEN_VALUE, NEN_VID, NEN_CNT, "LASGN" },
+  { NODE_LIT, NEN_LIT, NEN_NONE, NEN_NONE, "LIT" },
+  { NODE_LVAR, NEN_VID, NEN_CNT, NEN_NONE, "LVAR" },
+  { NODE_MASGN, NEN_ARGS, NEN_HEAD, NEN_VALUE, "MASGN" },
+  { NODE_MATCH, NEN_HEAD, NEN_VALUE, NEN_NONE, "MATCH" },
+  { NODE_MATCH2, NEN_VALUE, NEN_RECV, NEN_NONE, "MATCH2" },
+  { NODE_MATCH3, NEN_VALUE, NEN_RECV, NEN_NONE, "MATCH3" },
+  { NODE_MEMO, NEN_NONE, NEN_NONE, NEN_NONE, "MEMO" },
+  { NODE_METHOD, NEN_BODY, NEN_NOEX, NEN_NONE, "METHOD" },
+  { NODE_MODULE, NEN_BODY, NEN_CNAME, NEN_NONE, "MODULE" },
+  { NODE_NEWLINE, NEN_NEXT, NEN_NONE, NEN_NONE, "NEWLINE" },
+  { NODE_NEXT, NEN_STTS, NEN_NONE, NEN_NONE, "NEXT" },
+  { NODE_NIL, NEN_NONE, NEN_NONE, NEN_NONE, "NIL" },
+  { NODE_NOT, NEN_BODY, NEN_NONE, NEN_NONE, "NOT" },
+  { NODE_NTH_REF, NEN_NTH, NEN_CNT, NEN_NONE, "NTH_REF" },
+  { NODE_OPT_N, NEN_BODY, NEN_NONE, NEN_NONE, "OPT_N" },
+  { NODE_OP_ASGN1, NEN_ARGS, NEN_MID, NEN_RECV, "OP_ASGN1" },
+  { NODE_OP_ASGN2, NEN_VALUE, NEN_NEXT, NEN_RECV, "OP_ASGN2" },
+  { NODE_OP_ASGN2_ARG, NEN_VID, NEN_AID, NEN_MID, "OP_ASGN2_ARG" },
+  { NODE_OP_ASGN_AND, NEN_VALUE, NEN_RECV, NEN_NONE, "OP_ASGN_AND" },
+  { NODE_OP_ASGN_OR, NEN_AID, NEN_VALUE, NEN_RECV, "OP_ASGN_OR" },
+  { NODE_OR, NEN_1ST, NEN_2ND, NEN_NONE, "OR" },
+  { NODE_POSTEXE, NEN_NONE, NEN_NONE, NEN_NONE, "POSTEXE" },
+  { NODE_REDO, NEN_NONE, NEN_NONE, NEN_NONE, "REDO" },
+  { NODE_RESBODY, NEN_HEAD, NEN_ARGS, NEN_BODY, "RESBODY" },
+  { NODE_RESCUE, NEN_HEAD, NEN_ELSE, NEN_RESQ, "RESCUE" },
+  { NODE_RETRY, NEN_NONE, NEN_NONE, NEN_NONE, "RETRY" },
+  { NODE_RETURN, NEN_STTS, NEN_NONE, NEN_NONE, "RETURN" },
+  { NODE_SCLASS, NEN_BODY, NEN_RECV, NEN_NONE, "SCLASS" },
+  { NODE_SCOPE, NEN_TBL, NEN_RVAL, NEN_NEXT, "SCOPE" },
+  { NODE_SELF, NEN_NONE, NEN_NONE, NEN_NONE, "SELF" },
+  { NODE_STR, NEN_LIT, NEN_NONE, NEN_NONE, "STR" },
+  { NODE_SUPER, NEN_ARGS, NEN_NONE, NEN_NONE, "SUPER" },
+  { NODE_TRUE, NEN_NONE, NEN_NONE, NEN_NONE, "TRUE" },
+  { NODE_UNDEF, NEN_MID, NEN_NONE, NEN_NONE, "UNDEF" },
+  { NODE_UNTIL, NEN_BODY, NEN_COND, NEN_STATE, "UNTIL" },
+  { NODE_VALIAS, NEN_1ST, NEN_2ND, NEN_NONE, "VALIAS" },
+  { NODE_VCALL, NEN_MID, NEN_NONE, NEN_NONE, "VCALL" },
+  { NODE_WHEN, NEN_HEAD, NEN_BODY, NEN_NEXT, "WHEN" },
+  { NODE_WHILE, NEN_BODY, NEN_COND, NEN_STATE, "WHILE" },
+  { NODE_XSTR, NEN_LIT, NEN_NONE, NEN_NONE, "XSTR" },
+  { NODE_YIELD, NEN_HEAD, NEN_STATE, NEN_NONE, "YIELD" },
+  { NODE_ZARRAY, NEN_NONE, NEN_NONE, NEN_NONE, "ZARRAY" },
+  { NODE_ZSUPER, NEN_NONE, NEN_NONE, NEN_NONE, "ZSUPER" },
+  { NODE_LAST, NEN_NONE, NEN_NONE, NEN_NONE, "LAST" },
+};
+
+static Node_Type_Descrip * node_type_descrips[NUM_NODE_TYPE_DESCRIPS];
+static int node_type_descrips_initialized = 0;
+
+static void init_node_type_descrips()
+{
+  if(!node_type_descrips_initialized)
+  {
+    Node_Type_Descrip * descrip;
+    memset(node_type_descrips, 0, sizeof(node_type_descrips));
+    for(descrip = node_type_descrips_unsorted;
+        descrip->nt != NODE_LAST;
+        ++descrip)
+    {
+      if(node_type_descrips[descrip->nt])
+      {
+        rb_raise(rb_eRuntimeError, "duplicate entry for node type %d (%s is also %s)\n", descrip->nt, descrip->name, node_type_descrips[descrip->nt]->name);
+      }
+      else
+      {
+        node_type_descrips[descrip->nt] = descrip;
+      }
+    }
+    node_type_descrips_initialized = 1;
+  }
+}
+
+/* Given a node, find out the types of the three elements it contains */
+Node_Type_Descrip const * node_type_descrip(enum node_type nt)
+{
+  init_node_type_descrips();
+  if(node_type_descrips[nt])
+  {
+    return node_type_descrips[nt];
+  }
+  else
+  {
+    rb_raise(rb_eArgError, "Unknown node type %d", nt);
+  }
+}
+