jsduck 4.0.1 → 4.1.1

data/lib/jsduck/batch_parser.rb

@@ -0,0 +1,106 @@
+require 'jsduck/util/parallel'
+require 'jsduck/util/io'
+require 'jsduck/source/file'
+require 'jsduck/aggregator'
+require 'jsduck/class'
+require 'jsduck/relations'
+require 'jsduck/logger'
+require 'jsduck/inherit_doc'
+require 'jsduck/importer'
+require 'jsduck/return_values'
+require 'jsduck/lint'
+
+module JsDuck
+
+  # Performs the parsing of all input files.  Input files are read
+  # from options object (originating from command line).
+  class BatchParser
+    def initialize(opts)
+      @opts = opts
+    end
+
+    # Array of Source::File objects.
+    # Available after calling the #run method.
+    attr_reader :parsed_files
+
+    # Parses the files and returns instance of Relations class.
+    def run
+      @parsed_files = parallel_parse(@opts.input_files)
+      result = aggregate(@parsed_files)
+      @relations = filter_classes(result)
+      apply_extra_processing
+      return @relations
+    end
+
+    private
+
+    # Parses the files in parallel using as many processes as available CPU-s
+    def parallel_parse(filenames)
+      Util::Parallel.map(filenames) do |fname|
+        Logger.log("Parsing", fname)
+        begin
+          Source::File.new(Util::IO.read(fname), fname, @opts)
+        rescue
+          Logger.fatal_backtrace("Error while parsing #{fname}", $!)
+          exit(1)
+        end
+      end
+    end
+
+    # Aggregates parsing results sequencially
+    def aggregate(parsed_files)
+      agr = Aggregator.new
+      parsed_files.each do |file|
+        Logger.log("Aggregating", file.filename)
+        agr.aggregate(file)
+      end
+      agr.classify_orphans
+      agr.create_global_class
+      agr.remove_ignored_classes
+      agr.create_accessors
+      if @opts.ext4_events == true || (@opts.ext4_events == nil && agr.ext4?)
+        agr.append_ext4_event_options
+      end
+      agr.process_enums
+      # Ignore override classes after applying them to actual classes
+      @opts.external_classes += agr.process_overrides.map {|o| o[:name] }
+      agr.result
+    end
+
+    # Turns all aggregated data into Class objects.
+    # Depending on --ignore-global either keeps or discards the global class.
+    # Warnings for global members are printed regardless of that setting,
+    # but of course can be turned off using --warnings=-global
+    def filter_classes(docs)
+      classes = []
+      docs.each do |d|
+        cls = Class.new(d)
+        if d[:name] != "global"
+          classes << cls
+        else
+          # add global class only if --ignore-global not specified
+          classes << cls unless @opts.ignore_global
+
+          # Print warning for each global member
+          cls.all_local_members.each do |m|
+            type = m[:tagname].to_s
+            name = m[:name]
+            file = m[:files][0]
+            Logger.warn(:global, "Global #{type}: #{name}", file[:filename], file[:linenr])
+          end
+        end
+      end
+      Relations.new(classes, @opts.external_classes)
+    end
+
+    # Do all kinds of post-processing on relations.
+    def apply_extra_processing
+      InheritDoc.new(@relations).resolve_all
+      Importer.import(@opts.imports, @relations, @opts.new_since)
+      ReturnValues.auto_detect(@relations)
+      Lint.new(@relations).run
+    end
+
+  end
+
+end

data/lib/jsduck/categories.rb

@@ -1,5 +1,4 @@
 require 'jsduck/logger'
-require 'jsduck/json_duck'
 require 'jsduck/file_categories'
 require 'jsduck/auto_categories'
 
@@ -23,7 +22,7 @@ module JsDuck
     end
 
     # Returns HTML listing of classes divided into categories
-    def to_html
+    def to_html(style="")
       html = @categories.map do |category|
         [
           "<div class='section'>",
@@ -35,7 +34,7 @@ module JsDuck
       end.flatten.join("\n")
 
       return <<-EOHTML
-        <div id='categories-content' style='display:none'>
+        <div id='categories-content' style='#{style}'>
             #{html}
         </div>
       EOHTML
@@ -58,9 +57,9 @@ module JsDuck
       return groups.map do |g|
         [
           "<h3>#{g['name']}</h3>",
-          "<div class='links'>",
-          g["classes"].map {|cls| @relations[cls] ? @doc_formatter.link(cls, nil, cls) : cls },
-          "</div>",
+          "<ul class='links'>",
+          g["classes"].map {|cls| "<li>" + (@relations[cls] ? @doc_formatter.link(cls, nil, cls) : cls) + "</li>" },
+          "</ul>",
         ]
       end
     end

data/lib/jsduck/class.rb

@@ -1,4 +1,5 @@
 require 'jsduck/logger'
+require 'jsduck/members_index'
 
 module JsDuck
 
@@ -8,6 +9,10 @@ module JsDuck
   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.
@@ -18,19 +23,37 @@ module JsDuck
       # differenciating between existing and missing classes.
       @doc[:name] = ClassNameString.new(@doc[:name], class_exists)
 
-      @doc[:members] = Class.default_members_hash if !@doc[:members]
-      @doc[:statics] = Class.default_members_hash if !@doc[:statics]
+      @doc[:members] = [] if !@doc[:members]
+
+      @members_index = MembersIndex.new(self)
+
       @relations = nil
     end
 
-    # Accessors for internal doc object.  These are used to run
-    # ClassFormatter on the internal doc object and then assign it
-    # back.
+    # 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 = 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
@@ -93,272 +116,87 @@ module JsDuck
         Class.new({:name => classname}, false)
       else
         context = @doc[:files][0]
-        Logger.instance.warn(:extend, "Class #{classname} not found", context[:filename], context[:linenr])
+        Logger.warn(:extend, "Class #{classname} not found", context[:filename], context[:linenr])
         # Create placeholder class
         Class.new({:name => classname}, false)
       end
     end
 
-    # Returns copy of @doc hash
-    def to_hash
-      @doc.clone
-    end
-
-    def to_json(*a)
-      to_hash.to_json(*a)
-    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 full_name == class_name || (parent ? parent.inherits_from?(class_name) : false)
+      return @doc[:name] == class_name || (parent ? parent.inherits_from?(class_name) : false)
     end
 
-    # Returns array of all public members of particular type in a class,
-    # sorted by name.
+    # Returns list of members filtered by a query.
+    # Searches both local and inherited members.
     #
-    # For methods the the constructor is listed first.
+    # The query hash can contain the following fields:
     #
-    # See members_hash for details.
-    def members(type, context=:members)
-      ms = members_hash(type, context).values #.find_all {|m| !m[:private] }
-      ms.sort! {|a,b| a[:name] <=> b[:name] }
-      type == :method ? constructor_first(ms) : ms
-    end
-
-    # If methods list contains constructor, rename it with class name
-    # and move into beginning of methods list.
-    def constructor_first(ms)
-      constr = ms.find {|m| m[:name] == "constructor" }
-      if constr
-        ms.delete(constr)
-        ms.unshift(constr)
-      end
-      ms
-    end
-
-    # Returns hash of all members in class (and of parent classes
-    # and mixin classes).  Members are methods, properties, cfgs,
-    # events (member type is specified through 'type' parameter).
+    # - :name : String    - the name of the member to find.
     #
-    # When parent and child have members with same name,
-    # member from child overrides tha parent member.
-    def members_hash(type, context=:members)
-      # Singletons have no static members
-      if @doc[:singleton] && context == :statics
-        # Warn if singleton has static members
-        @doc[context][type].each do |m|
-          ctx = m[:files][0]
-          msg = "Singleton class #{@doc[:name]} can't have static members, remove the @static tag."
-          Logger.instance.warn(:sing_static, msg, ctx[:filename], ctx[:linenr])
-        end
-        return {}
-      end
-
-      ms = parent ? parent.members_hash(type, context) : {}
-
-      mixins.each do |mix|
-        merge!(ms, mix.members_hash(type, context))
-      end
-
-      # For static members, exclude everything not explicitly marked as inheritable
-      if context == :statics
-        ms.delete_if {|key, member| !member[:inheritable] }
-      end
-
-      merge!(ms, local_members_hash(type, context))
-
-      # If singleton has static members, include them as if they were
-      # instance members.  Otherwise they will be completely excluded
-      # from the docs, as the static members block is not created for
-      # singletons.
-      if @doc[:singleton] && @doc[:statics][type].length > 0
-        merge!(ms, local_members_hash(type, :statics))
-      end
-
-      ms
-    end
-
-    # merges second members hash into first one
-    def merge!(hash1, hash2, skip_overrides=false)
-      hash2.each_pair do |name, m|
-        if m[:meta] && m[:meta][:hide]
-          if hash1[name]
-            hash1.delete(name)
-          else
-            ctx = m[:files][0]
-            msg = "@hide used but #{m[:tagname]} #{m[:name]} not found in parent class"
-            Logger.instance.warn(:hide, msg, ctx[:filename], ctx[:linenr])
-          end
-        else
-          if hash1[name]
-            store_overrides(hash1[name], m)
-          end
-          hash1[name] = m
-        end
-      end
-    end
-
-    # Invoked when merge! finds two members with the same name.
-    # New member always overrides the old, but inside new we keep
-    # a list of members it overrides.  Normally one member will
-    # override one other member, but a member from mixin can override
-    # multiple members - although there's not a single such case in
-    # ExtJS, we have to handle it.
+    # - :tagname : Symbol - the member type to look for.
     #
-    # Every overridden member is listed just once.
-    def store_overrides(old, new)
-      # Sometimes a class is included multiple times (like Ext.Base)
-      # resulting in its members overriding themselves.  Because of
-      # this, ignore overriding itself.
-      if new[:owner] != old[:owner]
-        new[:overrides] = [] unless new[:overrides]
-        unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
-          # Make a copy of the important properties for us.  We can't
-          # just push the actual `old` member itself, because there
-          # can be circular overrides (notably with Ext.Base), which
-          # will result in infinite loop when we try to convert our
-          # class into JSON.
-          new[:overrides] << {
-            :name => old[:name],
-            :owner => old[:owner],
-            :id => old[:id],
-          }
-        end
+    # - :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.local_by_id.values
+      else
+        ms = @members_index.global_by_id.values
       end
-    end
 
-    # Helper method to get the direct members of this class
-    def local_members_hash(type, context)
-      local_members = {}
-      (@doc[context][type] || []).each do |m|
-        local_members[m[:name]] = m
+      if query[:tagname]
+        ms = ms.find_all {|m| m[:tagname] == query[:tagname] }
       end
-      local_members
-    end
 
-    # Returns members by name. An array of one or more members, or
-    # empty array when nothing matches.
-    #
-    # Optionally one can also specify type name to differenciate
-    # between different types of members.
-    #
-    # Finally static flag can be specified. True to look only at
-    # static members, false to look at instance members, and nil to
-    # look at both.
-    def get_members(name, type_name=nil, static=nil)
-      # build hash of all members
-      unless @members_map
-        @members_map = {}
-        [:members, :statics].each do |group|
-          @doc[group].each_key do |type|
-            members_hash(type, group).each_pair do |key, member|
-              @members_map[key] = (@members_map[key] || []) + [member]
-            end
-          end
-        end
+      if query[:static] == true
+        ms = ms.find_all {|m| m[:meta] && m[:meta][:static] }
+      elsif query[:static] == false
+        ms = ms.reject {|m| m[:meta] && m[:meta][:static] }
       end
 
-      ms = @members_map[name] || []
-      ms = ms.find_all {|m| m[:tagname] == type_name } if type_name
-      # static = true | false | nil
-      ms = ms.find_all {|m| m[:meta][:static] } if static == true
-      ms = ms.find_all {|m| !m[:meta][:static] } if static == false
-      return ms
-    end
-
-    # Call this when renaming or moving members inside class.
-    def reset_members_lookup!
-      @members_map = nil
+      ms
     end
 
-    # Returns all members of class, including the inherited and mixed in ones
-    def all_members
-      all = []
-      [:members, :statics].each do |group|
-        @doc[group].each_key do |type|
-          all += members(type, group)
-        end
+    # This must be called whenever member hashes are changed.
+    # It updates the :id fields of members and clears the caches.
+    def update_members!(members)
+      members.each do |m|
+        m[:id] = Class.member_id(m)
       end
-      all
+      @members_index.invalidate!
     end
 
     # Returns all local members of class
     def all_local_members
-      all = []
-      [:members, :statics].each do |group|
-        @doc[group].each_value do |ms|
-          all += ms
-        end
-      end
-      all
-    end
-
-    # A way to access full class name with similar syntax to
-    # package_name and short_name
-    def full_name
-      @doc[:name]
-    end
-
-    # Returns package name of the class.
-    #
-    # That is the namespace part of full class name.
-    #
-    # For example "My.package" is package_name of "My.package.Class"
-    def package_name
-      Class.package_name(@doc[:name])
-    end
-
-    # Returns last part of full class name
-    #
-    # For example for "My.package.Class" it is "Class"
-    def short_name
-      Class.short_name(@doc[:name])
-    end
-
-    # Returns CSS icons class for the class
-    def icon
-      if @doc[:singleton]
-        "icon-singleton"
-      elsif inherits_from?("Ext.Component")
-        "icon-component"
-      else
-        "icon-class"
-      end
+      @doc[:members]
     end
 
     # Static methods
 
-    # Utility method that given a package or class name finds the name
-    # of its parent package.
-    def self.package_name(name)
-      name.slice(0, name.length - self.short_name(name).length - 1) || ""
-    end
-
-    # Utility method that given full package or class name extracts
-    # the "class"-part of the name.
-    #
-    # Because we try to emulate ext-doc, it's not as simple as just
-    # taking the last part.  See class_spec.rb for details.
-    def self.short_name(name)
-      parts = name.split(/\./)
-      short = parts.pop
-      while parts.length > 1 && parts.last =~ /^[A-Z]/
-        short = parts.pop + "." + short
-      end
-      short
+    # Generates member :id from member hash
+    def self.member_id(m)
+      # Sanitize $ in member names with something safer
+      name = m[:name].gsub(/\$/, 'S-')
+      "#{m[:meta][:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
     end
 
-    # Returns default hash that has empty array for each member type
-    def self.default_members_hash
-      return {
-        :cfg => [],
-        :property => [],
-        :method => [],
-        :event => [],
-        :css_var => [],
-        :css_mixin => [],
-      }
+    # Loops through all available member types,
+    # passing the tagname of the member to the block.
+    def self.each_member_type(&block)
+      [:cfg, :property, :method, :event, :css_var, :css_mixin].each(&block)
     end
   end