solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/img/dir.rb

@@ -0,0 +1,94 @@
+require 'dimensions'
+require 'jsduck/logger'
+
+module JsDuck
+  module Img
+
+    # Looks up images from a directory.
+    class Dir
+      def initialize(full_path, relative_path)
+        @full_path = full_path
+        @relative_path = relative_path
+        @images = {}
+      end
+
+      # Retrieves hash of information for a given relative image
+      # filename.  It will have the fields:
+      #
+      # - :filename - the same as the parameter of this method
+      # - :full_path - actual path in the filesystem.
+      # - :relative_path - relative path to be used inside <img> tag.
+      # - :width - Image width
+      # - :height - Image height
+      #
+      # When the image is not found, returns nil.
+      def get(filename)
+        img = scan_img(filename)
+        if img
+          @images[filename] = img
+        end
+        img
+      end
+
+      # Returns all used images.
+      def all_used
+        @images.values
+      end
+
+      # Print warnings about all unused images.
+      def report_unused
+        scan_for_unused_images.each {|img| warn_unused(img) }
+      end
+
+      private
+
+      def scan_img(filename)
+        full_path = File.join(@full_path, filename)
+        if File.exists?(File.join(@full_path, filename))
+          img_record(filename)
+        else
+          nil
+        end
+      end
+
+      # Scans directory for image files, building a hash of image files
+      # found in that directory.
+      def scan_for_unused_images
+        unused = []
+        ::Dir[@full_path+"/**/*.{png,jpg,jpeg,gif}"].each do |path|
+          filename = relative_path(@full_path, path)
+          unused << img_record(filename) unless @images[filename]
+        end
+        unused
+      end
+
+      def warn_unused(img)
+        Logger.warn(:image_unused, "Image not used.", {:filename => img[:full_path]})
+      end
+
+      def img_record(filename)
+        full_path = File.join(@full_path, filename)
+        width, height = Dimensions.dimensions(full_path)
+
+        return {
+          :filename => filename,
+          :relative_path => File.join(@relative_path, filename),
+          :full_path => full_path,
+          :width => width,
+          :height => height,
+        }
+      end
+
+      # Given a path to directory and a path to file, returns the path
+      # to this file relative to the given dir. For example:
+      #
+      #     base_path("/foo/bar", "/foo/bar/baz/img.jpg") --> "baz/img.jpg"
+      #
+      def relative_path(dir_path, file_path)
+        file_path.slice(dir_path.length+1, file_path.length)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/img/dir_set.rb

@@ -0,0 +1,39 @@
+require "jsduck/img/dir"
+require "jsduck/logger"
+require "fileutils"
+
+module JsDuck
+  module Img
+
+    # A collection if Img::Dir objects.
+    #
+    # Looks up images from directories specified through --images
+    # option.
+    #
+    # This class provides the same interface as Img::Dir, except that
+    # the constructor takes array of full_paths not just one.
+    class DirSet
+      def initialize(full_paths, relative_path)
+        @dirs = full_paths.map {|path| Img::Dir.new(path, relative_path) }
+      end
+
+      def get(filename)
+        @dirs.each do |dir|
+          if img = dir.get(filename)
+            return img
+          end
+        end
+        return nil
+      end
+
+      def all_used
+        @dirs.map {|dir| dir.all_used }.flatten
+      end
+
+      def report_unused
+        @dirs.each {|dir| dir.report_unused }
+      end
+    end
+
+  end
+end

data/lib/jsduck/img/writer.rb

@@ -0,0 +1,23 @@
+require "jsduck/logger"
+require "fileutils"
+
+module JsDuck
+  module Img
+
+    # Copies images to destination directory.
+    class Writer
+      # Takes an array of image records retrieved from
+      # Img::Dir#all_used or Img::DirSet#all_used and copies all of
+      # them to given output directory.
+      def self.copy(images, output_dir)
+        images.each do |img|
+          dest = File.join(output_dir, img[:filename])
+          Logger.log("Copying image", dest)
+          FileUtils.makedirs(File.dirname(dest))
+          FileUtils.cp(img[:full_path], dest)
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/inline/auto_link.rb

@@ -0,0 +1,106 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Inline
+
+    # Takes care of the auto-detection of links in text.
+    class AutoLink
+      # Sets up instance to work in context of particular class, so it
+      # knows that #blah is in context of SomeClass.
+      attr_accessor :class_context
+
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
+      def initialize(link_renderer)
+        @class_context = ""
+        @doc_context = {}
+        @relations = link_renderer.relations
+        @renderer = link_renderer
+        @magic_link_re = magic_link_re
+      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 replace(input)
+        input.gsub(@magic_link_re) do
+          cls = $1 || $3
+          member = $2 || $4
+          replace_magic_link(cls, member)
+        end
+      end
+
+      private
+
+      # Generates regex for auto-linking class and member names in text.
+      def magic_link_re
+        ident_re = "(?:[A-Za-z_$][A-Za-z0-9_$]*)"
+        cls_re = "(#{ident_re}(?:\\.#{ident_re})*)"
+        ns_cls_re = "(#{ident_re}(?:\\.#{ident_re})+)"
+        member_re = "(?:#(#{ident_re}))"
+        /#{cls_re}#{member_re}|#{ns_cls_re}|#{member_re}/m
+      end
+
+      def replace_magic_link(cls, member)
+        if cls && member
+          if @relations[cls] && @renderer.get_matching_member(cls, {:name => member})
+            return @renderer.link(cls, member, cls+"."+member)
+          else
+            warn_magic_link("#{cls}##{member} links to non-existing " + (@relations[cls] ? "member" : "class"))
+          end
+        elsif cls
+          if @relations[cls]
+            return @renderer.link(cls, nil, cls)
+          else
+            cls2, member2 = split_to_cls_and_member(cls)
+            if @relations[cls2] && @renderer.get_matching_member(cls2, {:name => member2})
+              return @renderer.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
+        else
+          if @renderer.get_matching_member(@class_context, {:name => member})
+            return @renderer.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)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/inline/example.rb

@@ -0,0 +1,44 @@
+require 'ostruct'
+
+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=OpenStruct.new)
+        @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,63 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+require 'ostruct'
+
+module JsDuck
+  module Inline
+
+    # Implementation of inline tag {@img}
+    class Img
+      # Instance of Img::Dir or Img::DirSet that's used for looking up
+      # image information.
+      attr_accessor :images
+
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
+      def initialize(opts=OpenStruct.new)
+        @tpl = opts.img || '<img src="%u" alt="%a" width="%w" height="%h"/>'
+
+        @re = /\{@img\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 image template
+      def apply_tpl(url, alt_text)
+        img = @images.get(url)
+        if !img
+          Logger.warn(:image, "Image #{url} not found.", @doc_context)
+          img = {}
+        end
+
+        @tpl.gsub(/(%\w)/) do
+          case $1
+          when '%u'
+            img[:relative_path]
+          when '%a'
+            Util::HTML.escape(alt_text||"")
+          when '%w'
+            img[:width]
+          when '%h'
+            img[:height]
+          else
+            $1
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/inline/link.rb

@@ -0,0 +1,100 @@
+require 'jsduck/logger'
+require 'jsduck/member_registry'
+
+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
+
+      def initialize(link_renderer)
+        @class_context = ""
+        @doc_context = {}
+        @relations = link_renderer.relations
+        @renderer = link_renderer
+        @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-)?#{MemberRegistry.regex}?(.*)$/
+          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
+
+        if !@relations[cls]
+          Logger.warn(:link, "#{full_link} links to non-existing class", @doc_context)
+          return text
+        elsif member
+          ms = @renderer.find_members(cls, {:name => member, :tagname => type, :static => static})
+          if ms.length == 0
+            Logger.warn(:link, "#{full_link} links to non-existing member", @doc_context)
+            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[: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, @doc_context)
+            elsif instance_ms.length == 0
+              static_ms = ms.find_all {|m| m[:static] }
+              alternatives = static_ms.map {|m| "static " + m[:tagname].to_s }.join(", ")
+              Logger.warn(:link_ambiguous, "#{full_link} is ambiguous: "+alternatives, @doc_context)
+            end
+          end
+
+          return @renderer.link(cls, member, text, type, static)
+        else
+          return @renderer.link(cls, false, text)
+        end
+      end
+
+    end
+
+  end
+end