jsduck 3.7.0 → 3.8.0

data/lib/jsduck/json_duck.rb

@@ -1,3 +1,4 @@
+require 'jsduck/io'
 require 'json'
 
 module JsDuck
@@ -33,7 +34,7 @@ module JsDuck
 
     # Reads and parses JSON from file
     def self.read(filename)
-      self.parse(IO.read(filename))
+      self.parse(JsDuck::IO.read(filename))
     end
 
     # Parses JSON string

data/lib/jsduck/options.rb

@@ -1,6 +1,7 @@
 require 'optparse'
 require 'jsduck/meta_tag_registry'
 require 'jsduck/logger'
+require 'jsduck/io'
 
 module JsDuck
 
@@ -163,11 +164,8 @@ module JsDuck
           @meta_tag_paths << canonical(path)
         end
 
-        opts.on('--no-warnings',
-          "Turns off all warnings.",
-          "(Deprecated, use --warnings=-all instead.)", " ") do
-          Logger.instance.warn(nil, "--no-warnings is deprecated. Use --warnings=-all instead.")
-          Logger.instance.set_warning(:all, false)
+        opts.on('--encoding=NAME', "Input encoding (defaults to UTF-8).", " ") do |encoding|
+          JsDuck::IO.encoding = encoding
         end
 
         opts.on('-v', '--verbose', "This will fill up your console.", " ") do
@@ -260,7 +258,7 @@ module JsDuck
           "Possible placeholders:",
           "%u - URL from @img tag (e.g. 'some/path.png')",
           "%a - alt text for image",
-          "Default is: '<p><img src=\"doc-resources/%u\" alt=\"%a\"></p>'", " ") do |tpl|
+          "Default is: '<p><img src=\"%u\" alt=\"%a\"></p>'", " ") do |tpl|
           @img_tpl = tpl
         end
 
@@ -380,7 +378,7 @@ module JsDuck
             main_opts = [
               /--output/,
               /--builtin-classes/,
-              /--no-warnings/,
+              /--encoding/,
               /--verbose/,
               /--help/,
               /--version/,
@@ -449,7 +447,7 @@ module JsDuck
 
     # Extracts files of first build in jsb file
     def extract_jsb_files(jsb_file)
-      json = JSON.parse(IO.read(jsb_file))
+      json = JSON.parse(JsDuck::IO.read(jsb_file))
       basedir = File.dirname(jsb_file)
 
       return json["builds"][0]["packages"].map do |package_id|

data/lib/jsduck/search_data.rb

@@ -4,11 +4,12 @@ module JsDuck
   # Creates list of all members in all classes that is used by the
   # searching feature in UI.
   class SearchData
-    # Given list of class documentation objects returns an array of
-    # hashes describing all the members.
-    def create(docs)
+    # Given list of classes and other assets, returns an array of
+    # hashes describing the search data.
+    def create(classes, assets)
       list = []
-      docs.each do |cls|
+
+      classes.each do |cls|
         list << class_node(cls)
 
         cls[:alternateClassNames].each do |name|
@@ -32,61 +33,96 @@ module JsDuck
           end
         end
       end
+
+      assets.guides.each_item {|g| list << guide_node(g) }
+
+      assets.videos.each_item {|v| list << video_node(v) }
+
+      assets.examples.each_item {|e| list << example_node(e) }
+
       list
     end
 
-    # Creates structure representing one alias
+    private
+
     def alias_node(key, name, cls)
       return {
-        :cls => alias_display_name(key)+": "+name,
-        :member => name,
-        :type => :class,
-        :icon => cls.icon,
-        :id => cls.full_name,
+        :name => name,
+        :fullName => alias_display_name(key)+": "+name,
+        :icon => cls.icon + "-redirect",
+        :url => "#!/api/" + cls.full_name,
         :meta => cls[:meta],
         :sort => 0,
       }
     end
 
-    # Creates structure representing one class
     def class_node(cls)
       return {
-        :cls => cls.full_name,
-        :member => cls.short_name,
-        :type => :class,
+        :name => cls.short_name,
+        :fullName => cls.full_name,
         :icon => cls.icon,
-        :id => cls.full_name,
+        :url => "#!/api/" + cls.full_name,
         :meta => cls[:meta],
         :sort => 1,
       }
     end
 
-    # Creates structure representing one alternate classname
     def alt_node(name, cls)
       return {
-        :cls => name,
-        :member => Class.short_name(name),
+        :name => Class.short_name(name),
+        :fullName => name,
         :type => :class,
-        :icon => cls.icon,
-        :id => cls.full_name,
+        :icon => cls.icon + "-redirect",
+        :url => "#!/api/" + cls.full_name,
         :meta => cls[:meta],
         :sort => 2,
       }
     end
 
-    # Creates structure representing one member
     def member_node(member, cls)
       return {
-        :cls => cls.full_name,
-        :member => member[:name],
-        :type => :member,
+        :name => member[:name],
+        :fullName => cls.full_name + "." + member[:name],
         :icon => "icon-" + member[:tagname].to_s,
-        :id => cls.full_name + "-" + member[:id],
+        :url => "#!/api/" + cls.full_name + "-" + member[:id],
         :meta => member[:meta],
         :sort => 3,
       }
     end
 
+    def guide_node(guide)
+      return {
+        :name => guide["title"],
+        :fullName => "guide: " + guide["title"],
+        :icon => "icon-guide",
+        :url => "#!/guide/" + guide["name"],
+        :meta => {},
+        :sort => 4,
+      }
+    end
+
+    def video_node(video)
+      return {
+        :name => video["title"],
+        :fullName => "video: " + video["title"],
+        :icon => "icon-video",
+        :url => "#!/video/" + video["name"],
+        :meta => {},
+        :sort => 4,
+      }
+    end
+
+    def example_node(example)
+      return {
+        :name => example["title"],
+        :fullName => "example: " + example["title"],
+        :icon => "icon-example",
+        :url => "#!/example/" + example["name"],
+        :meta => {},
+        :sort => 4,
+      }
+    end
+
     # Some alias types are shown differently.
     # e.g. instead of "widget:" we show "xtype:"
     def alias_display_name(key)

data/lib/jsduck/tag/aside.rb

@@ -3,9 +3,6 @@ require "jsduck/logger"
 
 module JsDuck::Tag
   # Implementation of @aside tag.
-  #
-  # To document members that were present in previous version but are
-  # completely gone now.  Other than that it behaves exactly like @deprecated.
   class Aside < JsDuck::MetaTag
     def initialize
       @name = "aside"

data/lib/jsduck/type_parser.rb

@@ -2,17 +2,40 @@ require 'strscan'
 
 module JsDuck
 
-  # Validates the syntax of type definitions
+  # Validates the syntax of type definitions.
   #
-  # Quick summary of supported types:
+  # The parser supports a combination of two syntaxes:
   #
-  # - SomeType
-  # - Name.spaced.Type
-  # - Number[]
-  # - String/RegExp
-  # - Type...
+  # 1. Traditional type expressions found in ExtJS code:
   #
-  # Details are covered in spec.
+  #     SomeType
+  #     Name.spaced.Type
+  #     Number[]
+  #     String/RegExp
+  #     Type...
+  #
+  # 2. Google Closure Compiler Type Expressions:
+  #
+  #     boolean
+  #     Window
+  #     goog.ui.Menu
+  #
+  #     Array.<string>
+  #     Object.<string, number>
+  #
+  #     {myNum: number, myObject}
+  #
+  #     (number|boolean)
+  #     ?number
+  #     !Object
+  #     ...number
+  #     *
+  #
+  #     function(string, boolean): number
+  #     function(new:goog.ui.Menu, string)
+  #     function(this:goog.ui.Menu, string)
+  #     function(?string=, number=)
+  #     function(string, ...[number])
   #
   class TypeParser
     # Allows to check the type of error that was encountered.
@@ -29,22 +52,27 @@ module JsDuck
     def initialize(relations={}, formatter={})
       @relations = relations
       @formatter = formatter
+      @primitives = {
+        "boolean" => "Boolean",
+        "number" => "Number",
+        "string" => "String",
+        "null" => "null",
+        "undefined" => "undefined",
+        "void" => "void",
+      }
     end
 
+    # Parses the type definition
+    #
+    #     <type> ::= <alteration-type>
+    #
     def parse(str)
       @input = StringScanner.new(str)
       @error = :syntax
       @out = []
 
-      # Return immediately if base type doesn't match
-      return false unless base_type
-
-      # Go through enumeration of types, separated with "/"
-      while @input.check(/\//)
-        @out << @input.scan(/\//)
-        # Fail if there's no base type after "/"
-        return false unless base_type
-      end
+      # Return immediately if the base type doesn't match
+      return false unless alteration_type
 
       # Concatenate all output
       @out = @out.join
@@ -53,34 +81,281 @@ module JsDuck
       return @input.eos?
     end
 
-    # The basic type
+    private
+
+    #
+    #     <alteration-type> ::= <varargs-type> [ ("/" | "|") <varargs-type> ]*
+    #
+    def alteration_type
+      skip_whitespace
+
+      # Return immediately if varargs-type doesn't match
+      return false unless varargs_type
+
+      skip_whitespace
+
+      # Go through enumeration of types, separated with "/" or "|"
+      while @input.check(/[\/|]/)
+        @out << @input.scan(/[\/|]/)
+
+        skip_whitespace
+        return false unless varargs_type
+        skip_whitespace
+      end
+
+      true
+    end
+
+    #
+    #     <varargs-type> ::= "..." <null-type>
+    #                      | "..." "[" <null-type> "]"
+    #                      | <null-type> "..."
+    #                      | <null-type>
+    #
+    def varargs_type
+      if @input.scan(/\.\.\./)
+        varargs = true
+        @out << "..."
+        if @input.scan(/\[/)
+          varargs_bracketed = true
+          @out << "["
+        end
+      end
+
+      return false unless null_type
+
+      if !varargs
+        @out << "..." if @input.scan(/\.\.\./)
+      end
+
+      if varargs_bracketed
+        return false unless @input.scan(/\]/)
+        @out << "]"
+      end
+
+      true
+    end
+
+    #
+    #     <null-type> ::= [ "?" | "!" ] <array-type>
+    #
+    #     <array-type> ::= <atomic-type> [ "[]" ]*
+    #
+    #     <atomic-type> ::= <union-type> | <record-type> | <function-type> | <type-name>
+    #
+    def null_type
+      if nullability = @input.scan(/[?!]/)
+        @out << nullability
+      end
+
+      if @input.check(/\(/)
+        return false unless union_type
+      elsif @input.check(/\{/)
+        return false unless record_type
+      elsif @input.check(/function\(/)
+        return false unless function_type
+      else
+        return false unless type_name
+      end
+
+      while @input.scan(/\[\]/)
+        @out << "[]"
+      end
+
+      true
+    end
+
+    #
+    #     <union-type> ::= "(" <alteration-type> ")"
+    #
+    def union_type
+      @out << @input.scan(/\(/)
+
+      return false unless alteration_type
+
+      return false unless @input.scan(/\)/)
+      @out << ")"
+
+      true
+    end
+
+    #
+    #     <record-type> ::= "{" <rtype-item> [ "," <rtype-item> ]* "}"
+    #
+    def record_type
+      @out << @input.scan(/\{/)
+
+      return false unless rtype_item
+
+      while @input.scan(/,/)
+        @out << ","
+        return false unless rtype_item
+      end
+
+      return false unless @input.scan(/\}/)
+      @out << "}"
+
+      true
+    end
+
+    #
+    #     <rtype-item> ::= <ident> ":" <null-type>
+    #                    | <ident>
+    #
+    def rtype_item
+      skip_whitespace
+
+      key = @input.scan(/[a-zA-Z0-9_]+/)
+      return false unless key
+
+      skip_whitespace
+      if @input.scan(/:/)
+        @out << ":"
+        skip_whitespace
+        return false unless null_type
+        skip_whitespace
+      end
+
+      true
+    end
+
+    #
+    #     <function-type> ::= "function(" <function-type-arguments> ")" [ ":" <null-type> ]
+    #
+    def function_type
+      @out << @input.scan(/function\(/)
+
+      skip_whitespace
+      if !@input.check(/\)/)
+        return false unless function_type_arguments
+      end
+
+      return false unless @input.scan(/\)/)
+      @out << ")"
+
+      skip_whitespace
+      if @input.scan(/:/)
+        @out << ":"
+        skip_whitespace
+        return false unless null_type
+      end
+
+      true
+    end
+
+    #
+    #     <function-type-arguments> ::= <ftype-first-arg> [ "," <ftype-arg> ]*
     #
-    #     <ident> [ "." <ident> ]* [ "[]" ]* [ "..." ]
+    #     <ftype-first-arg> ::= "new" ":" <type-name>
+    #                         | "this" ":" <type-name>
+    #                         | <ftype-arg>
     #
-    # dot-separated identifiers followed by optional "[]"
-    def base_type
-      type = @input.scan(/[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*/)
+    def function_type_arguments
+      skip_whitespace
+
+      # First argument is special
+      if s = @input.scan(/new\s*:\s*/)
+        @out << s
+        return false unless type_name
+      elsif s = @input.scan(/this\s*:\s*/)
+        @out << s
+        return false unless type_name
+      else
+        return false unless ftype_arg
+      end
+
+      skip_whitespace
+
+      # Go through additional arguments, separated with ","
+      while @input.check(/,/)
+        @out << @input.scan(/,/)
+        return false unless ftype_arg
+      end
 
-      if !type
+      true
+    end
+
+    #
+    #     <ftype-arg> ::= <alteration-type> [ "=" ]
+    #
+    def ftype_arg
+      return false unless alteration_type
+
+      # Each argument can be optional (ending with "=")
+      @out << "=" if @input.scan(/[=]/)
+      skip_whitespace
+
+      true
+    end
+
+    #
+    #     <type-name> ::= <type-application> | "*"
+    #
+    #     <type-application> ::= <ident-chain> [ "." "<" <type-arguments> ">" ]
+    #
+    #     <type-arguments> ::= <alteration-type> [ "," <alteration-type> ]*
+    #
+    #     <ident-chain> ::= <ident> [ "." <ident> ]*
+    #
+    #     <ident> ::= [a-zA-Z0-9_]+
+    #
+    def type_name
+      name = @input.scan(/[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*|\*/)
+
+      if !name
         return false
-      elsif @relations[type]
-        @out << @formatter.link(type, nil, type)
-      elsif @relations.ignore?(type) || type == "undefined"
-        @out << type
+      elsif @relations[name]
+        @out << @formatter.link(name, nil, name)
+      elsif @primitives[name]
+        if @relations[@primitives[name]]
+          @out << @formatter.link(@primitives[name], nil, name)
+        else
+          @out << name
+        end
+      elsif @relations.ignore?(name) || name == "*"
+        @out << name
       else
         @error = :name
         return false
       end
 
-      while @input.scan(/\[\]/)
-        @out << "[]"
+      # All type names besides * can be followed by .<arguments>
+      if name != "*" && @input.scan(/\.</)
+        return false unless type_arguments
+        return false unless @input.scan(/>/)
       end
 
-      @out << "..." if @input.scan(/\.\.\./)
+      true
+    end
+
+    #
+    #     <type-arguments> ::= <alteration-type> [ "," <alteration-type> ]*
+    #
+    def type_arguments
+      skip_whitespace
+
+      # First argument is required
+      return false unless alteration_type
+
+      skip_whitespace
+
+      # Go through additional arguments, separated with ","
+      while @input.check(/,/)
+        @out << @input.scan(/,/)
+
+        skip_whitespace
+        return false unless alteration_type
+        skip_whitespace
+      end
 
       true
     end
 
+    def skip_whitespace
+      ws = @input.scan(/\s*/)
+      @out << ws if ws
+    end
+
   end
 
 end