node_dump.c

   1 /**********************************************************************
   2
   3   node_dump.c - dump ruby node tree
   4
   5   $Author: mame $
   6   created at: 09/12/06 21:23:44 JST
   7
   8   Copyright (C) 2009 Yusuke Endoh
   9
  10 **********************************************************************/
  11
  12 #include "internal.h"
  13 #include "internal/hash.h"
  14 #include "internal/variable.h"
  15 #include "ruby/ruby.h"
  16 #include "vm_core.h"
  17
  18 #define A(str) rb_str_cat2(buf, (str))
  19 #define AR(str) rb_str_concat(buf, (str))
  20
  21 #define A_INDENT add_indent(buf, indent)
  22 #define D_INDENT rb_str_cat2(indent, next_indent)
  23 #define D_DEDENT rb_str_resize(indent, RSTRING_LEN(indent) - 4)
  24 #define A_ID(id) add_id(buf, (id))
  25 #define A_INT(val) rb_str_catf(buf, "%d", (val))
  26 #define A_LONG(val) rb_str_catf(buf, "%ld", (val))
  27 #define A_LIT(lit) AR(rb_dump_literal(lit))
  28 #define A_NODE_HEADER(node, term) \
  29     rb_str_catf(buf, "@ %s (id: %d, line: %d, location: (%d,%d)-(%d,%d))%s"term, \
  30                 ruby_node_name(nd_type(node)), nd_node_id(node), nd_line(node), \
  31                 nd_first_lineno(node), nd_first_column(node), \
  32                 nd_last_lineno(node), nd_last_column(node), \
  33                 (node->flags & NODE_FL_NEWLINE ? "*" : ""))
  34 #define A_FIELD_HEADER(len, name, term) \
  35     rb_str_catf(buf, "+- %.*s:"term, (len), (name))
  36 #define D_FIELD_HEADER(len, name, term) (A_INDENT, A_FIELD_HEADER(len, name, term))
  37
  38 #define D_NULL_NODE (A_INDENT, A("(null node)\n"))
  39 #define D_NODE_HEADER(node) (A_INDENT, A_NODE_HEADER(node, "\n"))
  40
  41 #define COMPOUND_FIELD(len, name) \
  42     FIELD_BLOCK((D_FIELD_HEADER((len), (name), "\n"), D_INDENT), D_DEDENT)
  43
  44 #define COMPOUND_FIELD1(name, ann) \
  45     COMPOUND_FIELD(FIELD_NAME_LEN(name, ann), \
  46                    FIELD_NAME_DESC(name, ann))
  47
  48 #define FIELD_NAME_DESC(name, ann) name " (" ann ")"
  49 #define FIELD_NAME_LEN(name, ann) (int)( \
  50         comment ? \
  51         rb_strlen_lit(FIELD_NAME_DESC(name, ann)) : \
  52         rb_strlen_lit(name))
  53 #define SIMPLE_FIELD(len, name) \
  54     FIELD_BLOCK(D_FIELD_HEADER((len), (name), " "), A("\n"))
  55
  56 #define FIELD_BLOCK(init, reset) \
  57     for (init, field_flag = 1; \
  58          field_flag; /* should be optimized away */ \
  59          reset, field_flag = 0)
  60
  61 #define SIMPLE_FIELD1(name, ann)    SIMPLE_FIELD(FIELD_NAME_LEN(name, ann), FIELD_NAME_DESC(name, ann))
  62 #define F_CUSTOM1(name, ann)        SIMPLE_FIELD1(#name, ann)
  63 #define F_ID(name, ann)             SIMPLE_FIELD1(#name, ann) A_ID(node->name)
  64 #define F_INT(name, ann)            SIMPLE_FIELD1(#name, ann) A_INT(node->name)
  65 #define F_LONG(name, ann)           SIMPLE_FIELD1(#name, ann) A_LONG(node->name)
  66 #define F_LIT(name, ann)            SIMPLE_FIELD1(#name, ann) A_LIT(node->name)
  67 #define F_MSG(name, ann, desc)      SIMPLE_FIELD1(#name, ann) A(desc)
  68
  69 #define F_NODE(name, ann) \
  70     COMPOUND_FIELD1(#name, ann) {dump_node(buf, indent, comment, node->name);}
  71
  72 #define ANN(ann) \
  73     if (comment) { \
  74         A_INDENT; A("| # " ann "\n"); \
  75     }
  76
  77 #define LAST_NODE (next_indent = "    ")
  78
  79 VALUE
  80 rb_dump_literal(VALUE lit)
  81 {
  82     if (!RB_SPECIAL_CONST_P(lit)) {
  83         VALUE str;
  84         switch (RB_BUILTIN_TYPE(lit)) {
  85           case T_CLASS: case T_MODULE: case T_ICLASS:
  86             str = rb_class_path(lit);
  87             if (FL_TEST(lit, FL_SINGLETON)) {
  88                 str = rb_sprintf("<%"PRIsVALUE">", str);
  89             }
  90             return str;
  91           default:
  92             break;
  93         }
  94     }
  95     return rb_inspect(lit);
  96 }
  97
  98 static void
  99 add_indent(VALUE buf, VALUE indent)
 100 {
 101     AR(indent);
 102 }
 103
 104 static void
 105 add_id(VALUE buf, ID id)
 106 {
 107     if (id == 0) {
 108         A("(null)");
 109     }
 110     else {
 111         VALUE str = rb_id2str(id);
 112         if (str) {
 113             A(":"); AR(str);
 114         }
 115         else {
 116             rb_str_catf(buf, "(internal variable: 0x%"PRIsVALUE")", id);
 117         }
 118     }
 119 }
 120
 121 struct add_option_arg {
 122     VALUE buf, indent;
 123     st_index_t count;
 124 };
 125
 126 static void dump_node(VALUE, VALUE, int, const NODE *);
 127 static const char default_indent[] = "|   ";
 128
 129 static void
 130 dump_array(VALUE buf, VALUE indent, int comment, const NODE *node)
 131 {
 132     int field_flag;
 133     const char *next_indent = default_indent;
 134     F_LONG(nd_alen, "length");
 135     F_NODE(nd_head, "element");
 136     while (node->nd_next && nd_type_p(node->nd_next, NODE_LIST)) {
 137         node = node->nd_next;
 138         F_NODE(nd_head, "element");
 139     }
 140     LAST_NODE;
 141     F_NODE(nd_next, "next element");
 142 }
 143
 144 static void
 145 dump_node(VALUE buf, VALUE indent, int comment, const NODE * node)
 146 {
 147     int field_flag;
 148     int i;
 149     const char *next_indent = default_indent;
 150     enum node_type type;
 151
 152     if (!node) {
 153         D_NULL_NODE;
 154         return;
 155     }
 156
 157     D_NODE_HEADER(node);
 158
 159     type = nd_type(node);
 160     switch (type) {
 161       case NODE_BLOCK:
 162         ANN("statement sequence");
 163         ANN("format: [nd_head]; ...; [nd_next]");
 164         ANN("example: foo; bar");
 165         i = 0;
 166         do {
 167             A_INDENT;
 168             rb_str_catf(buf, "+- nd_head (%s%d):\n",
 169                         comment ? "statement #" : "", ++i);
 170             if (!node->nd_next) LAST_NODE;
 171             D_INDENT;
 172             dump_node(buf, indent, comment, node->nd_head);
 173             D_DEDENT;
 174         } while (node->nd_next &&
 175                  nd_type_p(node->nd_next, NODE_BLOCK) &&
 176                  (node = node->nd_next, 1));
 177         if (node->nd_next) {
 178             LAST_NODE;
 179             F_NODE(nd_next, "next block");
 180         }
 181         return;
 182
 183       case NODE_IF:
 184         ANN("if statement");
 185         ANN("format: if [nd_cond] then [nd_body] else [nd_else] end");
 186         ANN("example: if x == 1 then foo else bar end");
 187         F_NODE(nd_cond, "condition expr");
 188         F_NODE(nd_body, "then clause");
 189         LAST_NODE;
 190         F_NODE(nd_else, "else clause");
 191         return;
 192
 193       case NODE_UNLESS:
 194         ANN("unless statement");
 195         ANN("format: unless [nd_cond] then [nd_body] else [nd_else] end");
 196         ANN("example: unless x == 1 then foo else bar end");
 197         F_NODE(nd_cond, "condition expr");
 198         F_NODE(nd_body, "then clause");
 199         LAST_NODE;
 200         F_NODE(nd_else, "else clause");
 201         return;
 202
 203       case NODE_CASE:
 204         ANN("case statement");
 205         ANN("format: case [nd_head]; [nd_body]; end");
 206         ANN("example: case x; when 1; foo; when 2; bar; else baz; end");
 207         F_NODE(nd_head, "case expr");
 208         LAST_NODE;
 209         F_NODE(nd_body, "when clauses");
 210         return;
 211       case NODE_CASE2:
 212         ANN("case statement with no head");
 213         ANN("format: case; [nd_body]; end");
 214         ANN("example: case; when 1; foo; when 2; bar; else baz; end");
 215         F_NODE(nd_head, "case expr");
 216         LAST_NODE;
 217         F_NODE(nd_body, "when clauses");
 218         return;
 219       case NODE_CASE3:
 220         ANN("case statement (pattern matching)");
 221         ANN("format: case [nd_head]; [nd_body]; end");
 222         ANN("example: case x; in 1; foo; in 2; bar; else baz; end");
 223         F_NODE(nd_head, "case expr");
 224         LAST_NODE;
 225         F_NODE(nd_body, "in clauses");
 226         return;
 227
 228       case NODE_WHEN:
 229         ANN("when clause");
 230         ANN("format: when [nd_head]; [nd_body]; (when or else) [nd_next]");
 231         ANN("example: case x; when 1; foo; when 2; bar; else baz; end");
 232         F_NODE(nd_head, "when value");
 233         F_NODE(nd_body, "when body");
 234         LAST_NODE;
 235         F_NODE(nd_next, "next when clause");
 236         return;
 237
 238       case NODE_IN:
 239         ANN("in clause");
 240         ANN("format: in [nd_head]; [nd_body]; (in or else) [nd_next]");
 241         ANN("example: case x; in 1; foo; in 2; bar; else baz; end");
 242         F_NODE(nd_head, "in pattern");
 243         F_NODE(nd_body, "in body");
 244         LAST_NODE;
 245         F_NODE(nd_next, "next in clause");
 246         return;
 247
 248       case NODE_WHILE:
 249         ANN("while statement");
 250         ANN("format: while [nd_cond]; [nd_body]; end");
 251         ANN("example: while x == 1; foo; end");
 252         goto loop;
 253       case NODE_UNTIL:
 254         ANN("until statement");
 255         ANN("format: until [nd_cond]; [nd_body]; end");
 256         ANN("example: until x == 1; foo; end");
 257       loop:
 258         F_CUSTOM1(nd_state, "begin-end-while?") {
 259             A_INT((int)node->nd_state);
 260             A((node->nd_state == 1) ? " (while-end)" : " (begin-end-while)");
 261         }
 262         F_NODE(nd_cond, "condition");
 263         LAST_NODE;
 264         F_NODE(nd_body, "body");
 265         return;
 266
 267       case NODE_ITER:
 268         ANN("method call with block");
 269         ANN("format: [nd_iter] { [nd_body] }");
 270         ANN("example: 3.times { foo }");
 271         goto iter;
 272       case NODE_FOR:
 273         ANN("for statement");
 274         ANN("format: for * in [nd_iter] do [nd_body] end");
 275         ANN("example: for i in 1..3 do foo end");
 276       iter:
 277         F_NODE(nd_iter, "iteration receiver");
 278         LAST_NODE;
 279         F_NODE(nd_body, "body");
 280         return;
 281
 282       case NODE_FOR_MASGN:
 283         ANN("vars of for statement with masgn");
 284         ANN("format: for [nd_var] in ... do ... end");
 285         ANN("example: for x, y in 1..3 do foo end");
 286         LAST_NODE;
 287         F_NODE(nd_var, "var");
 288         return;
 289
 290       case NODE_BREAK:
 291         ANN("break statement");
 292         ANN("format: break [nd_stts]");
 293         ANN("example: break 1");
 294         goto jump;
 295       case NODE_NEXT:
 296         ANN("next statement");
 297         ANN("format: next [nd_stts]");
 298         ANN("example: next 1");
 299         goto jump;
 300       case NODE_RETURN:
 301         ANN("return statement");
 302         ANN("format: return [nd_stts]");
 303         ANN("example: return 1");
 304       jump:
 305         LAST_NODE;
 306         F_NODE(nd_stts, "value");
 307         return;
 308
 309       case NODE_REDO:
 310         ANN("redo statement");
 311         ANN("format: redo");
 312         ANN("example: redo");
 313         return;
 314
 315       case NODE_RETRY:
 316         ANN("retry statement");
 317         ANN("format: retry");
 318         ANN("example: retry");
 319         return;
 320
 321       case NODE_BEGIN:
 322         ANN("begin statement");
 323         ANN("format: begin; [nd_body]; end");
 324         ANN("example: begin; 1; end");
 325         LAST_NODE;
 326         F_NODE(nd_body, "body");
 327         return;
 328
 329       case NODE_RESCUE:
 330         ANN("rescue clause");
 331         ANN("format: begin; [nd_body]; (rescue) [nd_resq]; else [nd_else]; end");
 332         ANN("example: begin; foo; rescue; bar; else; baz; end");
 333         F_NODE(nd_head, "body");
 334         F_NODE(nd_resq, "rescue clause list");
 335         LAST_NODE;
 336         F_NODE(nd_else, "rescue else clause");
 337         return;
 338
 339       case NODE_RESBODY:
 340         ANN("rescue clause (cont'd)");
 341         ANN("format: rescue [nd_args]; [nd_body]; (rescue) [nd_head]");
 342         ANN("example: begin; foo; rescue; bar; else; baz; end");
 343         F_NODE(nd_args, "rescue exceptions");
 344         F_NODE(nd_body, "rescue clause");
 345         LAST_NODE;
 346         F_NODE(nd_head, "next rescue clause");
 347         return;
 348
 349       case NODE_ENSURE:
 350         ANN("ensure clause");
 351         ANN("format: begin; [nd_head]; ensure; [nd_ensr]; end");
 352         ANN("example: begin; foo; ensure; bar; end");
 353         F_NODE(nd_head, "body");
 354         LAST_NODE;
 355         F_NODE(nd_ensr, "ensure clause");
 356         return;
 357
 358       case NODE_AND:
 359         ANN("&& operator");
 360         ANN("format: [nd_1st] && [nd_2nd]");
 361         ANN("example: foo && bar");
 362         goto andor;
 363       case NODE_OR:
 364         ANN("|| operator");
 365         ANN("format: [nd_1st] || [nd_2nd]");
 366         ANN("example: foo || bar");
 367       andor:
 368         while (1) {
 369             F_NODE(nd_1st, "left expr");
 370             if (!node->nd_2nd || !nd_type_p(node->nd_2nd, type))
 371                 break;
 372             node = node->nd_2nd;
 373         }
 374         LAST_NODE;
 375         F_NODE(nd_2nd, "right expr");
 376         return;
 377
 378       case NODE_MASGN:
 379         ANN("multiple assignment");
 380         ANN("format: [nd_head], [nd_args] = [nd_value]");
 381         ANN("example: a, b = foo");
 382         F_NODE(nd_value, "rhsn");
 383         F_NODE(nd_head, "lhsn");
 384         if (NODE_NAMED_REST_P(node->nd_args)) {
 385             LAST_NODE;
 386             F_NODE(nd_args, "splatn");
 387         }
 388         else {
 389             F_MSG(nd_args, "splatn", "NODE_SPECIAL_NO_NAME_REST (rest argument without name)");
 390         }
 391         return;
 392
 393       case NODE_LASGN:
 394         ANN("local variable assignment");
 395         ANN("format: [nd_vid](lvar) = [nd_value]");
 396         ANN("example: x = foo");
 397         F_ID(nd_vid, "local variable");
 398         if (NODE_REQUIRED_KEYWORD_P(node)) {
 399             F_MSG(nd_value, "rvalue", "NODE_SPECIAL_REQUIRED_KEYWORD (required keyword argument)");
 400         }
 401         else {
 402             LAST_NODE;
 403             F_NODE(nd_value, "rvalue");
 404         }
 405         return;
 406       case NODE_DASGN:
 407         ANN("dynamic variable assignment");
 408         ANN("format: [nd_vid](dvar) = [nd_value]");
 409         ANN("example: x = nil; 1.times { x = foo }");
 410         ANN("example: 1.times { x = foo }");
 411         F_ID(nd_vid, "local variable");
 412         if (NODE_REQUIRED_KEYWORD_P(node)) {
 413             F_MSG(nd_value, "rvalue", "NODE_SPECIAL_REQUIRED_KEYWORD (required keyword argument)");
 414         }
 415         else {
 416             LAST_NODE;
 417             F_NODE(nd_value, "rvalue");
 418         }
 419         return;
 420       case NODE_IASGN:
 421         ANN("instance variable assignment");
 422         ANN("format: [nd_vid](ivar) = [nd_value]");
 423         ANN("example: @x = foo");
 424         F_ID(nd_vid, "instance variable");
 425         LAST_NODE;
 426         F_NODE(nd_value, "rvalue");
 427         return;
 428       case NODE_CVASGN:
 429         ANN("class variable assignment");
 430         ANN("format: [nd_vid](cvar) = [nd_value]");
 431         ANN("example: @@x = foo");
 432         F_ID(nd_vid, "class variable");
 433         LAST_NODE;
 434         F_NODE(nd_value, "rvalue");
 435         return;
 436       case NODE_GASGN:
 437         ANN("global variable assignment");
 438         ANN("format: [nd_vid](gvar) = [nd_value]");
 439         ANN("example: $x = foo");
 440         F_ID(nd_vid, "global variable");
 441         LAST_NODE;
 442         F_NODE(nd_value, "rvalue");
 443         return;
 444
 445       case NODE_CDECL:
 446         ANN("constant declaration");
 447         ANN("format: [nd_else]::[nd_vid](constant) = [nd_value]");
 448         ANN("example: X = foo");
 449         if (node->nd_vid) {
 450             F_ID(nd_vid, "constant");
 451             F_MSG(nd_else, "extension", "not used");
 452         }
 453         else {
 454             F_MSG(nd_vid, "constant", "0 (see extension field)");
 455             F_NODE(nd_else, "extension");
 456         }
 457         LAST_NODE;
 458         F_NODE(nd_value, "rvalue");
 459         return;
 460
 461       case NODE_OP_ASGN1:
 462         ANN("array assignment with operator");
 463         ANN("format: [nd_recv] [ [nd_args->nd_head] ] [nd_mid]= [nd_args->nd_body]");
 464         ANN("example: ary[1] += foo");
 465         F_NODE(nd_recv, "receiver");
 466         F_ID(nd_mid, "operator");
 467         F_NODE(nd_args->nd_head, "index");
 468         LAST_NODE;
 469         F_NODE(nd_args->nd_body, "rvalue");
 470         return;
 471
 472       case NODE_OP_ASGN2:
 473         ANN("attr assignment with operator");
 474         ANN("format: [nd_recv].[attr] [nd_next->nd_mid]= [nd_value]");
 475         ANN("          where [attr]: [nd_next->nd_vid]");
 476         ANN("example: struct.field += foo");
 477         F_NODE(nd_recv, "receiver");
 478         F_CUSTOM1(nd_next->nd_vid, "attr") {
 479             if (node->nd_next->nd_aid) A("? ");
 480             A_ID(node->nd_next->nd_vid);
 481         }
 482         F_ID(nd_next->nd_mid, "operator");
 483         LAST_NODE;
 484         F_NODE(nd_value, "rvalue");
 485         return;
 486
 487       case NODE_OP_ASGN_AND:
 488         ANN("assignment with && operator");
 489         ANN("format: [nd_head] &&= [nd_value]");
 490         ANN("example: foo &&= bar");
 491         goto asgn_andor;
 492       case NODE_OP_ASGN_OR:
 493         ANN("assignment with || operator");
 494         ANN("format: [nd_head] ||= [nd_value]");
 495         ANN("example: foo ||= bar");
 496       asgn_andor:
 497         F_NODE(nd_head, "variable");
 498         LAST_NODE;
 499         F_NODE(nd_value, "rvalue");
 500         return;
 501
 502       case NODE_OP_CDECL:
 503         ANN("constant declaration with operator");
 504         ANN("format: [nd_head](constant) [nd_aid]= [nd_value]");
 505         ANN("example: A::B ||= 1");
 506         F_NODE(nd_head, "constant");
 507         F_ID(nd_aid, "operator");
 508         LAST_NODE;
 509         F_NODE(nd_value, "rvalue");
 510         return;
 511
 512       case NODE_CALL:
 513         ANN("method invocation");
 514         ANN("format: [nd_recv].[nd_mid]([nd_args])");
 515         ANN("example: obj.foo(1)");
 516         F_ID(nd_mid, "method id");
 517         F_NODE(nd_recv, "receiver");
 518         LAST_NODE;
 519         F_NODE(nd_args, "arguments");
 520         return;
 521
 522       case NODE_OPCALL:
 523         ANN("method invocation");
 524         ANN("format: [nd_recv] [nd_mid] [nd_args]");
 525         ANN("example: foo + bar");
 526         F_ID(nd_mid, "method id");
 527         F_NODE(nd_recv, "receiver");
 528         LAST_NODE;
 529         F_NODE(nd_args, "arguments");
 530         return;
 531
 532       case NODE_FCALL:
 533         ANN("function call");
 534         ANN("format: [nd_mid]([nd_args])");
 535         ANN("example: foo(1)");
 536         F_ID(nd_mid, "method id");
 537         LAST_NODE;
 538         F_NODE(nd_args, "arguments");
 539         return;
 540
 541       case NODE_VCALL:
 542         ANN("function call with no argument");
 543         ANN("format: [nd_mid]");
 544         ANN("example: foo");
 545         F_ID(nd_mid, "method id");
 546         return;
 547
 548       case NODE_QCALL:
 549         ANN("safe method invocation");
 550         ANN("format: [nd_recv]&.[nd_mid]([nd_args])");
 551         ANN("example: obj&.foo(1)");
 552         F_ID(nd_mid, "method id");
 553         F_NODE(nd_recv, "receiver");
 554         LAST_NODE;
 555         F_NODE(nd_args, "arguments");
 556         return;
 557
 558       case NODE_SUPER:
 559         ANN("super invocation");
 560         ANN("format: super [nd_args]");
 561         ANN("example: super 1");
 562         LAST_NODE;
 563         F_NODE(nd_args, "arguments");
 564         return;
 565
 566       case NODE_ZSUPER:
 567         ANN("super invocation with no argument");
 568         ANN("format: super");
 569         ANN("example: super");
 570         return;
 571
 572       case NODE_LIST:
 573         ANN("list constructor");
 574         ANN("format: [ [nd_head], [nd_next].. ] (length: [nd_alen])");
 575         ANN("example: [1, 2, 3]");
 576         goto ary;
 577       case NODE_VALUES:
 578         ANN("return arguments");
 579         ANN("format: [ [nd_head], [nd_next].. ] (length: [nd_alen])");
 580         ANN("example: return 1, 2, 3");
 581       ary:
 582         dump_array(buf, indent, comment, node);
 583         return;
 584
 585       case NODE_ZLIST:
 586         ANN("empty list constructor");
 587         ANN("format: []");
 588         ANN("example: []");
 589         return;
 590
 591       case NODE_HASH:
 592         if (!node->nd_brace) {
 593             ANN("keyword arguments");
 594             ANN("format: [nd_head]");
 595             ANN("example: a: 1, b: 2");
 596         }
 597         else {
 598             ANN("hash constructor");
 599             ANN("format: { [nd_head] }");
 600             ANN("example: { 1 => 2, 3 => 4 }");
 601         }
 602         F_CUSTOM1(nd_brace, "keyword arguments or hash literal") {
 603             switch (node->nd_brace) {
 604               case 0: A("0 (keyword argument)"); break;
 605               case 1: A("1 (hash literal)"); break;
 606             }
 607         }
 608         LAST_NODE;
 609         F_NODE(nd_head, "contents");
 610         return;
 611
 612       case NODE_YIELD:
 613         ANN("yield invocation");
 614         ANN("format: yield [nd_head]");
 615         ANN("example: yield 1");
 616         LAST_NODE;
 617         F_NODE(nd_head, "arguments");
 618         return;
 619
 620       case NODE_LVAR:
 621         ANN("local variable reference");
 622         ANN("format: [nd_vid](lvar)");
 623         ANN("example: x");
 624         F_ID(nd_vid, "local variable");
 625         return;
 626       case NODE_DVAR:
 627         ANN("dynamic variable reference");
 628         ANN("format: [nd_vid](dvar)");
 629         ANN("example: 1.times { x = 1; x }");
 630         F_ID(nd_vid, "local variable");
 631         return;
 632       case NODE_IVAR:
 633         ANN("instance variable reference");
 634         ANN("format: [nd_vid](ivar)");
 635         ANN("example: @x");
 636         F_ID(nd_vid, "instance variable");
 637         return;
 638       case NODE_CONST:
 639         ANN("constant reference");
 640         ANN("format: [nd_vid](constant)");
 641         ANN("example: X");
 642         F_ID(nd_vid, "constant");
 643         return;
 644       case NODE_CVAR:
 645         ANN("class variable reference");
 646         ANN("format: [nd_vid](cvar)");
 647         ANN("example: @@x");
 648         F_ID(nd_vid, "class variable");
 649         return;
 650
 651       case NODE_GVAR:
 652         ANN("global variable reference");
 653         ANN("format: [nd_vid](gvar)");
 654         ANN("example: $x");
 655         F_ID(nd_vid, "global variable");
 656         return;
 657
 658       case NODE_NTH_REF:
 659         ANN("nth special variable reference");
 660         ANN("format: $[nd_nth]");
 661         ANN("example: $1, $2, ..");
 662         F_CUSTOM1(nd_nth, "variable") { A("$"); A_LONG(node->nd_nth); }
 663         return;
 664
 665       case NODE_BACK_REF:
 666         ANN("back special variable reference");
 667         ANN("format: $[nd_nth]");
 668         ANN("example: $&, $`, $', $+");
 669         F_CUSTOM1(nd_nth, "variable") {
 670             char name[3] = "$ ";
 671             name[1] = (char)node->nd_nth;
 672             A(name);
 673         }
 674         return;
 675
 676       case NODE_MATCH:
 677         ANN("match expression (against $_ implicitly)");
 678         ANN("format: [nd_lit] (in condition)");
 679         ANN("example: if /foo/; foo; end");
 680         F_LIT(nd_lit, "regexp");
 681         return;
 682
 683       case NODE_MATCH2:
 684         ANN("match expression (regexp first)");
 685         ANN("format: [nd_recv] =~ [nd_value]");
 686         ANN("example: /foo/ =~ 'foo'");
 687         F_NODE(nd_recv, "regexp (receiver)");
 688         if (!node->nd_args) LAST_NODE;
 689         F_NODE(nd_value, "string (argument)");
 690         if (node->nd_args) {
 691             LAST_NODE;
 692             F_NODE(nd_args, "named captures");
 693         }
 694         return;
 695
 696       case NODE_MATCH3:
 697         ANN("match expression (regexp second)");
 698         ANN("format: [nd_recv] =~ [nd_value]");
 699         ANN("example: 'foo' =~ /foo/");
 700         F_NODE(nd_recv, "string (receiver)");
 701         LAST_NODE;
 702         F_NODE(nd_value, "regexp (argument)");
 703         return;
 704
 705       case NODE_LIT:
 706         ANN("literal");
 707         ANN("format: [nd_lit]");
 708         ANN("example: 1, /foo/");
 709         goto lit;
 710       case NODE_STR:
 711         ANN("string literal");
 712         ANN("format: [nd_lit]");
 713         ANN("example: 'foo'");
 714         goto lit;
 715       case NODE_XSTR:
 716         ANN("xstring literal");
 717         ANN("format: [nd_lit]");
 718         ANN("example: `foo`");
 719       lit:
 720         F_LIT(nd_lit, "literal");
 721         return;
 722
 723       case NODE_ONCE:
 724         ANN("once evaluation");
 725         ANN("format: [nd_body]");
 726         ANN("example: /foo#{ bar }baz/o");
 727         LAST_NODE;
 728         F_NODE(nd_body, "body");
 729         return;
 730       case NODE_DSTR:
 731         ANN("string literal with interpolation");
 732         ANN("format: [nd_lit]");
 733         ANN("example: \"foo#{ bar }baz\"");
 734         goto dlit;
 735       case NODE_DXSTR:
 736         ANN("xstring literal with interpolation");
 737         ANN("format: [nd_lit]");
 738         ANN("example: `foo#{ bar }baz`");
 739         goto dlit;
 740       case NODE_DREGX:
 741         ANN("regexp literal with interpolation");
 742         ANN("format: [nd_lit]");
 743         ANN("example: /foo#{ bar }baz/");
 744         goto dlit;
 745       case NODE_DSYM:
 746         ANN("symbol literal with interpolation");
 747         ANN("format: [nd_lit]");
 748         ANN("example: :\"foo#{ bar }baz\"");
 749       dlit:
 750         F_LIT(nd_lit, "preceding string");
 751         if (!node->nd_next) return;
 752         F_NODE(nd_next->nd_head, "interpolation");
 753         LAST_NODE;
 754         F_NODE(nd_next->nd_next, "tailing strings");
 755         return;
 756
 757       case NODE_EVSTR:
 758         ANN("interpolation expression");
 759         ANN("format: \"..#{ [nd_body] }..\"");
 760         ANN("example: \"foo#{ bar }baz\"");
 761         LAST_NODE;
 762         F_NODE(nd_body, "body");
 763         return;
 764
 765       case NODE_ARGSCAT:
 766         ANN("splat argument following arguments");
 767         ANN("format: ..(*[nd_head], [nd_body..])");
 768         ANN("example: foo(*ary, post_arg1, post_arg2)");
 769         F_NODE(nd_head, "preceding array");
 770         LAST_NODE;
 771         F_NODE(nd_body, "following array");
 772         return;
 773
 774       case NODE_ARGSPUSH:
 775         ANN("splat argument following one argument");
 776         ANN("format: ..(*[nd_head], [nd_body])");
 777         ANN("example: foo(*ary, post_arg)");
 778         F_NODE(nd_head, "preceding array");
 779         LAST_NODE;
 780         F_NODE(nd_body, "following element");
 781         return;
 782
 783       case NODE_SPLAT:
 784         ANN("splat argument");
 785         ANN("format: *[nd_head]");
 786         ANN("example: foo(*ary)");
 787         LAST_NODE;
 788         F_NODE(nd_head, "splat'ed array");
 789         return;
 790
 791       case NODE_BLOCK_PASS:
 792         ANN("arguments with block argument");
 793         ANN("format: ..([nd_head], &[nd_body])");
 794         ANN("example: foo(x, &blk)");
 795         F_NODE(nd_head, "other arguments");
 796         LAST_NODE;
 797         F_NODE(nd_body, "block argument");
 798         return;
 799
 800       case NODE_DEFN:
 801         ANN("method definition");
 802         ANN("format: def [nd_mid] [nd_defn]; end");
 803         ANN("example: def foo; bar; end");
 804         F_ID(nd_mid, "method name");
 805         LAST_NODE;
 806         F_NODE(nd_defn, "method definition");
 807         return;
 808
 809       case NODE_DEFS:
 810         ANN("singleton method definition");
 811         ANN("format: def [nd_recv].[nd_mid] [nd_defn]; end");
 812         ANN("example: def obj.foo; bar; end");
 813         F_NODE(nd_recv, "receiver");
 814         F_ID(nd_mid, "method name");
 815         LAST_NODE;
 816         F_NODE(nd_defn, "method definition");
 817         return;
 818
 819       case NODE_ALIAS:
 820         ANN("method alias statement");
 821         ANN("format: alias [nd_1st] [nd_2nd]");
 822         ANN("example: alias bar foo");
 823         F_NODE(nd_1st, "new name");
 824         LAST_NODE;
 825         F_NODE(nd_2nd, "old name");
 826         return;
 827
 828       case NODE_VALIAS:
 829         ANN("global variable alias statement");
 830         ANN("format: alias [nd_alias](gvar) [nd_orig](gvar)");
 831         ANN("example: alias $y $x");
 832         F_ID(nd_alias, "new name");
 833         F_ID(nd_orig, "old name");
 834         return;
 835
 836       case NODE_UNDEF:
 837         ANN("method undef statement");
 838         ANN("format: undef [nd_undef]");
 839         ANN("example: undef foo");
 840         LAST_NODE;
 841         F_NODE(nd_undef, "old name");
 842         return;
 843
 844       case NODE_CLASS:
 845         ANN("class definition");
 846         ANN("format: class [nd_cpath] < [nd_super]; [nd_body]; end");
 847         ANN("example: class C2 < C; ..; end");
 848         F_NODE(nd_cpath, "class path");
 849         F_NODE(nd_super, "superclass");
 850         LAST_NODE;
 851         F_NODE(nd_body, "class definition");
 852         return;
 853
 854       case NODE_MODULE:
 855         ANN("module definition");
 856         ANN("format: module [nd_cpath]; [nd_body]; end");
 857         ANN("example: module M; ..; end");
 858         F_NODE(nd_cpath, "module path");
 859         LAST_NODE;
 860         F_NODE(nd_body, "module definition");
 861         return;
 862
 863       case NODE_SCLASS:
 864         ANN("singleton class definition");
 865         ANN("format: class << [nd_recv]; [nd_body]; end");
 866         ANN("example: class << obj; ..; end");
 867         F_NODE(nd_recv, "receiver");
 868         LAST_NODE;
 869         F_NODE(nd_body, "singleton class definition");
 870         return;
 871
 872       case NODE_COLON2:
 873         ANN("scoped constant reference");
 874         ANN("format: [nd_head]::[nd_mid]");
 875         ANN("example: M::C");
 876         F_ID(nd_mid, "constant name");
 877         LAST_NODE;
 878         F_NODE(nd_head, "receiver");
 879         return;
 880
 881       case NODE_COLON3:
 882         ANN("top-level constant reference");
 883         ANN("format: ::[nd_mid]");
 884         ANN("example: ::Object");
 885         F_ID(nd_mid, "constant name");
 886         return;
 887
 888       case NODE_DOT2:
 889         ANN("range constructor (incl.)");
 890         ANN("format: [nd_beg]..[nd_end]");
 891         ANN("example: 1..5");
 892         goto dot;
 893       case NODE_DOT3:
 894         ANN("range constructor (excl.)");
 895         ANN("format: [nd_beg]...[nd_end]");
 896         ANN("example: 1...5");
 897         goto dot;
 898       case NODE_FLIP2:
 899         ANN("flip-flop condition (incl.)");
 900         ANN("format: [nd_beg]..[nd_end]");
 901         ANN("example: if (x==1)..(x==5); foo; end");
 902         goto dot;
 903       case NODE_FLIP3:
 904         ANN("flip-flop condition (excl.)");
 905         ANN("format: [nd_beg]...[nd_end]");
 906         ANN("example: if (x==1)...(x==5); foo; end");
 907       dot:
 908         F_NODE(nd_beg, "begin");
 909         LAST_NODE;
 910         F_NODE(nd_end, "end");
 911         return;
 912
 913       case NODE_SELF:
 914         ANN("self");
 915         ANN("format: self");
 916         ANN("example: self");
 917         return;
 918
 919       case NODE_NIL:
 920         ANN("nil");
 921         ANN("format: nil");
 922         ANN("example: nil");
 923         return;
 924
 925       case NODE_TRUE:
 926         ANN("true");
 927         ANN("format: true");
 928         ANN("example: true");
 929         return;
 930
 931       case NODE_FALSE:
 932         ANN("false");
 933         ANN("format: false");
 934         ANN("example: false");
 935         return;
 936
 937       case NODE_ERRINFO:
 938         ANN("virtual reference to $!");
 939         ANN("format: rescue => id");
 940         ANN("example: rescue => id");
 941         return;
 942
 943       case NODE_DEFINED:
 944         ANN("defined? expression");
 945         ANN("format: defined?([nd_head])");
 946         ANN("example: defined?(foo)");
 947         F_NODE(nd_head, "expr");
 948         return;
 949
 950       case NODE_POSTEXE:
 951         ANN("post-execution");
 952         ANN("format: END { [nd_body] }");
 953         ANN("example: END { foo }");
 954         LAST_NODE;
 955         F_NODE(nd_body, "END clause");
 956         return;
 957
 958       case NODE_ATTRASGN:
 959         ANN("attr assignment");
 960         ANN("format: [nd_recv].[nd_mid] = [nd_args]");
 961         ANN("example: struct.field = foo");
 962         F_NODE(nd_recv, "receiver");
 963         F_ID(nd_mid, "method name");
 964         LAST_NODE;
 965         F_NODE(nd_args, "arguments");
 966         return;
 967
 968       case NODE_LAMBDA:
 969         ANN("lambda expression");
 970         ANN("format: -> [nd_body]");
 971         ANN("example: -> { foo }");
 972         LAST_NODE;
 973         F_NODE(nd_body, "lambda clause");
 974         return;
 975
 976       case NODE_OPT_ARG:
 977         ANN("optional arguments");
 978         ANN("format: def method_name([nd_body=some], [nd_next..])");
 979         ANN("example: def foo(a, b=1, c); end");
 980         F_NODE(nd_body, "body");
 981         LAST_NODE;
 982         F_NODE(nd_next, "next");
 983         return;
 984
 985       case NODE_KW_ARG:
 986         ANN("keyword arguments");
 987         ANN("format: def method_name([nd_body=some], [nd_next..])");
 988         ANN("example: def foo(a:1, b:2); end");
 989         F_NODE(nd_body, "body");
 990         LAST_NODE;
 991         F_NODE(nd_next, "next");
 992         return;
 993
 994       case NODE_POSTARG:
 995         ANN("post arguments");
 996         ANN("format: *[nd_1st], [nd_2nd..] = ..");
 997         ANN("example: a, *rest, z = foo");
 998         if (NODE_NAMED_REST_P(node->nd_1st)) {
 999             F_NODE(nd_1st, "rest argument");
1000         }
1001         else {
1002             F_MSG(nd_1st, "rest argument", "NODE_SPECIAL_NO_NAME_REST (rest argument without name)");
1003         }
1004         LAST_NODE;
1005         F_NODE(nd_2nd, "post arguments");
1006         return;
1007
1008       case NODE_ARGS:
1009         ANN("method parameters");
1010         ANN("format: def method_name(.., [nd_ainfo->nd_optargs], *[nd_ainfo->rest_arg], [nd_ainfo->first_post_arg], .., [nd_ainfo->kw_args], **[nd_ainfo->kw_rest_arg], &[nd_ainfo->block_arg])");
1011         ANN("example: def foo(a, b, opt1=1, opt2=2, *rest, y, z, kw: 1, **kwrest, &blk); end");
1012         F_INT(nd_ainfo->pre_args_num, "count of mandatory (pre-)arguments");
1013         F_NODE(nd_ainfo->pre_init, "initialization of (pre-)arguments");
1014         F_INT(nd_ainfo->post_args_num, "count of mandatory post-arguments");
1015         F_NODE(nd_ainfo->post_init, "initialization of post-arguments");
1016         F_ID(nd_ainfo->first_post_arg, "first post argument");
1017         F_CUSTOM1(nd_ainfo->rest_arg, "rest argument") {
1018             if (node->nd_ainfo->rest_arg == NODE_SPECIAL_EXCESSIVE_COMMA) {
1019                 A("1 (excessed comma)");
1020             }
1021             else {
1022                 A_ID(node->nd_ainfo->rest_arg);
1023             }
1024         }
1025         F_ID(nd_ainfo->block_arg, "block argument");
1026         F_NODE(nd_ainfo->opt_args, "optional arguments");
1027         F_NODE(nd_ainfo->kw_args, "keyword arguments");
1028         LAST_NODE;
1029         F_NODE(nd_ainfo->kw_rest_arg, "keyword rest argument");
1030         return;
1031
1032       case NODE_SCOPE:
1033         ANN("new scope");
1034         ANN("format: [nd_tbl]: local table, [nd_args]: arguments, [nd_body]: body");
1035         F_CUSTOM1(nd_tbl, "local table") {
1036             rb_ast_id_table_t *tbl = node->nd_tbl;
1037             int i;
1038             int size = tbl ? tbl->size : 0;
1039             if (size == 0) A("(empty)");
1040             for (i = 0; i < size; i++) {
1041                 A_ID(tbl->ids[i]); if (i < size - 1) A(",");
1042             }
1043         }
1044         F_NODE(nd_args, "arguments");
1045         LAST_NODE;
1046         F_NODE(nd_body, "body");
1047         return;
1048
1049       case NODE_ARYPTN:
1050         ANN("array pattern");
1051         ANN("format: [nd_pconst]([pre_args], ..., *[rest_arg], [post_args], ...)");
1052         F_NODE(nd_pconst, "constant");
1053         F_NODE(nd_apinfo->pre_args, "pre arguments");
1054         if (NODE_NAMED_REST_P(node->nd_apinfo->rest_arg)) {
1055             F_NODE(nd_apinfo->rest_arg, "rest argument");
1056         }
1057         else {
1058             F_MSG(nd_apinfo->rest_arg, "rest argument", "NODE_SPECIAL_NO_NAME_REST (rest argument without name)");
1059         }
1060         LAST_NODE;
1061         F_NODE(nd_apinfo->post_args, "post arguments");
1062         return;
1063
1064       case NODE_FNDPTN:
1065         ANN("find pattern");
1066         ANN("format: [nd_pconst](*[pre_rest_arg], args, ..., *[post_rest_arg])");
1067         F_NODE(nd_pconst, "constant");
1068         if (NODE_NAMED_REST_P(node->nd_fpinfo->pre_rest_arg)) {
1069             F_NODE(nd_fpinfo->pre_rest_arg, "pre rest argument");
1070         }
1071         else {
1072             F_MSG(nd_fpinfo->pre_rest_arg, "pre rest argument", "NODE_SPECIAL_NO_NAME_REST (rest argument without name)");
1073         }
1074         F_NODE(nd_fpinfo->args, "arguments");
1075
1076         LAST_NODE;
1077         if (NODE_NAMED_REST_P(node->nd_fpinfo->post_rest_arg)) {
1078             F_NODE(nd_fpinfo->post_rest_arg, "post rest argument");
1079         }
1080         else {
1081             F_MSG(nd_fpinfo->post_rest_arg, "post rest argument", "NODE_SPECIAL_NO_NAME_REST (rest argument without name)");
1082         }
1083         return;
1084
1085       case NODE_HSHPTN:
1086         ANN("hash pattern");
1087         ANN("format: [nd_pconst]([nd_pkwargs], ..., **[nd_pkwrestarg])");
1088         F_NODE(nd_pconst, "constant");
1089         F_NODE(nd_pkwargs, "keyword arguments");
1090         LAST_NODE;
1091         if (node->nd_pkwrestarg == NODE_SPECIAL_NO_REST_KEYWORD) {
1092             F_MSG(nd_pkwrestarg, "keyword rest argument", "NODE_SPECIAL_NO_REST_KEYWORD (**nil)");
1093         }
1094         else {
1095             F_NODE(nd_pkwrestarg, "keyword rest argument");
1096         }
1097         return;
1098       case NODE_ERROR:
1099         ANN("Broken input recovered by Error Tolerant mode");
1100         return;
1101
1102       case NODE_ARGS_AUX:
1103       case NODE_LAST:
1104         break;
1105     }
1106
1107     rb_bug("dump_node: unknown node: %s", ruby_node_name(nd_type(node)));
1108 }
1109
1110 VALUE
1111 rb_parser_dump_tree(const NODE *node, int comment)
1112 {
1113     VALUE buf = rb_str_new_cstr(
1114         "###########################################################\n"
1115         "## Do NOT use this node dump for any purpose other than  ##\n"
1116         "## debug and research.  Compatibility is not guaranteed. ##\n"
1117         "###########################################################\n\n"
1118     );
1119     dump_node(buf, rb_str_new_cstr("# "), comment, node);
1120     return buf;
1121 }