In Files

  • rdoc/text.rb

Class/Module Index [+]



Methods for manipulating comment text



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


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

See also encode_fallback.

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 58
def self.encode_fallback character, encoding, fallback
  character.encode(encoding, :fallback => { character => fallback },
                   :undef => :replace, :replace => fallback)

Public Instance Methods

expand_tabs(text) click to toggle source

Expands tab characters in text to eight spaces

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

  text.each_line do |line|
    line.gsub!(/^((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
      r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
      r.force_encoding text.encoding if Object.const_defined? :Encoding
    end until line !~ /\t/

    expanded << line

flush_left(text) click to toggle source

Flush text left based on the shortest line

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

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

  empty = ''
  empty.force_encoding text.encoding if Object.const_defined? :Encoding

  text.gsub(/^ {0,#{indent}}/, empty)
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 104
def markup text
  parse(text).accept formatter
normalize_comment(text) click to toggle source

Strips hashes, expands tabs then flushes text to the left

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

  text = strip_stars    text
  text = strip_hashes   text
  text = expand_tabs    text
  text = flush_left     text
  text = strip_newlines text
parse(text, format = 'rdoc') click to toggle source

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

               # File rdoc/text.rb, line 125
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 if text =~ /\A\n*\z/

  MARKUP_FORMAT[format].parse text
snippet(text, limit = 100) click to toggle source

The first limit characters of text as HTML

               # File rdoc/text.rb, line 139
def snippet text, limit = 100
  document = parse text document
strip_hashes(text) click to toggle source

Strips leading # characters from text

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

  empty = ''
  empty.force_encoding text.encoding if Object.const_defined? :Encoding

  text.gsub(/^\s*(#+)/) { $ '#', ' ' }.gsub(/^\s+$/, empty)
strip_newlines(text) click to toggle source

Strips leading and trailing n characters from text

               # File rdoc/text.rb, line 160
def strip_newlines text
  text.gsub(/\A\n*(.*?)\n*\z/) do $1 end # block preserves String encoding
strip_stars(text) click to toggle source

Strips style comments

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

  encoding = text.encoding if Object.const_defined? :Encoding

  text = text.gsub %rDocument-method:\s+[\w:.#=!?]+%, ''

  space = ' '
  space.force_encoding encoding if encoding

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

  empty = ''
  empty.force_encoding encoding if encoding
  text.gsub(/^\s+$/, empty)
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 190
def to_html text
  if Object.const_defined? :Encoding then
    html = ''.encode text.encoding

    encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
    html = ''
    encoded = {
      :close_dquote => '”',
      :close_squote => '’',
      :copyright    => '©',
      :ellipsis     => '…',
      :em_dash      => '—',
      :en_dash      => '–',
      :open_dquote  => '“',
      :open_squote  => '‘',
      :trademark    => '®',

  s = text
  insquotes = false
  indquotes = false
  after_word = nil

  until s.eos? do
    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]
        html << encoded[:open_squote]
        insquotes = true

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

      if match then
        html << match
        after_word = match =~ /\w$/
        html <<

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

Wraps txt to line_len

               # File rdoc/text.rb, line 284
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
      while p > sp and txt[p] != ?\s
        p -= 1
      if p <= sp
        p = sp + line_len
        while p < ep and txt[p] != ?\s
          p += 1
    res << txt[sp...p] << "\n"
    sp = p
    sp += 1 while sp < ep and txt[sp] == ?\s


Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit

blog comments powered by Disqus