jsduck 4.0.1 → 4.1.1

data/lib/jsduck/inline/example.rb

@@ -0,0 +1,42 @@
+module JsDuck
+  module Inline
+
+    # Implementation of @example tag.
+    #
+    # Looks for @example tag at the beginning of code blocks. When
+    # found, adds an "inline-example" CSS class to the <pre> element.
+    #
+    # Unlike other Inline:: classes this doesn't implement an
+    # {@example} tag as could be expected.  But it fits nicely along
+    # with other inline tags as it's processed inside DocFormatter, so
+    # it mostly fits here along with the others.
+    #
+    class Example
+      # Constructor takes opts parameter for consistency with other
+      # JsDuck::Inline::* classes.
+      def initialize(opts={})
+        @re = /<pre><code>\s*@example( +[^\n]*)?\s+/m
+      end
+
+      # Takes StringScanner instance.
+      #
+      # Looks for "<pre><code>@example" at the current scan pointer
+      # position, when found, moves scan pointer forward and performs
+      # the apporpriate replacement.
+      def replace(input)
+        if input.check(@re)
+          # Match possible classnames following @example and add them
+          # as CSS classes inside <pre> element.
+          input.scan(@re) =~ @re
+          css_classes = ($1 || "").strip
+
+          return "<pre class='inline-example #{css_classes}'><code>"
+        else
+          false
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/inline/img.rb

@@ -0,0 +1,55 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+
+module JsDuck
+  module Inline
+
+    # Implementation of inline tag {@img}
+    class Img
+      # Base path to prefix images from {@img} tags.
+      # Defaults to no prefix.
+      attr_accessor :base_path
+
+      # This will hold list of all image paths gathered from {@img} tags.
+      attr_accessor :images
+
+      def initialize(opts={})
+        @tpl = opts[:img_tpl] || '<img src="%u" alt="%a"/>'
+
+        @re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
+
+        @base_path = nil
+        @images = []
+      end
+
+      # Takes StringScanner instance.
+      #
+      # Looks for inline tag at the current scan pointer position, when
+      # found, moves scan pointer forward and performs the apporpriate
+      # replacement.
+      def replace(input)
+        if input.check(@re)
+          input.scan(@re).sub(@re) { apply_tpl($1, $2) }
+        else
+          false
+        end
+      end
+
+      # applies the image template
+      def apply_tpl(url, alt_text)
+        @images << url
+        @tpl.gsub(/(%\w)/) do
+          case $1
+          when '%u'
+            @base_path ? (@base_path + "/" + url) : url
+          when '%a'
+            Util::HTML.escape(alt_text||"")
+          else
+            $1
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/inline/link.rb

@@ -0,0 +1,227 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+
+module JsDuck
+  module Inline
+
+    # Implementation of inline tag {@link}
+    #
+    # It also takes care of the auto-detection of links in text
+    # through the #create_magic_links method.
+    class Link
+      # Sets up instance to work in context of particular class, so
+      # that when {@link #blah} is encountered it knows that
+      # Context#blah is meant.
+      attr_accessor :class_context
+
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
+      # JsDuck::Relations for looking up class names.
+      #
+      # When auto-creating class links from CamelCased names found from
+      # text, we check the relations object to see if a class with that
+      # name actually exists.
+      attr_accessor :relations
+
+      def initialize(opts={})
+        @class_context = ""
+        @doc_context = {}
+        @relations = {}
+
+        # Template HTML that replaces {@link Class#member anchor text}.
+        # Can contain placeholders:
+        #
+        # %c - full class name (e.g. "Ext.Panel")
+        # %m - class member name prefixed with member type (e.g. "method-urlEncode")
+        # %# - inserts "#" if member name present
+        # %- - inserts "-" if member name present
+        # %a - anchor text for link
+        @tpl = opts[:link_tpl] || '<a href="%c%#%m">%a</a>'
+
+        @re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
+      end
+
+      # Takes StringScanner instance.
+      #
+      # Looks for inline tag at the current scan pointer position, when
+      # found, moves scan pointer forward and performs the apporpriate
+      # replacement.
+      def replace(input)
+        if input.check(@re)
+          input.scan(@re).sub(@re) { apply_tpl($1, $2, $&) }
+        else
+          false
+        end
+      end
+
+      # applies the link template
+      def apply_tpl(target, text, full_link)
+        if target =~ /^(.*)#(static-)?(?:(cfg|property|method|event|css_var|css_mixin)-)?(.*)$/
+          cls = $1.empty? ? @class_context : $1
+          static = $2 ? true : nil
+          type = $3 ? $3.intern : nil
+          member = $4
+        else
+          cls = target
+          static = nil
+          type = false
+          member = false
+        end
+
+        # Construct link text
+        if text
+          text = text
+        elsif member
+          text = (cls == @class_context) ? member : (cls + "." + member)
+        else
+          text = cls
+        end
+
+        file = @doc_context[:filename]
+        line = @doc_context[:linenr]
+        if !@relations[cls]
+          Logger.warn(:link, "#{full_link} links to non-existing class", file, line)
+          return text
+        elsif member
+          ms = find_members(cls, {:name => member, :tagname => type, :static => static})
+          if ms.length == 0
+            Logger.warn(:link, "#{full_link} links to non-existing member", file, line)
+            return text
+          end
+
+          if ms.length > 1
+            # When multiple public members, see if there remains just
+            # one when we ignore the static members. If there's more,
+            # report ambiguity. If there's only static members, also
+            # report ambiguity.
+            instance_ms = ms.find_all {|m| !m[:meta][:static] }
+            if instance_ms.length > 1
+              alternatives = instance_ms.map {|m| "#{m[:tagname]} in #{m[:owner]}" }.join(", ")
+              Logger.warn(:link_ambiguous, "#{full_link} is ambiguous: "+alternatives, file, line)
+            elsif instance_ms.length == 0
+              static_ms = ms.find_all {|m| m[:meta][:static] }
+              alternatives = static_ms.map {|m| "static " + m[:tagname].to_s }.join(", ")
+              Logger.warn(:link_ambiguous, "#{full_link} is ambiguous: "+alternatives, file, line)
+            end
+          end
+
+          return link(cls, member, text, type, static)
+        else
+          return link(cls, false, text)
+        end
+      end
+
+      # Looks input text for patterns like:
+      #
+      #  My.ClassName
+      #  MyClass#method
+      #  #someProperty
+      #
+      # and converts them to links, as if they were surrounded with
+      # {@link} tag. One notable exception is that Foo is not created to
+      # link, even when Foo class exists, but Foo.Bar is. This is to
+      # avoid turning normal words into links. For example:
+      #
+      #     Math involves a lot of numbers. Ext JS is a JavaScript framework.
+      #
+      # In these sentences we don't want to link "Math" and "Ext" to the
+      # corresponding JS classes.  And that's why we auto-link only
+      # class names containing a dot "."
+      #
+      def create_magic_links(input)
+        cls_re = "([A-Z][A-Za-z0-9.]*[A-Za-z0-9])"
+        member_re = "(?:#([A-Za-z0-9]+))"
+
+        input.gsub(/\b#{cls_re}#{member_re}?\b|#{member_re}\b/m) do
+          replace_magic_link($1, $2 || $3)
+        end
+      end
+
+      def replace_magic_link(cls, member)
+        if cls && member
+          if @relations[cls] && get_matching_member(cls, {:name => member})
+            return link(cls, member, cls+"."+member)
+          else
+            warn_magic_link("#{cls}##{member} links to non-existing " + (@relations[cls] ? "member" : "class"))
+          end
+        elsif cls && cls =~ /\./
+          if @relations[cls]
+            return link(cls, nil, cls)
+          else
+            cls2, member2 = split_to_cls_and_member(cls)
+            if @relations[cls2] && get_matching_member(cls2, {:name => member2})
+              return link(cls2, member2, cls2+"."+member2)
+            elsif cls =~ /\.(js|css|html|php)\Z/
+              # Ignore common filenames
+            else
+              warn_magic_link("#{cls} links to non-existing class")
+            end
+          end
+        elsif !cls && member
+          if get_matching_member(@class_context, {:name => member})
+            return link(@class_context, member, member)
+          elsif member =~ /\A([A-F0-9]{3}|[A-F0-9]{6})\Z/i || member =~ /\A[0-9]/
+            # Ignore HEX color codes and
+            # member names beginning with number
+          else
+            warn_magic_link("##{member} links to non-existing member")
+          end
+        end
+
+        return "#{cls}#{member ? '#' : ''}#{member}"
+      end
+
+      def split_to_cls_and_member(str)
+        parts = str.split(/\./)
+        return [parts.slice(0, parts.length-1).join("."), parts.last]
+      end
+
+      def warn_magic_link(msg)
+        Logger.warn(:link_auto, msg, @doc_context[:filename], @doc_context[:linenr])
+      end
+
+      # applies the link template
+      def link(cls, member, anchor_text, type=nil, static=nil)
+        # Use the canonical class name for link (not some alternateClassName)
+        cls = @relations[cls][:name]
+        # prepend type name to member name
+        member = member && get_matching_member(cls, {:name => member, :tagname => type, :static => static})
+
+        @tpl.gsub(/(%[\w#-])/) do
+          case $1
+          when '%c'
+            cls
+          when '%m'
+            member ? member[:id] : ""
+          when '%#'
+            member ? "#" : ""
+          when '%-'
+            member ? "-" : ""
+          when '%a'
+            Util::HTML.escape(anchor_text||"")
+          else
+            $1
+          end
+        end
+      end
+
+      def get_matching_member(cls, query)
+        ms = find_members(cls, query).find_all {|m| !m[:private] }
+        if ms.length > 1
+          instance_ms = ms.find_all {|m| !m[:meta][:static] }
+          instance_ms.length > 0 ? instance_ms[0] : ms.find_all {|m| m[:meta][:static] }[0]
+        else
+          ms[0]
+        end
+      end
+
+      def find_members(cls, query)
+        @relations[cls] ? @relations[cls].find_members(query) : []
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/inline/video.rb

@@ -0,0 +1,67 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+
+module JsDuck
+  module Inline
+
+    # Implementation of inline tag {@video}
+    class Video
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
+      def initialize(opts={})
+        @doc_context = {}
+
+        @templates = {
+          "html5" => '<video src="%u">%a</video>',
+          "vimeo" => [
+            '<p><object width="640" height="360">',
+            '<param name="allowfullscreen" value="true" />',
+            '<param name="allowscriptaccess" value="always" />',
+            '<param name="flashvars" value="api=1" />',
+            '<param name="movie" value="http://vimeo.com/moogaloop.swf?clip_id=%u&amp;server=vimeo.com&amp;color=4CC208&amp;fullscreen=1" />',
+            '<embed src="http://vimeo.com/moogaloop.swf?clip_id=%u&amp;server=vimeo.com&amp;color=4CC208&amp;fullscreen=1" ',
+            'type="application/x-shockwave-flash" allowfullscreen="true" allowscriptaccess="always" width="640" height="360"></embed>',
+            '</object></p>',
+          ].join
+        }
+
+        @re = /\{@video\s+(\w+)\s+(\S*?)(?:\s+(.+?))?\}/m
+      end
+
+      # Takes StringScanner instance.
+      #
+      # Looks for inline tag at the current scan pointer position, when
+      # found, moves scan pointer forward and performs the apporpriate
+      # replacement.
+      def replace(input)
+        if input.check(@re)
+          input.scan(@re).sub(@re) { apply_tpl($1, $2, $3) }
+        else
+          false
+        end
+      end
+
+      # applies the video template of the specified type
+      def apply_tpl(type, url, alt_text)
+        unless @templates.has_key?(type)
+          ctx = @doc_context
+          Logger.warn(nil, "Unknown video type #{type}", ctx[:filename], ctx[:linenr])
+        end
+
+        @templates[type].gsub(/(%\w)/) do
+          case $1
+          when '%u'
+            url
+          when '%a'
+            Util::HTML.escape(alt_text||"")
+          else
+            $1
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/inline_examples.rb

@@ -1,5 +1,5 @@
-require 'jsduck/json_duck'
-require 'jsduck/html'
+require 'jsduck/util/json'
+require 'jsduck/util/html'
 
 module JsDuck
 
@@ -16,9 +16,9 @@ module JsDuck
       relations.each do |cls|
         extract(cls[:doc]).each_with_index do |ex, i|
           @examples << {
-            :id => cls.full_name + "-" + i.to_s,
-            :name => cls.full_name + " example #" + (i+1).to_s,
-            :href => '#!/api/' + cls.full_name,
+            :id => cls[:name] + "-" + i.to_s,
+            :name => cls[:name] + " example #" + (i+1).to_s,
+            :href => '#!/api/' + cls[:name],
             :code => ex[:code],
             :options => ex[:options],
           }
@@ -47,7 +47,7 @@ module JsDuck
 
     # Writes all found examples to .js file
     def write(filename)
-      JsonDuck.write_jsonp(filename, "__inline_examples__", @examples)
+      Util::Json.write_jsonp(filename, "__inline_examples__", @examples)
     end
 
     # Extracts inline examples from HTML
@@ -65,7 +65,7 @@ module JsDuck
             ex = s.scan_until(@end_example_re).sub(@end_example_re, '')
 
             examples << {
-              :code => HTML.unescape(HTML.strip_tags(ex)),
+              :code => Util::HTML.unescape(Util::HTML.strip_tags(ex)),
               :options => options,
             }
           else

data/lib/jsduck/js_parser.rb

@@ -25,7 +25,7 @@ module JsDuck
     #     }
     #
     def parse
-      @ast = Esprima.instance.parse(@input)
+      @ast = Esprima.parse(@input)
 
       @ast["comments"] = merge_comments(@ast["comments"])
       locate_comments
@@ -62,10 +62,11 @@ module JsDuck
     end
 
     # Two comments can be merged if they are both line-comments and
-    # they are separated only by whitespace (but no newlines)
+    # 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[ \t]*\Z/ =~ @input.slice((c1["range"][1])..(c2["range"][0]-1))
+        /\A(\r\n|\n|\r)?[ \t]*\Z/ =~ @input.slice((c1["range"][1])..(c2["range"][0]-1))
       else
         false
       end
@@ -156,7 +157,7 @@ module JsDuck
       properties = NODE_TYPES[node["type"]]
 
       unless properties
-        Logger.instance.fatal("Unknown node type: "+node["type"])
+        Logger.fatal("Unknown node type: "+node["type"])
         exit(1)
       end