solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag_registry.rb

@@ -0,0 +1,95 @@
+require "jsduck/tag_loader"
+
+module JsDuck
+
+  # Access to all @tag definitions.
+  class TagRegistry
+    # Access to the singleton instance (only used internally)
+    def self.instance
+      @instance = TagRegistry.new unless @instance
+      @instance
+    end
+
+    # Configures TagRegistry according to the command line options.
+    def self.configure(opts)
+      if opts.tags.length > 0
+        # Reconfigures the registry with additional load paths.
+        @instance = TagRegistry.new(opts.tags)
+      else
+        # Ensure the TagRegistry get instantiated just once.
+        # Otherwise the parallel processing causes multiple requests
+        # to initialize the TagRegistry, resulting in loading the Tag
+        # definitions multiple times.
+        instance
+      end
+
+      # The tooltip of @new can now be configured.
+      get_by_name(:new).init_tooltip!(opts)
+    end
+
+    # Redirect calls from TagRegistry.method to TagRegistry.instance.method,
+    # making it behave like other Singleton classes.
+    def self.method_missing(meth, *args, &block)
+      self.instance.send(meth, *args, &block)
+    end
+
+    def initialize(load_paths=[])
+      @patterns = {}
+      @tagnames = {}
+      @signatures = []
+      @tags = []
+
+      instantiate_tags(TagLoader.new(load_paths).load_all)
+    end
+
+    # Instantiates all descendants of JsDuck::Tag::Tag
+    def instantiate_tags(tag_classes)
+      tag_classes.each do |cls|
+        tag = cls.new()
+
+        Array(tag.pattern).each do |pattern|
+          @patterns[pattern] = tag
+        end
+
+        if tag.tagname
+          @tagnames[tag.tagname] = tag
+        end
+
+        if tag.signature
+          tag.signature[:tagname] = tag.tagname
+          @signatures << tag.signature
+        end
+
+        @tags << tag
+      end
+    end
+
+    #
+    # Accessors for lists of tags
+    #
+
+    # Array of attributes to be shown in member signatures
+    # (and in order they should be shown in).
+    attr_reader :signatures
+
+    # Array of all available tags
+    attr_reader :tags
+
+    #
+    # Accessors for a single tag
+    #
+
+    # Accesses tag by @name pattern
+    def get_by_pattern(name)
+      @patterns[name]
+    end
+
+    # Accesses tag by name - the symbol under which the tag data
+    # is stored in final hash.
+    def get_by_name(name)
+      @tagnames[name]
+    end
+
+  end
+
+end

data/lib/jsduck/type_parser.rb

@@ -0,0 +1,388 @@
+require 'strscan'
+
+module JsDuck
+
+  # Validates the syntax of type definitions.
+  #
+  # The parser supports a combination of two syntaxes:
+  #
+  # 1. Traditional type expressions found in ExtJS code:
+  #
+  #     "string"
+  #     3.14
+  #     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.
+    # It will be either of the two:
+    # - :syntax - type definition syntax is incorrect
+    # - :name - one of the names of the types is unknown
+    attr_reader :error
+
+    # When parsing was successful, then contains the output HTML - the
+    # input type-definition with types themselves replaced with links.
+    attr_reader :out
+
+    # Initializes the parser with a Format::Doc instance.
+    def initialize(formatter)
+      @relations = formatter.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 the base type doesn't match
+      return false unless alteration_type
+
+      # Concatenate all output
+      @out = @out.join
+
+      # Success if we have reached the end of input
+      return @input.eos?
+    end
+
+    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> | <string-literal> | <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
+      elsif @input.check(/['"]/)
+        return false unless string_literal
+      elsif @input.check(/[\d-]/)
+        return false unless number_literal
+      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
+      @out << 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> ]*
+    #
+    #     <ftype-first-arg> ::= "new" ":" <type-name>
+    #                         | "this" ":" <type-name>
+    #                         | <ftype-arg>
+    #
+    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
+
+      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
+
+    #
+    #     <string-literal> ::= '.*' | ".*"
+    #
+    def string_literal
+      @out << @input.scan(/"([^\\"]|\\.)*?"|'([^\\']|\\.)*?'/)
+
+      true
+    end
+
+    #
+    #     <number-literal> ::= [ "-" ] <digit>+ [ "." <digit>+ ]
+    #
+    def number_literal
+      @out << @input.scan(/-?\d+(\.\d+)?/)
+
+      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[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
+
+      # All type names besides * can be followed by .<arguments>
+      if name != "*" && @input.scan(/\.</)
+        @out << ".&lt;"
+        return false unless type_arguments
+        return false unless @input.scan(/>/)
+        @out << "&gt;"
+      end
+
+      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