Module: RDoc::Text (Ruby 2.7.5)
Description: Module : RDoc::Text - Ruby 2.7.5

### Home Classes Methods

### In Files

- rdoc/text.rb

### Methods

- ::encode_fallback
- #expand_tabs
- #flush_left
- #markup
- #normalize_comment
- #parse
- #snippet
- #strip_hashes
- #strip_newlines
- #strip_stars
- #to_html
- #wrap

### Class/Module Index

Quicksearch

- RDoc
- RDoc::Alias
- RDoc::AnonClass
- RDoc::AnyMethod
- RDoc::Attr
- RDoc::ClassModule
- RDoc::CodeObject
- RDoc::Comment
- RDoc::Constant
- RDoc::Context
- RDoc::Context::Section
- RDoc::CrossReference
- RDoc::ERBIO
- RDoc::ERBPartial
- RDoc::Encoding
- RDoc::Error
- RDoc::Extend
- RDoc::Generator
- RDoc::Generator::Darkfish
- RDoc::Generator::JsonIndex
- RDoc::Generator::Markup
- RDoc::Generator::POT
- RDoc::Generator::POT::MessageExtractor
- RDoc::Generator::POT::PO
- RDoc::Generator::POT::POEntry
- RDoc::Generator::RI
- RDoc::GhostMethod
- RDoc::I18n
- RDoc::I18n::Locale
- RDoc::I18n::Text
- RDoc::Include
- RDoc::Markdown
- RDoc::Markdown::Literals
- RDoc::Markup
- RDoc::Markup::AttrChanger
- RDoc::Markup::AttrSpan
- RDoc::Markup::AttributeManager
- RDoc::Markup::Attributes
- RDoc::Markup::BlankLine
- RDoc::Markup::BlockQuote
- RDoc::Markup::Document
- RDoc::Markup::Formatter
- RDoc::Markup::HardBreak
- RDoc::Markup::Include
- RDoc::Markup::IndentedParagraph
- RDoc::Markup::List
- RDoc::Markup::ListItem
- RDoc::Markup::Paragraph
- RDoc::Markup::Parser
- RDoc::Markup::Parser::Error
- RDoc::Markup::Parser::MyStringScanner
- RDoc::Markup::Parser::ParseError
- RDoc::Markup::PreProcess
- RDoc::Markup::Raw
- RDoc::Markup::RegexpHandling
- RDoc::Markup::Rule
- RDoc::Markup::ToAnsi
- RDoc::Markup::ToBs
- RDoc::Markup::ToHtml
- RDoc::Markup::ToHtmlCrossref
- RDoc::Markup::ToHtmlSnippet
- RDoc::Markup::ToJoinedParagraph
- RDoc::Markup::ToLabel
- RDoc::Markup::ToMarkdown
- RDoc::Markup::ToRdoc
- RDoc::Markup::ToTableOfContents
- RDoc::Markup::ToTest
- RDoc::Markup::ToTtOnly
- RDoc::Markup::Verbatim
- RDoc::MetaMethod
- RDoc::MethodAttr
- RDoc::Mixin
- RDoc::NormalClass
- RDoc::NormalModule
- RDoc::Options
- RDoc::Parser
- RDoc::Parser::C
- RDoc::Parser::ChangeLog
- RDoc::Parser::Markdown
- RDoc::Parser::RD
- RDoc::Parser::RipperStateLex
- RDoc::Parser::RipperStateLex::InnerStateLex
- RDoc::Parser::Ruby
- RDoc::Parser::RubyTools
- RDoc::Parser::Simple
- RDoc::Parser::Text
- RDoc::RD
- RDoc::RD::BlockParser
- RDoc::RD::Inline
- RDoc::RD::InlineParser
- RDoc::RDoc
- RDoc::RI
- RDoc::RI::Driver
- RDoc::RI::Driver::Error
- RDoc::RI::Driver::NotFoundError
- RDoc::RI::Error
- RDoc::RI::Paths
- RDoc::RI::Task
- RDoc::Require
- RDoc::RubygemsHook
- RDoc::Servlet
- RDoc::SingleClass
- RDoc::Stats
- RDoc::Stats::Normal
- RDoc::Stats::Quiet
- RDoc::Stats::Verbose
- RDoc::Store
- RDoc::Store::Error
- RDoc::Store::MissingFileError
- RDoc::Task
- RDoc::Text
- RDoc::TokenStream
- RDoc::TomDoc
- RDoc::TopLevel
- RDocTask

No matching classes.

# RDoc::Text

Methods for manipulating comment text

### Constants

MARKUP_FORMAT

  Maps markup formats to classes that can parse them. If the format is unknown, “rdoc” format is used.

TO_HTML_CHARACTERS

  Maps an encoding to a Hash of characters properly transcoded for that encoding.

  See also encode_fallback.

### Attributes

language[RW]

### Public Class Methods

encode_fallback(character, encoding, fallback) click to toggle source

Transcodes `character` to `encoding` with a `fallback` character.

                   # File rdoc/text.rb, line 51
    def self.encode_fallback character, encoding, fallback
      character.encode(encoding, :fallback => { character => fallback },
                       :undef => :replace, :replace => fallback)
    end

### Public Instance Methods

expand_tabs(text) click to toggle source

Expands tab characters in `text` to eight spaces

                   # File rdoc/text.rb, line 59
    def expand_tabs text
      expanded = []

      text.each_line do |line|
        nil while line.gsub!(/(?:\G|\r)((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
          r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
          r = RDoc::Encoding.change_encoding r, text.encoding
          r
        end

        expanded << line
      end

      expanded.join
    end

flush_left(text) click to toggle source

Flush `text` left based on the shortest line

                   # File rdoc/text.rb, line 78
    def flush_left text
      indent = 9999

      text.each_line do |line|
        line_indent = line =~ /\S/ || 9999
        indent = line_indent if indent > line_indent
      end

      empty = ''
      empty = RDoc::Encoding.change_encoding empty, text.encoding

      text.gsub(/^ {0,#{indent}}/, empty)
    end

markup(text) click to toggle source

Convert a string in markup format into HTML.

Requires the including class to implement formatter

                   # File rdoc/text.rb, line 97
    def markup text
      if @store.rdoc.options
        locale = @store.rdoc.options.locale
      else
        locale = nil
      end
      if locale
        i18n_text = RDoc::I18n::Text.new(text)
        text = i18n_text.translate(locale)
      end
      parse(text).accept formatter
    end

normalize_comment(text) click to toggle source

Strips hashes, expands tabs then flushes `text` to the left

                   # File rdoc/text.rb, line 113
    def normalize_comment text
      return text if text.empty?

      case language
      when :ruby
        text = strip_hashes text
      when :c
        text = strip_stars text
      end
      text = expand_tabs    text
      text = flush_left     text
      text = strip_newlines text
      text
    end

parse(text, format = 'rdoc') click to toggle source

Normalizes `text` then builds a `RDoc::Markup::Document` from it

                   # File rdoc/text.rb, line 131
    def parse text, format = 'rdoc'
      return text if RDoc::Markup::Document === text
      return text.parse if RDoc::Comment === text

      text = normalize_comment text # TODO remove, should not be necessary

      return RDoc::Markup::Document.new if text =~ /\A\n*\z/

      MARKUP_FORMAT[format].parse text
    end

snippet(text, limit = 100) click to toggle source

The first `limit` characters of `text` as HTML

                   # File rdoc/text.rb, line 145
    def snippet text, limit = 100
      document = parse text

      RDoc::Markup::ToHtmlSnippet.new(options, limit).convert document
    end

strip_hashes(text) click to toggle source

Strips leading # characters from `text`

                   # File rdoc/text.rb, line 154
    def strip_hashes text
      return text if text =~ /^(?>\s*)[^\#]/

      empty = ''
      empty = RDoc::Encoding.change_encoding empty, text.encoding

      text.gsub(/^\s*(#+)/) { $1.tr '#', ' ' }.gsub(/^\s+$/, empty)
    end

strip_newlines(text) click to toggle source

Strips leading and trailing n characters from `text`

                   # File rdoc/text.rb, line 166
    def strip_newlines text
      text.gsub(/\A\n*(.*?)\n*\z/m) do $1 end # block preserves String encoding
    end

strip_stars(text) click to toggle source

Strips /* */ style comments

                   # File rdoc/text.rb, line 173
    def strip_stars text
      return text unless text =~ %r%/\*.*\*/%m

      encoding = text.encoding

      text = text.gsub %r%Document-method:\s+[\w:.#=!?|^&<>~+\-/*\%@`\[\]]+%, ''

      space = ' '
      space = RDoc::Encoding.change_encoding space, encoding if encoding

      text.sub!  %r%/\*+%       do space * $&.length end
      text.sub!  %r%\*+/%       do space * $&.length end
      text.gsub! %r%^[ \t]*\*%m do space * $&.length end

      empty = ''
      empty = RDoc::Encoding.change_encoding empty, encoding if encoding
      text.gsub(/^\s+$/, empty)
    end

to_html(text) click to toggle source

Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in `text` to properly encoded characters.

                   # File rdoc/text.rb, line 196
    def to_html text
      html = (''.encode text.encoding).dup

      encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]

      s = StringScanner.new text
      insquotes = false
      indquotes = false
      after_word = nil

      until s.eos? do
        case
        when s.scan(/<(tt|code)>.*?<\/\1>/) then # skip contents of tt
          html << s.matched.gsub('\\\\', '\\')
        when s.scan(/<(tt|code)>.*?/) then
          warn "mismatched <#{s[1]}> tag" # TODO signal file/line
          html << s.matched
        when s.scan(/<[^>]+\/?s*>/) then # skip HTML tags
          html << s.matched
        when s.scan(/\\(\S)/) then # unhandled suppressed crossref
          html << s[1]
          after_word = nil
        when s.scan(/\.\.\.(\.?)/) then
          html << s[1] << encoded[:ellipsis]
          after_word = nil
        when s.scan(/\(c\)/) then
          html << encoded[:copyright]
          after_word = nil
        when s.scan(/\(r\)/) then
          html << encoded[:trademark]
          after_word = nil
        when s.scan(/---/) then
          html << encoded[:em_dash]
          after_word = nil
        when s.scan(/--/) then
          html << encoded[:en_dash]
          after_word = nil
        when s.scan(/&quot;|"/) then
          html << encoded[indquotes ? :close_dquote : :open_dquote]
          indquotes = !indquotes
          after_word = nil
        when s.scan(/``/) then # backtick double quote
          html << encoded[:open_dquote]
          after_word = nil
        when s.scan(/''/) then # tick double quote
          html << encoded[:close_dquote]
          after_word = nil
        when s.scan(/'/) then # single quote
          if insquotes
            html << encoded[:close_squote]
            insquotes = false
          elsif after_word
            # Mary's dog, my parents' house: do not start paired quotes
            html << encoded[:close_squote]
          else
            html << encoded[:open_squote]
            insquotes = true
          end

          after_word = nil
        else # advance to the next potentially significant character
          match = s.scan(/.+?(?=[<\\.("'`&-])/) #"

          if match then
            html << match
            after_word = match =~ /\w$/
          else
            html << s.rest
            break
          end
        end
      end

      html
    end

wrap(txt, line_len = 76) click to toggle source

Wraps `txt` to `line_len`

                   # File rdoc/text.rb, line 275
    def wrap(txt, line_len = 76)
      res = []
      sp = 0
      ep = txt.length

      while sp < ep
        # scan back for a space
        p = sp + line_len - 1
        if p >= ep
          p = ep
        else
          while p > sp and txt[p] != ?\s
            p -= 1
          end
          if p <= sp
            p = sp + line_len
            while p < ep and txt[p] != ?\s
              p += 1
            end
          end
        end
        res << txt[sp...p] << "\n"
        sp = p
        sp += 1 while sp < ep and txt[sp] == ?\s
      end

      res.join.strip
    end