Class | YARD::DocstringParser
In: | lib/yard/docstring_parser.rb
Parent: | Object

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}.

## Subclassing Notes

The DocstringParser can be subclassed and subtituted during parsing by setting the {Docstring.default_parser} attribute with the name of the subclass. This allows developers to change the way docstrings are parsed, allowing for completely different docstring syntaxes.

@example Creating a Docstring with a DocstringParser

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

@example Creating a Custom DocstringParser

      # Parses docstrings backwards!
      class ReverseDocstringParser
        def parse_content(content)
          super(content.reverse)
        end
      end

      # Set the parser as default when parsing
      YARD::Docstring.default_parser = ReverseDocstringParser

@see parse_content @since 0.8.0

### Methods

after_parse after_parse_callbacks create_directive create_ref_tag create_tag new parse parse_content tag_is_directive? to_docstring

### Constants

META_MATCH | = | /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i |  | The regular expression to match the tag syntax

### Attributes

directives

[RW]

@return [Array<Directive>] a list of directives identified

      by the parser. This list will not be passed on to the
      Docstring object.

handler

[RW]

@return [Handlers::Base, nil] the handler parsing this

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

library

[RW]

@return [Tags::Library] the tag library being used to

      identify registered tags in the docstring.

object

[RW]

@return [CodeObjects::Base, nil] the object associated with

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

raw_text | [RW] | @return [String] the complete input string to the parser.

state

[RW]

@return [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).

tags

[RW]

@return [Array<Tag>] the list of meta-data tags identified

      by the parser

text

[RW]

@return [String] the parsed text portion of the docstring,

      with tags removed.

### Public Class methods

after_parse(&block)

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.

@yield [parser] a block to be called after a docstring is parsed @yieldparam [DocstringParser] parser the docstring parser object

      with all directives and tags created.

@yieldreturn [void] @return [void]

after_parse_callbacks()

@return [Array<Proc>] the {after_parse} callback proc objects

new(library = Tags::Library.instance)

Creates a new parser to parse docstring data

@param [Tags::Library] library a tag library for recognizing

      tags.

### Public Instance methods

create_directive(tag_name, tag_buf)

Creates a new directive using the registered {library} @return [Directive] the directive object that is created

create_ref_tag(tag_name, name, object_name)

Creates a {Tags::RefTag}

create_tag(tag_name, tag_buf = '')

Creates a tag from the {Tags::DefaultFactory tag factory}.

To add an already created tag object, append it to {tags}.

@param [String] tag_name the tag name @param [String] tag_buf the text attached to the tag with newlines removed. @return [Tags::Tag, Tags::RefTag] a tag

parse(content, object = nil, handler = nil)

Parses all content and returns itself.

@param [String] content the docstring text to parse @param [CodeObjects::Base] object the object that the docstring

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

@param [Handlers::Base, nil] handler the handler object that is

      parsing this object. May be nil if this parser is not being
      called from a {Parser::SourceParser} context.

@return [self] the parser object. To get the docstring,

      call {#to_docstring}.

@see to_docstring

parse_content(content)

Parses a given block of text.

@param [String] content the content to parse @note Subclasses can override this method to perform custom

      parsing of content data.

tag_is_directive?(tag_name)

Backward compatibility to detect old tags that should be specified as directives in 0.8 and onward.

to_docstring()

@return [Docstring] translates parsed text into

      a Docstring object.

[Validate]