Class LibXML::XML::Document
In: ext/libxml/libxml.c
lib/libxml/document.rb
Parent: Object

Reads or writes an XML document:

Reading: 

 require 'xml'

 doc = XML::Document.new()
 doc.root = XML::Node.new('root_node')
 doc.root << XML::Node.new('elem1')
 doc.save('output.xml', format)

Writing: 

 require 'libxml'
 doc = XML::Document.file('output.xml')
 root = doc.root

Methods

child   child?   compression   compression=   compression?   debug_dump   debug_dump_head   debug_format_dump   dump   encoding   encoding=   file   filename   find   find_first   format_dump   last   last?   new   next   next?   parent   parent?   prev   prev?   reader   root   root=   save   standalone?   to_s   url   validate   validate_relaxng   validate_schema   version   xinclude  

Public Class methods

XML::Document.file(filename) → document

Create a new XML::Document by parsing the specified file.

[Source]

/*
 * call-seq:
 *    XML::Document.file(filename) -> document
 * 
 * Create a new XML::Document by parsing the specified
 * file.
 */
VALUE
ruby_xml_document_new_file(VALUE class, VALUE filename) {
XML::Document.new(xml_version = 1.0) → document

Create a new XML::Document, optionally specifying the XML version.

[Source]

/*
 * call-seq:
 *    XML::Document.new(xml_version = 1.0) -> document
 * 
 * Create a new XML::Document, optionally specifying the
 * XML version.
 */
VALUE
ruby_xml_document_new(int argc, VALUE *argv, VALUE class) {

Public Instance methods

document.child → node

Get this document‘s child node.

[Source]

/*
 * call-seq:
 *    document.child -> node
 * 
 * Get this document's child node.
 */
VALUE
ruby_xml_document_child_get(VALUE self) {
document.child? → (true|false)

Determine whether this document has a child node.

[Source]

/*
 * call-seq:
 *    document.child? -> (true|false)
 * 
 * Determine whether this document has a child node.
 */
VALUE
ruby_xml_document_child_q(VALUE self) {
document.compression → num

Obtain this document‘s compression mode identifier.

[Source]

/*
 * call-seq:
 *    document.compression -> num
 * 
 * Obtain this document's compression mode identifier.
 */
VALUE
ruby_xml_document_compression_get(VALUE self) {
document.compression = num

Set this document‘s compression mode.

[Source]

/*
 * call-seq:
 *    document.compression = num
 * 
 * Set this document's compression mode.
 */
VALUE
ruby_xml_document_compression_set(VALUE self, VALUE num) {
document.compression? → (true|false)

Determine whether this document is compressed.

[Source]

/*
 * call-seq:
 *    document.compression? -> (true|false)
 * 
 * Determine whether this document is compressed.
 */
VALUE
ruby_xml_document_compression_q(VALUE self) {
document.debug_dump([stream]) → true

Debug version of dump.

[Source]

/*
 * call-seq:
 *    document.debug_dump([stream]) -> true
 * 
 * Debug version of dump.
 */
VALUE
ruby_xml_document_debug_dump(int argc, VALUE *argv, VALUE self) {
document.debug_dump_head([stream]) → true

Debug-dump this document‘s header to the specified IO stream. If no stream is specified, stdout is used.

[Source]

/*
 * call-seq:
 *    document.debug_dump_head([stream]) -> true
 * 
 * Debug-dump this document's header to the specified IO stream.
 * If no stream is specified, stdout is used.
 */
VALUE
ruby_xml_document_debug_dump_head(int argc, VALUE *argv, VALUE self) {
document.debug_format_dump([stream]) → true

Deprecated in favour of format_dump.

[Source]

/*
 * call-seq:
 *    document.debug_format_dump([stream]) -> true
 * 
 * *Deprecated* in favour of format_dump.
 */
VALUE
ruby_xml_document_debug_format_dump(int argc, VALUE *argv, VALUE self) {
document.dump([stream]) → true

Dump this document‘s XML to the specified IO stream. If no stream is specified, stdout is used.

[Source]

/*
 * call-seq:
 *    document.dump([stream]) -> true
 * 
 * Dump this document's XML to the specified IO stream.
 * If no stream is specified, stdout is used.
 */
VALUE
ruby_xml_document_dump(int argc, VALUE *argv, VALUE self) {
document.encoding → "encoding"

Obtain the encoding specified by this document.

[Source]

/*
 * call-seq:
 *    document.encoding -> "encoding"
 * 
 * Obtain the encoding specified by this document.
 */
VALUE
ruby_xml_document_encoding_get(VALUE self) {
document.encoding = "encoding"

Set the encoding for this document.

[Source]

/*
 * call-seq:
 *    document.encoding = "encoding"
 * 
 * Set the encoding for this document.
 */
VALUE
ruby_xml_document_encoding_set(VALUE self, VALUE encoding) {
document.filename → "filename"

Obtain the filename this document was read from.

[Source]

/*
 * call-seq:
 *    document.filename -> "filename"
 * 
 * Obtain the filename this document was read from.
 */
VALUE
ruby_xml_document_filename_get(VALUE self) {
find(xpath, nslist = nil)

Return the nodes matching the specified xpath expression, optionally using the specified namespace. For more information about working with namespaces, please refer to the XML::XPath documentation.

Parameters:

  • xpath - The xpath expression as a string
  • namespaces - An optional list of namespaces (see XML::XPath for information).
  • Returns - XML::XPath::Object 
 document.find('/foo', 'xlink:http://www.w3.org/1999/xlink')

IMPORTANT - The returned XML::Node::Set must be freed before its associated document. In a running Ruby program this will happen automatically via Ruby‘s mark and sweep garbage collector. However, if the program exits, Ruby does not guarantee the order in which objects are freed (see blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/17700). As a result, the associated document may be freed before the node list, which will cause a segmentation fault. To avoid this, use the following (non-ruby like) coding style: 

 nodes = doc.find('/header')
 nodes.each do |node|
   ... do stuff ...
 end

 nodes = nil
 GC.start

[Source]

    # File lib/libxml/document.rb, line 37
37:       def find(xpath, nslist = nil)
38:         context = XPath::Context.new(self)
39:         context.node = self.root  
40:         context.register_namespaces_from_node(self.root)
41:         context.register_namespaces(nslist) if nslist
42: 
43:         context.find(xpath)
44:       end
find_first(xpath, nslist = nil)

Return the first node matching the specified xpath expression. For more information, please refer to the documentation for XML::Document#find.

[Source]

    # File lib/libxml/document.rb, line 49
49:       def find_first(xpath, nslist = nil)
50:         find(xpath, nslist).first
51:       end
document.format_dump([stream], [spacing]) → true

Dump this document‘s formatted XML to the specified IO stream. If no stream is specified, stdout is used. If spacing is specified, it must be a boolean that determines whether spacing is used.

[Source]

/*
 * call-seq:
 *    document.format_dump([stream], [spacing]) -> true
 * 
 * Dump this document's formatted XML to the specified IO stream.
 * If no stream is specified, stdout is used. If spacing is 
 * specified, it must be a boolean that determines whether 
 * spacing is used.
 */
VALUE
ruby_xml_document_format_dump(int argc, VALUE *argv, VALUE self) {
document.last → node

Obtain the last node.

[Source]

/*
 * call-seq:
 *    document.last -> node
 * 
 * Obtain the last node.
 */
VALUE
ruby_xml_document_last_get(VALUE self) {
document.last? → (true|false)

Determine whether there is a last node.

[Source]

/*
 * call-seq:
 *    document.last? -> (true|false)
 * 
 * Determine whether there is a last node.
 */
VALUE
ruby_xml_document_last_q(VALUE self) {
document.next → node

Obtain the next node.

[Source]

/*
 * call-seq:
 *    document.next -> node
 * 
 * Obtain the next node.
 */
VALUE
ruby_xml_document_next_get(VALUE self) {
document.next? → (true|false)

Determine whether there is a next node.

[Source]

/*
 * call-seq:
 *    document.next? -> (true|false)
 * 
 * Determine whether there is a next node.
 */
VALUE
ruby_xml_document_next_q(VALUE self) {
document.parent → node

Obtain the parent node.

[Source]

/*
 * call-seq:
 *    document.parent -> node
 * 
 * Obtain the parent node.
 */
VALUE
ruby_xml_document_parent_get(VALUE self) {
document.parent? → (true|false)

Determine whether there is a parent node.

[Source]

/*
 * call-seq:
 *    document.parent? -> (true|false)
 * 
 * Determine whether there is a parent node.
 */
VALUE
ruby_xml_document_parent_q(VALUE self) {
document.prev → node

Obtain the previous node.

[Source]

/*
 * call-seq:
 *    document.prev -> node
 * 
 * Obtain the previous node.
 */
VALUE
ruby_xml_document_prev_get(VALUE self) {
document.prev? → (true|false)

Determine whether there is a previous node.

[Source]

/*
 * call-seq:
 *    document.prev? -> (true|false)
 * 
 * Determine whether there is a previous node.
 */
VALUE
ruby_xml_document_prev_q(VALUE self) {
document.reader → reader

Create a XML::Reader from the document. This is a shortcut to XML::Reader.walker().

[Source]

/*
 * call-seq:
 *    document.reader -> reader
 * 
 * Create a XML::Reader from the document. This is a shortcut to
 * XML::Reader.walker().
 */
static VALUE
ruby_xml_document_reader(VALUE self)
{
  return ruby_xml_reader_new_walker(cXMLReader, self);
}
document.root → node

Obtain the root node.

[Source]

/*
 * call-seq:
 *    document.root -> node
 * 
 * Obtain the root node.
 */
VALUE
ruby_xml_document_root_get(VALUE self) {
document.root = node

Set the root node.

[Source]

/*
 * call-seq:
 *    document.root = node
 * 
 * Set the root node.
 */
VALUE
ruby_xml_document_root_set(VALUE self, VALUE node) {
document.save(filename, format = false) → int

Save this document to the file given by filename, optionally formatting the output.

Parameters: 

 filename: The filename or URL of the new document
 format: Specifies whether formatting spaces should be added.
 returns: The number of bytes written or -1 in case of error.

[Source]

/*
 * call-seq:
 *    document.save(filename, format = false) -> int
 * 
 * Save this document to the file given by filename, 
 * optionally formatting the output.
 
 * Parameters:
 *  filename: The filename or URL of the new document
 *  format: Specifies whether formatting spaces should be added.
 *  returns: The number of bytes written or -1 in case of error. 
 */
VALUE
ruby_xml_document_save(int argc, VALUE *argv, VALUE self) {
document.standalone? → (true|false)

Determine whether this is a standalone document.

[Source]

/*
 * call-seq:
 *    document.standalone? -> (true|false)
 * 
 * Determine whether this is a standalone document.
 */
VALUE
ruby_xml_document_standalone_q(VALUE self) {
document.to_s({format=true,encoding) → "xml"

Coerce this document to a string representation of it‘s XML. The default is to pretty format, but this depends Parser#indent_tree_output==true or Parser#default_keep_blanks==false.

The encoding is not applied to the document, but is encoding target of the resulting string.

[Source]

/*
 * call-seq:
 *    document.to_s({format=true,encoding) -> "xml"
 * 
 * Coerce this document to a string representation
 * of it's XML. The default is to pretty format, but this
 * depends Parser#indent_tree_output==true or
 * Parser#default_keep_blanks==false.
 *
 * The encoding is not applied to the document, but is
 * encoding target of the resulting string.
 */
VALUE
ruby_xml_document_to_s(int argc, VALUE *argv, VALUE self) {
document.url → "url"

Obtain this document‘s source URL, if any.

[Source]

/*
 * call-seq:
 *    document.url -> "url"
 * 
 * Obtain this document's source URL, if any.
 */
VALUE
ruby_xml_document_url_get(VALUE self) {
document.validate(dtd) → (true|false)

Validate this document against the specified XML::DTD.

[Source]

/*
 * call-seq:
 *    document.validate(dtd) -> (true|false)
 * 
 * Validate this document against the specified XML::DTD.
 */
VALUE
ruby_xml_document_validate_dtd(VALUE self, VALUE dtd) {
document.validate_schema(relaxng) → (true|false)

Validate this document against the specified XML::RelaxNG.

If a block is provided it is used as an error handler for validaten errors. The block is called with two argument, the message and a flag indication if the message is an error (true) or a warning (false).

[Source]

/*
 * call-seq:
 *    document.validate_schema(relaxng) -> (true|false)
 * 
 * Validate this document against the specified XML::RelaxNG.
 *
 * If a block is provided it is used as an error handler for validaten errors.
 * The block is called with two argument, the message and a flag indication
 * if the message is an error (true) or a warning (false).
 */
VALUE
ruby_xml_document_validate_relaxng(VALUE self, VALUE relaxng) {
document.validate_schema(schema) → (true|false)

Validate this document against the specified XML::Schema.

If a block is provided it is used as an error handler for validaten errors. The block is called with two argument, the message and a flag indication if the message is an error (true) or a warning (false).

[Source]

/*
 * call-seq:
 *    document.validate_schema(schema) -> (true|false)
 * 
 * Validate this document against the specified XML::Schema.
 * 
 * If a block is provided it is used as an error handler for validaten errors.
 * The block is called with two argument, the message and a flag indication
 * if the message is an error (true) or a warning (false).
 */
VALUE
ruby_xml_document_validate_schema(VALUE self, VALUE schema) {
document.version → "version"

Obtain the XML version specified by this document.

[Source]

/*
 * call-seq:
 *    document.version -> "version"
 * 
 * Obtain the XML version specified by this document.
 */
VALUE
ruby_xml_document_version_get(VALUE self) {
document.xinclude → num

Process xinclude directives in this document.

[Source]

/*
 * call-seq:
 *    document.xinclude -> num
 * 
 * Process xinclude directives in this document. 
 */
VALUE
ruby_xml_document_xinclude(VALUE self) {

[Validate]