solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/cache.rb

@@ -0,0 +1,137 @@
+require 'digest/md5'
+require 'fileutils'
+require 'jsduck/util/null_object'
+require 'jsduck/version'
+require 'set'
+
+module JsDuck
+
+  # Reads/writes parsed files in cache.
+  #
+  # When writing to cache:
+  #
+  # - makes MD5 hash of <file name> + <file contents>
+  # - Dumps the the parsed data structure using Marshal into <md5>.dat
+  #
+  # When reading from cache:
+  #
+  # - makes MD5 hash of <file name> + <file contents>
+  # - Reads the parsed data structure using Marshal from <md5>.dat
+  #
+  # Additionally a manifest.txt file is saved into the cache
+  # directory, the contents of which is a string like the following:
+  #
+  #     Ruby: 1.9.3, JSDuck: 5.2.0
+  #
+  # This file is consulted before all other cache operations.  When
+  # the version numbers in there don't match with current Ruby and
+  # JSDuck versions, the whole cache gets invalidated - all cached
+  # files get deleted.  This is to avoid problems with the Marshal
+  # file format changes between Ruby versions and parsed data
+  # structure changes between JSDuck versions.
+  #
+  # After all files have been checked into cache, the files that
+  # weren't touched get deleted (using the #cleanup method).  This
+  # ensures that the number of files in cache only grows when more
+  # files are added to the documentation.
+  #
+  class Cache
+
+    # Factory method to produce a cache object.  When caching is
+    # disabled, returns a NullObject which emulates a cache that's
+    # always empty.
+    def self.create(opts)
+      # Check also for cache_dir, which will be nil when output_dir is :stdout
+      if opts.cache && opts.cache_dir
+        Cache.new(opts)
+      else
+        Util::NullObject.new(
+          :read => nil,
+          :write => nil,
+          :previous_entry => nil,
+          :cleanup => nil
+          )
+      end
+    end
+
+    # The name of the cache file that was previously read or written.
+    # When the #read call failed to find the file, it will be nil.
+    # But it will always be available after the #write call.
+    attr_reader :previous_entry
+
+    def initialize(opts)
+      @cache_dir = opts.cache_dir
+      @manifest_file = @cache_dir + "/manifest.txt"
+      @previous_entry = nil
+
+      FileUtils.mkdir_p(@cache_dir) unless File.exists?(@cache_dir)
+
+      # Invalidate the whole cache when it was generated with a
+      # different Ruby and/or JSDuck version.
+      invalidate_all! unless valid_manifest?
+    end
+
+    # Given the name and contents of a source file, reads the already
+    # parsed data structure from cache.  Returns nil when not found.
+    def read(file_name, file_contents)
+      fname = cache_file_name(file_name, file_contents)
+      if File.exists?(fname)
+        @previous_entry = fname
+        File.open(fname, "rb") {|file| Marshal::load(file) }
+      else
+        @previous_entry = nil
+        nil
+      end
+    end
+
+    # Writes parse data into cache under a name generated from the
+    # name and contents of a source file.
+    def write(file_name, file_contents, data)
+      fname = cache_file_name(file_name, file_contents)
+      @previous_entry = fname
+      File.open(fname, "wb") {|file| Marshal::dump(data, file) }
+    end
+
+    # Given listing of used cache files (those that were either read
+    # or written during this jsduck run) removes rest of the files
+    # from cache directory that were unused.
+    def cleanup(used_cache_entries)
+      used = Set.new(used_cache_entries)
+
+      Dir[@cache_dir + "/*.dat"].each do |file|
+        FileUtils.rm_rf(file) unless used.include?(file)
+      end
+    end
+
+    private
+
+    def cache_file_name(file_name, file_contents)
+      @cache_dir + "/" + md5(file_name + file_contents) + ".dat"
+    end
+
+    def md5(string)
+      Digest::MD5.hexdigest(string)
+    end
+
+    def valid_manifest?
+      manifest = File.exists?(@manifest_file) ? Util::IO.read(@manifest_file) : ""
+      return manifest == current_manifest
+    end
+
+    def invalidate_all!
+      FileUtils.rm_rf(@cache_dir)
+      FileUtils.mkdir(@cache_dir)
+      save_manifest
+    end
+
+    def save_manifest
+      File.open(@manifest_file, "w") {|f| f.write(current_manifest) }
+    end
+
+    def current_manifest
+      "Ruby: #{RUBY_VERSION}, JSDuck: #{JsDuck::VERSION}\n"
+    end
+
+  end
+
+end

data/lib/jsduck/categories/auto.rb

@@ -0,0 +1,83 @@
+module JsDuck
+  module Categories
+
+    # Automatically divides all available classes into categories
+    class Auto
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Performs the generation
+      def generate
+        # list names of all public classes
+        class_names = @relations.to_a.find_all {|cls| !cls[:private] }.map {|cls| cls[:name] }
+
+        # divide classes into top-level categories by namespace
+        categories = categorize(class_names)
+
+        # in each category, create sub-categories
+        categories.each_pair do |ns, classes|
+          categories[ns] = categorize(classes, 1)
+        end
+
+        # Turn categories hash into array, sort everything
+        categories_array = []
+        categories.each_pair do |ns, groups|
+          groups_array = []
+          groups.each_pair do |gns, classes|
+            groups_array << {
+              "name" => gns,
+              "classes" => classes.sort
+            }
+          end
+          groups_array.sort! {|a, b| cat_compare(a, b) }
+          categories_array << {
+            "name" => ns,
+            "groups" => groups_array
+          }
+        end
+        categories_array.sort! {|a, b| cat_compare(a, b) }
+
+        return categories_array
+      end
+
+      # Divides classes into categories by namespace.  Collapses
+      # categories having only one class into a category "Others..."
+      def categorize(class_names, level=0)
+        categories = {}
+        class_names.each do |name|
+          ns = name.split(/\./)[level] || name.split(/\./)[0]
+          categories[ns] = [] unless categories[ns]
+          categories[ns] << name
+        end
+
+        globals = []
+        categories.each_pair do |ns, classes|
+          if classes.length == 1
+            globals << classes[0]
+            categories.delete(ns)
+          end
+        end
+        if globals.length > 0
+          categories["Others..."] = globals
+        end
+
+        categories
+      end
+
+      # Comparison function for sorting categories that always places
+      # "Others..." category at the end.
+      def cat_compare(a, b)
+        if a["name"] == "Others..."
+          1
+        elsif b["name"] == "Others..."
+          -1
+        else
+          a["name"] <=> b["name"]
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/categories/class_name.rb

@@ -0,0 +1,39 @@
+module JsDuck
+  module Categories
+
+    # Renders class names for class categories page.
+    class ClassName
+      def initialize(doc_formatter, relations={})
+        @doc_formatter = doc_formatter
+        @relations = relations
+      end
+
+      # Renders the class name as a link or plain text.
+      #
+      # For new classes appends a star behind class name.  For classes
+      # with new members appends list n small stars behind class name
+      # (reflecting the number of new members).
+      def render(name)
+        cls = @relations[name]
+        if cls
+          @doc_formatter.link(name, nil, name) + render_new_label(cls)
+        else
+          name
+        end
+      end
+
+      private
+
+      # Adds small star to new classes in the current version.
+      def render_new_label(cls)
+        if cls[:new]
+          "&nbsp;<span class='new-class' title='New class'>&#9733;</span>"
+        else
+          ""
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/categories/factory.rb

@@ -0,0 +1,75 @@
+require 'jsduck/logger'
+require 'jsduck/categories/file'
+require 'jsduck/categories/auto'
+require 'jsduck/categories/class_name'
+require 'jsduck/columns'
+
+module JsDuck
+  module Categories
+
+    # Reads in categories and outputs them as HTML div
+    class Factory
+      def self.create(filename, doc_formatter, relations)
+        if filename
+          categories = Categories::File.new(filename, relations)
+        else
+          categories = Categories::Auto.new(relations)
+        end
+        Categories::Factory.new(categories.generate, doc_formatter, relations)
+      end
+
+      def initialize(categories, doc_formatter, relations={})
+        @categories = categories
+        @class_name = Categories::ClassName.new(doc_formatter, relations)
+        @columns = Columns.new("classes")
+      end
+
+      # Returns HTML listing of classes divided into categories
+      def to_html(style="")
+        html = @categories.map do |category|
+          [
+            "<div class='section'>",
+            "<h1>#{category['name']}</h1>",
+            render_columns(category['groups']),
+            "<div style='clear:both'></div>",
+            "</div>",
+          ]
+        end.flatten.join("\n")
+
+        return <<-EOHTML
+          <div id='categories-content' style='#{style}'>
+            #{html}
+          </div>
+        EOHTML
+      end
+
+      private
+
+      def render_columns(groups)
+        align = ["left-column", "middle-column", "right-column"]
+        i = -1
+        return @columns.split(groups, 3).map do |col|
+          i += 1
+          [
+            "<div class='#{align[i]}'>",
+            render_groups(col),
+            "</div>",
+          ]
+        end
+      end
+
+      def render_groups(groups)
+        return groups.map do |g|
+          [
+            "<h3>#{g['name']}</h3>",
+            "<ul class='links'>",
+            g["classes"].map {|cls| "<li>" + @class_name.render(cls) + "</li>" },
+            "</ul>",
+          ]
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/categories/file.rb

@@ -0,0 +1,69 @@
+require 'jsduck/logger'
+require 'jsduck/util/json'
+
+module JsDuck
+  module Categories
+
+    # Reads categories info from config file
+    class File
+      def initialize(filename, relations)
+        @filename = filename
+        @relations = relations
+      end
+
+      # Parses categories in JSON file
+      def generate
+        @categories = Util::Json.read(@filename)
+
+        # Perform expansion on all class names containing * wildcard
+        @categories.each do |cat|
+          cat["groups"].each do |group|
+            group["classes"] = group["classes"].map do |name|
+              expand(name)
+            end.flatten
+          end
+        end
+
+        validate
+
+        @categories
+      end
+
+      # Expands class name like 'Foo.*' into multiple class names.
+      def expand(name)
+        re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
+
+        classes = @relations.to_a.find_all do |cls|
+          re =~ cls[:name] && !cls[:private] && !cls[:deprecated]
+        end.map {|cls| cls[:name] }.sort
+
+        if classes.length == 0
+          Logger.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file", {:filename => @filename})
+        end
+        classes
+      end
+
+      # Prints warnings for missing classes in categories file
+      def validate
+        # Build a map of all classes listed in categories
+        listed_classes = {}
+        @categories.each do |cat|
+          cat["groups"].each do |group|
+            group["classes"].each do |cls_name|
+              listed_classes[cls_name] = true
+            end
+          end
+        end
+
+        # Check that each existing non-private & non-deprecated class is listed
+        @relations.each do |cls|
+          unless listed_classes[cls[:name]] || cls[:private] || cls[:deprecated]
+            Logger.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", {:filename => @filename})
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/class.rb

@@ -0,0 +1,218 @@
+require 'jsduck/logger'
+require 'jsduck/members_index'
+
+module JsDuck
+
+  # Encapsulates class documentation and provides some commonly needed
+  # methods on it.  Otherwise it acts like Hash, providing the []
+  # method.
+  class Class
+    attr_accessor :relations
+
+    # Used only by MembersIndex class itself to access the
+    # MembersIndex instances of parents and mixins.
+    attr_accessor :members_index
+
+    # Creates JSDuck class.
+    #
+    # Pass true as second parameter to create a placeholder class.
+    def initialize(doc, class_exists=true)
+      @doc = doc
+
+      # Wrap classname into custom string class that allows
+      # differenciating between existing and missing classes.
+      @doc[:name] = ClassNameString.new(@doc[:name], class_exists)
+
+      @doc[:members] = [] if !@doc[:members]
+
+      @members_index = MembersIndex.new(self)
+
+      @relations = nil
+    end
+
+    # Returns the internal doc object.
+    def internal_doc
+      @doc
+    end
+
+    # Sets the internal doc object.
+    #
+    # The doc object is processed in parallel and then assigned back
+    # through this method.  But because of parallel processing the
+    # assigned doc object will not be just a modified old @doc but a
+    # completely new.  If we were to just assign to @doc the
+    # #find_members caches would still point to old @doc members
+    # resulting in mysterious errors further along...
+    def internal_doc=(doc)
+      @doc.merge!(doc) do |key, oldval, newval|
+        if key == :members
+          oldval.zip(newval) do |ms|
+            ms[0].merge!(ms[1])
+          end
+          oldval
+        else
+          newval
+        end
+      end
+    end
+
+    # Accessor to internal hash
+    def [](key)
+      @doc[key]
+    end
+
+    # Assignment to internal hash keys
+    def []=(key, value)
+      @doc[key] = value
+    end
+
+    # Returns instance of parent class, or nil if there is none
+    def parent
+      @doc[:extends] ? lookup(@doc[:extends]) : nil
+    end
+
+    # Returns array of ancestor classes.
+    # Example result when asking ancestors of MyPanel might be:
+    #
+    #   [Ext.util.Observable, Ext.Component, Ext.Panel]
+    #
+    def superclasses
+      p = parent
+      p ? p.superclasses + [p]  : []
+    end
+
+    # Returns all direct mixins of this class. Same as #deps(:mixins).
+    def mixins
+      deps(:mixins)
+    end
+
+    # Returns an array of class instances this class directly depends on.
+    # Possible types are:
+    #
+    # - :mixins
+    # - :requires
+    # - :uses
+    #
+    def deps(type)
+      @doc[type] ? @doc[type].collect {|classname| lookup(classname) } : []
+    end
+
+    # Same ase #deps, but pulls out the dependencies from all parent classes.
+    def parent_deps(type)
+      parent ? parent.deps(type) + parent.parent_deps(type) : []
+    end
+
+    # Looks up class object by name
+    # When not found, prints warning message.
+    def lookup(classname)
+      if @relations[classname]
+        @relations[classname]
+      elsif @relations.ignore?(classname) || classname =~ /\*/
+        # Ignore explicitly ignored classes and classnames with
+        # wildcards in them.  We could expand the wildcard, but that
+        # can result in a very long list of classes, like when
+        # somebody requires 'Ext.form.*', so for now we do the
+        # simplest thing and ignore it.
+        Class.new({:name => classname}, false)
+      else
+        Logger.warn(:extend, "Class #{classname} not found", @doc[:files][0])
+        # Create placeholder class
+        Class.new({:name => classname}, false)
+      end
+    end
+
+    # Returns true when this class inherits from the specified class.
+    # Also returns true when the class itself is the one we are asking about.
+    def inherits_from?(class_name)
+      return @doc[:name] == class_name || (parent ? parent.inherits_from?(class_name) : false)
+    end
+
+    # Returns list of members filtered by a query.
+    # Searches both local and inherited members.
+    #
+    # The query hash can contain the following fields:
+    #
+    # - :name : String    - the name of the member to find.
+    #
+    # - :tagname : Symbol - the member type to look for.
+    #
+    # - :static : Boolean - true to only return static members,
+    #                       false to only return instance members.
+    #                       When nil or unspecified, both static
+    #                       and instance members are returned.
+    #
+    # - :local : Boolean -  true to only return non-inherited members.
+    #
+    # When called without arguments all members are returned.
+    #
+    # When nothing found, an empty array is returned.
+    def find_members(query={})
+      if query[:name]
+        ms = @members_index.global_by_name[query[:name]] || []
+        ms = ms.find_all {|m| m[:owner] == @doc[:name]} if query[:local]
+      elsif query[:local]
+        ms = @members_index.all_local
+      else
+        ms = @members_index.all_global
+      end
+
+      if query[:tagname]
+        ms = ms.find_all {|m| m[:tagname] == query[:tagname] }
+      end
+
+      if query[:static] == true
+        ms = ms.find_all {|m| m[:static] }
+      elsif query[:static] == false
+        ms = ms.reject {|m| m[:static] }
+      end
+
+      ms
+    end
+
+    # This must be called whenever member hashes are changed.
+    # It updates the :id fields of members and clears the caches.
+    def refresh_member_ids!
+      @doc[:members].each do |m|
+        m[:id] = Class.member_id(m)
+      end
+      @members_index.invalidate!
+    end
+
+    # Returns all local members of class
+    def all_local_members
+      @doc[:members]
+    end
+
+    # Static methods
+
+    # Generates member :id from member hash
+    def self.member_id(m)
+      # Sanitize $ in member names with something safer
+      name = m[:name].gsub(/\$/, 'S-')
+      "#{m[:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
+    end
+
+    # True if the given member is a constructor method
+    def self.constructor?(member)
+      member[:tagname] == :method && member[:name] == "constructor"
+    end
+  end
+
+  # String class for classnames that has extra method #exists? which
+  # returns false when class with such name doesn't exist.
+  #
+  # This ability is used by JsDuck::Renderer, which only receives
+  # names of various classes but needs to only render existing classes
+  # as links.
+  class ClassNameString < String
+    def initialize(str, exists=true)
+      super(str)
+      @exists = exists
+    end
+
+    def exists?
+      @exists
+    end
+  end
+
+end