Rename README to README.md and fix contents.

This commit is contained in:
jim teeuwen 2012-03-20 02:27:54 +01:00
parent 032fe9d27c
commit 45769307c0
3 changed files with 90 additions and 89 deletions

89
README
View File

@ -1,89 +0,0 @@
Author: Jim Teeuwen <jimteeuwen at gmail.com>
This package wraps the standard XML library and uses it to build a node tree of
any document you load. This allows you to look up nodes forwards and backwards,
as well as perform search queries (no xpath support).
Nodes now simply become collections and don't require you to read them in the
order in which the xml.Parser finds them.
================================================================================
DEPENDENCIES
================================================================================
none
================================================================================
API
================================================================================
The Document currently implements 2 simple search functions which allow you to
look for specific nodes.
*document.SelectNode(namespace, name string) *Node;
*document.SelectNodes(namespace, name string) []*Node;
SelectNode() returns the first, single node it finds matching the given name
and namespace. SelectNodes() returns a slice containing all the matching nodes.
Note that these search functions can be invoked on individual nodes as well.
This allows you to search only a subset of the entire document.
Each node exposes also a number of functions which allow easy access to a node
value or an attribute value. They come in various forms to allow transparent
conversion to types: int, int64, uint, uint64, float, float32, float64:
*node.S(ns, name string) string
*node.I(ns, name string) int
*node.I64(ns, name string) int64
*node.U(ns, name string) uint
*node.U64(ns, name string) uint64
*node.F(ns, name string) float
*node.F32(ns, name string) float32
*node.F64(ns, name string) float64
*node.B(namespace, name string) bool
Note that these functions actually consider child nodes for matching names as
well as the current node. In effect they first perform a node.SelectNode() and
then return the value of the resulting node converted to the appropriate type.
This allows you to do this:
Consider this piece of xml:
<car>
<color>red</color>
<brand>BMW</brand>
</car>
Now this code:
node := doc.SelectNode("", "car")
brand := node.S("", "brand")
Eventhough 'brand' is not the name of @node, we still get the right value
back (BMW), because node.S() searches through the child nodes when looking
for the value if the current node does not match the given namespace and
name.
For attributes, we only go through the attributes of the current node this
function is invoked on:
*node.As(ns, name string) string
*node.Ai(ns, name string) int
*node.Ai64(ns, name string) int64
*node.Au(ns, name string) uint
*node.Au64(ns, name string) uint64
*node.Af(ns, name string) float
*node.Af32(ns, name string) float32
*node.Af64(ns, name string) float64
*node.Ab(namespace, name string) bool
All of these functions return either "" or 0 when the specified node or
attribute could not be found. No errors are generated.
The namespace name specified in the functions above must either match the
namespace you expect a node/attr to have, or you can specify a wildcard "*".
This makes node searches easier in case you do not care what namespace name
there is or if there is one at all. Node and attribute names as well, may
be supplied as the wildcard "*". This allows us to fetch all child nodes for
a given namespace, regardless of their names.

89
README.md Normal file
View File

@ -0,0 +1,89 @@
## XMLX
This package wraps the standard XML library and uses it to build a node tree of
any document you load. This allows you to look up nodes forwards and backwards,
as well as perform search queries (no xpath support).
Nodes now simply become collections and don't require you to read them in the
order in which the xml.Parser finds them.
### Dependencies
None.
### API
The Document currently implements 2 simple search functions which allow you to
look for specific nodes.
*document.SelectNode(namespace, name string) *Node;
*document.SelectNodes(namespace, name string) []*Node;
`SelectNode()` returns the first, single node it finds matching the given name
and namespace. `SelectNodes()` returns a slice containing all the matching nodes.
Note that these search functions can be invoked on individual nodes as well.
This allows you to search only a subset of the entire document.
Each node exposes also a number of functions which allow easy access to a node
value or an attribute value. They come in various forms to allow transparent
conversion to types: int, int64, uint, uint64, float32, float64:
*node.S(ns, name string) string
*node.I(ns, name string) int
*node.I64(ns, name string) int64
*node.U(ns, name string) uint
*node.U64(ns, name string) uint64
*node.F32(ns, name string) float32
*node.F64(ns, name string) float64
*node.B(namespace, name string) bool
Note that these functions actually consider child nodes for matching names as
well as the current node. In effect they first perform a node.SelectNode() and
then return the value of the resulting node converted to the appropriate type.
This allows you to do this:
Consider this piece of xml:
<car>
<color>red</color>
<brand>BMW</brand>
</car>
Now this code:
node := doc.SelectNode("", "car")
brand := node.S("", "brand")
Eventhough `brand` is not the name of `node`, we still get the right value
back (BMW), because `node.S()` searches through the child nodes when looking
for the value if the current node does not match the given namespace and
name.
For attributes, we only go through the attributes of the current node this
function is invoked on:
*node.As(ns, name string) string
*node.Ai(ns, name string) int
*node.Ai64(ns, name string) int64
*node.Au(ns, name string) uint
*node.Au64(ns, name string) uint64
*node.Af32(ns, name string) float32
*node.Af64(ns, name string) float64
*node.Ab(namespace, name string) bool
All of these functions return either "" or 0 when the specified node or
attribute could not be found. No errors are generated.
The namespace name specified in the functions above must either match the
namespace you expect a node/attr to have, or you can specify a wildcard "*".
This makes node searches easier in case you do not care what namespace name
there is or if there is one at all. Node and attribute names as well, may
be supplied as the wildcard "*". This allows us to fetch all child nodes for
a given namespace, regardless of their names.
### License
This work is subject to the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
license. Its contents can be found in the LICENSE file.

1
test1.xml Normal file
View File

@ -0,0 +1 @@
<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="0.91"><channel><title>WriteTheWeb</title><link>http://writetheweb.com</link><description>News for web users that write back</description><language>en-us</language><copyright>Copyright 2000, WriteTheWeb team.</copyright><managingEditor>editor@writetheweb.com</managingEditor><webMaster>webmaster@writetheweb.com</webMaster><image><title>WriteTheWeb</title><url>http://writetheweb.com/images/mynetscape88.gif</url><link>http://writetheweb.com</link><width>88</width><height>31</height><description>News for web users that write back</description></image><item><title>Giving the world a pluggable Gnutella</title><link>http://writetheweb.com/read.php?item=24</link><description>WorldOS is a framework on which to build programs that work like Freenet or Gnutella -allowing distributed applications using peer-to-peer routing.</description></item><item><title>Syndication discussions hot up</title><link>http://writetheweb.com/read.php?item=23</link><description>After a period of dormancy, the Syndication mailing list has become active again, with contributions from leaders in traditional media and Web syndication.</description></item><item><title>Personal web server integrates file sharing and messaging</title><link>http://writetheweb.com/read.php?item=22</link><description>The Magi Project is an innovative project to create a combined personal web server and messaging system that enables the sharing and synchronization of information across desktop, laptop and palmtop devices.</description></item><item><title>Syndication and Metadata</title><link>http://writetheweb.com/read.php?item=21</link><description>RSS is probably the best known metadata format around. RDF is probably one of the least understood. In this essay, published on my O'Reilly Network weblog, I argue that the next generation of RSS should be based on RDF.</description></item><item><title>UK bloggers get organised</title><link>http://writetheweb.com/read.php?item=20</link><description>Looks like the weblogs scene is gathering pace beyond the shores of the US. There's now a UK-specific page on weblogs.com, and a mailing list at egroups.</description></item><item><title>Yournamehere.com more important than anything</title><link>http://writetheweb.com/read.php?item=19</link><description>Whatever you're publishing on the web, your site name is the most valuable asset you have, according to Carl Steadman.</description></item></channel></rss>