Module: RDoc::Text
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Included In:
Alias ,
AnonClass ,
AnyMethod ,
Attr ,
ClassModule ,
CodeObject ,
Comment ,
Constant ,
Context ,
Context::Section ,
Extend ,
Generator::JsonIndex ,
GhostMethod ,
Include ,
Markup::Parser ,
Markup::ToHtml ,
Markup::ToHtmlCrossref ,
Markup::ToHtmlSnippet ,
MetaMethod ,
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.
{ '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.
/[\p{Nd}\p{Lc}\p{Pc}]|[!-~&&\W]/
-
TO_HTML_CHARACTERS =
Maps an encoding to a Hash of characters properly transcoded for that encoding.
See also encode_fallback.
Hash.new do |h, encoding| h[encoding] = { :close_dquote => encode_fallback('”', encoding, '"'), :close_squote => encode_fallback('’', encoding, '\''), :copyright => encode_fallback('©', encoding, '(c)'), :ellipsis => encode_fallback('…', encoding, '...'), :em_dash => encode_fallback('—', encoding, '---'), :en_dash => encode_fallback('–', encoding, '--'), :open_dquote => encode_fallback('“', encoding, '"'), :open_squote => encode_fallback('‘', encoding, '\''), :trademark => encode_fallback('®', encoding, '(r)'), } end
Class Method Summary
-
.encode_fallback(character, encoding, fallback)
Transcodes
character
toencoding
with afallback
character.
Instance Attribute Summary
-
#language
rw
The language for this text.
Instance Method Summary
-
#expand_tabs(text)
Expands tab characters in
text
to eight spaces. -
#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 aMarkup::Document
from it. -
#snippet(text, limit = 100)
The first
limit
characters oftext
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.
-
#to_html(text)
Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in
text
to properly encoded characters. -
#wrap(txt, line_len = 76)
Wraps
txt
toline_len
Class Method Details
.encode_fallback(character, encoding, fallback)
Transcodes character
to encoding
with a fallback
character.
# File 'lib/rdoc/text.rb', line 55
def self.encode_fallback character, encoding, fallback character.encode(encoding, :fallback => { character => fallback }, :undef => :replace, :replace => fallback) end
Instance Attribute Details
#language (rw)
The language for this text. This affects stripping comments markers.
# File 'lib/rdoc/text.rb', line 17
attr_accessor :language
Instance Method Details
#expand_tabs(text)
Expands tab characters in text
to eight spaces
#flush_left(text)
Flush text
left based on the shortest line
#markup(text)
Convert a string in markup format into HTML.
Requires the including class to implement #formatter
#normalize_comment(text)
Strips hashes, expands tabs then flushes text
to the left
# File 'lib/rdoc/text.rb', line 117
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 = text text = flush_left text text = strip_newlines text text end
#parse(text, format = 'rdoc')
Normalizes text
then builds a Markup::Document
from it
# File 'lib/rdoc/text.rb', line 135
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
#strip_hashes(text)
Strips leading # characters from text
#strip_newlines(text)
Strips leading and trailing n characters from text
# File 'lib/rdoc/text.rb', line 170
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
# File 'lib/rdoc/text.rb', line 177
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)
Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in text
to properly encoded characters.
# File 'lib/rdoc/text.rb', line 200
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\)/i) then html << encoded[:copyright] after_word = nil when s.scan(/\(r\)/i) 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(/"|"/) 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(/(?:'|'){2}/) then # tick double quote html << encoded[:close_dquote] after_word = nil when s.scan(/`/) then # backtick if insquotes or after_word html << '`' after_word = false else html << encoded[:open_squote] insquotes = true end 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)
Wraps txt
to line_len
# File 'lib/rdoc/text.rb', line 287
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