class REXML::Document

表示一个 XML 文档。

一个文档可能具有

一个可以通过方法 root 访问的单个子节点。
一个 XML 声明。
一个文档类型。
处理指令。

赶时间？¶ ↑

如果您对 XML 有一些了解并且脑海中有一个特定的任务，您可能需要查看任务页面，特别是文档的任务页面。

常量

DECLARATION

一个方便的默认 XML 声明。使用

mydoc << XMLDecl.default

属性

entity_expansion_count[R]

entity_expansion_limit[W]

entity_expansion_text_limit[RW]

公共类方法

entity_expansion_limit() 点击切换源代码

获取实体展开限制。默认情况下，该限制设置为 10000。

已弃用。请改用 REXML::Security.entity_expansion_limit=。

# File rexml-3.4.0/lib/rexml/document.rb, line 417
def Document::entity_expansion_limit
  return Security.entity_expansion_limit
end

entity_expansion_limit=( val ) 点击切换源代码

设置实体展开限制。默认情况下，该限制设置为 10000。

已弃用。请改用 REXML::Security.entity_expansion_limit=。

# File rexml-3.4.0/lib/rexml/document.rb, line 410
def Document::entity_expansion_limit=( val )
  Security.entity_expansion_limit = val
end

entity_expansion_text_limit() 点击切换源代码

获取实体展开限制。默认情况下，该限制设置为 10240。

已弃用。请改用 REXML::Security.entity_expansion_text_limit。

# File rexml-3.4.0/lib/rexml/document.rb, line 431
def Document::entity_expansion_text_limit
  return Security.entity_expansion_text_limit
end

entity_expansion_text_limit=( val ) 点击切换源代码

设置实体展开限制。默认情况下，该限制设置为 10240。

已弃用。请改用 REXML::Security.entity_expansion_text_limit=。

# File rexml-3.4.0/lib/rexml/document.rb, line 424
def Document::entity_expansion_text_limit=( val )
  Security.entity_expansion_text_limit = val
end

new(string = nil, context = {}) → new_document 点击切换源代码

new(io_stream = nil, context = {}) → new_document

new(document = nil, context = {}) → new_document

返回一个新的 REXML::Document 对象。

当没有给出参数时，返回一个空文档

d = REXML::Document.new
d.to_s # => ""

当给出参数 string 时，它必须是一个包含有效 XML 文档的字符串

xml_string = '<root><foo>Foo</foo><bar>Bar</bar></root>'
d = REXML::Document.new(xml_string)
d.to_s # => "<root><foo>Foo</foo><bar>Bar</bar></root>"

当给出参数 io_stream 时，它必须是一个为读取而打开的 IO 对象，并且在读取时必须返回一个有效的 XML 文档

File.write('t.xml', xml_string)
d = File.open('t.xml', 'r') do |io|
  REXML::Document.new(io)
end
d.to_s # => "<root><foo>Foo</foo><bar>Bar</bar></root>"

当给出参数 document 时，它必须是一个现有的文档对象，其上下文和属性（但不是子节点）被克隆到新文档中

d = REXML::Document.new(xml_string)
d.children    # => [<root> ... </>]
d.context = {raw: :all, compress_whitespace: :all}
d.add_attributes({'bar' => 0, 'baz' => 1})
d1 = REXML::Document.new(d)
d1.children   # => []
d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}

当给出参数 context 时，它必须是一个包含文档上下文条目的哈希；请参见元素上下文

context = {raw: :all, compress_whitespace: :all}
d = REXML::Document.new(xml_string, context)
d.context # => {:raw=>:all, :compress_whitespace=>:all}

调用超类方法

# File rexml-3.4.0/lib/rexml/document.rb, line 92
def initialize( source = nil, context = {} )
  @entity_expansion_count = 0
  @entity_expansion_limit = Security.entity_expansion_limit
  @entity_expansion_text_limit = Security.entity_expansion_text_limit
  super()
  @context = context
  return if source.nil?
  if source.kind_of? Document
    @context = source.context
    super source
  else
    build(  source )
  end
end

parse_stream( source, listener ) 点击切换源代码

# File rexml-3.4.0/lib/rexml/document.rb, line 403
def Document::parse_stream( source, listener )
  Parsers::StreamParser.new( source, listener ).parse
end

公共实例方法

<<( child )

别名为：add

add(xml_decl) → self 点击切换源代码

add(doc_type) → self

add(object) → self

向文档添加一个对象；返回 self。

当给出参数 xml_decl 时，它必须是一个 REXML::XMLDecl 对象，它将成为文档的 XML 声明，替换之前的 XML 声明（如果有）

d = REXML::Document.new
d.xml_decl.to_s # => ""
d.add(REXML::XMLDecl.new('2.0'))
d.xml_decl.to_s # => "<?xml version='2.0'?>"

当给出参数 doc_type 时，它必须是一个 REXML::DocType 对象，它将成为文档的文档类型，替换之前的文档类型（如果有）

d = REXML::Document.new
d.doctype.to_s # => ""
d.add(REXML::DocType.new('foo'))
d.doctype.to_s # => "<!DOCTYPE foo>"

当给出参数 object (不是 REXML::XMLDecl 或 REXML::DocType 对象) 时，它将作为最后一个子节点添加

d = REXML::Document.new
d.add(REXML::Element.new('foo'))
d.to_s # => "<foo/>"

调用超类方法

# File rexml-3.4.0/lib/rexml/document.rb, line 172
def add( child )
  if child.kind_of? XMLDecl
    if @children[0].kind_of? XMLDecl
      @children[0] = child
    else
      @children.unshift child
    end
    child.parent = self
  elsif child.kind_of? DocType
    # Find first Element or DocType node and insert the decl right
    # before it.  If there is no such node, just insert the child at the
    # end.  If there is a child and it is an DocType, then replace it.
    insert_before_index = @children.find_index { |x|
      x.kind_of?(Element) || x.kind_of?(DocType)
    }
    if insert_before_index # Not null = not end of list
      if @children[ insert_before_index ].kind_of? DocType
        @children[ insert_before_index ] = child
      else
        @children[ insert_before_index-1, 0 ] = child
      end
    else  # Insert at end of list
      @children << child
    end
    child.parent = self
  else
    rv = super
    raise "attempted adding second root element to document" if @elements.size > 1
    rv
  end
end

别名也为：<<

add_element(name_or_element = nil, attributes = nil) → new_element 点击切换源代码

通过调用 REXML::Element.add_element 向文档添加一个元素

REXML::Element.add_element(name_or_element, attributes)

调用超类方法

# File rexml-3.4.0/lib/rexml/document.rb, line 211
def add_element(arg=nil, arg2=nil)
  rv = super
  raise "attempted adding second root element to document" if @elements.size > 1
  rv
end

clone → new_document 点击切换源代码

返回执行 Document.new(self) 后产生的新文档。请参见Document.new。

# File rexml-3.4.0/lib/rexml/document.rb, line 122
def clone
  Document.new self
end

doctype → doc_type or nil 点击切换源代码

返回文档的 DocType 对象（如果存在），否则返回 nil

d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
d.doctype.class # => REXML::DocType
d = REXML::Document.new('')
d.doctype.class # => nil

# File rexml-3.4.0/lib/rexml/document.rb, line 243
def doctype
  @children.find { |item| item.kind_of? DocType }
end

document() 点击切换源代码

# File rexml-3.4.0/lib/rexml/document.rb, line 446
def document
  self
end

encoding → encoding_string 点击切换源代码

返回文档的 XMLDecl 编码（如果已设置），否则返回默认编码

d = REXML::Document.new('<?xml version="1.0" encoding="UTF-16"?>')
d.encoding # => "UTF-16"
d = REXML::Document.new('')
d.encoding # => "UTF-8"

# File rexml-3.4.0/lib/rexml/document.rb, line 292
def encoding
  xml_decl().encoding
end

expanded_name -> empty_string 点击切换源代码

返回一个空字符串。

# File rexml-3.4.0/lib/rexml/document.rb, line 131
def expanded_name
  ''
  #d = doc_type
  #d ? d.name : "UNDEFINED"
end

别名也为：name

name()

别名为：expanded_name

node_type → :document 点击切换源代码

返回符号 :document。

# File rexml-3.4.0/lib/rexml/document.rb, line 112
def node_type
  :document
end

record_entity_expansion() 点击切换源代码

# File rexml-3.4.0/lib/rexml/document.rb, line 439
def record_entity_expansion
  @entity_expansion_count += 1
  if @entity_expansion_count > @entity_expansion_limit
    raise "number of entity expansions exceeded, processing aborted."
  end
end

root → root_element or nil 点击切换源代码

返回文档的根元素（如果存在），否则返回 nil

d = REXML::Document.new('<root></root>')
d.root # => <root/>
d = REXML::Document.new('')
d.root # => nil

# File rexml-3.4.0/lib/rexml/document.rb, line 227
def root
  elements[1]
  #self
  #@children.find { |item| item.kind_of? Element }
end

stand_alone? 点击切换源代码

返回文档的 XMLDecl 独立值（作为字符串）（如果已设置），否则返回默认独立值

d = REXML::Document.new('<?xml standalone="yes"?>')
d.stand_alone? # => "yes"
d = REXML::Document.new('')
d.stand_alone? # => nil

# File rexml-3.4.0/lib/rexml/document.rb, line 307
def stand_alone?
  xml_decl().stand_alone?
end

version → version_string 点击切换源代码

返回此文档的 XMLDecl 版本（作为字符串）（如果已设置），否则返回默认版本

d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
d.version # => "2.0"
d = REXML::Document.new('')
d.version # => "1.0"

# File rexml-3.4.0/lib/rexml/document.rb, line 277
def version
  xml_decl().version
end

write(output=$stdout, indent=-1, transtive=false, ie_hack=false, encoding=nil) 点击切换源代码

write(options={:output => $stdout, :indent => -1, :transtive => false, :ie_hack => false, :encoding → nil})

输出 XML 树，可以选择缩进。这将输出整个 XML 文档，包括 XML 声明、doctype 声明和处理指令（如果提供了）。

一个有争议的点是，无论用户（或源文档）是否提供 XML 声明（<?xml version=‘1.0’?>），Document 是否应该始终写入 XML 声明。REXML 在未指定的情况下不会写入，因为它会为 XML-RPC 等应用程序增加不必要的带宽。

接受 Nth 参数样式和选项哈希样式作为参数。对于一个或多个参数的情况，建议使用选项哈希样式。

示例

Document.new("<a><b/></a>").write

output = ""
Document.new("<a><b/></a>").write(output)

output = ""
Document.new("<a><b/></a>").write(:output => output, :indent => 2)

另请参阅 rexml/formatters 包中的类，以了解更改 XML 输出的默认格式的正确方法。

示例

output = ""
tr = Transitive.new
tr.write(Document.new("<a><b/></a>"), output)

output: 输出一个支持“<< string”的对象；这是文档将被写入的地方。
indent: 一个整数。如果为 -1，则不使用缩进；否则，缩进将是此数字的两倍空格，并且子节点将额外缩进一定的量。对于值为 3，每个项目将额外缩进 3 个级别，或 6 个空格 (2 * 3)。默认为 -1
transitive: 如果 transitive 为 true 且 indent >= 0，则输出将以一种方式进行漂亮打印，使得添加的空格不会影响文档的绝对值——也就是说，它使文档中 Text 节点的值和数量保持不变。
ie_hack: 此 hack 在空标签上的 /> 前插入一个空格，以解决 Internet Explorer 的一个限制。默认为 false
encoding: Encoding 名称作为字符串。将输出编码更改为指定的编码，而不是 XML 声明中的编码。默认为 nil。这意味着使用 XML 声明中的编码。

# File rexml-3.4.0/lib/rexml/document.rb, line 367
def write(*arguments)
  if arguments.size == 1 and arguments[0].class == Hash
    options = arguments[0]

    output     = options[:output]
    indent     = options[:indent]
    transitive = options[:transitive]
    ie_hack    = options[:ie_hack]
    encoding   = options[:encoding]
  else
    output, indent, transitive, ie_hack, encoding, = *arguments
  end

  output   ||= $stdout
  indent   ||= -1
  transitive = false if transitive.nil?
  ie_hack    = false if ie_hack.nil?
  encoding ||= xml_decl.encoding

  if encoding != 'UTF-8' && !output.kind_of?(Output)
    output = Output.new( output, encoding )
  end
  formatter = if indent > -1
      if transitive
        require_relative "formatters/transitive"
        REXML::Formatters::Transitive.new( indent, ie_hack )
      else
        REXML::Formatters::Pretty.new( indent, ie_hack )
      end
    else
      REXML::Formatters::Default.new( ie_hack )
    end
  formatter.write( self, output )
end

xml_decl → xml_decl 点击切换源代码

返回文档的 XMLDecl 对象（如果存在），否则返回默认的 XMLDecl 对象

d = REXML::Document.new('<?xml version="1.0" encoding="UTF-8"?>')
d.xml_decl.class # => REXML::XMLDecl
d.xml_decl.to_s  # => "<?xml version='1.0' encoding='UTF-8'?>"
d = REXML::Document.new('')
d.xml_decl.class # => REXML::XMLDecl
d.xml_decl.to_s  # => ""

# File rexml-3.4.0/lib/rexml/document.rb, line 260
def xml_decl
  rv = @children[0]
  return rv if rv.kind_of? XMLDecl
  @children.unshift(XMLDecl.default)[0]
end

私有实例方法

build( source ) 点击切换源代码

# File rexml-3.4.0/lib/rexml/document.rb, line 451
def build( source )
  Parsers::TreeParser.new( source, self ).parse
end