Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

first version of rewritten and separated documentation

  • Loading branch information...
commit 390dbe866c9101ea38fcf073fca4c927048662c7 1 parent 8f2342e
Alex Bradbury authored
Showing with 217 additions and 0 deletions.
  1. +216 −0 DOCUMENTATION.mkd
  2. +1 −0  TODO
216 DOCUMENTATION.mkd
View
@@ -0,0 +1,216 @@
+# `xmlreader`
+Provides the XmlReader interface. All functions may return `nil` plus an error
+message if LibXML2 reports an error.
+
+# Iterators
+
+## `reader:read()`
+Moves the position of `reader` to the next node in the stream. Returns `true`
+if the node was read successfully, `false` if there are no more nodes to be
+read.
+
+## `reader:read_inner_xml()`
+Reads the contents of the current node's child nodes, does not include the
+tags of the current node. Returns a string containing the XML content, or
+`nil` plus an error message if the current node is neither an element nor
+attribute, or has no child nodes.
+
+## `reader:read_outer_xml()`
+Reads the contents of the current node, including child nodes and markup.
+Returns a string containing the XML content, or `nil` plus an error message if
+the current node is neither an element nor attribute, or has no child nodes.
+
+## `reader:read_string()`
+Reads the contents of an element of a text node as a string. Returns a string
+or nil plus an error message if the reader is position on any other type of
+node.
+
+## `reader:read_attribute_value()`
+Parses an attribute value into one or more Text and EntityReference nodes.
+Returns `true` in case of success, `false` if the reader was not positioned on
+an attribute node or all the attribute value have been read.
+
+# Retrieve information about the current node
+These methods do not move the reader.
+
+## `reader:attribute_count()`
+The number of attributes of the current node.
+
+## `reader:depth()`
+The depth of the node in the tree.
+
+## `reader:has_attributes`
+Returns a boolean indicating whether the current node has attributes.
+
+## `reader:has_value()`
+Returns a boolean indicating whether the current node can have an associated
+text value.
+
+## `reader:is_default()`
+Returns a boolean indicating whether the current node is an attribute that was
+generated from the default value defined in the DTD or schema.
+
+## `reader:is_empty_element()`
+Returns a boolean indicating whether the current node is an empty element.
+
+## `reader:node_type()`
+Returns the node type of the current node as a string. Possible types are:
+
+ * `none` returned if no read method has been called on `reader`, or no more
+ nodes are available to be read.
+ * `element` an XML element, e.g. `<foo>`.
+ * `attribute` an attribute. e.g. `href="http://example.com"`.
+ * `cdata` a CDATA section. e.g. `<![CDATA[escaped text]]>`.
+ * `entity reference` a reference to an entity. e.g. `&num`.
+ * `entity` an entity declaration, e.g. `<!ENTITY ...>`.
+ * `processing instruction` e.g. `<?pi test?>`.
+ * `comment` e.g. `<!-- a comment -->`
+ * `document` a document object that, as the root of the entire tree, provides
+ access to the entire XML document.
+ * `doctype` e.g. `<!DOCTYPE ...>`
+ * `document fragment` associates a node or sub-tree within a document without
+ actually being contained within the document.
+ * `notation` a notation in the document type declaration. e.g. `<!NOTATION
+ ...>`
+ * `whitespace` white space between markup.
+ * `significant whitespace` white space between markup in a mixed content
+ model or white space within the `xml:space="preserve"` scope.
+ * `end element` an end element tag, e.g. `</foo>`
+ * `end entity`
+ * `xml declaration` e.g. `<?xml version="1.0"?>`
+
+## `reader:quote_char()`
+Returns the quotation mark character of an attribute - either `"` or `'`.
+
+## `reader:read_state()`
+Returns the read state of the reader as a string, which is one of `"initial"`,
+`"interactive"`, `"error"`, `"eof"`, `"closed"` or `"reading"`.
+
+## `reader:is_namespace_declaration()`
+Returns a boolean indicating whether the current node is a namespace
+declaration rather than a regular attribute.
+
+## `reader:base_uri()`
+Returns the base URI of the current node or `nil` if it is not available (e.g.
+when parsing an in-memory string). A networked XML document may be comprised
+of chunks of data aggregated using various W3C standard inclusion mechanisms.
+The base URI tells you where a particular node came from.
+
+## `reader:local_name()`
+Returns the local name of the node or `nil` if it is not available. e.g. the
+local name for the element `<bk:book>` is `book`.
+
+## `reader:name()`
+Returns the qualified name of the current node. e.g. the qualified name for
+the element `<bk:book>` is `bk:book`.
+
+## `reader:namespace_uri()`
+Returns the namespace URI associated with the current node or `nil` if it has
+no associated namespace URI.
+
+## `reader:prefix()`
+Returns the namespace prefix associated with the current node or `nil` if it
+is not available. e.g. the prefix for the element `<bk:book>` is `bk`.
+
+## `reader:value()`
+Returns the text value of the current node or `nil` if not available.
+
+## `reader:close()`
+Closes the `xmlreader` instance. Returns `true` or `nil` plus an error
+message.
+
+## `reader:get_attribute(name|idx)`
+Returns the value of the attribute with either the specifed qualified name, or
+the specified zero-based index of the attribute relative to the containing
+element. e.g. `reader:get_attribute("id")` or `reader:get_attribute(0)`.
+
+## `reader:get_attribute_ns(local_name, nsuri)`
+Returns the value of the attribute specified by the given local name and
+namespace URI.
+
+## `reader:lookup_namespace(prefix)`
+Resolves the namespace prefix in the scope of the current element. Returns a
+string containing the namespace URI to which the prefix maps. Give the empty
+string to get the default namespace.
+
+NOTE the convention is that if false is returned, the reader's position has
+not changed.
+
+## `reader:move_to_attribute(name|idx)`
+Moves the position of `reader` to the attribute with the specified qualified
+name or the specified zero-based index. Returns `true` in case of success and
+`false` if the attribute is not found.
+
+## `reader:move_to_attribute_ns(localname, nsuri)`
+Moves the position of `reader` to the attribute with the specified local name
+and namespace URI. Returns `true` in case of success and `false` if the
+attribute is not found.
+
+## `reader:move_to_first_attribute()`
+Moves the position of `reader` to the first attribute of the current node.
+Returns `true` in case of success (the current node contains at least 1
+attribute) otherwise `false`.
+
+## `reader:move_to_next_attribute()`
+Moves the position of `reader` to the next attribute associated with the
+current node. Returns `true` if the position has been moved to the next
+attribute or `false` if there were no more attributes.
+
+## `reader:move_to_element()`
+Moves to the node that contains the current attribute node. Returns `true` in
+case of success or `false` if the position is unchanged (`reader` was not
+positioned on an attribute node).
+
+The following are extensions to the standard XmlReader API
+
+## `reader:line_number()`
+Returns the current line number, or `0` if not available.
+
+## `reader:column_name()`
+Returns the current column number, or `0` if not available.
+
+## `reader:next_node()`
+Slkip to the node following the current one in document order while avoiding
+the subtree if any. Returns `true` if the node was reader successfully or
+`false` if there are no more nodes to read.
+
+## `reader:is_valid()`
+Returns a boolean indicating the validity status as retrieved from teh parser
+context.
+
+## `reader:xml_version()`
+Returns the XML version of the document being read as a string.
+
+## `reader:is_standalone()`
+Returns a boolean indicating whether the document was declarated to be
+standalone.
+
+## `reader_bytes_consumed()`
+Returns the current index of the parser used by the reader relative to the
+start of the current entity.
+
+Valid parser options are:
+
+* `recover` recover on errors
+* `noent` substitute entities
+* `dtdload` load the external subset
+* `dtdattr` default DTD attributes
+* `dtdvalid` validate with the DTD
+* `noerror` supress error reports
+* `nowarning` supress warning reports
+* `pedantic` pedantic error reporting
+* `noblanks` remove blank nodes
+* `sax1` use the SAX1 interface internally
+* `xinclude` implement XInclude substitution
+* `nonet` forbid network access
+* `nodict` do no reuse the context dictionary
+* `nsclean` remove redundant namespaces declarations
+* `nocdata` merge CDATA as text nodes
+* `noexincnode` do not generate XInclude START/END nodes
+* `compact` compact small text nodes
+
+## `xmlreader.from_file(filename [, encoding] [, options...])`
+Parse an XML file from the filesystem or the given URL.
+
+## `xmlreader.from_string(str [, base_url] [, encoding] [, options...])`
+Creates an `xmlreader` object by parsing the given XML document.
1  TODO
View
@@ -0,0 +1 @@
+Raise a lua_error if the underlying library errors?
Please sign in to comment.
Something went wrong with that request. Please try again.