Class: YARD::DocstringParser

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/docstring_parser.rb

Overview

Parses text and creates a Docstring object to represent documentation for a CodeObjects::Base. To create a new docstring, you should initialize the parser and call #parse followed by #to_docstring.

Examples:

Creating a Docstring with a DocstringParser

DocstringParser.new.parse("text here").to_docstring

Since:

  • 0.8.0

Constant Summary collapse

META_MATCH =

The regular expression to match the tag syntax

Since:

  • 0.8.0

/^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(library = Tags::Library.instance) ⇒ DocstringParser

Creates a new parser to parse docstring data

Parameters:

  • library (Tags::Library) (defaults to: Tags::Library.instance) —

    a tag library for recognizing tags.

Since:

  • 0.8.0



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/yard/docstring_parser.rb', line 74

def initialize(library = Tags::Library.instance)
  @text = ""
  @raw_text = ""
  @tags = []
  @directives = []
  @library = library
  @object = nil
  @handler = nil
  @state = OpenStruct.new
end

Instance Attribute Details

#directives ⇒ Array<Directive> (readonly)

Returns a list of directives identified by the parser. This list will not be passed on to the Docstring object.

Returns:

  • (Array<Directive>) —

    a list of directives identified by the parser. This list will not be passed on to the Docstring object.

Since:

  • 0.8.0



45
46
47
 
# File 'lib/yard/docstring_parser.rb', line 45

def directives
  @directives
end

#handler ⇒ Handlers::Base?

Returns the handler parsing this docstring. May be nil if this docstring parser is not initialized through.

Returns:

  • (Handlers::Base, nil) —

    the handler parsing this docstring. May be nil if this docstring parser is not initialized through

Since:

  • 0.8.0



61
62
63
 
# File 'lib/yard/docstring_parser.rb', line 61

def handler
  @handler
end

#library ⇒ Tags::Library

Returns the tag library being used to identify registered tags in the docstring.

Returns:

  • (Tags::Library) —

    the tag library being used to identify registered tags in the docstring.

Since:

  • 0.8.0



65
66
67
 
# File 'lib/yard/docstring_parser.rb', line 65

def library
  @library
end

#object ⇒ CodeObjects::Base?

Returns the object associated with the docstring being parsed. May be nil if the docstring is not attached to any object.

Returns:

  • (CodeObjects::Base, nil) —

    the object associated with the docstring being parsed. May be nil if the docstring is not attached to any object.

Since:

  • 0.8.0



56
57
58
 
# File 'lib/yard/docstring_parser.rb', line 56

def object
  @object
end

#raw_text ⇒ String (readonly)

Returns the complete input string to the parser.

Returns:

  • (String) —

    the complete input string to the parser.

Since:

  • 0.8.0



36
37
38
 
# File 'lib/yard/docstring_parser.rb', line 36

def raw_text
  @raw_text
end

#state ⇒ OpenStruct (readonly)

Returns any arbitrary state to be passed between tags during parsing. Mainly used by directives to coordinate behaviour (so that directives can be aware of other directives used in a docstring).

Returns:

  • (OpenStruct) —

    any arbitrary state to be passed between tags during parsing. Mainly used by directives to coordinate behaviour (so that directives can be aware of other directives used in a docstring).

Since:

  • 0.8.0



51
52
53
 
# File 'lib/yard/docstring_parser.rb', line 51

def state
  @state
end

#tags ⇒ Array<Tag> (readonly)

Returns the list of meta-data tags identified by the parser.

Returns:

  • (Array<Tag>) —

    the list of meta-data tags identified by the parser

Since:

  • 0.8.0



40
41
42
 
# File 'lib/yard/docstring_parser.rb', line 40

def tags
  @tags
end

#text ⇒ String (readonly)

Returns the parsed text portion of the docstring, with tags removed.

Returns:

  • (String) —

    the parsed text portion of the docstring, with tags removed.

Since:

  • 0.8.0



33
34
35
 
# File 'lib/yard/docstring_parser.rb', line 33

def text
  @text
end

Class Method Details

.after_parse {|parser| ... } ⇒ void

This method returns an undefined value.

Creates a callback that is called after a docstring is successfully parsed. Use this method to perform sanity checks on a docstring’s tag data, or add any extra tags automatically to a docstring.

Yields:

  • (parser) —

    a block to be called after a docstring is parsed

Yield Parameters:

  • parser (DocstringParser) —

    the docstring parser object with all directives and tags created.

Yield Returns:

  • (void)

Since:

  • 0.8.0



21
22
23
 
# File 'lib/yard/docstring_parser.rb', line 21

def self.after_parse(&block)
  self.after_parse_callbacks << block
end

Instance Method Details

#parse(content, object = nil, handler = nil) ⇒ self

Parses all content and returns itself.

Parameters:

  • content (String) —

    the docstring text to parse

  • object (CodeObjects::Base) (defaults to: nil) —

    the object that the docstring is attached to. Will be passed to directives to act on this object.

  • handler (Handlers::Base, nil) (defaults to: nil) —

    the handler object that is parsing this object. May be nil if this parser is not being called from a Parser::SourceParser context.

Returns:

  • (self) —

    the parser object. To get the docstring, call #to_docstring.

See Also:

Since:

  • 0.8.0



97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/yard/docstring_parser.rb', line 97

def parse(content, object = nil, handler = nil)
  @object = object
  @handler = handler
  @raw_text = content
  text = parse_content(content)
  # Remove trailing/leading whitespace / newlines
  @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
  call_directives_after_parse
  call_after_parse_callbacks
  self
end

#to_docstring ⇒ Docstring

Returns translates parsed text into a Docstring object.

Returns:

  • (Docstring) —

    translates parsed text into a Docstring object.

Since:

  • 0.8.0



111
112
113
 
# File 'lib/yard/docstring_parser.rb', line 111

def to_docstring
  Docstring.new!(text, tags, object, raw_text)
end