In Files

  • rdoc/text.rb

Class/Module Index [+]

Quicksearch

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.

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)
end
            

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
      r
    end until line !~ /\t/

    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 85
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.force_encoding text.encoding if Object.const_defined? :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 104
def markup text
  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 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
  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 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 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 139
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 148
def strip_hashes text
  return text if text =~ /^(?>\s*)[^\#]/

  empty = ''
  empty.force_encoding text.encoding if Object.const_defined? :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 160
def strip_newlines text
  text.gsub(/\A\n*(.*?)\n*\z/) do $1 end # block preserves String encoding
end
            
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)
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 190
def to_html text
  if Object.const_defined? :Encoding then
    html = ''.encode text.encoding

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

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

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 visit Documenting-ruby.org.

blog comments powered by Disqus