class RDoc::Markup::Formatter

RDoc 标记格式化器的基类

格式化器是一个访问器，它将RDoc::Markup树（来自注释）转换为某种输出。RDoc 附带了用于转换回 rdoc、ANSI 文本、HTML、目录和其他格式的格式化器。

如果您想编写自己的Formatter，请使用 RDoc::Markup::FormatterTestCase。如果您正在编写文本输出格式化器，请使用 RDoc::Markup::TextFormatterTestCase，它提供了额外的测试用例。

常量

InlineTag: 用于内联标记的标签，其中包含用于位掩码的 bit 以及 on 和 off 触发器。

公共类方法

gen_relative_url(path, target) 点击以切换源代码

将目标 URL 转换为相对于给定路径的 URL

# File rdoc/markup/formatter.rb, line 24
def self.gen_relative_url path, target
  from        = File.dirname path
  to, to_file = File.split target

  from = from.split "/"
  to   = to.split "/"

  from.delete '.'
  to.delete '.'

  while from.size > 0 and to.size > 0 and from[0] == to[0] do
    from.shift
    to.shift
  end

  from.fill ".."
  from.concat to
  from << to_file
  File.join(*from)
end

new(options, markup = nil) 点击以切换源代码

创建一个新的Formatter

# File rdoc/markup/formatter.rb, line 48
def initialize options, markup = nil
  @options = options

  @markup = markup || RDoc::Markup.new
  @am     = @markup.attribute_manager
  @am.add_regexp_handling(/<br>/, :HARD_BREAK)

  @attributes = @am.attributes

  @attr_tags = []

  @in_tt = 0
  @tt_bit = @attributes.bitmap_for :TT

  @hard_break = ''
  @from_path = '.'
end

公共实例方法

accept_document(document) 点击以切换源代码

将 document 添加到输出

# File rdoc/markup/formatter.rb, line 69
def accept_document document
  document.parts.each do |item|
    case item
    when RDoc::Markup::Document then # HACK
      accept_document item
    else
      item.accept self
    end
  end
end

add_regexp_handling_RDOCLINK() 点击以切换源代码

为 rdoc-… 形式的链接添加正则表达式处理

# File rdoc/markup/formatter.rb, line 83
def add_regexp_handling_RDOCLINK
  @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
end

add_regexp_handling_TIDYLINK() 点击以切换源代码

为 ”>word> 形式的链接添加正则表达式处理

# File rdoc/markup/formatter.rb, line 91
def add_regexp_handling_TIDYLINK
  @markup.add_regexp_handling(/(?:
                                \{[^{}]*\} | # multi-word label
                                \b[^\s{}]+? # single-word label
                               )

                               \[\S+?\]     # link target
                              /x, :TIDYLINK)
end

add_tag(name, start, stop) 点击以切换源代码

为属性添加一组新标签。为了灵活性，我们允许单独的开始和结束标签

# File rdoc/markup/formatter.rb, line 105
def add_tag(name, start, stop)
  attr = @attributes.bitmap_for name
  @attr_tags << InlineTag.new(attr, start, stop)
end

annotate(tag) 点击以切换源代码

允许使用附加信息修饰 tag。

# File rdoc/markup/formatter.rb, line 113
def annotate(tag)
  tag
end

convert(content) 点击以切换源代码

标记 content

# File rdoc/markup/formatter.rb, line 120
def convert content
  @markup.convert content, self
end

convert_flow(flow) 点击以切换源代码

转换流项目 flow

# File rdoc/markup/formatter.rb, line 127
def convert_flow(flow)
  res = []

  flow.each do |item|
    case item
    when String then
      res << convert_string(item)
    when RDoc::Markup::AttrChanger then
      off_tags res, item
      on_tags res, item
    when RDoc::Markup::RegexpHandling then
      res << convert_regexp_handling(item)
    else
      raise "Unknown flow element: #{item.inspect}"
    end
  end

  res.join
end

convert_regexp_handling(target) 点击以切换源代码

转换添加的正则表达式处理。请参阅RDoc::Markup#add_regexp_handling

# File rdoc/markup/formatter.rb, line 150
def convert_regexp_handling target
  return target.text if in_tt?

  handled = false

  @attributes.each_name_of target.type do |name|
    method_name = "handle_regexp_#{name}"

    if respond_to? method_name then
      target.text = public_send method_name, target
      handled = true
    end
  end

  unless handled then
    target_name = @attributes.as_string target.type

    raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
  end

  target.text
end

convert_string(string) 点击以切换源代码

如果需要，将字符串转换为更花哨的格式

# File rdoc/markup/formatter.rb, line 176
def convert_string string
  string
end

each_attr_tag(attr_mask, reverse = false) { |tag| ... } 点击以切换源代码

# File rdoc/markup/formatter.rb, line 225
def each_attr_tag attr_mask, reverse = false
  return if attr_mask.zero?

  @attr_tags.public_send(reverse ? :reverse_each : :each) do |tag|
    if attr_mask & tag.bit != 0 then
      yield tag
    end
  end
end

ignore(*node) 点击以切换源代码

在您的子类中使用 ignore 来忽略节点的内容。

##
# We don't support raw nodes in ToNoRaw

alias accept_raw ignore

# File rdoc/markup/formatter.rb, line 188
def ignore *node
end

in_tt?() 点击以切换源代码

我们目前在 tt 标签内吗？

# File rdoc/markup/formatter.rb, line 194
def in_tt?
  @in_tt > 0
end

off_tags(res, item) 点击以切换源代码

关闭 res 上 item 的标签

# File rdoc/markup/formatter.rb, line 218
def off_tags res, item
  each_attr_tag(item.turn_off, true) do |tag|
    @in_tt -= 1 if tt? tag
    res << annotate(tag.off)
  end
end

on_tags(res, item) 点击以切换源代码

打开 res 上 item 的标签

# File rdoc/markup/formatter.rb, line 208
def on_tags res, item
  each_attr_tag(item.turn_on) do |tag|
    res << annotate(tag.on)
    @in_tt += 1 if tt? tag
  end
end

parse_url(url) 点击以切换源代码

从 url 中提取方案、URL 和锚点 ID 并返回它们。

# File rdoc/markup/formatter.rb, line 238
def parse_url url
  case url
  when /^rdoc-label:([^:]*)(?::(.*))?/ then
    scheme = 'link'
    path   = "##{$1}"
    id     = " id=\"#{$2}\"" if $2
  when /([A-Za-z]+):(.*)/ then
    scheme = $1.downcase
    path   = $2
  when /^#/ then
  else
    scheme = 'http'
    path   = url
    url    = url
  end

  if scheme == 'link' then
    url = if path[0, 1] == '#' then # is this meaningful?
            path
          else
            self.class.gen_relative_url @from_path, path
          end
  end

  [scheme, url, id]
end

tt?(tag) 点击以切换源代码

tag 是 tt 标签吗？

# File rdoc/markup/formatter.rb, line 268
def tt? tag
  tag.bit == @tt_bit
end

tt_tag?(attr_mask, reverse = false) 点击以切换源代码

# File rdoc/markup/formatter.rb, line 198
def tt_tag? attr_mask, reverse = false
  each_attr_tag(attr_mask, reverse) do |tag|
    return true if tt? tag
  end
  false
end