Documentation ¶
Overview ¶
Unmarshal dynamic / arbitrary XML docs and extract values (using wildcards, if necessary).
Copyright 2012-2013 Charles Banning. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file
Unmarshal dynamic / arbitrary XML docs and extract values (using wildcards, if necessary). One useful function is: - Unmarshal(doc []byte, v interface{}) error where v is a pointer to a variable of type 'map[string]interface{}', 'string', or any other type supported by xml.Unmarshal(). To retrieve a value for specific tag use: - DocValue(doc, path string, attrs ...string) (interface{},error) - MapValue(m map[string]interface{}, path string, attr map[string]interface{}, recast ...bool) (interface{}, error) The 'path' argument is a period-separated tag hierarchy - also known as dot-notation. It is the program's responsibility to cast the returned value to the proper type; possible types are the normal JSON unmarshaling types: string, float64, bool, []interface, map[string]interface{}. To retrieve all values associated with a tag occurring anywhere in the XML document use: - ValuesForTag(doc, tag string) ([]interface{}, error) - ValuesForKey(m map[string]interface{}, key string) []interface{} Demos: http://play.golang.org/p/m8zP-cpk0O http://play.golang.org/p/cIteTS1iSg http://play.golang.org/p/vd8pMiI21b Returned values should be one of map[string]interface, []interface{}, or string. All the values assocated with a tag-path that may include one or more wildcard characters - '*' - can also be retrieved using: - ValuesFromTagPath(doc, path string, getAttrs ...bool) ([]interface{}, error) - ValuesFromKeyPath(map[string]interface{}, path string, getAttrs ...bool) []interface{} Demos: http://play.golang.org/p/kUQnZ8VuhS http://play.golang.org/p/l1aMHYtz7G NOTE: care should be taken when using "*" at the end of a path - i.e., "books.book.*". See the x2jpath_test.go case on how the wildcard returns all key values and collapses list values; the same message structure can load a []interface{} or a map[string]interface{} (or an interface{}) value for a tag. See the test cases in "x2jpath_test.go" and programs in "example" subdirectory for more. XML PARSING CONVENTIONS - Attributes are parsed to map[string]interface{} values by prefixing a hyphen, '-', to the attribute label. - If the element is a simple element and has attributes, the element value is given the key '#text' for its map[string]interface{} representation. (See the 'atomFeedString.xml' test data, below.) io.Reader HANDLING ToTree(), ToMap(), ToJson(), and ToJsonIndent() provide parsing of messages from an io.Reader. If you want to handle a message stream, look at XmlMsgsFromReader(). NON-UTF8 CHARACTER SETS Use the X2jCharsetReader variable to assign io.Reader for alternative character sets.
Index ¶
- Variables
- func ByteDocToJson(doc []byte, recast ...bool) (string, error)
- func ByteDocToMap(doc []byte, recast ...bool) (map[string]interface{}, error)
- func DocToJson(doc string, recast ...bool) (string, error)
- func DocToJsonIndent(doc string, recast ...bool) (string, error)
- func DocToMap(doc string, recast ...bool) (map[string]interface{}, error)
- func DocValue(doc, path string, attrs ...string) (interface{}, error)
- func MapValue(m map[string]interface{}, path string, attr map[string]interface{}, r ...bool) (interface{}, error)
- func NewAttributeMap(kv ...string) (map[string]interface{}, error)
- func ReaderValuesForTag(rdr io.Reader, tag string) ([]interface{}, error)
- func ReaderValuesFromTagPath(rdr io.Reader, path string, getAttrs ...bool) ([]interface{}, error)
- func ToJson(rdr io.Reader, recast ...bool) (string, error)
- func ToJsonIndent(rdr io.Reader, recast ...bool) (string, error)
- func ToMap(rdr io.Reader, recast ...bool) (map[string]interface{}, error)
- func Unmarshal(doc []byte, v interface{}) error
- func ValuesForKey(m map[string]interface{}, key string) []interface{}
- func ValuesForTag(doc, tag string) ([]interface{}, error)
- func ValuesFromKeyPath(m map[string]interface{}, path string, getAttrs ...bool) []interface{}
- func ValuesFromTagPath(doc, path string, getAttrs ...bool) ([]interface{}, error)
- func WriteMap(m interface{}, offset ...int) string
- func XmlBufferToJson(b *bytes.Buffer, recast ...bool) (string, error)
- func XmlBufferToMap(b *bytes.Buffer, recast ...bool) (map[string]interface{}, error)
- func XmlMsgsFromFile(fname string, phandler func(map[string]interface{}) bool, ...) error
- func XmlMsgsFromFileAsJson(fname string, phandler func(string) bool, ehandler func(error) bool, ...) error
- func XmlMsgsFromReader(rdr io.Reader, phandler func(map[string]interface{}) bool, ...) error
- func XmlMsgsFromReaderAsJson(rdr io.Reader, phandler func(string) bool, ehandler func(error) bool, ...) error
- type Node
- type XmlBuffer
Constants ¶
This section is empty.
Variables ¶
If X2jCharsetReader != nil, it will be used to decode the doc or stream if required
import charset "code.google.com/p/go-charset/charset" ... x2j.X2jCharsetReader = charset.NewReader s, err := x2j.DocToJson(doc)
Functions ¶
func ByteDocToJson ¶
ByteDocToJson - return an XML doc as a JSON string.
If the optional argument 'recast' is 'true', then values will be converted to boolean or float64 if possible.
func ByteDocToMap ¶
ByteDocToMap - convert an XML doc into a map[string]interface{}. (This is analogous to unmarshalling a JSON string to map[string]interface{} using json.Unmarshal().)
If the optional argument 'recast' is 'true', then values will be converted to boolean or float64 if possible. Note: recasting is only applied to element values, not attribute values.
func DocToJson ¶
DocToJson - return an XML doc as a JSON string.
If the optional argument 'recast' is 'true', then values will be converted to boolean or float64 if possible.
func DocToJsonIndent ¶
DocToJsonIndent - return an XML doc as a prettified JSON string.
If the optional argument 'recast' is 'true', then values will be converted to boolean or float64 if possible. Note: recasting is only applied to element values, not attribute values.
func DocToMap ¶
DocToMap - convert an XML doc into a map[string]interface{}. (This is analogous to unmarshalling a JSON string to map[string]interface{} using json.Unmarshal().)
If the optional argument 'recast' is 'true', then values will be converted to boolean or float64 if possible. Note: recasting is only applied to element values, not attribute values.
func DocValue ¶
DocValue - return a value for a specific tag
'doc' is a valid XML message. 'path' is a hierarchy of XML tags, e.g., "doc.name". 'attrs' is an OPTIONAL list of "name:value" pairs for attributes. Note: 'recast' is not enabled here. Use DocToMap(), NewAttributeMap(), and MapValue() calls for that.
func MapValue ¶
func MapValue(m map[string]interface{}, path string, attr map[string]interface{}, r ...bool) (interface{}, error)
MapValue - retrieves value based on walking the map, 'm'.
'm' is the map value of interest. 'path' is a period-separated hierarchy of keys in the map. 'attr' is a map of attribute "name:value" pairs from NewAttributeMap(). May be 'nil'. If the path can't be traversed, an error is returned. Note: the optional argument 'r' can be used to coerce attribute values, 'attr', if done so for 'm'.
func NewAttributeMap ¶
NewAttributeMap() - generate map of attributes=value entries as map["-"+string]string.
'kv' arguments are "name:value" pairs that appear as attributes, name="value". If len(kv) == 0, the return is (nil, nil).
func ReaderValuesForTag ¶
ReaderValuesForTag - io.Reader version of ValuesForTag()
func ReaderValuesFromTagPath ¶
ReaderValuesFromTagPath - io.Reader version of ValuesFromTagPath()
func ToJsonIndent ¶
ToJsonIndent - the pretty form of ReaderToJson
func Unmarshal ¶
Unmarshal - wraps xml.Unmarshal with handling of map[string]interface{} and string type variables.
Usage: x2j.Unmarshal(doc,&m) where m of type map[string]interface{} x2j.Unmarshal(doc,&s) where s of type string (Overrides xml.Unmarshal().) x2j.Unmarshal(doc,&struct) - passed to xml.Unmarshal() x2j.Unmarshal(doc,&slice) - passed to xml.Unmarshal()
func ValuesForKey ¶
ValuesForKey - return all values in map associated with 'key'
Returns nil if the 'key' does not occur in the map
func ValuesForTag ¶
ValuesForTag - return all values in doc associated with 'tag'.
Returns nil if the 'tag' does not occur in the doc. If there is an error encounted while parsing doc, that is returned. If you want values 'recast' use DocToMap() and ValuesForKey().
func ValuesFromKeyPath ¶
ValuesFromKeyPath - deliver all values for a path node from a map[string]interface{} If there are no values for the path 'nil' is returned.
'm' is the map to be walked 'path' is a dot-separated path of key values 'getAttrs' can be set 'true' to return attribute values for "*"-terminated path If a node is '*', then everything beyond is walked. E.g., see ValuesFromTagPath documentation.
func ValuesFromTagPath ¶
ValuesFromTagPath - deliver all values for a path node from a XML doc If there are no values for the path 'nil' is returned. A return value of (nil, nil) means that there were no values and no errors parsing the doc.
'doc' is the XML document 'path' is a dot-separated path of tag nodes 'getAttrs' can be set 'true' to return attribute values for "*"-terminated path If a node is '*', then everything beyond is scanned for values. E.g., "doc.books' might return a single value 'book' of type []interface{}, but "doc.books.*" could return all the 'book' entries as []map[string]interface{}. "doc.books.*.author" might return all the 'author' tag values as []string - or "doc.books.*.author.lastname" might be required, depending on he schema.
func WriteMap ¶
WriteMap - dumps the map[string]interface{} for examination.
'offset' is initial indentation count; typically: WriteMap(m). NOTE: with XML all element types are 'string'. But code written as generic for use with maps[string]interface{} values from json.Unmarshal(). Or it can handle a DocToMap(doc,true) result where values have been recast'd.
func XmlBufferToJson ¶
XmlBufferToJson - process XML message from a bytes.Buffer
'b' is the buffer Optional argument 'recast' coerces values to float64 or bool where possible.
func XmlBufferToMap ¶
XmlBufferToMap - process XML message from a bytes.Buffer
'b' is the buffer Optional argument 'recast' coerces map values to float64 or bool where possible.
func XmlMsgsFromFile ¶
func XmlMsgsFromFile(fname string, phandler func(map[string]interface{}) bool, ehandler func(error) bool, recast ...bool) error
XmlMsgsFromFile()
'fname' is name of file 'phandler' is the map processing handler. Return of 'false' stops further processing. 'ehandler' is the parsing error handler. Return of 'false' stops further processing and returns error. Note: phandler() and ehandler() calls are blocking, so reading and processing of messages is serialized. This means that you can stop reading the file on error or after processing a particular message. To have reading and handling run concurrently, pass arguments to a go routine in handler and return true.
func XmlMsgsFromFileAsJson ¶
func XmlMsgsFromFileAsJson(fname string, phandler func(string) bool, ehandler func(error) bool, recast ...bool) error
XmlMsgsFromFileAsJson()
'fname' is name of file 'phandler' is the JSON string processing handler. Return of 'false' stops further processing. 'ehandler' is the parsing error handler. Return of 'false' stops further processing and returns error. Note: phandler() and ehandler() calls are blocking, so reading and processing of messages is serialized. This means that you can stop reading the file on error or after processing a particular message. To have reading and handling run concurrently, pass arguments to a go routine in handler and return true.
func XmlMsgsFromReader ¶
func XmlMsgsFromReader(rdr io.Reader, phandler func(map[string]interface{}) bool, ehandler func(error) bool, recast ...bool) error
XmlMsgsFromReader() - io.Reader version of XmlMsgsFromFile
'rdr' is an io.Reader for an XML message (stream) 'phandler' is the map processing handler. Return of 'false' stops further processing. 'ehandler' is the parsing error handler. Return of 'false' stops further processing and returns error. Note: phandler() and ehandler() calls are blocking, so reading and processing of messages is serialized. This means that you can stop reading the file on error or after processing a particular message. To have reading and handling run concurrently, pass arguments to a go routine in handler and return true.
func XmlMsgsFromReaderAsJson ¶
func XmlMsgsFromReaderAsJson(rdr io.Reader, phandler func(string) bool, ehandler func(error) bool, recast ...bool) error
XmlMsgsFromReaderAsJson() - io.Reader version of XmlMsgsFromFileAsJson
'rdr' is an io.Reader for an XML message (stream) 'phandler' is the JSON string processing handler. Return of 'false' stops further processing. 'ehandler' is the parsing error handler. Return of 'false' stops further processing and returns error. Note: phandler() and ehandler() calls are blocking, so reading and processing of messages is serialized. This means that you can stop reading the file on error or after processing a particular message. To have reading and handling run concurrently, pass arguments to a go routine in handler and return true.
Types ¶
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
func ByteDocToTree ¶
ByteDocToTree - convert an XML doc into a tree of nodes.
func XmlBufferToTree ¶
BufferToTree - derived from DocToTree()
type XmlBuffer ¶
type XmlBuffer struct {
// contains filtered or unexported fields
}
XmlBuffer - create XML decoder buffer for a string from anywhere, not necessarily a file.
func BytesNewXmlBuffer ¶
BytesNewXmlBuffer() - creates a bytes.Buffer from b with possibly multiple messages
Use Close() function to release the buffer for garbage collection.
func NewXmlBuffer ¶
NewXmlBuffer() - creates a bytes.Buffer from a string with multiple messages
Use Close() function to release the buffer for garbage collection.