模块 RDoc::Text

用于操作注释文本的方法

常量

MARKUP_FORMAT

将标记格式映射到可以解析它们的类。如果格式未知，则使用“rdoc”格式。

SPACE_SEPARATED_LETTER_CLASS

连接行时用空格分隔的字符类。

TO_HTML_CHARACTERS

将编码映射到该编码正确转码的字符哈希。

另请参见 encode_fallback。

属性

language[RW]

此文本的语言。这会影响删除注释标记。

公共类方法

encode_fallback(character, encoding, fallback) 点击切换源代码

使用 fallback 字符将 character 转码为 encoding。

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

公共实例方法

expand_tabs(text) 点击切换源代码

将 text 中的制表符扩展为八个空格

# File rdoc/text.rb, line 63
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) 点击切换源代码

根据最短的行将 text 向左对齐

# File rdoc/text.rb, line 82
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) 点击切换源代码

将标记格式的字符串转换为 HTML。

要求包含类实现 formatter

# File rdoc/text.rb, line 101
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) 点击切换源代码

删除哈希符号、扩展制表符，然后将 text 向左对齐

# File 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 = expand_tabs    text
  text = flush_left     text
  text = strip_newlines text
  text
end

parse(text, format = 'rdoc') 点击切换源代码

规范化 text 然后从中构建一个 RDoc::Markup::Document

# File 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) 点击切换源代码

text 的前 limit 个字符，以 HTML 格式显示

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

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

strip_hashes(text) 点击切换源代码

从 text 中删除前导 # 字符

# File rdoc/text.rb, line 158
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) 点击切换源代码

从 text 中删除前导和尾随的换行符

# File 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) 点击切换源代码

删除 /* */ 样式注释

# File 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) 点击切换源代码

将 text 中的和号、破折号、省略号、引号、版权和注册商标符号转换为正确编码的字符。

# File 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(/&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(/(?:&#39;|'){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(/&#39;|'/) 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) 点击切换源代码

将 txt 包装到 line_len

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