Class: YARD::DocstringParser

### Home Classes Methods

### In Files

- lib/yard/docstring_parser.rb

### Parent

Object

### Methods

- ::after_parse
- ::after_parse_callbacks
- ::new
- #create_directive
- #create_ref_tag
- #create_tag
- #parse
- #parse_content
- #tag_is_directive?
- #to_docstring

### Files

- LICENSE.txt
- MIT.txt

### Class/Module Index

Quicksearch

- YARD
- YARD::CLI
- YARD::CLI::Command
- YARD::CLI::CommandParser
- YARD::CLI::Config
- YARD::CLI::Diff
- YARD::CLI::Display
- YARD::CLI::Gems
- YARD::CLI::Graph
- YARD::CLI::GraphOptions
- YARD::CLI::Help
- YARD::CLI::I18n
- YARD::CLI::List
- YARD::CLI::MarkupTypes
- YARD::CLI::Server
- YARD::CLI::Stats
- YARD::CLI::YRI
- YARD::CLI::Yardoc
- YARD::CLI::YardocOptions
- YARD::CLI::YardoptsCommand
- YARD::CodeObjects
- YARD::CodeObjects::Base
- YARD::CodeObjects::ClassObject
- YARD::CodeObjects::ClassVariableObject
- YARD::CodeObjects::CodeObjectList
- YARD::CodeObjects::ConstantObject
- YARD::CodeObjects::ExtendedMethodObject
- YARD::CodeObjects::ExtraFileObject
- YARD::CodeObjects::MacroObject
- YARD::CodeObjects::MethodObject
- YARD::CodeObjects::ModuleObject
- YARD::CodeObjects::NamespaceObject
- YARD::CodeObjects::Proxy
- YARD::CodeObjects::ProxyMethodError
- YARD::CodeObjects::RootObject
- YARD::Config
- YARD::Docstring
- YARD::DocstringParser
- YARD::Handlers
- YARD::Handlers::Base
- YARD::Handlers::C
- YARD::Handlers::C::AliasHandler
- YARD::Handlers::C::AttributeHandler
- YARD::Handlers::C::Base
- YARD::Handlers::C::ClassHandler
- YARD::Handlers::C::ConstantHandler
- YARD::Handlers::C::HandlerMethods
- YARD::Handlers::C::InitHandler
- YARD::Handlers::C::MethodHandler
- YARD::Handlers::C::MixinHandler
- YARD::Handlers::C::ModuleHandler
- YARD::Handlers::C::OverrideCommentHandler
- YARD::Handlers::C::PathHandler
- YARD::Handlers::C::StructHandler
- YARD::Handlers::C::SymbolHandler
- YARD::Handlers::HandlerAborted
- YARD::Handlers::NamespaceMissingError
- YARD::Handlers::Processor
- YARD::Handlers::Ruby
- YARD::Handlers::Ruby::AliasHandler
- YARD::Handlers::Ruby::AttributeHandler
- YARD::Handlers::Ruby::Base
- YARD::Handlers::Ruby::ClassConditionHandler
- YARD::Handlers::Ruby::ClassHandler
- YARD::Handlers::Ruby::ClassVariableHandler
- YARD::Handlers::Ruby::CommentHandler
- YARD::Handlers::Ruby::ConstantHandler
- YARD::Handlers::Ruby::DSLHandler
- YARD::Handlers::Ruby::DSLHandlerMethods
- YARD::Handlers::Ruby::ExceptionHandler
- YARD::Handlers::Ruby::ExtendHandler
- YARD::Handlers::Ruby::HandlesExtension
- YARD::Handlers::Ruby::Legacy
- YARD::Handlers::Ruby::Legacy::AliasHandler
- YARD::Handlers::Ruby::Legacy::AttributeHandler
- YARD::Handlers::Ruby::Legacy::Base
- YARD::Handlers::Ruby::Legacy::ClassConditionHandler
- YARD::Handlers::Ruby::Legacy::ClassHandler
- YARD::Handlers::Ruby::Legacy::ClassVariableHandler
- YARD::Handlers::Ruby::Legacy::CommentHandler
- YARD::Handlers::Ruby::Legacy::ConstantHandler
- YARD::Handlers::Ruby::Legacy::DSLHandler
- YARD::Handlers::Ruby::Legacy::ExceptionHandler
- YARD::Handlers::Ruby::Legacy::ExtendHandler
- YARD::Handlers::Ruby::Legacy::MethodHandler
- YARD::Handlers::Ruby::Legacy::MixinHandler
- YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
- YARD::Handlers::Ruby::Legacy::ModuleHandler
- YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler
- YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
- YARD::Handlers::Ruby::Legacy::VisibilityHandler
- YARD::Handlers::Ruby::Legacy::YieldHandler
- YARD::Handlers::Ruby::MethodCallWrapper
- YARD::Handlers::Ruby::MethodConditionHandler
- YARD::Handlers::Ruby::MethodHandler
- YARD::Handlers::Ruby::MixinHandler
- YARD::Handlers::Ruby::ModuleFunctionHandler
- YARD::Handlers::Ruby::ModuleHandler
- YARD::Handlers::Ruby::PrivateClassMethodHandler
- YARD::Handlers::Ruby::PrivateConstantHandler
- YARD::Handlers::Ruby::StructHandlerMethods
- YARD::Handlers::Ruby::TestNodeWrapper
- YARD::Handlers::Ruby::VisibilityHandler
- YARD::Handlers::Ruby::YieldHandler
- YARD::I18n
- YARD::I18n::Locale
- YARD::I18n::Message
- YARD::I18n::Messages
- YARD::I18n::POParser
- YARD::I18n::PotGenerator
- YARD::I18n::Text
- YARD::Logger
- YARD::Options
- YARD::Parser
- YARD::Parser::Base
- YARD::Parser::C
- YARD::Parser::C::BodyStatement
- YARD::Parser::C::CParser
- YARD::Parser::C::Comment
- YARD::Parser::C::CommentParser
- YARD::Parser::C::Statement
- YARD::Parser::C::ToplevelStatement
- YARD::Parser::OrderedParser
- YARD::Parser::ParserSyntaxError
- YARD::Parser::Ruby
- YARD::Parser::Ruby::AstNode
- YARD::Parser::Ruby::ClassNode
- YARD::Parser::Ruby::CommentNode
- YARD::Parser::Ruby::ConditionalNode
- YARD::Parser::Ruby::KeywordNode
- YARD::Parser::Ruby::Legacy
- YARD::Parser::Ruby::Legacy::RubyLex
- YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
- YARD::Parser::Ruby::Legacy::RubyParser
- YARD::Parser::Ruby::Legacy::RubyToken
- YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
- YARD::Parser::Ruby::Legacy::RubyToken::TkError
- YARD::Parser::Ruby::Legacy::RubyToken::TkId
- YARD::Parser::Ruby::Legacy::RubyToken::TkKW
- YARD::Parser::Ruby::Legacy::RubyToken::TkNode
- YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN
- YARD::Parser::Ruby::Legacy::RubyToken::TkOp
- YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
- YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar
- YARD::Parser::Ruby::Legacy::RubyToken::TkVal
- YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
- YARD::Parser::Ruby::Legacy::RubyToken::Token
- YARD::Parser::Ruby::Legacy::Statement
- YARD::Parser::Ruby::Legacy::StatementList
- YARD::Parser::Ruby::Legacy::TokenList
- YARD::Parser::Ruby::LiteralNode
- YARD::Parser::Ruby::LoopNode
- YARD::Parser::Ruby::MethodCallNode
- YARD::Parser::Ruby::MethodDefinitionNode
- YARD::Parser::Ruby::ModuleNode
- YARD::Parser::Ruby::ParameterNode
- YARD::Parser::Ruby::ReferenceNode
- YARD::Parser::Ruby::RipperParser
- YARD::Parser::Ruby::RubyParser
- YARD::Parser::SourceParser
- YARD::Parser::UndocumentableError
- YARD::Rake
- YARD::Rake::YardocTask
- YARD::Registry
- YARD::RegistryStore
- YARD::Serializers
- YARD::Serializers::Base
- YARD::Serializers::FileSystemSerializer
- YARD::Serializers::ProcessSerializer
- YARD::Serializers::StdoutSerializer
- YARD::Serializers::YardocSerializer
- YARD::Server
- YARD::Server::Adapter
- YARD::Server::Commands
- YARD::Server::Commands::Base
- YARD::Server::Commands::DisplayFileCommand
- YARD::Server::Commands::DisplayObjectCommand
- YARD::Server::Commands::FramesCommand
- YARD::Server::Commands::LibraryCommand
- YARD::Server::Commands::LibraryIndexCommand
- YARD::Server::Commands::LibraryOptions
- YARD::Server::Commands::ListCommand
- YARD::Server::Commands::SearchCommand
- YARD::Server::Commands::StaticFileCommand
- YARD::Server::DocServerHelper
- YARD::Server::DocServerSerializer
- YARD::Server::FinishRequest
- YARD::Server::LibraryNotPreparedError
- YARD::Server::LibraryVersion
- YARD::Server::NotFoundError
- YARD::Server::RackAdapter
- YARD::Server::RackMiddleware
- YARD::Server::Router
- YARD::Server::StaticCaching
- YARD::Server::WebrickAdapter
- YARD::Server::WebrickServlet
- YARD::StubProxy
- YARD::Tags
- YARD::Tags::AttributeDirective
- YARD::Tags::DefaultFactory
- YARD::Tags::DefaultTag
- YARD::Tags::Directive
- YARD::Tags::EndGroupDirective
- YARD::Tags::GroupDirective
- YARD::Tags::Library
- YARD::Tags::MacroDirective
- YARD::Tags::MethodDirective
- YARD::Tags::OptionTag
- YARD::Tags::OverloadTag
- YARD::Tags::ParseDirective
- YARD::Tags::RefTag
- YARD::Tags::RefTagList
- YARD::Tags::ScopeDirective
- YARD::Tags::Tag
- YARD::Tags::TagFormatError
- YARD::Tags::VisibilityDirective
- YARD::Templates
- YARD::Templates::Engine
- YARD::Templates::ErbCache
- YARD::Templates::Helpers
- YARD::Templates::Helpers::BaseHelper
- YARD::Templates::Helpers::FilterHelper
- YARD::Templates::Helpers::HtmlHelper
- YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
- YARD::Templates::Helpers::Markup
- YARD::Templates::Helpers::Markup::RDocMarkdown
- YARD::Templates::Helpers::Markup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::MarkupHelper
- YARD::Templates::Helpers::MethodHelper
- YARD::Templates::Helpers::ModuleHelper
- YARD::Templates::Helpers::TextHelper
- YARD::Templates::Helpers::UMLHelper
- YARD::Templates::Section
- YARD::Templates::Template
- YARD::Templates::Template::ClassMethods
- YARD::Templates::TemplateOptions
- YARD::Verifier
- Gem
- Gem::DocManager
- Gem::SourceIndex
- Gem::Specification
- Rack
- Rack::Request
- WEBrick
- WEBrick::HTTPRequest
- Array
- File
- Hash
- Insertion
- Module
- Object
- String
- SymbolHash

No matching classes.

# YARD::DocstringParser

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

### Constants

META_MATCH

  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.

reference[RW]

@return [CodeObjects::Base, nil] the object referenced by

    the docstring being parsed. May be nil if the docstring doesn't
    refer to any object.

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) click to toggle source

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]

    # File lib/yard/docstring_parser.rb, line 286
    def self.after_parse(&block)
      self.after_parse_callbacks << block
    end

after_parse_callbacks() click to toggle source

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

    # File lib/yard/docstring_parser.rb, line 291
    def self.after_parse_callbacks
      @after_parse_callbacks ||= []
    end

new(library = Tags::Library.instance) click to toggle source

Creates a new parser to parse docstring data

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

    tags.

    # File lib/yard/docstring_parser.rb, line 80
    def initialize(library = Tags::Library.instance)
      @text = ""
      @raw_text = ""
      @tags = []
      @directives = []
      @library = library
      @object = nil
      @reference = nil
      @handler = nil
      @state = OpenStruct.new
    end

### Public Instance Methods

create_directive(tag_name, tag_buf) click to toggle source

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

    # File lib/yard/docstring_parser.rb, line 214
    def create_directive(tag_name, tag_buf)
      if library.has_directive?(tag_name)
        dir = library.directive_create(tag_name, tag_buf, self)
        if dir.is_a?(Tags::Directive)
          @directives << dir
          dir
        end
      else
        log.warn "Unknown directive @!#{tag_name}" +
          (object ? " in file `#{object.file}` near line #{object.line}" : "")
        nil
      end
    rescue Tags::TagFormatError
      log.warn "Invalid directive format for @!#{tag_name}" +
        (object ? " in file `#{object.file}` near line #{object.line}" : "")
      nil
    end

create_ref_tag(tag_name, name, object_name) click to toggle source

Creates a {Tags::RefTag}

    # File lib/yard/docstring_parser.rb, line 208
    def create_ref_tag(tag_name, name, object_name)
      @tags << Tags::RefTagList.new(tag_name, P(object, object_name), name)
    end

create_tag(tag_name, tag_buf = '') click to toggle source

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

    # File lib/yard/docstring_parser.rb, line 191
    def create_tag(tag_name, tag_buf = '')
      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
        return create_ref_tag(tag_name, $1, $2)
      end

      if library.has_tag?(tag_name)
        @tags += [library.tag_create(tag_name, tag_buf)].flatten
      else
        log.warn "Unknown tag @#{tag_name}" +
          (object ? " in file `#{object.file}` near line #{object.line}" : "")
      end
    rescue Tags::TagFormatError
      log.warn "Invalid tag format for @#{tag_name}" +
        (object ? " in file `#{object.file}` near line #{object.line}" : "")
    end

parse(content, object = nil, handler = nil) click to toggle source

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

    # File lib/yard/docstring_parser.rb, line 112
    def parse(content, object = nil, handler = nil)
      @object = object
      @handler = handler
      @reference, @raw_text = detect_reference(content)
      text = parse_content(@raw_text)
      # 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

parse_content(content) click to toggle source

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.

    # File lib/yard/docstring_parser.rb, line 129
    def parse_content(content)
      content = content.split(/\r?\n/) if content.is_a?(String)
      return '' if !content || content.empty?
      docstring = ""

      indent, last_indent = content.first[/^\s*/].length, 0
      orig_indent = 0
      directive = false
      last_line = ""
      tag_name, tag_klass, tag_buf = nil, nil, []

      (content+['']).each_with_index do |line, index|
        indent = line[/^\s*/].length
        empty = (line =~ /^\s*$/ ? true : false)
        done = content.size == index

        if tag_name && (((indent < orig_indent && !empty) || done ||
            (indent == 0 && !empty)) || (indent <= last_indent && line =~ META_MATCH))
          buf = tag_buf.join("\n")
          if directive || tag_is_directive?(tag_name)
            directive = create_directive(tag_name, buf)
            if directive
              docstring << parse_content(directive.expanded_text).chomp
            end
          else
            create_tag(tag_name, buf)
          end
          tag_name, tag_buf, directive = nil, [], false
          orig_indent = 0
        end

        # Found a meta tag
        if line =~ META_MATCH
          directive, tag_name, tag_buf = $1, $2, [($3 || '')]
        elsif tag_name && indent >= orig_indent && !empty
          orig_indent = indent if orig_indent == 0
          # Extra data added to the tag on the next line
          last_empty = last_line =~ /^[ \t]*$/ ? true : false

          tag_buf << '' if last_empty
          tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
        elsif !tag_name
          # Regular docstring text
          docstring << line << "\n"
        end

        last_indent = indent
        last_line = line
      end

      docstring
    end

tag_is_directive?(tag_name) click to toggle source

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

    # File lib/yard/docstring_parser.rb, line 234
    def tag_is_directive?(tag_name)
      list = %(attribute endgroup group macro method scope visibility)
      list.include?(tag_name)
    end

to_docstring() click to toggle source

@return [Docstring] translates parsed text into

    a Docstring object.

    # File lib/yard/docstring_parser.rb, line 94
    def to_docstring
      Docstring.new!(text, tags, object, raw_text, reference)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.