class JsDuck::Doc::StandardTagParser

Helper in parsing the standard tag pattern with type definition followed by name and default value:

@tag {Type} [some.name=default]

Public Class Methods

new(doc_scanner) click to toggle source

Initialized with Doc::Scanner instance

# File lib/jsduck/doc/standard_tag_parser.rb, line 13
def initialize(doc_scanner)
  @ds = doc_scanner
  @delimited_parser = Doc::DelimitedParser.new(doc_scanner)
end

Public Instance Methods

parse(cfg) click to toggle source

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.

# File lib/jsduck/doc/standard_tag_parser.rb, line 38
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 Instance Methods

add_name_with_default(tag, cfg) click to toggle source

matches: <ident-chain>

| <ident-chain> [ "=" <default-value>
| "[" <ident-chain> [ "=" <default-value> ] "]"
# File lib/jsduck/doc/standard_tag_parser.rb, line 82
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
add_type(tag, cfg) click to toggle source

matches {type} if possible and sets it on given tag hash. Also checks for {optionality=} in type definition.

# File lib/jsduck/doc/standard_tag_parser.rb, line 51
def add_type(tag, cfg)
  if hw.look(/\{/)
    tdf = typedef
    tag[:type] = tdf[:type]
    tag[:optional] = true if tdf[:optional] && cfg[:optional]
  end
end
hw() click to toggle source
# File lib/jsduck/doc/standard_tag_parser.rb, line 115
def hw
  @ds.hw
end
ident_chain() click to toggle source

Forward these calls to Doc::Scanner

# File lib/jsduck/doc/standard_tag_parser.rb, line 103
def ident_chain
  @ds.ident_chain
end
look(re) click to toggle source
# File lib/jsduck/doc/standard_tag_parser.rb, line 107
def look(re)
  @ds.look(re)
end
match(re) click to toggle source
# File lib/jsduck/doc/standard_tag_parser.rb, line 111
def match(re)
  @ds.match(re)
end
typedef() click to toggle source

matches {…=} and returns text inside brackets

# File lib/jsduck/doc/standard_tag_parser.rb, line 60
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
warn(msg) click to toggle source
# File lib/jsduck/doc/standard_tag_parser.rb, line 119
def warn(msg)
  @ds.warn(:tag_syntax, msg)
end