class REXML::Document

[edit]

要約

XMLの完全な文書(ドキュメント)を表すクラス。

XML処理命令(Processing Instruction, PI)、 DTD(文書型定義、Document Type Definition)、などを含んでいます。ドキュメントは直下の子ノードをただ一つ持っています(rootと呼び、 REXML::Document#root でアクセスできます)。 2つ目の要素を(REXML::Element#add_elementなどで)追加しようとすると例外(RuntimeError)が発生します。

目次

特異メソッド
インスタンスメソッド
定数

継承しているメソッド

REXML::Elementから継承しているメソッド
REXML::Namespaceから継承しているメソッド
REXML::Parentから継承しているメソッド
Enumerableから継承しているメソッド
REXML::Childから継承しているメソッド
REXML::Nodeから継承しているメソッド

特異メソッド

entity_expansion_limit -> Integer[permalink][rdoc][edit]

実体参照の展開回数の上限を返します。

XML 文書(REXML::Document)ごとの展開回数がこの値を越えると例外を発生させ、処理を中断します。

実体参照の展開処理を使った DoS 攻撃に対抗するための仕組みです。

デフォルトは 10000 です。

このメソッドは Ruby 2.1 から deprecated になりました。 REXML::Security.entity_expansion_limit を使ってください。

[SEE_ALSO] REXML::Document.entity_expansion_limit=

entity_expansion_limit=(val)[permalink][rdoc][edit]

実体参照の展開回数の上限を指定します。

XML 文書(REXML::Document)ごとの展開回数がこの値を越えると例外を発生させ、処理を中断します。

デフォルトは 10000 です。

このメソッドは Ruby 2.1 から deprecated になりました。 REXML::Security.entity_expansion_limit= を使ってください。

[PARAM] val:
設定する上限値(整数)

[SEE_ALSO] REXML::Document.entity_expansion_limit

entity_expansion_text_limit -> Integer[permalink][rdoc][edit]

実体参照の展開による文字列の増分(テキストのバイト数)の最大値を指定します。

展開によって増分値がこの値を越えると例外を発生させ、処理を中断します。

実体参照の展開処理を使った DoS 攻撃に対抗するための仕組みです。

デフォルトは 10240 (byte) です。

このメソッドは Ruby 2.1 から deprecated になりました。 REXML::Security.entity_expansion_text_limit を使ってください。

[SEE_ALSO] REXML::Document.entity_expansion_text_limit=, http://www.ruby-lang.org/ja/news/2013/02/22/rexml-dos-2013-02-22/

entity_expansion_text_limit=(val)[permalink][rdoc][edit]

実体参照の展開による文字列の増分(テキストのバイト数)の最大値を指定します。

展開によって増分値がこの値を越えると例外を発生させ、処理を中断します。

実体参照の展開処理を使った DoS 攻撃に対抗するための仕組みです。

デフォルトは 10240 (byte) です。

このメソッドは Ruby 2.1 から deprecated になりました。 REXML::Security.entity_expansion_text_limit= を使ってください。

[SEE_ALSO] REXML::Document.entity_expansion_text_limit http://www.ruby-lang.org/ja/news/2013/02/22/rexml-dos-2013-02-22/

new(source = nil, context = {}) -> REXML::Document[permalink][rdoc][edit]

Document オブジェクトを生成します。

source には String、IO、REXML::Document のいずかが指定できます。 REXML::Document を指定するとコンテキストと要素、属性が複製されます。文字列の場合はそれを XML と見なしてパースします。 IOの場合は、XML文書を読み出してパースします。

context で「コンテキスト」を指定します。テキストノードの空白や特殊文字の取り扱いを Hash で指定します。以下の Symbol をハッシュのキーとして使います。

:respect_whitespace

空白を考慮して欲しい要素の名前の集合を文字列の配列で指定します。また、すべての要素で空白を考慮して欲しい場合には :all を指定します。デフォルト値は :all です。 REXML::Element#whitespace も参照してください。

:compress_whitespace

空白を無視して欲しい要素の名前の集合を文字列の配列で指定します。この指定は :respect_whitespace での指定を上書きします。すべての要素で空白を無視して欲しい場合には :all を指定します。 REXML::Element#whitespace も参照してください。

:ignore_whitespace_nodes

空白のみからなるノードを無視して欲しい要素の名前の集合を文字列の配列で指定します。すべての要素で無視して欲しい場合は :all を指定します。これが設定された場合、空白のみからなる text node は追加されません。 REXML::Element#ignore_whitespace_nodes も参照してください。

:raw

raw mode で取り扱いをして欲しい要素の名前の集合を文字列の配列で指定します。すべてのノードを raw mode で取り扱って欲しい場合は :all を指定します。 raw mode においては、text 中の特殊文字は一切変換されません。 REXML::Element#raw も参照してください。

[PARAM] source:
XML文書(文字列, IO)もしくは REXML::Document オブジェクト
[PARAM] context:
コンテキスト
[EXCEPTION] REXML::ParseException:
XML文書のパースに失敗した場合に発生します
[EXCEPTION] REXML::UndefinedNamespaceException:
XML文書のパース中に、定義されていない名前空間が現れた場合に発生します
parse_stream(source, listener) -> ()[permalink][rdoc][edit]

XML文書を source から読み込み、パースした結果を listener にコールバックで伝えます。

このメソッドは 

Parsers::StreamParser.new( source, listener ).parse

と同じ挙動をします。

コールバックの詳しい仕組みなどについては REXML::Parsers::StreamParser および REXML::StreamListener を参照してください。

[PARAM] source:
入力(文字列、IO、IO互換オブジェクト(StringIOなど))
[PARAM] listner:
コールバックオブジェクト

インスタンスメソッド

add(child) -> ()[permalink][rdoc][edit]
self << child -> ()

子ノードを追加します。

追加できるものは

のいずれかです。

clone -> REXML::Document[permalink][rdoc][edit]

self を複製します。

REXML::Document.new(self) と同じです。

doctype -> REXML::DocType | nil[permalink][rdoc][edit]

文書の DTD を返します。

文書が DTD を持たない場合は nil を返します。

encoding -> String[permalink][rdoc][edit]

XML 宣言に含まれている XML 文書のエンコーディングを返します。

文書が XML 宣言を持たない場合はデフォルトの値 (REXML::XMLDecl.defaultで宣言されているもの)を返します。

例

require 'rexml/document'
doc = REXML::Document.new(<<EOS)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<e />
EOS
doc.encoding # => "UTF-8"
expanded_name -> String[permalink][rdoc][edit]
name -> String

""(空文字列)を返します。

XMLの仕様上、このオブジェクトはexpanded name名前を持ちえません。

node_type -> Symbol[permalink][rdoc][edit]

シンボル :document を返します。

root -> REXML::Element | nil[permalink][rdoc][edit]

文書のルート要素を返します。

文書がルート要素を持たない場合は nil を返します。

stand_alone? -> String[permalink][rdoc][edit]

XML 宣言の standalone の値を文字列で返します。

例

require 'rexml/document'
doc = REXML::Document.new(<<EOS)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<e />
EOS
doc.stand_alone? # => "yes"
version -> String[permalink][rdoc][edit]

XML 宣言に含まれている XML 文書のバージョンを返します。

文書が XML 宣言を持たない場合はデフォルトの値 (REXML::XMLDecl.defaultで宣言されているもの)を返します。

例

require 'rexml/document'
doc = REXML::Document.new(<<EOS)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<e />
EOS
doc.version # => "1.0"
write(output = $stdout, indent = -1, transitive = false, ie_hack = false, encoding=nil) -> ()[permalink][rdoc][edit]
write(output: $stdout, indent: -1, transitive: false, ie_hack: false, encoding: nil) -> ()

output に XML 文書を出力します。

XML宣言、DTD、処理命令を(もしあるならば)含む文書を出力します。

注意すべき点として、元の XML 文書が XML宣言を含んでいなくとも出力される XML はデフォルトの XML 宣言を含んでいるべきであるが、 REXML は明示しない限り(つまりXML宣言を REXML::Document#add で追加しない限り) それをしない、ということである。XML-RPCのような利用法ではネットワークバンドを少しでも節約する必要があるためである。

2.0.0以降ではキーワード引数による引数指定が可能です。

[PARAM] output:
出力先(IO のように << で書き込めるオブジェクト)
[PARAM] indent:
インデントのスペースの数(-1 だとインデントしない)
[PARAM] transitive:
XMLではインデントのスペースでDOMが変化してしまう場合がある。これに真を渡すと、XMLのDOMに余計な要素が加わらないように空白の出力を適当に抑制するようになる
[PARAM] ie_hack:
IEはバージョンによってはXMLをちゃんと解釈できないので、それに対応したXMLを出力するかどうかを真偽値で指定する
xml_decl -> REXML::XMLDecl | nil[permalink][rdoc][edit]

文書の XML 宣言を返します。

文書が XML 宣言を持たない場合は nil を返します。

定数

DECLARATION -> REXML::XMLDecl[permalink][rdoc][edit]

この定数は deprecated です。REXML::XMLDecl.default を代わりに使ってください。

デフォルトとして使えるXML宣言オブジェクト。