Update parser-related documentation

Author: eregon

doc/contributor/parser.md

@@ -8,14 +8,67 @@
 
 ## Print Detailed Prism AST
 
+### From the Prism repository
+
 ```bash
-cd prism
-bundle exec rake
-bin/parse -e '1&.itself'
+$ cd prism
+$ bundle exec rake compile
+$ bin/parse -e '1&.itself'
+@ ProgramNode (location: (1,0)-(1,9))
+├── locals: []
+└── statements:
+    @ StatementsNode (location: (1,0)-(1,9))
+    └── body: (length: 1)
+        └── @ CallNode (location: (1,0)-(1,9))
+            ├── flags: safe_navigation
+            ├── receiver:
+            │   @ IntegerNode (location: (1,0)-(1,1))
+            │   └── flags: decimal
+            ├── call_operator_loc: (1,1)-(1,3) = "&."
+            ├── name: :itself
+            ├── message_loc: (1,3)-(1,9) = "itself"
+            ├── opening_loc: ∅
+            ├── arguments: ∅
+            ├── closing_loc: ∅
+            └── block: ∅
 ```
 
+### From TruffleRuby
+
 We can also see what the AST as Java nodes and without extra location fields looks like on TruffleRuby with:
 ```bash
-cd truffleruby
-jt -q ruby -e 'puts Truffle::Debug.yarp_parse(ARGV[0])' -- '1&.itself'
+$ cd truffleruby
+$ t -q ruby tool/parse_ast.rb '1&.itself'
+Source:
+1&.itself
+
+AST:
+ProgramNode
+  locals:
+  statements: StatementsNode
+    body:
+      CallNode[Li]
+        flags: 1
+        receiver: IntegerNode
+          flags: 2
+        name: "itself"
+        arguments: null
+        block: null
+```
+
+```bash
+$ jt -q ruby tool/parse_ast.rb some_file.rb
+```
+
+You can also compare to JRuby's AST with:
+```bash
+$ jruby tool/parse_ast.rb '1&.itself'
+Source:
+1&.itself
+
+AST:
+RootNode line: 0
+  CallNode*[lazy]:itself line: 0
+    FixnumNode line: 0, long: 1
+, null, null
 ```

doc/contributor/prism.md

@@ -321,9 +321,3 @@ file to fix it.
 
 You can also recompute the tags automatically for an entire test file with
 `jt retag test/mri/tests/file.rb`.
-
-## Building the parser
-
-TruffleRuby uses the Jay parser generator. A copy of this is located in
-`tool/jay`. The command `jt build parser` will build Jay, if needed, and then
-regenerate the parser. We check the generated parser into the source repository.

doc/contributor/updating-jruby-parser.md

@@ -208,14 +208,6 @@ Engine Yard and are released under an MIT licence (see `mit.txt`).
 We do not distribute the FFI Specs, but they are copyright 2008-2014
 Ruby-FFI contributors and are released under an MIT licence (see `mit.txt`).
 
-## Jay
-
-TruffleRuby uses the Jay parser generator, modified from
-https://github.com/jruby/jay revision `9ffc59a`. Jay is copyright 1989 The
-Regents of the University of California, ported by Axel T. Schreiner, and is
-covered by the three-clause BSD licence (see `jay.txt`). We only distribute Jay
-in the source repository - it isn't part of releases.
-
 ## Written offer for source code
 
 For any software that you receive from Oracle in binary form which is licensed

doc/contributor/workflow.md

@@ -44,11 +44,12 @@ def indent(string)
 puts code
 puts
 
-print "AST:"
 if RUBY_ENGINE == "jruby"
+  print "AST:"
   require 'jruby'
   ast_to_string = JRuby.parse(code).to_string
 else
+  puts "AST:"
   ast_to_string = Truffle::Debug.parse_ast(code)
 end
 puts indent(ast_to_string)