jsduck 2.0.pre4 → 3.0.pre

data/lib/jsduck/doc_parser.rb

@@ -1,4 +1,6 @@
 require 'strscan'
+require 'jsduck/js_literal_parser'
+require 'jsduck/js_literal_builder'
 
 module JsDuck
 
@@ -23,7 +25,8 @@ module JsDuck
   class DocParser
     # Pass in :css to be able to parse CSS doc-comments
     def initialize(mode = :js)
-      @ident_pattern = (mode == :css) ? /\$[a-zA-Z0-9_-]*/ : /\w+/
+      @ident_pattern = (mode == :css) ? /\$?[\w-]+/ : /[$\w]\w*/
+      @ident_chain_pattern = (mode == :css) ? /\$?[\w-]+(\.[\w-]+)*/ : /[$\w]\w*(\.\w+)*/
     end
 
     def parse(input)
@@ -183,21 +186,28 @@ module JsDuck
       skip_white
     end
 
-    # matches @param {type} variable ...
+    # matches @param {type} [name] (optional) ...
     def at_param
       match(/@param/)
       add_tag(:param)
       maybe_type
-      maybe_name
+      maybe_name_with_default
+      maybe_optional
       skip_white
     end
 
-    # matches @return {type} ...
+    # matches @return {type} [ return.name ] ...
     def at_return
       match(/@returns?/)
       add_tag(:return)
       maybe_type
       skip_white
+      if look(/return\.\w/)
+        @current_tag[:name] = ident_chain
+      else
+        @current_tag[:name] = "return"
+      end
+      skip_white
     end
 
     # matches @cfg {type} name ...
@@ -205,7 +215,8 @@ module JsDuck
       match(/@cfg/)
       add_tag(:cfg)
       maybe_type
-      maybe_name
+      maybe_name_with_default
+      maybe_required
       skip_white
     end
 
@@ -219,7 +230,7 @@ module JsDuck
       match(/@property/)
       add_tag(:property)
       maybe_type
-      maybe_name
+      maybe_ident_chain(:name)
       skip_white
     end
 
@@ -278,7 +289,7 @@ module JsDuck
       match(/@alias/)
       add_tag(:alias)
       skip_horiz_white
-      if look(/\w/)
+      if look(@ident_chain_pattern)
         @current_tag[:cls] = ident_chain
         if look(/#\w/)
           @input.scan(/#/)
@@ -336,6 +347,44 @@ module JsDuck
       end
     end
 
+    # matches: <ident-chain> | "[" <ident-chain> [ "=" <literal> ] "]"
+    def maybe_name_with_default
+      skip_horiz_white
+      if look(/\[/)
+        match(/\[/)
+        maybe_ident_chain(:name)
+        skip_horiz_white
+        if look(/=/)
+          match(/=/)
+          skip_horiz_white
+          @current_tag[:default] = literal
+        end
+        skip_horiz_white
+        match(/\]/)
+        @current_tag[:optional] = true
+      else
+        maybe_ident_chain(:name)
+      end
+    end
+
+    # matches: "(optional)"
+    def maybe_optional
+      skip_horiz_white
+      if look(/\(optional\)/i)
+        match(/\(optional\)/i)
+        @current_tag[:optional] = true
+      end
+    end
+
+    # matches: "(required)"
+    def maybe_required
+      skip_horiz_white
+      if look(/\(required\)/i)
+        match(/\(required\)/i)
+        @current_tag[:optional] = false
+      end
+    end
+
     # matches identifier name if possible and sets it on @current_tag
     def maybe_name
       skip_horiz_white
@@ -347,11 +396,16 @@ module JsDuck
     # matches ident.chain if possible and sets it on @current_tag
     def maybe_ident_chain(propname)
       skip_horiz_white
-      if look(/\w/)
+      if look(@ident_chain_pattern)
         @current_tag[propname] = ident_chain
       end
     end
 
+    def literal
+      lit = JsLiteralParser.new(@input).literal
+      lit ? JsLiteralBuilder.new.to_s(lit) : nil
+    end
+
     # matches {...} and returns text inside brackets
     def typedef
       match(/\{/)
@@ -364,7 +418,7 @@ module JsDuck
     def class_list
       skip_horiz_white
       classes = []
-      while look(/\w/)
+      while look(@ident_chain_pattern)
         classes << ident_chain
         skip_horiz_white
       end
@@ -373,7 +427,7 @@ module JsDuck
 
     # matches chained.identifier.name and returns it
     def ident_chain
-      @input.scan(/[\w.]+/)
+      @input.scan(@ident_chain_pattern)
     end
 
     # matches identifier and returns its name

data/lib/jsduck/examples.rb

@@ -0,0 +1,33 @@
+require 'jsduck/json_duck'
+
+module JsDuck
+
+  # Reads in examples JSON file
+  class Examples
+    def initialize
+      @examples = []
+    end
+
+    # Parses examples config file
+    def parse(filename)
+      @examples = JsonDuck.read(filename)
+    end
+
+    # Writes examples JSON file to dir
+    def write(dir)
+      return if @examples.length == 0
+
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+      # Write the JSON to output dir, so it's available in released
+      # version of docs and people can use it with JSDuck by themselves.
+      JsonDuck.write_json(dir+"/examples.json", @examples)
+    end
+
+    # Returns all examples as array
+    def to_array
+      @examples
+    end
+
+  end
+
+end

data/lib/jsduck/exporter.rb

@@ -1,17 +1,11 @@
-require 'jsduck/doc_formatter'
-
 module JsDuck
 
   # Export class data as hash with :cfg being replace with :cfgs and
   # including all the inherited members too.  Same for :properties,
   # :methods, and :events.
-  #
-  # Also all the :doc elements will be formatted - converted from
-  # markdown to HTML and @links resolved.
   class Exporter
-    def initialize(relations, formatter)
+    def initialize(relations)
       @relations = relations
-      @formatter = formatter
     end
 
     # Returns all data in Class object as hash.
@@ -27,50 +21,32 @@ module JsDuck
       h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
       h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c.full_name }
       h[:allMixins] = cls.all_mixins.collect {|c| c.full_name }
-      format_class(h)
+      h
     end
 
-    # converts :doc properties from markdown to html and resolve @links
-    def format_class(c)
-      @formatter.class_context = c[:name]
-      @formatter.doc_context = c
-      c[:doc] = @formatter.format(c[:doc]) if c[:doc]
-      c[:members].each_pair do |type, members|
-        c[:members][type] = members.map {|m| format_member(m) }
-      end
-      c[:statics].each_pair do |type, members|
-        c[:statics][type] = members.map {|m| format_member(m) }
-      end
-      c
+    # removes extra data from export
+    def compact(cls)
+      cls.delete(:doc)
+      cls[:members] = compact_members_group(cls[:members])
+      cls[:statics] = compact_members_group(cls[:statics])
+      cls
     end
 
-    def format_member(m)
-      m = m.clone
-      @formatter.doc_context = m
-      m[:doc] = @formatter.format(m[:doc]) if m[:doc]
-      m[:deprecated][:text] = @formatter.format(m[:deprecated][:text]) if m[:deprecated]
-      if m[:params] || @formatter.too_long?(m[:doc])
-        m[:shortDoc] = @formatter.shorten(m[:doc])
+    def compact_members_group(group)
+      c_group = {}
+      group.each_pair do |type, members|
+        c_group[type] = members.map {|m| compact_member(m) }
       end
-      m[:params] = format_params(m[:params]) if m[:params]
-      m[:return] = format_return(m[:return]) if m[:return]
-      m
+      c_group
     end
 
-    def format_params(params)
-      params.map do |p|
-        p = p.clone
-        p[:doc] = @formatter.format(p[:doc]) if p[:doc]
-        p
+    def compact_member(m)
+      m_copy = {}
+      [:name, :tagname, :owner, :protected, :static, :deprecated, :required].each do |key|
+        m_copy[key] = m[key]
       end
+      m_copy
     end
-
-    def format_return(r)
-      r = r.clone
-      r[:doc] = @formatter.format(r[:doc]) if r[:doc]
-      r
-    end
-
   end
 
 end

data/lib/jsduck/guides.rb

@@ -1,109 +1,76 @@
-require 'jsduck/jsonp'
 require 'jsduck/logger'
+require 'jsduck/json_duck'
 require 'fileutils'
 
 module JsDuck
 
   # Reads in guides and converts them to JsonP files
   class Guides
-    def initialize(formatter, order=nil)
-      @guides = []
+    def initialize(formatter)
       @formatter = formatter
-      @order = order
+      @guides = []
     end
 
-    # Looks for guide in each subdir of given directory.
-    def parse_dir(guides_dir)
-      Dir.glob(guides_dir + "/*").each do |dir|
-        if File.directory?(dir)
-          parse_guide(dir)
-        end
-      end
+    # Parses guides config file
+    def parse(filename)
+      @path = File.dirname(filename)
+      @guides = JsonDuck.read(filename)
+    end
 
-      if @order
-        # When order specified, place guides into that order and
-        # exclude those guides that aren't listed in @order
-        @guides = @order.map {|name| @guides.find {|g| g[:name] =~ Regexp.new("^"+Regexp.escape(name)) } }
-      else
-        # Otherwise sort guides alphabetically
-        @guides.sort! {|a, b| a[:title] <=> b[:title] }
-      end
+    # Writes all guides to given dir in JsonP format
+    def write(dir)
+      return if @guides.length == 0
+
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+      @guides.each {|group| group["items"].each {|g| write_guide(g, dir) } }
+      # Write the JSON to output dir, so it's available in released
+      # version of docs and people can use it with JSDuck by themselves.
+      JsonDuck.write_json(dir+"/guides.json", @guides)
     end
 
-    def parse_guide(dir)
-      guide_file = dir + "/README.md"
-      unless File.exists?(guide_file)
-        return Logger.instance.warn("README.md not found in #{dir}")
-      end
+    def write_guide(guide, dir)
+      in_dir = @path + "/" + guide["name"]
+      out_dir = dir + "/" + guide["name"]
+      return Logger.instance.warn("Guide #{in_dir} not found") unless File.exists?(in_dir)
+      guide_file = in_dir + "/README.md"
+      return Logger.instance.warn("README.md not found in #{in_dir}") unless File.exists?(guide_file)
 
-      Logger.instance.log("Parsing guide #{guide_file} ...")
-      markdown = IO.read(guide_file)
-      name = File.basename(dir)
-      # Treat the first line of file as title
-      title = markdown.match(/^#\s*([^\n]*?)(\r?\n|$)/)[1]
+      Logger.instance.log("Writing guide #{out_dir} ...")
+      # Copy the whole guide dir over
+      FileUtils.cp_r(in_dir, out_dir)
 
       @formatter.doc_context = {:filename => guide_file, :linenr => 0}
-      html = @formatter.format(markdown)
+      html = @formatter.format(IO.read(guide_file))
+      name = File.basename(in_dir)
       html.gsub!(/<img src="/, "<img src=\"guides/#{name}/")
 
-      @guides << {
-        :dir => dir,
-        :name => name,
-        :title => title,
-        :icon => File.exists?(dir+"/icon.png"),
-        :html => html,
-      }
+      JsonDuck.write_jsonp(out_dir+"/README.js", name, {:guide => html, :title => guide["title"]})
     end
 
-    # Writes all guides to given dir in JsonP format
-    def write(dir)
-      # Skip it all when we have no guides
-      FileUtils.mkdir(dir) if @guides.length > 0
-
-      @guides.each do |guide|
-        out_dir = dir+"/"+guide[:name]
-        FileUtils.cp_r(guide[:dir], out_dir)
-        # Write the JsonP file
-        JsonP.write(out_dir+"/README.js", guide[:name], {:guide => guide[:html]})
-      end
+    # Returns all guides as array
+    def to_array
+      @guides
     end
 
     # Returns HTML listing of guides
     def to_html
       return "" if @guides.length == 0
 
-      links = @guides.map do |g|
-        style = g[:icon] ? "style='background: url(guides/#{g[:name]}/icon.png) no-repeat'" : ""
-        "<a class='guide' rel='#{g[:name]}' #{style} href='#/guide/#{g[:name]}'>#{g[:title]}</a>"
-      end
+      html = @guides.map do |group|
+        [
+          "<h3>#{group['title']}</h3>",
+          "<ul>",
+          group["items"].map {|g| "<li><a href='#!/guide/#{g['name']}'>#{g['title']}</a></li>" },
+          "</ul>",
+        ]
+      end.flatten.join("\n")
 
-      # Divide to three columns: lft, mid, rgt
-      col_height = (links.length / 3).ceil
       return <<-EOHTML
         <div id='guides-content' style='display:none'>
-            <div class="lft">
-                #{links.slice(0, col_height).join("\n")}
-            </div>
-            <div class="mid">
-                #{links.slice(col_height, col_height).join("\n")}
-            </div>
-            <div class="rgt">
-                #{links.slice(col_height*2, col_height).join("\n")}
-            </div>
+            #{html}
         </div>
       EOHTML
     end
-
-    # Iterates over each guide
-    def each(&block)
-      @guides.each &block
-    end
-
-    # Returns number of guides
-    def length
-      @guides.length
-    end
-
   end
 
 end

data/lib/jsduck/icons.rb

@@ -0,0 +1,28 @@
+module JsDuck
+
+  # Creates an array of small hashes documenting name, parent class
+  # and icon of a class.
+  class Icons
+    def create(classes)
+      classes.map do |cls|
+        {
+          :name => cls[:name],
+          :extends => cls[:extends],
+          :private => cls[:private],
+          :icon => icon(cls),
+        }
+      end
+    end
+
+    def icon(cls)
+      if cls[:singleton]
+        "icon-singleton"
+      elsif cls.inherits_from?("Ext.Component")
+        "icon-component"
+      else
+        "icon-class"
+      end
+    end
+  end
+
+end

data/lib/jsduck/js_literal_builder.rb

@@ -0,0 +1,21 @@
+module JsDuck
+
+  # Takes output of JsLiteralParser and converts it to string
+  class JsLiteralBuilder
+
+    # Converts literal object definition to string
+    def to_s(lit)
+      if lit[:type] == :string
+        '"' + lit[:value] + '"'
+      elsif lit[:type] == :array
+        "[" + lit[:value].map {|v| to_s(v) }.join(", ") + "]"
+      elsif lit[:type] == :object
+        "{" + lit[:value].map {|v| to_s(v[:key]) + ": " + to_s(v[:value]) }.join(", ") + "}"
+      else
+        lit[:value]
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/js_literal_parser.rb

@@ -0,0 +1,106 @@
+require 'jsduck/lexer'
+
+module JsDuck
+
+  # Parser for JavaScript literals: numbers, strings, booleans,
+  # regexes, arrays, objects.
+  #
+  # Almost like a JSON parser, but regexes are also valid values and
+  # object keys don't need to be quoted.
+  class JsLiteralParser
+    def initialize(input)
+      @lex = Lexer.new(input)
+    end
+
+    # Parses a literal.
+    #
+    # Returns a Ruby hash representing this literal.  For example parsing this:
+    #
+    #     [5, "foo"]
+    #
+    # Returns the following structure:
+    #
+    #     {:type => :array, :value => [
+    #         {:type => :number, :value => "5"},
+    #         {:type => :string, :value => "foo"}
+    #     ]}
+    #
+    def literal
+      if look(:number)
+        match(:number)
+      elsif look(:string)
+        match(:string)
+      elsif look(:regex)
+        match(:regex)
+      elsif look("[")
+        array_literal
+      elsif look("{")
+        object_literal
+      elsif look(:ident) && (look("true") || look("false") || look("undefined") || look("null"))
+        match(:ident)
+      end
+    end
+
+    def array_literal
+      match("[")
+      r = []
+      while (lit = literal)
+        r << lit
+        break unless look(",")
+        match(",")
+      end
+      return unless look("]")
+      match("]")
+      return {:type => :array, :value => r}
+    end
+
+    def object_literal
+      match("{")
+      r = []
+      while (look(:ident) || look(:string))
+        lit = object_literal_pair
+        return unless lit
+        r << lit
+        break unless look(",")
+        match(",")
+      end
+
+      return unless look("}")
+      match("}")
+      return {:type => :object, :value => r}
+    end
+
+    def object_literal_pair
+      if look(:ident)
+        key = match(:ident)
+      elsif look(:string)
+        key = match(:string)
+      end
+
+      return unless look(":")
+      match(":")
+
+      value = literal
+      return unless value
+
+      return {:key => key, :value => value}
+    end
+
+    # Matches all arguments, returns the value of last match
+    # When the whole sequence doesn't match, throws exception
+    def match(*args)
+      if look(*args)
+        last = nil
+        args.length.times { last = @lex.next(true) }
+        last
+      else
+        throw "Expected: " + args.join(", ")
+      end
+    end
+
+    def look(*args)
+      @lex.look(*args)
+    end
+  end
+
+end