readme, export simplevalue and is_simple

Author: joshday

README.md

@@ -4,34 +4,28 @@
 
 <br><br>
 
-## Introduction
+# Introduction
 
 This package offers fast data structures for reading and writing XML files with a consistent interface:
 
-#### `Node`/`LazyNode` Interface:
+### `Node`/`LazyNode` Interface:
 
-- `nodetype(node)   →   XML.NodeType` (an enum with one of the following values):
-    - `Document`: `children...`
-    - `DTD`: `<!DOCTYPE ...>`
-    - `Declaration`: `<?xml attributes... ?>`
-    - `ProcessingInstruction`: `<?NAME attributes... ?>`
-    - `Comment`: `<!-- ... -->`
-    - `CData`: `<![CData[...]]>`
-    - `Element`: `<NAME attributes... > children... </NAME>`
-    - `Text`: `text`
-- `tag(node)        →   String or Nothing`
-- `attributes(node) →   Dict{String,String} or Nothing`
-- `value(node)      →   String or Nothing`
-- `children(node)   →   Vector{typeof(node)}`
+- `nodetype(node)   →   XML.NodeType` (an enum type):
+- `tag(node)          →   String or Nothing`
+- `attributes(node)   →   Dict{String,String} or Nothing`
+- `value(node)        →   String or Nothing`
+- `children(node)     →   Vector{typeof(node)}`
+- `is_simple(node)    →   Bool (whether node is simple .e.g. <tag>item</tag>)`
+- `simplevalue(node)  →   Return the `value` of the only child (e.g. "item" from <tag>item</tag>)`
 
-#### Extended Interface for `LazyNode`
+### Extended Interface for `LazyNode`
 
 - `depth(node)      →   Int`
 - `next(node)       →   typeof(node)`
 - `prev(node)       →   typeof(node)`
 - `parent(node)     →   typeof(node)`
 
-## Quickstart
+# Quickstart
 
 ```julia
 using XML
@@ -52,41 +46,47 @@ doc[end][2]  # Second child of root
 # Node Element <book id="bk102"> (6 children)
 ```
 
-## Node Types
+# Data Structures that Represent XML Nodes
 
-### `XML.Node`
+## Preliminary: `NodeType`
 
-- An eager data structure that loads the entire XML DOM in memory.
+- Each item in an XML DOM is classified by its `NodeType`.
+- Every `XML.jl` struct defines a `nodetype(x)` method that returns its `NodeType`.
+
+| NodeType | XML Representation | `Node` Constructor |
+|----------|--------------------|------------------|
+| `Document` | An entire document | `Document(children...)`
+| `DTD` | `<!DOCTYPE ...>` | `DTD(...) `
+| `Declaration` | `<?xml attributes... ?>` | `Declaration(; attrs...)`
+| `ProcessingInstruction` | `<?tag attributes... ?>` | `ProcessingInstruction(tag; attrs...)`
+| `Comment` | `<!-- text -->` | `Comment(text)`
+| `CData` | `<![CData[text]]>` | `CData(text)`
+| `Element` | `<tag attributes... > children... </NAME>` | `Element(tag, children...; attrs...)`
+| `Text` | the `text` part of `<tag>text</tag>` | `Text(text)`
+
+
+## `Node`: Probably What You're Looking For
+
+- `read`-ing a `Node` loads the entire XML DOM in memory.
 - **This is what you would use to build an XML document programmatically.**
+- See the table above for convenience constructors.
 - `Node`s have some additional methods that aid in construction/mutation:
 
 ```julia
 # Add a child:
 push!(parent::Node, child::Node)
 
-
 # Replace a child:
 parent[2] = child
 
-
 # Add/change an attribute:
 node["key"] = value
-```
-
-- **XML** defines `(::NodeType)(args...; kw...)` for more convenient syntax in creating `Node`s, e.g.:
 
-```julia
-CData(value)
-Comment(value)
-Declaration(; attributes...)
-Document(children...)
-DTD(; attributes...)
-Element(tag, children...; attributes...)
-ProcessingInstruction(tag; attributes...)
-Text(value)
+node["key"]
 ```
 
-### `XML.LazyNode`
+
+## `XML.LazyNode`: For Fast Iteration through an XML File
 
 A lazy data structure that just keeps track of the position in the raw data (`Vector{UInt8}`) to read from.
 
@@ -134,6 +134,7 @@ XML.write(node)  # String
 
 ## Performance
 
+- XML.jl performs comparatively to [EzXML.jl](https://github.com/JuliaIO/EzXML.jl), which wraps the C library [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home).
 - See the `benchmarks/suite.jl` for the code to produce these results.
 - The following output was generated in a Julia session with the following `versioninfo`:
 

src/XML.jl

@@ -6,7 +6,7 @@ export
     # Core Types:
     Node, LazyNode,
     # Interface:
-    children, nodetype, tag, attributes, value,
+    children, nodetype, tag, attributes, value, is_simple, simplevalue,
     # Extended Interface for LazyNode:
     parent, depth, next, prev