Module: RDoc::Text

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `Alias`, `AnyMethod`, `Attr`, `ClassModule`, `CodeObject`, `Comment`, `Constant`, `Context`, `Context::Section`, `Extend`, `Generator::JsonIndex`, `Include`, `Markup::Parser`, `Markup::ToHtml`, `Markup::ToHtmlCrossref`, `Markup::ToHtmlSnippet`, `MethodAttr`, `Mixin`, `NormalClass`, `NormalModule`, `Parser::C`, `Require`, `SingleClass`, `Stats`, `TomDoc`, `TopLevel`
Defined in:	lib/rdoc/text.rb

Overview

Methods for manipulating comment text

Constant Summary

MARKUP_FORMAT =

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

# File 'lib/rdoc/text.rb', line 23

{
  'markdown' => RDoc::Markdown,
  'rdoc'     => RDoc::Markup,
  'rd'       => RDoc::RD,
  'tomdoc'   => RDoc::TomDoc,
}

SPACE_SEPARATED_LETTER_CLASS =

Character class to be separated by a space when concatenating lines.

# File 'lib/rdoc/text.rb', line 204
```
/[\p{Nd}\p{Lc}\p{Pc}]|[!-~&&\W]/
```

Instance Attribute Summary

#language rw

The language for this text.

Instance Method Summary

#flush_left(text)

Flush text left based on the shortest line.
#markup(text)

Convert a string in markup format into HTML.
#normalize_comment(text)

Strips hashes, expands tabs then flushes text to the left.
#parse(text, format = 'rdoc')

Normalizes text then builds a Markup::Document from it.
#snippet(text, limit = 100)

The first limit characters of text as HTML.
#strip_hashes(text)

Strips leading # characters from text
#strip_newlines(text)

Strips leading and trailing \n characters from text
#strip_stars(text)

Strips /* */ style comments.
#wrap(txt, line_len = 76)

Wraps txt to line_len

Instance Attribute Details

#language (rw)

The language for this text. This affects stripping comments markers.

[ GitHub ]

# File 'lib/rdoc/text.rb', line 17


attr_accessor :language

Instance Method Details

#flush_left(text)

Flush text left based on the shortest line

[ GitHub ]

# File 'lib/rdoc/text.rb', line 54


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)

Convert a string in markup format into HTML.

Requires the including class to implement #formatter

[ GitHub ]

# File 'lib/rdoc/text.rb', line 73


def markup(text)
  if @store.options
    locale = @store.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)

Strips hashes, expands tabs then flushes text to the left

[ GitHub ]

# File 'lib/rdoc/text.rb', line 89


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

Normalizes text then builds a Markup::Document from it

[ GitHub ]

# File 'lib/rdoc/text.rb', line 107


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)

The first limit characters of text as HTML

[ GitHub ]

# File 'lib/rdoc/text.rb', line 121


def snippet(text, limit = 100)
  document = parse text

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

#strip_hashes(text)

Strips leading # characters from text

[ GitHub ]

# File 'lib/rdoc/text.rb', line 130


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)

Strips leading and trailing \n characters from text

[ GitHub ]

# File 'lib/rdoc/text.rb', line 142


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

#strip_stars(text)

Strips /* */ style comments

[ GitHub ]

# File 'lib/rdoc/text.rb', line 149


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

#wrap(txt, line_len = 76)

Wraps txt to line_len

[ GitHub ]

# File 'lib/rdoc/text.rb', line 171


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