solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/doc/delimited_parser.rb

@@ -0,0 +1,105 @@
+module JsDuck
+  module Doc
+
+    # Helper in parsing the default values and type definitions where
+    # we take into account correctly nested parenthesis and strings.
+    # But at the same time we don't care much about the actual
+    # contents.
+    class DelimitedParser
+      # Initialized with Doc::Scanner instance
+      def initialize(doc_scanner)
+        @ds = doc_scanner
+      end
+
+      # Parses until a closing "}".
+      def parse_until_close_curly
+        parse_until_close_paren(/\}/, /[^\}]*/)
+      end
+
+      # Parses until a closing "]".
+      def parse_until_close_square
+        parse_until_close_paren(/\]/, /[^\]]*/)
+      end
+
+      # Parses until a closing parenthesis or space.
+      def parse_until_space
+        begin
+          parse_while(/[^\[\]\{\}\(\)'"\s]/)
+        rescue
+          nil
+        end
+      end
+
+      private
+
+      # Parses until a given closing parenthesis.
+      # When unsuccessful, try simple parsing.
+      def parse_until_close_paren(re_paren, re_simple)
+        begin
+          start_pos = @ds.input.pos
+          result = parse_while(/[^\[\]\{\}\(\)'"]/)
+          if look(re_paren)
+            result
+          else
+            throw "Closing brace expected"
+          end
+        rescue
+          @ds.input.pos = start_pos
+          match(re_simple)
+        end
+      end
+
+      def parse_while(regex)
+        result = ""
+        while r = parse_compound || match(regex)
+          result += r
+        end
+        result
+      end
+
+      def parse_compound
+        if look(/\[/)
+          parse_balanced(/\[/, /\]/)
+        elsif look(/\{/)
+          parse_balanced(/\{/, /\}/)
+        elsif look(/\(/)
+          parse_balanced(/\(/, /\)/)
+        elsif look(/"/)
+          parse_string('"')
+        elsif look(/'/)
+          parse_string("'")
+        end
+      end
+
+      def parse_balanced(re_open, re_close)
+        result = match(re_open)
+
+        result += parse_while(/[^\[\]\{\}\(\)'"]/)
+
+        if r = match(re_close)
+          result + r
+        else
+          throw "Unbalanced parenthesis"
+        end
+      end
+
+      # Parses "..." or '...' including the escape sequence \' or '\"
+      def parse_string(quote)
+        re_quote = Regexp.new(quote)
+        re_rest = Regexp.new("(?:[^"+quote+"\\\\]|\\\\.)*")
+        match(re_quote) + match(re_rest) + (match(re_quote) || "")
+      end
+
+      ### Forward these calls to Doc::Scanner
+
+      def look(re)
+        @ds.look(re)
+      end
+
+      def match(re)
+        @ds.match(re)
+      end
+    end
+
+  end
+end

data/lib/jsduck/doc/map.rb

@@ -0,0 +1,23 @@
+module JsDuck
+  module Doc
+
+    # Helper for building at-tags lookup table.
+    class Map
+
+      # Builds map of at-tags for quick lookup
+      def self.build(docs)
+        map = {}
+        docs.each do |tag|
+          if map[tag[:tagname]]
+            map[tag[:tagname]] << tag
+          else
+            map[tag[:tagname]] = [tag]
+          end
+        end
+        map
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/parser.rb

@@ -0,0 +1,135 @@
+require 'strscan'
+require 'jsduck/doc/comment'
+require 'jsduck/doc/scanner'
+require 'jsduck/tag_registry'
+require 'jsduck/logger'
+
+module JsDuck
+  module Doc
+
+    # Parses doc-comment into array of @tags
+    #
+    # For each @tag it produces Hash like the following:
+    #
+    #     {
+    #       :tagname => :cfg/:property/:type/:extends/...,
+    #       :doc => "Some documentation for this tag",
+    #       ...@tag specific stuff like :name, :type, and so on...
+    #     }
+    #
+    # When doc-comment begins with comment, not preceded by @tag, then
+    # the comment will be placed into Hash with :tagname => :default.
+    #
+    # Unrecognized @tags are left as is into documentation as if they
+    # were normal text.
+    #
+    # @example, {@img}, {@link} and {@video} are parsed separately in
+    # JsDuck::DocFormatter.
+    #
+    class Parser < Doc::Scanner
+      def parse(input, filename="", linenr = 0)
+        @position = {:filename => filename, :linenr => linenr}
+        @tags = []
+        @non_repeatable_tags = {}
+        @input = StringScanner.new(Doc::Comment.purify(input))
+
+        parse_loop
+
+        strip_docs
+        @tags
+      end
+
+      # The parsing process can leave whitespace at the ends of
+      # doc-strings, here we get rid of it.
+      def strip_docs
+        @tags.each do |tag|
+          tag[:doc].strip! if tag[:doc]
+        end
+      end
+
+      # The main loop of the DocParser
+      def parse_loop
+        add_tag({:tagname => :doc, :doc => :multiline})
+
+        while !@input.eos? do
+          if look(/@/)
+            parse_at_tag
+          elsif look(/[^@]/)
+            skip_to_next_at_tag
+          end
+        end
+      end
+
+      # Appends new @tag to parsed tags list
+      def add_tag(tag)
+        @tags << tag
+
+        if tag[:doc] == :multiline
+          tag[:doc] = ""
+          @multiline_tag = tag
+        end
+      end
+
+      # Processes anything beginning with @-sign.
+      #
+      # - When @ is not followed by any word chars, do nothing.
+      # - When it's one of the builtin tags, process it as such.
+      # - When it's something else, print a warning.
+      #
+      def parse_at_tag
+        match(/@/)
+        name = look(/\w+/)
+
+        if !name
+          # ignore
+        elsif tag = TagRegistry.get_by_pattern(name)
+          match(/\w+/)
+          hw # Skip the whitespace right after the tag.
+
+          tags = tag.parse_doc(self, @position)
+          if tags.is_a?(Hash)
+            add_tag(tags)
+          elsif tags.is_a?(Array)
+            tags.each {|t| add_tag(t) }
+          end
+
+          if !tag.repeatable
+            if @non_repeatable_tags[name]
+              warn(:tag_repeated, "@#{name} tag can occur only once per doc-comment")
+            end
+            @non_repeatable_tags[name] = true
+          end
+
+          skip_white
+        else
+          warn(:tag, "Unsupported tag: @#{name}", [name.to_sym])
+          @multiline_tag[:doc] += "@"
+        end
+      end
+
+      # Skips until the beginning of next @tag.
+      #
+      # There must be space before the next @tag - this ensures that we
+      # don't detect tags inside "foo@example.com" or "{@link}".
+      #
+      # Also check that the @tag is not part of an indented code block -
+      # in which case we also ignore the tag.
+      def skip_to_next_at_tag
+        @multiline_tag[:doc] += match(/[^@]+/)
+
+        while look(/@/) && (!prev_char_is_whitespace? || indented_as_code?)
+          @multiline_tag[:doc] += match(/@+[^@]+/)
+        end
+      end
+
+      def prev_char_is_whitespace?
+        @multiline_tag[:doc][-1,1] =~ /\s/
+      end
+
+      def indented_as_code?
+        @multiline_tag[:doc] =~ /^ {4,}[^\n]*\z/
+      end
+    end
+
+  end
+end

data/lib/jsduck/doc/processor.rb

@@ -0,0 +1,52 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Doc
+
+    # Processes @tag data detected from doc-comment, transforming it
+    # into a class/member hash which can be then later further merged
+    # with code hash.
+    #
+    # Its main work is done through calling the #process_doc method of
+    # all the Tag classes that have registered themselves to process a
+    # particular set of @tags through defining a .tagname attribute.
+    class Processor
+      # Allow passing in filename and line for error reporting
+      attr_accessor :filename
+      attr_accessor :linenr
+
+      def initialize
+        @filename = ""
+        @linenr = 0
+      end
+
+      # Given tagname and map of tags from DocParser, produces docs
+      # of the type determined by tagname.
+      def process(tagname, doc_map)
+        hash = {
+          :tagname => tagname,
+          :doc => extract_doc(doc_map),
+        }
+
+        position = {:filename => @filename, :linenr => @linenr}
+
+        doc_map.each_pair do |name, value|
+          if tag = TagRegistry.get_by_name(name)
+            tag.process_doc(hash, value, position)
+          end
+        end
+
+        return hash
+      end
+
+      private
+
+      def extract_doc(doc_map)
+        tag = doc_map[:doc] ? doc_map[:doc].first : {}
+        return tag[:doc] || ""
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/scanner.rb

@@ -0,0 +1,83 @@
+require 'jsduck/doc/standard_tag_parser'
+require 'jsduck/logger'
+
+module JsDuck
+  module Doc
+
+    # Abstract base class for parsing doc-comments.
+    #
+    # The methods of this class are to be called from implementations
+    # of concrete @tags.  Although the @tag classes will get passed an
+    # instance of Doc::Parser, only methods of Doc::Scanner should be
+    # called by them.
+    #
+    class Scanner
+      def initialize
+        @ident_pattern = /[$\w-]+/
+        @ident_chain_pattern = /[$\w-]+(\.[$\w-]+)*/
+
+        @input = nil # set to StringScanner in subclass
+        @position = {} # set in subclass
+      end
+
+      # Provides access to StringScanner
+      attr_accessor :input
+
+      # Parses standard pattern common in several builtin tags, which
+      # goes like this:
+      #
+      #     @tag {Type} [some.name=default]
+      #
+      # See StandardTagParser#parse for details.
+      #
+      def standard_tag(cfg)
+        Doc::StandardTagParser.new(self).parse(cfg)
+      end
+
+      # matches chained.identifier.name and returns it
+      def ident_chain
+        @input.scan(@ident_chain_pattern)
+      end
+
+      # matches identifier and returns its name
+      def ident
+        @input.scan(@ident_pattern)
+      end
+
+      # Looks for the existance of pattern.  Returns the matching
+      # string on success, nil on failure, but doesn't advance the
+      # scan pointer.
+      def look(re)
+        @input.check(re)
+      end
+
+      # Matches the given pattern and advances the scan pointer
+      # returning the string that matched.  When the pattern doesn't
+      # match, nil is returned.
+      def match(re)
+        @input.scan(re)
+      end
+
+      # Skips all whitespace.  Moves scan pointer to next non-whitespace
+      # character.
+      def skip_white
+        @input.scan(/\s+/)
+      end
+
+      # Skips horizontal whitespace (tabs and spaces).  Moves scan
+      # pointer to next non-whitespace character or to the end of line.
+      # Returns self to allow chaining.
+      def hw
+        @input.scan(/[ \t]+/)
+        self
+      end
+
+      # Prints a warning message
+      def warn(type, msg, params=[])
+        Logger.warn(type, msg, @position, params)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/doc/standard_tag_parser.rb

@@ -0,0 +1,125 @@
+require 'jsduck/doc/delimited_parser'
+
+module JsDuck
+  module Doc
+
+    # Helper in parsing the standard tag pattern with type definition
+    # followed by name and default value:
+    #
+    # @tag {Type} [some.name=default]
+    #
+    class StandardTagParser
+      # Initialized with Doc::Scanner instance
+      def initialize(doc_scanner)
+        @ds = doc_scanner
+        @delimited_parser = Doc::DelimitedParser.new(doc_scanner)
+      end
+
+      # Parses the standard tag pattern.
+      #
+      # Takes as parameter a configuration hash which can contain the
+      # following keys:
+      #
+      # - :tagname => The :tagname of the hash to return.
+      #
+      # - :type => True to parse `{Type}` section.
+      #
+      # - :name => True to parse `some.name` section.
+      #
+      # - :default => True to parse `=<default-value>` after name.
+      #
+      # - :optional => True to allow placing name and default value
+      #       inside [ and ] brackets to denote optionality.
+      #       Also returns :optional=>true when {SomType=} syntax used.
+      #
+      # Returns tag definition hash containing the fields specified by
+      # config.
+      #
+      def parse(cfg)
+        @tagname = cfg[:tagname]
+        tag = {}
+        tag[:tagname] = cfg[:tagname] if cfg[:tagname]
+        add_type(tag, cfg) if cfg[:type]
+        add_name_with_default(tag, cfg) if cfg[:name]
+        tag
+      end
+
+      private
+
+      # matches {type} if possible and sets it on given tag hash.
+      # Also checks for {optionality=} in type definition.
+      def add_type(tag, cfg)
+        if hw.look(/\{/)
+          tdf = typedef
+          tag[:type] = tdf[:type]
+          tag[:optional] = true if tdf[:optional] && cfg[:optional]
+        end
+      end
+
+      # matches {...=} and returns text inside brackets
+      def typedef
+        match(/\{/)
+
+        name = @delimited_parser.parse_until_close_curly
+
+        unless match(/\}/)
+          warn("@#{@tagname} tag syntax: '}' expected")
+        end
+
+        if name =~ /=$/
+          name = name.chop
+          optional = true
+        else
+          optional = nil
+        end
+
+        return {:type => name, :optional => optional}
+      end
+
+      # matches:   <ident-chain>
+      #          | <ident-chain> [ "=" <default-value>
+      #          | "[" <ident-chain> [ "=" <default-value> ] "]"
+      def add_name_with_default(tag, cfg)
+        if hw.look(/\[/) && cfg[:optional]
+          match(/\[/)
+          tag[:name] = hw.ident_chain
+          if hw.match(/=/)
+            hw
+            tag[:default] = @delimited_parser.parse_until_close_square
+          end
+          hw.match(/\]/) or warn("@#{@tagname} tag syntax: ']' expected")
+          tag[:optional] = true
+        elsif name = ident_chain
+          tag[:name] = name
+          if cfg[:default] && hw.match(/=/)
+            hw
+            tag[:default] = @delimited_parser.parse_until_space
+          end
+        end
+      end
+
+      ### Forward these calls to Doc::Scanner
+
+      def ident_chain
+        @ds.ident_chain
+      end
+
+      def look(re)
+        @ds.look(re)
+      end
+
+      def match(re)
+        @ds.match(re)
+      end
+
+      def hw
+        @ds.hw
+      end
+
+      def warn(msg)
+        @ds.warn(:tag_syntax, msg)
+      end
+    end
+
+  end
+end