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.

cpanm PRANG

perl -MCPAN -e shell
install PRANG