\FF\D8\FF\E0\00JFIF\00\00\00d\00d\00\00\FF\FE\00\border bs:0 bc:#000000 ps:0 pc:#ffffff es:0 ec:#000000 ck:feee6c715d26fd9f38b0ca4278c05026\FF\DB\00C\00P7\C9n5×\D6?\BDê\9Ds\EBp\9F[`8m\B7)o\B5\E8\E6I\99\FE3]]A2\BA\8Cw\D6E\93\\DEv\C8\009\F2\F1NI?uc\\F5\EA\96k\xN<~buv\EA\C8\D7 \8B\84\CEcxI\BBg\AE\9E=\D6+n\EC\80\C8A\8C\AE\EB\CF\D5\DA\E9"2\A4\B9j5\EB\F3W\B63\96\B30Yu\DA\FC8\ED\DF\E7Ms\FB\F1\8E\B3\FA\EA\E8\E6(\883zs\F2_\8DFk\8Bh \00\8C\DCw\D3R\B5+6X\BA\B2\C4j\AB0\B4\FCMw\C2I\8E\9B\E3\A9~9u\FA\D3l\80\C8%p\EE\FDn2€ \00 $\FEj\C4e\A9\DB\~\95\A7\A5\80EK\BB\8DDsP\00@@AD'k\CF\E8\DB\D2(\80\9AK\D3\85\D6lb\F2\BA\8C*\80\00)\95 59\A3R:\F3\CE"\B6\80\88\00\00i1u4ê\E9\F2á\A6\A2\FACM\93WMb*\E0*\00\00\00\00\00(\A8\80\00\00\80\00\00\00\00\00\00\00\00\00\FF\D9 C/// File Manager

File Manager

Path: /opt/cpanel/ea-ruby27/root/usr/share/ruby/rdoc/

Viewing File: tom_doc.rb

# frozen_string_literal: true
# :markup: tomdoc

# A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
#
# The TomDoc specification can be found at:
#
# http://tomdoc.org
#
# The latest version of the TomDoc specification can be found at:
#
# https://github.com/mojombo/tomdoc/blob/master/tomdoc.md
#
# To choose TomDoc as your only default format see RDoc::Options@Saved+Options
# for instructions on setting up a <code>.rdoc_options</code> file to store
# your project default.
#
# There are a few differences between this parser and the specification.  A
# best-effort was made to follow the specification as closely as possible but
# some choices to deviate were made.
#
# A future version of RDoc will warn when a MUST or MUST NOT is violated and
# may warn when a SHOULD or SHOULD NOT is violated.  RDoc will always try
# to emit documentation even if given invalid TomDoc.
#
# Here are some implementation choices this parser currently makes:
#
# This parser allows rdoc-style inline markup but you should not depended on
# it.
#
# This parser allows a space between the comment and the method body.
#
# This parser does not require the default value to be described for an
# optional argument.
#
# This parser does not examine the order of sections.  An Examples section may
# precede the Arguments section.
#
# This class is documented in TomDoc format.  Since this is a subclass of the
# RDoc markup parser there isn't much to see here, unfortunately.

class RDoc::TomDoc < RDoc::Markup::Parser

  # Internal: Token accessor

  attr_reader :tokens

  # Internal: Adds a post-processor which sets the RDoc section based on the
  # comment's status.
  #
  # Returns nothing.

  def self.add_post_processor # :nodoc:
    RDoc::Markup::PreProcess.post_process do |comment, code_object|
      next unless code_object and
                  RDoc::Comment === comment and comment.format == 'tomdoc'

      comment.text.gsub!(/(\A\s*# )(Public|Internal|Deprecated):\s+/) do
        section = code_object.add_section $2
        code_object.temporary_section = section

        $1
      end
    end
  end

  add_post_processor

  # Public: Parses TomDoc from text
  #
  # text - A String containing TomDoc-format text.
  #
  # Examples
  #
  #   RDoc::TomDoc.parse <<-TOMDOC
  #   This method does some things
  #
  #   Returns nothing.
  #   TOMDOC
  #   # => #<RDoc::Markup::Document:0xXXX @parts=[...], @file=nil>
  #
  # Returns an RDoc::Markup::Document representing the TomDoc format.

  def self.parse text
    parser = new

    parser.tokenize text
    doc = RDoc::Markup::Document.new
    parser.parse doc
    doc
  end

  # Internal: Extracts the Signature section's method signature
  #
  # comment - An RDoc::Comment that will be parsed and have the signature
  #           extracted
  #
  # Returns a String containing the signature and nil if not

  def self.signature comment
    return unless comment.tomdoc?

    document = comment.parse

    signature = nil
    found_heading = false
    found_signature = false

    document.parts.delete_if do |part|
      next false if found_signature

      found_heading ||=
        RDoc::Markup::Heading === part && part.text == 'Signature'

      next false unless found_heading

      next true if RDoc::Markup::BlankLine === part

      if RDoc::Markup::Verbatim === part then
        signature = part
        found_signature = true
      end
    end

    signature and signature.text
  end

  # Public: Creates a new TomDoc parser.  See also RDoc::Markup::parse

  def initialize
    super

    @section      = nil
    @seen_returns = false
  end

  # Internal: Builds a heading from the token stream
  #
  # level - The level of heading to create
  #
  # Returns an RDoc::Markup::Heading

  def build_heading level
    heading = super

    @section = heading.text

    heading
  end

  # Internal: Builds a verbatim from the token stream.  A verbatim in the
  # Examples section will be marked as in Ruby format.
  #
  # margin - The indentation from the margin for lines that belong to this
  #          verbatim section.
  #
  # Returns an RDoc::Markup::Verbatim

  def build_verbatim margin
    verbatim = super

    verbatim.format = :ruby if @section == 'Examples'

    verbatim
  end

  # Internal: Builds a paragraph from the token stream
  #
  # margin - Unused
  #
  # Returns an RDoc::Markup::Paragraph.

  def build_paragraph margin
    p :paragraph_start => margin if @debug

    paragraph = RDoc::Markup::Paragraph.new

    until @tokens.empty? do
      type, data, = get

      case type
      when :TEXT then
        @section = 'Returns' if data =~ /\A(Returns|Raises)/

        paragraph << data
      when :NEWLINE then
        if :TEXT == peek_token[0] then
          # Lines beginning with 'Raises' in the Returns section should not be
          # treated as multiline text
          if 'Returns' == @section and
            peek_token[1].start_with?('Raises') then
            break
          else
            paragraph << ' '
          end
        else
          break
        end
      else
        unget
        break
      end
    end

    p :paragraph_end => margin if @debug

    paragraph
  end

  ##
  # Detects a section change to "Returns" and adds a heading

  def parse_text parent, indent # :nodoc:
    paragraph = build_paragraph indent

    if false == @seen_returns and 'Returns' == @section then
      @seen_returns = true
      parent << RDoc::Markup::Heading.new(3, 'Returns')
      parent << RDoc::Markup::BlankLine.new
    end

    parent << paragraph
  end

  # Internal: Turns text into an Array of tokens
  #
  # text - A String containing TomDoc-format text.
  #
  # Returns self.

  def tokenize text
    text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')

    setup_scanner text

    until @s.eos? do
      pos = @s.pos

      # leading spaces will be reflected by the column of the next token
      # the only thing we loose are trailing spaces at the end of the file
      next if @s.scan(/ +/)

      @tokens << case
                 when @s.scan(/\r?\n/) then
                   token = [:NEWLINE, @s.matched, *pos]
                   @s.newline!
                   token
                 when @s.scan(/(Examples|Signature)$/) then
                   @tokens << [:HEADER, 3, *pos]

                   [:TEXT, @s[1], *pos]
                 when @s.scan(/([:\w][\w\[\]]*)[ ]+- /) then
                   [:NOTE, @s[1], *pos]
                 else
                   @s.scan(/.*/)
                   [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
                 end
    end

    self
  end

end