NAME
PRANG::Graph::Context - parse/emit state for Marshalling operations
SYNOPSIS
my $context = PRANG::Graph::Context->new(
base => PRANG::Marshaller->get($class),
xpath => "/nodename",
);DESCRIPTION
This is a data class, it basically is like a loop counter for parsing (or emitting). Except instead of walking over a list, it 'walks' over a tree of a certain, bound shape.
The shape of the XML Graph at each node is limited to:
Seq -> Quant -> Choice -> Element -> ( Text | Null )(any of the above may be absent)
There are assumptions that nodes only connect as above, and not just in this class.
These state in this object allows the code to remember where it is. A new instance is created for each node which may have children for the parsing efforts for that node.
ATTRIBUTES
- seq_pos
- quant_found
- chosen
- element_ok
-
The above four properties are state information for any PRANG::Graph::Seq, PRANG::Graph::Quant, PRANG::Graph::Choice or PRANG::Graph::Element objects which exist in the graph for a given class. As the nodes always connect in a particular order, setting one value will clear all of the values for the settings which follow.
- xpath
-
The XML location of the current node. Used for helpful error messages.
- xsi
- rxsi
-
These attributes contain mappings from XML prefixes to namespace URIs and vice versa. They should not be modified, as they are copy-on-write from the parent Context objects.
- old_xsi
-
The xsi attribute from the parent object. Used for
prefix_new - xsi_virgin
-
Unset the first time a prefix is defined.
METHODS
This API is probably subject to quite some change. It is mainly provided for assisting understanding with internal code.
$ctx->exception("message", $node?, $skip_ok?)
Raise a context-sensitive exception via die. The XPath that the current node was constructed with is appended with the nodename of the passed node to provide an XML path for the error.
Where parsing or emitting errors happen with one of these objects around, it should always be used for reporting the error. The error is a structured object (of type PRANG::Graph::Context::Error) which knows how to stringify into a readable error message.
next_ctx( Maybe[Str] $xmlns, Str $newnode_name, $thing? ) returns PRANG::Graph::Context
This returns a new PRANG::Graph::Context object, for the next level of parsing.
get_xmlns( Str $prefix ) returns Str
Returns the XML namespace associated with the passed prefix.
get_prefix( Str $xmlns, Object $thing?, XML::LibXML::Element $victim? ) returns Str
Used for emitting. This is an alternative to reading the rxsi hash attribute directly. It returns the prefix for the given namespace URI ($xmlns), and if it is not already defined it will figure out based on the type of $thing what prefix to use, and add XML namespace nodes to the $victim XML namespace node. If the $thing does not specify a default XML namespace prefix, then one is chosen for it.
add_xmlns( Str $prefix, Str $xmlns )
Used for parsing. This associates the given prefix with the given XML namespace URI.
prefix_new( Str $prefix )
This tells you whether or not the passed prefix was declared with this Context or not. Used for emitting.
SEE ALSO
PRANG::Graph::Meta::Class, PRANG::Graph::Meta::Attr, PRANG::Graph::Meta::Element, PRANG::Marshaller,
Implementations:
PRANG::Graph::Seq, PRANG::Graph::Quant, PRANG::Graph::Choice, PRANG::Graph::Element, PRANG::Graph::Text
AUTHOR AND LICENCE
Development commissioned by NZ Registry Services, and carried out by Catalyst IT - http://www.catalyst.net.nz/
Copyright 2009, 2010, NZ Registry Services. This module is licensed under the Artistic License v2.0, which permits relicensing under other Free Software licenses.