= RKelly Remix

https://github.com/nene/rkelly-remix

== DESCRIPTION

RKelly Remix is a fork of the
RKelly[https://github.com/tenderlove/rkelly] JavaScript parser.

== Install

  gem install rkelly-remix

Note that you can't have rkelly and rkelly-remix both installed at the
same time.  That would cause a conflict since they're both 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[https://github.com/senchalabs/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[http://esprima.org] ).

  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 (c) 2007, 2008, 2009 Aaron Patterson, John Barnette

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
