parsejs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 41b39d4f01ad6648dbb147d8cf758bb0b5cd45ff
+  data.tar.gz: 3877eb40098d127ed7a2a036f2ceee54983e2c6b
+SHA512:
+  metadata.gz: e4fe5a4c22dea6bb05393054ea312a3eedf38bc76b083b24a73cc0b23736889fb9ca2a8019dd7e8a5cfd0cdd2cbd90d8a87264086746d7bc68f3bd16d13bcd1f
+  data.tar.gz: e56c48ca152263de721598472e4b03ac2145455193dd38e4d37dcee4fd66f79a402963e1cd90ec843142050e2e5d4731b937a477f7b972ad78a02fad7d910a49

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbx
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+bin

data/.rspec

@@ -0,0 +1 @@
+-cfs

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+  - rbx-18mode
+  - rbx-19mode
+script: rake spec

data/Gemfile

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gemspec
+
+gem "pry"

data/README.markdown

@@ -0,0 +1,85 @@
+# ParseJS
+
+ParseJS is a JavaScript parser written in Ruby using the KPeg parser generator. It also
+takes a JavaScript parse tree and emits semantically identical JavaScript. The parser is
+tested by parsing large, popular JavaScript libraries (such as jQuery) and confirming that
+the minified output after a round-trip through ParseJS is the same as minifying the original
+source.
+
+The ParseJS stringifier does not guarantee equivalent whitespace and comments in a
+round-trip, but it should guarantee semantic equivalence.
+
+The ParseJS parser maintains comments in most cases where comments would represent inline
+documentation.
+
+* top-level statement: a ParseJS top-level statement node contains any comment that
+	immediately preceded it.
+* property: in a property list (object literal), a property node contains any comment
+	that immediately preceded it.
+
+There is a work-in-progress AST walker that associates comments with particular structures.
+The ultimate goal of this walker is to identify JavaScript structures that represent
+"classes" or similar structures and associate their comments with information extracted
+from the code.
+
+# Usage
+
+ParseJS is provided as a Rubygem. At the moment, you can use it in your Gemfile by using
+Bundler's git feature.
+
+```ruby
+gem "parsejs", :git => "git://github.com/wycats/parsejs.git"
+```
+
+You can parse a String of JavaScript and receive an AST by using
+`ParseJS.parse`.
+
+```ruby
+ast = ParseJS.parse(some_data)
+```
+
+You can convert the AST back into a JavaScript String using the
+stringifier. You can mutate the AST before converting it into a String
+if you wish.
+
+```
+ParseJS::Stringifier.to_string(ast)
+```
+
+You can write your own AST walker without implementing visitors for all
+nodes by subclassing `ParseJS::Visitor`. Take a look
+[at that class](https://github.com/wycats/parsejs/blob/master/lib/parsejs/visitor.rb)
+to see the default visitor behavior for a particular node.
+
+By default, nodes `accept` their children. Nodes that have children that
+are `Array`s of nodes (e.g. `FunctionDeclaration`, which has an `Array` of
+parameters and an `Array` of statements as children) default to looping
+over the `Array`s and accepting their members.
+
+You can take a look at the in-progress
+[docs extractor](https://github.com/wycats/parsejs/blob/master/lib/parsejs/docs.rb)
+or the [stringifier](https://github.com/wycats/parsejs/blob/master/lib/parsejs/stringifier.rb)
+for examples of subclasses of `ParseJS::Visitor`.
+
+# LICENSE
+
+Copyright (C) 2012 Yehuda Katz
+
+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.
+

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "bundler/setup"
+
+file "lib/parsejs/grammar.kpeg.rb" => "lib/parsejs/grammar.kpeg" do
+  sh "kpeg -f lib/parsejs/grammar.kpeg --stand-alone --debug"
+end
+
+task :compile => "lib/parsejs/grammar.kpeg.rb"
+
+task :spec => :compile do
+  sh "rspec -cfs spec"
+end
+
+task :default => :compile

data/lib/parsejs.rb

@@ -0,0 +1,14 @@
+require "parsejs/version"
+require "parsejs/grammar.kpeg"
+require "parsejs/stringifier"
+require "parsejs/ast"
+require "parsejs/scope"
+
+module ParseJS
+  def self.parse(string)
+    string = string.force_encoding('BINARY') if string.respond_to?(:force_encoding)
+    parser = ParseJS::Parser.new(string)
+    parser.parse
+    parser.result
+  end
+end

data/lib/parsejs/ast.rb

@@ -0,0 +1,84 @@
+require "parsejs/scope"
+
+module ParseJS
+  module AST
+    class Node
+      def type?(string)
+        self.class.name.split("::").last == string
+      end
+
+      def cuddly?
+        false
+      end
+
+      def statement?
+        false
+      end
+
+      def needs_newline?
+        false
+      end
+    end
+
+    class Comment
+      def multiline?
+        @type == 'multiline'
+      end
+    end
+
+    class SequenceExpression
+      attr_accessor :parens
+    end
+
+    class BlockStatement
+      attr_accessor :cuddly
+
+      def cuddle!
+        @cuddly = true
+      end
+
+      def needs_newline?
+        !@cuddly
+      end
+
+      def cuddly?
+        true
+      end
+
+      def statement?
+        true
+      end
+    end
+
+    class FunctionExpression
+      include ParseJS::AST::Scope
+    end
+
+    class FunctionDeclaration
+      include ParseJS::AST::Scope
+    end
+
+    class Program
+      include ParseJS::AST::Scope
+    end
+
+    statements  = [VariableDeclaration, EmptyStatement, ExpressionStatement, IfStatement]
+    statements += [WhileStatement, ForStatement, ForInStatement, DoWhileStatement]
+    statements += [ContinueStatement, BreakStatement, ReturnStatement, WithStatement]
+    statements += [LabeledStatement, SwitchStatement, ThrowStatement, TryStatement]
+    statements += [DebuggerStatement, FunctionDeclaration]
+
+    statements.each do |statement|
+      statement.class_eval do
+        def needs_newline?
+          true
+        end
+
+        def statement?
+          true
+        end
+      end
+    end
+  end
+end
+

data/lib/parsejs/docs.rb

@@ -0,0 +1,237 @@
+require "parsejs/visitor"
+require "yard"
+
+module ParseJS
+  class CommentScanner < Visitor
+    include ParseJS::AST
+
+    def initialize(*)
+      @current_comment = nil
+      super
+    end
+
+    def comment?
+      return false unless @current_comment
+      return false if @current_comment.empty?
+      return @current_comment.any?(&:multiline?)
+    end
+
+    def stringify(node)
+      Stringifier.to_string(Marshal.load(Marshal.dump(node)))
+    end
+
+    def visit_AssignmentExpression(expr)
+      process_comment(expr)
+      super
+    end
+
+    def visit_CommentedStatement(comment)
+      @current_comment = comment.comments
+
+      super
+    end
+
+    def visit_Property(property)
+      @current_comment = property.comments
+      process_comment(property)
+
+      super
+    end
+
+    def process_comment(node)
+      print_comment(node)
+    end
+
+    def print_comment(node)
+      return unless comment?
+
+      puts
+      puts "-" * 10 + node.class.name + "-" * 10
+      puts @current_comment.map { |c| next unless c.multiline?; c.body }.join("\n")
+      puts "-" * (10 + node.class.name.size + 10)
+      puts
+
+      puts Stringifier.to_string(Marshal.load(Marshal.dump(node)))
+      puts
+    ensure
+      @current_comment = nil
+    end
+
+    def strip_leading_whitespace(string)
+      min = string.scan(/^[ \t]*(?=\S)/).min
+      size = min ? min.size : 0
+      string.gsub(/^[ \t]{#{size}}/, '')
+    end
+  end
+
+  class ExtractDocs < CommentScanner
+    include AST
+
+    def initialize(*)
+      @current_variables = []
+      @current_class = []
+    end
+
+    def visit_Program(program)
+      with_variables(program, []) { super }
+    end
+
+    def visit_FunctionDeclaration(decl)
+      with_variables(decl, decl.params.list.map(&:val)) { super }
+    end
+
+    def visit_FunctionExpression(expr)
+      with_variables(expr, expr.params.list.map(&:val)) { super }
+    end
+
+    def with_variables(expr, params=expr.params.map(&:val))
+      locals = FindVars.find_variables(expr)
+      @current_variables.push(locals | params)
+      yield
+    ensure
+      @current_variables.pop
+    end
+
+    def variable?(name)
+      @current_variables.find do |list|
+        list.include?(name)
+      end
+    end
+
+    def member_left(expr)
+      object = expr
+
+      while object
+        if object.is_a?(Identifier)
+          return object.val
+        elsif object.is_a?(ThisExpression)
+          return "this"
+        elsif object.respond_to?(:object)
+          object = object.object
+        else
+          return nil
+        end
+      end
+    end
+
+    def visit_AssignmentExpression(expr)
+      right = expr.right
+      in_class = false
+
+      if right.is_a?(CallExpression)
+        callee = expr.right.callee
+        if callee.is_a?(MemberExpression) && !callee.computed
+          property = callee.property.val
+          if property == "extend"
+            if expr.left.is_a?(MemberExpression)
+              left_id = member_left(expr.left)
+              extends = stringify(expr.right.callee).sub(/\.extend$/, '')
+
+              if variable?(left_id)
+                # found private class
+              else
+                klass = stringify(expr.left)
+
+                left_string = stringify(expr.left)
+                namespace_obj = build_namespace left_string.split(".")[0...-1].join("::")
+
+                class_name = left_string.split(".")[-1]
+
+                obj = YARD::CodeObjects::ClassObject.new(namespace_obj, class_name)
+                obj.docstring = stripped_comment
+
+                @current_class.push [klass, extends, obj]
+                in_class = true
+              end
+            end
+          end
+        end
+      end
+
+      super
+
+    ensure
+      @current_class.pop if in_class
+    end
+
+    def build_namespace(namespace)
+      if namespace.empty?
+        YARD::Registry.root
+      elsif ns = YARD::Registry.at(namespace)
+        ns
+      else
+        name = namespace.gsub('::', '.')
+        YARD::CodeObjects::NamespaceObject.new(:root, name)
+      end
+    end
+
+    def current_class_name
+      klass, parent = @current_class.last
+      "#{klass} < #{parent}"
+    end
+
+    def current_yard_class
+      @current_class.last[2]
+    end
+
+    def visit_Property(property)
+      return if @current_class.empty?
+
+      @current_comment = property.comments
+      return if stripped_comment.empty?
+
+      case property.value
+      when FunctionDeclaration, FunctionExpression
+        obj = YARD::CodeObjects::MethodObject.new(current_yard_class, property.key.val)
+        obj.docstring = stripped_comment
+      else
+        # found a non-method property
+      end
+
+      super
+    end
+
+    def stripped_comment
+      comments = @current_comment.map do |c|
+        next unless c.multiline?
+        c.body
+      end
+
+      string = comments.join("\n")
+      string = string.gsub(/\A\**\n/, '')
+      strip_leading_whitespace(string)
+    end
+
+    def process_comment(*)
+    end
+  end
+
+  require "set"
+
+  class FindVars < Visitor
+    def self.find_variables(ast)
+      ast = Marshal.load(Marshal.dump(ast))
+
+      finder = new
+      finder.accept(ast)
+      finder.variables
+    end
+
+    attr_reader :variables
+
+    def initialize(*)
+      @variables = Set.new
+      super
+    end
+
+    def visit_VariableDeclarator(expr)
+      @variables << expr.id.val
+    end
+
+    def visit_FunctionDeclaration(*)
+    end
+
+    def visit_FunctionExpression(*)
+    end
+  end
+end