README.rdoc

RKelly Turbo¶ ↑

github.com/hmdne/rkelly-turbo

DESCRIPTION¶ ↑

RKelly Turbo is a fork of the RKelly Remix which in turn is a fork of RKelly JavaScript parser.

Install¶ ↑

gem install rkelly-turbo

Note that you can’t have rkelly, rkelly-remix, rkelly-turbo (any two) installed at the same time. That would cause a conflict since they’re all included with:

require 'rkelly'

Example¶ ↑

# Iterate over and modify a JavaScript AST.  Then print the modified
# AST as JavaScript.
require 'rkelly'

parser = RKelly::Parser.new
ast    = parser.parse(
  "for(var i = 0; i < 10; i++) { var x = 5 + 5; }"
)

ast.each do |node|
  node.value  = 'hello' if node.value == 'i'
  node.name   = 'hello' if node.respond_to?(:name) && node.name == 'i'
end
puts ast.to_ecma # => awesome javascript

Why fork?¶ ↑

Currently the original RKelly project is unmaintained. The latest release was in late 2012, and since then the author has not responded to bug reports or pull requests.

I created this fork mainly to satisfy the needs of my JSDuck project, but you too should consider using it, as it fixes several problems in the original RKelly:

Much improved speed¶ ↑

• 20 x faster in Ruby 1.8.

• 2 x faster in Ruby 1.9 and 2.0.

Correct start/end position data for all syntax nodes¶ ↑

Original RKelly only had a rudimentary support for getting the line number of an AST node, and even that was often wrong.

In RKelly Remix each AST node has a range property, which contains granular data about the exact location of the node in source code:

parser = RKelly::Parser.new
ast = parser.parse(<<-eojs)
  function aaron() {
    var x = 10;
    return 1 + 1;
  }
eojs

node = ast.pointcut(ReturnNode).matches.first

node.range.to_s  # <{line:3 char:5 (41)}...{line:3 char:17 (53)}>

node.range.from.line   # 3
node.range.from.char   # 5
node.range.from.index  # 41

node.range.to.line     # 3
node.range.to.char     # 17
node.range.to.index    # 53

Sensible comments handling¶ ↑

Original RKelly attempted to associate each comment with a related AST node, but failed to correctly do so, which is understandable, as there is no standard way to do such a mapping. RKelly Remix abandons this and just lists all commenst in the root node, leaving the user with the task of associating them with AST nodes if he desires so (the same approach is taken by another JS parser: Esprima ).

parser = RKelly::Parser.new
ast = parser.parse(<<-eojs)
  /**
   * This is an awesome test comment.
   */
  function aaron() { // This is a side comment
    var x = 10;
    return 1 + 1; // Equals two!
  }
eojs

# print out all the comments
ast.comments.each do |c|
  puts c.value
end

Improved parser¶ ↑

• List of reserved words matches with ECMAScript 5.1.

• Keywords are allowed in property names.

• Multibyte characters are supported in Ruby >= 1.9.

• Correct parsing of regexes like /[/]/

License¶ ↑

The MIT License

Copyright © 2007, 2008, 2009, 2021 Aaron Patterson, John Barnette, hmdne

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE