jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/js/node_array.rb

@@ -0,0 +1,36 @@
+require "jsduck/js/node"
+
+module JsDuck
+  module Js
+
+    # Wraps around array of AST nodes.
+    class NodeArray
+      # Initialized with array of AST Hashes from Esprima.
+      def initialize(nodes)
+        @nodes = nodes || []
+      end
+
+      # Returns a child AST node as AstNode class.
+      def [](i)
+        Js::Node.create(@nodes[i])
+      end
+
+      # The length of array
+      def length
+        @nodes.length
+      end
+
+      # Iterates over all the AstNodes in array.
+      def each
+        @nodes.each {|p| yield(Js::Node.create(p)) }
+      end
+
+      # Maps over all the AstNodes in array.
+      def map
+        @nodes.map {|p| yield(Js::Node.create(p)) }
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/js/parser.rb

@@ -0,0 +1,223 @@
+require 'jsduck/js/esprima'
+require 'jsduck/logger'
+
+module JsDuck
+  module Js
+
+    # JavaScript parser that internally uses Esprima.js
+    class Parser
+
+      # Initializes the parser with JavaScript source code to be parsed.
+      def initialize(input, options = {})
+        @input = input
+
+        # Initialize line number counting
+        @start_index = 0
+        @start_linenr = 1
+      end
+
+      # Parses JavaScript source code and returns array of hashes like this:
+      #
+      #     {
+      #         :comment => "The contents of the comment",
+      #         :code => {...AST data structure for code following the comment...},
+      #         :linenr => 12,  // Beginning with 1
+      #         :type => :doc_comment, // or :plain_comment
+      #     }
+      #
+      def parse
+        @ast = Js::Esprima.parse(@input)
+
+        @ast["comments"] = merge_comments(@ast["comments"])
+        locate_comments
+      end
+
+      private
+
+      # Merges consecutive line-comments and Establishes links between
+      # comments, so we can easily use comment["next"] to get to the
+      # next comment.
+      def merge_comments(original_comments)
+        result = []
+
+        comment = original_comments[0]
+        i = 0
+
+        while comment
+          i += 1
+          next_comment = original_comments[i]
+
+          if next_comment && mergeable?(comment, next_comment)
+            # Merge next comment to current one
+            comment["value"] += "\n" + next_comment["value"]
+            comment["range"][1] = next_comment["range"][1]
+          else
+            # Create a link and continue with next comment
+            comment["next"] = next_comment
+            result << comment
+            comment = next_comment
+          end
+        end
+
+        result
+      end
+
+      # Two comments can be merged if they are both line-comments and
+      # they are separated only by whitespace (only one newline at the
+      # end of the first comment is allowed)
+      def mergeable?(c1, c2)
+        if c1["type"] == "Line" && c2["type"] == "Line"
+          /\A(\r\n|\n|\r)?[ \t]*\z/ =~ @input.slice((c1["range"][1])..(c2["range"][0]-1))
+        else
+          false
+        end
+      end
+
+      def locate_comments
+        @ast["comments"].map do |comment|
+          # Detect comment type and strip * at the beginning of doc-comment
+          value = comment["value"]
+          if comment["type"] == "Block" && value =~ /\A\*/
+            type = :doc_comment
+            value = value.slice(1, value.length-1)
+          else
+            type = :plain_comment
+          end
+
+          {
+            :comment => value,
+            :code => stuff_after(comment),
+            :linenr => line_number(comment["range"][0]),
+            :type => type,
+          }
+        end
+      end
+
+      # Given index inside input string, returns the corresponding line number
+      def line_number(index)
+        # To speed things up, remember the index until which we counted,
+        # then next time just begin counting from there.  This way we
+        # only count each line once.
+        @start_linenr = @input[@start_index...index].count("\n") + @start_linenr
+        @start_index = index
+        return @start_linenr
+      end
+
+      # Sees if there is some code following the comment.
+      # Returns the code found.  But if the comment is instead
+      # followed by another comment, returns nil.
+      def stuff_after(comment)
+        code = code_after(comment["range"], @ast)
+        if code && comment["next"]
+          return code["range"][0] < comment["next"]["range"][0] ? code : nil
+        else
+          code
+        end
+      end
+
+      # Looks for code following the given range.
+      #
+      # The second argument is the parent node within which we perform
+      # our search.
+      def code_after(range, parent)
+        # Look through all child nodes of parent...
+        child_nodes(parent).each do |node|
+          if less(range, node["range"])
+            # If node is after our range, then that's it.  There could
+            # be comments in our way, but that's taken care of in
+            # #stuff_after method.
+            return node
+          elsif within(range, node["range"])
+            # Our range is within the node --> recurse
+            return code_after(range, node)
+          end
+        end
+
+        return nil
+      end
+
+
+      # True if range A is less than range B
+      def less(a, b)
+        return a[1] <= b[0]
+      end
+
+      # True if range A is greater than range B
+      def greater(a, b)
+        return a[0] >= b[1]
+      end
+
+      # True if range A is within range B
+      def within(a, b)
+        return b[0] <= a[0] && a[1] <= b[1]
+      end
+
+
+      # Returns array of child nodes of given node
+      def child_nodes(node)
+        properties = NODE_TYPES[node["type"]]
+
+        unless properties
+          Logger.fatal("Unknown node type: "+node["type"])
+          exit(1)
+        end
+
+        properties.map {|p| node[p] }.compact.flatten
+      end
+
+      # All possible node types in Esprima-created abstract syntax tree
+      #
+      # Each node type maps to list of properties of that node into
+      # which we can recurse for further parsing.
+      NODE_TYPES = {
+        "Program" => ["body"],
+
+        "BlockStatement" => ["body"],
+        "BreakStatement" => [],
+        "ContinueStatement" => [],
+        "DoWhileStatement" => ["body", "test"],
+        "DebuggerStatement" => [],
+        "EmptyStatement" => [],
+        "ExpressionStatement" => ["expression"],
+        "ForStatement" => ["init", "test", "update", "body"],
+        "ForInStatement" => ["left", "right", "body"],
+        "IfStatement" => ["test", "consequent", "alternate"],
+        "LabeledStatement" => ["body"],
+        "ReturnStatement" => ["argument"],
+        "SwitchStatement" => ["discriminant", "cases"],
+        "SwitchCase" => ["test", "consequent"],
+        "ThrowStatement" => ["argument"],
+        "TryStatement" => ["block", "handlers", "finalizer"],
+        "CatchClause" => ["param", "body"],
+        "WhileStatement" => ["test", "body"],
+        "WithStatement" => ["object", "body"],
+
+        "FunctionDeclaration" => ["id", "params", "body"],
+        "VariableDeclaration" => ["declarations"],
+        "VariableDeclarator" => ["id", "init"],
+
+        "AssignmentExpression" => ["left", "right"],
+        "ArrayExpression" => ["elements"],
+        "BinaryExpression" => ["left", "right"],
+        "CallExpression" => ["callee", "arguments"],
+        "ConditionalExpression" => ["test", "consequent", "alternate"],
+        "FunctionExpression" => ["body"],
+
+        "LogicalExpression" => ["left", "right"],
+        "MemberExpression" => ["object", "property"],
+        "NewExpression" => ["callee", "arguments"],
+        "ObjectExpression" => ["properties"],
+        "Property" => ["key", "value"],
+
+        "SequenceExpression" => ["expressions"],
+        "ThisExpression" => [],
+        "UnaryExpression" => ["argument"],
+        "UpdateExpression" => ["argument"],
+
+        "Identifier" => [],
+        "Literal" => [],
+      }
+    end
+
+  end
+end

data/lib/jsduck/js/serializer.rb

@@ -0,0 +1,263 @@
+module JsDuck
+  module Js
+
+    # Transforms Esprima AST into string
+    class Serializer
+
+      # Turns AST node into string
+      def to_s(ast)
+        case ast["type"]
+        when "Program"
+          ast["body"].map {|s| to_s(s) }.join
+
+          # Statements
+
+        when "BlockStatement"
+          "{" + ast["body"].map {|s| to_s(s) }.join + "}"
+
+        when "BreakStatement"
+          "break" + (ast["label"] ? " " + to_s(ast["label"]) : "") + ";"
+
+        when "ContinueStatement"
+          "continue" + (ast["label"] ? " " + to_s(ast["label"]) : "") + ";"
+
+        when "DoWhileStatement"
+          "do " + to_s(ast["body"]) + " while (" + to_s(ast["test"]) + ");"
+
+        when "DebuggerStatement"
+          "debugger;"
+
+        when "EmptyStatement"
+          ";"
+
+        when "ExpressionStatement"
+          to_s(ast["expression"]) + ";"
+
+        when "ForStatement"
+          init = ast["init"] ? to_s(ast["init"]).sub(/;\z/, "") : ""
+          test = ast["test"] ? to_s(ast["test"]) : ""
+          update = ast["update"] ? to_s(ast["update"]) : ""
+          "for (" + init + "; " + test + "; " + update + ") " + to_s(ast["body"])
+
+        when "ForInStatement"
+          left = to_s(ast["left"]).sub(/;\z/, "")
+          right = to_s(ast["right"])
+          "for (" + left + " in " + right + ") " + to_s(ast["body"])
+
+        when "IfStatement"
+          alternate = ast["alternate"] ? " else " + to_s(ast["alternate"]) : ""
+          "if (" + to_s(ast["test"]) + ") " + to_s(ast["consequent"]) + alternate
+
+        when "LabeledStatement"
+          to_s(ast["label"]) + ": " + to_s(ast["body"])
+
+        when "ReturnStatement"
+          arg = ast["argument"] ? to_s(ast["argument"]) : ""
+          "return " + arg + ";"
+
+        when "SwitchStatement"
+          "switch (" + to_s(ast["discriminant"]) + ") {" + ast["cases"].map {|c| to_s(c) }.join + "}"
+
+        when "SwitchCase"
+          test = ast["test"] ? "case " + to_s(ast["test"]) : "default"
+          test + ": " + ast["consequent"].map {|c| to_s(c) }.join
+
+        when "ThrowStatement"
+          "throw " + to_s(ast["argument"]) + ";"
+
+        when "TryStatement"
+          handlers = ast["handlers"].map {|h| to_s(h) }.join
+          finalizer = ast["finalizer"] ? " finally " + to_s(ast["finalizer"]) : ""
+          "try " + to_s(ast["block"]) + handlers + finalizer
+
+        when "CatchClause"
+          param = ast["param"] ? to_s(ast["param"]) : ""
+          " catch (" + param + ") " + to_s(ast["body"])
+
+        when "WhileStatement"
+          "while (" + to_s(ast["test"]) + ") " + to_s(ast["body"])
+
+        when "WithStatement"
+          "with (" + to_s(ast["object"]) + ") " + to_s(ast["body"])
+
+
+          # Declarations
+
+        when "FunctionDeclaration"
+          function(ast)
+
+        when "VariableDeclaration"
+          ast["kind"] + " " + list(ast["declarations"]) + ";"
+
+        when "VariableDeclarator"
+          if ast["init"]
+            to_s(ast["id"]) + " = " + to_s(ast["init"])
+          else
+            to_s(ast["id"])
+          end
+
+          # Expressions
+
+        when "AssignmentExpression"
+          parens(ast, ast["left"]) + " " + ast["operator"] + " " + to_s(ast["right"])
+
+        when "ArrayExpression"
+          "[" + list(ast["elements"]) + "]"
+
+        when "BinaryExpression"
+          binary(ast)
+
+        when "CallExpression"
+          call(ast)
+
+        when "ConditionalExpression"
+          parens(ast, ast["test"]) + " ? " + to_s(ast["consequent"]) + " : " + to_s(ast["alternate"])
+
+        when "FunctionExpression"
+          function(ast)
+
+        when "LogicalExpression"
+          binary(ast)
+
+        when "MemberExpression"
+          if ast["computed"]
+            parens(ast, ast["object"]) + "[" + to_s(ast["property"]) + "]"
+          else
+            parens(ast, ast["object"]) + "." + to_s(ast["property"])
+          end
+
+        when "NewExpression"
+          "new " + call(ast)
+
+        when "ObjectExpression"
+          "{" + list(ast["properties"]) + "}"
+
+        when "Property"
+          to_s(ast["key"]) + ": " + to_s(ast["value"])
+
+        when "SequenceExpression"
+          list(ast["expressions"])
+
+        when "ThisExpression"
+          "this"
+
+        when "UnaryExpression"
+          ast["operator"] + parens(ast, ast["argument"])
+
+        when "UpdateExpression"
+          if ast["prefix"]
+            ast["operator"] + parens(ast, ast["argument"])
+          else
+            parens(ast, ast["argument"]) + ast["operator"]
+          end
+
+          # Basics
+
+        when "Identifier"
+          ast["name"]
+
+        when "Literal"
+          ast["raw"]
+
+        else
+          throw "Unknown node type: " + (ast["type"] || "nil")
+        end
+      end
+
+      private
+
+      # serializes function declaration or expression
+      def function(ast)
+        params = list(ast["params"])
+        id = ast["id"] ? to_s(ast["id"]) : ""
+        "function " + id + "(" + params + ") " + to_s(ast["body"])
+      end
+
+      # serializes list of comma-separated items
+      def list(array)
+        array.map {|x| to_s(x) }.join(", ")
+      end
+
+      # serializes call- and new-expression
+      def call(ast)
+        parens(ast, ast["callee"]) + "(" + list(ast["arguments"]) + ")"
+      end
+
+      # Handles both binary- and logical-expression
+      def binary(ast)
+        parens(ast, ast["left"]) + " " + ast["operator"] + " " + parens(ast, ast["right"])
+      end
+
+      # serializes child node and wraps it inside parenthesis if the
+      # precedence rules compared to parent node would require so.
+      def parens(parent, child)
+        if precedence(parent) >= precedence(child)
+          to_s(child)
+        else
+          "(" + to_s(child) + ")"
+        end
+      end
+
+      # Returns the precedence of operator represented by given AST node
+      def precedence(ast)
+        p = PRECEDENCE[ast["type"]]
+        if p.is_a? Fixnum
+          p
+        elsif p.is_a? Hash
+          p[ast["operator"]]
+        else
+          0
+        end
+      end
+
+      # Precedence rules of JavaScript operators.
+      #
+      # Taken from: https://developer.mozilla.org/en/JavaScript/Reference/Operators/Operator_Precedence
+      #
+      PRECEDENCE = {
+        "SequenceExpression" => 17,
+        "AssignmentExpression" => 16,
+        "ConditionalExpression" => 15,
+        "LogicalExpression" => {
+          "||" => 14,
+          "&&" => 13,
+        },
+        "BinaryExpression" => {
+          "|" => 12,
+          "^" => 11,
+          "&" => 10,
+
+          "==" => 9,
+          "!=" => 9,
+          "===" => 9,
+          "!==" => 9,
+
+          "<" => 8,
+          "<=" => 8,
+          ">" => 8,
+          ">=" => 8,
+          "in" => 8,
+          "instanceof" => 8,
+
+          "<<" => 7,
+          ">>" => 7,
+          ">>>" => 7,
+
+          "+" => 6,
+          "-" => 6,
+
+          "*" => 5,
+          "/" => 5,
+          "%" => 5,
+        },
+        "UnaryExpression" => 4,
+        "UpdateExpression" => 3,
+        "CallExpression" => 2,
+        "MemberExpression" => 1,
+        "NewExpression" => 1,
+      }
+
+    end
+
+  end
+end