Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::Compile::TranslatUser Contributed Perl DocumentXML::Compile::Translate(3)

NAME
       XML::Compile::Translate - create	an XML data parser

INHERITANCE
	XML::Compile::Translate	is extended by
	  XML::Compile::Translate::Reader
	  XML::Compile::Translate::Template
	  XML::Compile::Translate::Writer

SYNOPSIS
	# for internal use only
	my $code = XML::Compile::Translate->compile(...);

DESCRIPTION
       This module converts a schema type definition into a code reference
       which can be used to interpret a	schema.	 The sole public function in
       this package is compile(), and is called	by
       XML::Compile::Schema::compile(),	which does a lot of set-ups.  Please
       do not try to use this package directly!

       The code	in this	package	interprets schemas; it understands, for
       instance, how complexType definitions work.  Then, when the schema
       syntax is decoded, it will knot the pieces together into	one CODE
       reference which can be used in the main user program.

   Unsupported features
       This implementation is work in progress,	but by far most	structures in
       W3C schemas are implemented (and	tested!).

       Missing are
	schema noNamespaceSchemaLocation
	any ##local
	anyAttribute ##local

       Some things do not work in schemas anyway: "import", "include".	They
       only work if everyone always has	a working connection to	internet.  You
       have to require them manually.  Include also does work, because it does
       not use namespaces.  (see XML::Compile::Schema::importDefinitions())

       Ignored,	because	not for	our purpose is the search optimization
       information: "key, unique, keyref, selector, field", and	de schema
       documentation: "notation, annotation".  Compile the schema schema
       itself to interpret the message if you need them.

       A few nuts are still to crack:
	openContent
	facets on dates	and base64Binary
	final is not protected

       Of course, the latter list is all fixed in next release ;-) See chapter
       "DETAILS" for more on how the tune the translator.

METHODS
   Constructors
       $obj->new($translator, %options)
	   The %options	are described in XML::Compile::Schema::compile().
	   Those descriptions will probably move here, eventually.

	    -Option--Default
	     nss     <required>

	   nss => XML::Compile::Schema::NameSpaces
       $obj->register($name)
       XML::Compile::Translate->register($name)
	   Register a new back-end.

	   example:

	    use	XML::Compile::Translate::SomeBackend;
	    XML::Compile::Translate::SomeBackend->register('SomeNAME');
	    my $coderef	= $schemas->compile('SomeNAME' => ...);

   Attributes
   Handlers
       XML::Compile::Translate->compile($element|$attribute|$type, %options)
	   Do not call this function yourself, but use
	   XML::Compile::Schema::compile() (or wrappers	around that).

	   This	function returns a CODE	reference, which can translate between
	   Perl	datastructures and XML,	based on a schema.  Before this	method
	   is called is	the schema already translated into a table of types.

DETAILS
   Translator options
       performance optimization

       The XML::Compile::Schema::compile() method (and wrappers) defines a set
       options to improve performance or usability.  These options are
       translated into the executed code: compile time,	not run-time!

       The following options with their	implications:

       sloppy_integers BOOLEAN
	   The "integer" type, as defined by the schema	built-in
	   specification, accepts really huge values.  Also the	derived	types,
	   like	"nonNegativeInteger" can contain much larger values than
	   Perl's internal "long".  Therefore, the module will start to	use
	   Math::BigInt	for these types	if needed.

	   However, in most cases, people design "integer" where an "int"
	   suffices.  The use of big-int values	comes with heigh performance
	   costs.  Set this option to "true" when you are sure that ALL	USES
	   of "integer"	in the scheme will fit into signed longs (are between
	   -2147483648 and 2147483647 inclusive)

	   If you do not want limit the	number-space, you can safely add
	     use Math::BigInt try => 'GMP' to the top of your main program,
	   and install Math::BigInt::GMP.  Then, a C library will do the work,
	   much	faster than the	Perl implementation.

       sloppy_floats BOOLEAN
	   The float types of XML are all quite	big, and may be	NaN, INF, and
	   -INF.  Perl's normal	floats do not, and therefore Math::BigFloat is
	   used.  This,	however, is slow.

	   When	this option is true, your application will crash on any	value
	   which is not	understood by Perl's internal float implementation...
	   but run much	faster.

       check_values BOOLEAN
	   Check the validity of the values, before parsing them.  This	will
	   report errors for the reader, instead of crashes.  The writer will
	   not produce invalid data.

       check_occurs BOOLEAN
	   Checking whether the	number of occurrences for an item are between
	   "minOccurs" and "maxOccurs" (implied	for "all", "sequence", and
	   "choice" or explicitly specified) takes time.  Of course, in	cases
	   errors must be handled.  When this option is	set to "false",	only
	   distinction between single and array	elements is made.

       ignore_facets BOOLEAN
	   Facets limit	field content in the restriction block of a
	   simpleType.	When this option is "true", no checks are performed on
	   the values.	In some	cases, this may	cause problems:	especially
	   with	whiteSpace and digits of floats.  However, you may be able to
	   control this	yourself.  In most cases, luck even plays a part in
	   this.  Less checks means a better performance.

	   Simple type restrictions are	not implemented	by other XML perl
	   modules.  When the schema is	nicely detailed, this will give	extra
	   security.

       validation BOOLEAN
	   When	used, it overrules the above "check_values", "check_occurs",
	   and "ignore_facets" options.	 A true	value enables all checks, a
	   false value will disable them all.  Of course, the latter is	the
	   fastest but also less secure: your program will need	to validate
	   the values in some other way.

	   XML::LibXML has its own validate method, but	I have not yet seen
	   any performance figures on that.  If	you use	it, however, it	is of
	   course a good idea to turn XML::Compile's validation	off.

       qualified XML

       The produced XML	may not	use the	name-spaces as defined by the schemas,
       just to simplify	the input and output.  The structural definition of
       the schemas is still in-tact, but name-space collission may appear.

       Per schema, it can be specified whether the elements and	attributes
       defined in-there	need to	be used	qualified (with	prefix)	or not.	 This
       can cause horrible output when within an	unqualified schema elements
       are used	from another schema which is qualified.

       The suggested solution in articles about	the subject is to provide
       people with both	a schema which is qualified as one which is not.  Perl
       is known	to be blunt in its approach: we	simply define a	flag which can
       force one of both on all	schemas	together, using	"elements_qualified"
       and "attributes_qualified".  May	people and applications	do not
       understand name-spaces sufficiently, and	these options may make your
       day!

       Name-spaces

       The translator does respect name-spaces,	but not	all senders and
       receivers of XML	are name-space capable.	 Therefore, you	have some
       options to interfere.

       prefixes	HASH|ARRAY-of-PAIRS
	   The translator will create XML elements (WRITER) which use name-
	   spaces, based on its	own name-space/prefix mapping administration.
	   This	is needed because the XML tree is created bottom-up, where
	   XML::LibXML namespace management can	only handle this top-down.

	   When	your pass your own HASH	as argument, you can explicitly
	   specify the prefixes	you like to be used for	which name-space.
	   Found name-spaces will be added to the HASH,	as well	the use	count.
	   When	a new name-space URI is	discovered, an attempt is made to use
	   the prefix as found in the schema. Prefix collisions	are actively
	   avoided: when two URIs want the same	prefix,	a sequence number is
	   added to one	of them	which makes it unique.

	   The HASH structure looks like this:

	     my	%namespaces =
	       ( myns => { uri => 'myns', prefix => 'mypref', used => 1}
	       , ...  => { uri => ... }
	       );

	     my	$make =	$schema->compile
	       ( WRITER	=> ...
	       , prefixes => \%namespaces
	       );

	     # share the same namespace	defs with another component
	     my	$other = $schema->compile
	       ( WRITER	=> ...
	       , prefixes => \%namespaces
	       );

	   When	used is	specified and larger than 0, then the namespace	will
	   appear in the top-level output element (unless "include_namespaces"
	   is false).

	   Initializing	using an ARRAY is a little simpler:

	    prefixes =>	[ mypref => 'myns', ...	=> ... ];

	   However, be warned that this	does not work well with	a false	value
	   for "include_namespaces": detected namespaces are added to an
	   internal HASH now, which is not returned; that information is lost.
	   You will need to know each used namespace beforehand.

       include_namespaces BOOLEAN|CODE
	   When	true and WRITER, the top level returned	XML element will
	   contain the prefix definitions.  Only name-spaces which are
	   actually used will be included (a count is kept by the translator).
	   It may very well list name-spaces which are not in the actual
	   output because the fields which require them	are not	included for
	   there is not	value for those	fields.

	   If you like to combine XML output from separate translated parts
	   (for	instance in case of generating SOAP), you may want to delay
	   the inclusion of name-spaces	until a	higher level of	the XML
	   hierarchy which is produced later.

	   When	a CODE reference is passed, it will be called for each used
	   namespace, with the uri and prefix as parameters.  Only when	the
	   CODE	returns	true, the namespace declaration	will be	included.

	   When	the compilation	produces an attribute, then this option	cannot
	   be used.

       namespace_reset BOOLEAN
	   You can pass	the same HASH to a next	call to	a reader or writer to
	   get consistent name-space usage.  However, when
	   "include_namespaces"	is used, you may get ghost name-space
	   listings.  This option will reset the counts	on all defined name-
	   spaces.

       use_default_namespace BOOLEAN (added in release 0.57)
	   When	a true value, the blank	prefix will be used for	the first
	   namespace URI which requires	a auto-generated prefix.  However, in
	   quite some environments, people mix horrible	non-namespace
	   qualified elements with nice	namespace qualified elements.  In such
	   situations, namespace the qualified-but-default prefix (i.e., no
	   prefix) is confusing.  Therefore, the option	defaults to false: do
	   not use the invisible prefix.

	   You may explicitly specify a	blank prefix with "prefixes", which
	   will	be used	when applicable.

       block_namespace NAMESPACE|TYPE|HASH|CODE|ARRAY
	   [1.06] Available on global scale via
	   XML::Compile::Schema::new(block_namespace) or
	   XML::Compile::Schema::blockNamespace(), and for a single compiled
	   instance via	XML::Compile::Schema::compile(block_namespace).

	   Some	schemas	include	other schemas which you	do not need.  For
	   instance, the other schema is only used in rare cases, or the other
	   schema defines deprecated types and elements.  Of course, you can
	   simply not load those schemas... however: the main schema may refer
	   to those types and elements you do not need.	 So, with this option,
	   you can make	the compilation	to ignore whole	namespaces and
	   specific elements or	types.

	   The NAMESPACE is a uri, which will disable use of any element or
	   type	defined	in that	space.	You may	also provide a specific	full
	   $type (toplevel element or type name).  You may also	give an	LIST
	   or ARRAY of these, but then a HASH is much more suitable: with
	   linear lookup time.

	   When	you provide a CODE reference, it will be called	for each type
	   and element to be judged.  Passed are $type,	$ns, $local, and
	   $path.  The "$ns/$local" is the decomposition of $type.  When the
	   CODE	returns	"undef", then it is undecisive,	letting	other rules
	   decide.  When it returns 0, then the	thing will not be blocked
	   (whatever the other rules decide).  In other	cases, the thing will
	   not be used.

	     # block a whole namespace
	     $schema->blockNamespace("http://xyz.example.com");

	     # block only a single element or typedef
	     $schema->blockNamespace("{http://xyz.example.com}buggy");

	     # block $ns1 and $type1, unblock $ns2
	     $schema->blockNamespace( {$ns1 => 1, $ns2 => 0, $type1 => 1} );

	     $schema->blockNamespace($ns1, $type1);
	     $schema->compile(..., block_namespace => [$ns1, $type1]);
	     $schema->new(..., block_namespace => [$ns1, $type1]);

	     # very flexible
	     sub want_block($$$$) ( my ($type,$ns,$local,$path)	= @_; undef}
	     $schema->blockNamespace(\&want_block);

	   It is very well possible that the blocking of some namespaces
	   breaks the validness	of messages: when those	elements are required
	   but set to be ignored.  There is no way to detect this, on the
	   moment.

       Wildcards handlers

       Wildcards are a serious complication: the "any" and "anyAttribute"
       entities	do not describe	exactly	what can be found, which seriously
       hinders the quality of validation and the preparation of	XML::Compile.
       Therefore, if you use them then you need	to process that	parts of XML
       yourself.  See the various backends on how to create or process these
       elements.

       Automatic decoding is problematic: you do not know what to expect, so
       cannot prepare for these	data-structures	compile-time.  However,
       XML::Compile::Cache offers a way	out: you can declare the handlers for
       these "any" components and therewith be prepared	for them.  With
       "XML::Compile::Cache::new(allow_undeclared)", you can permit run-time
       compilation of  the found components.

       any_element CODE|'TAKE_ALL'|'SKIP_ALL'
	   [0.89] This will be called when the type definition contains	an
	   "any" definition, after processing the other	element	components.
	   By default, all "any" specifications	will be	ignored.

       any_attribute CODE|'TAKE_ALL'|'SKIP_ALL'
	   [0.89] This will be called when the type definitions	contains an
	   "anyAttribute" definition, after processing the other attributes.
	   By default, all "anyAttribute" specifications will be ignored.

       any_type	CODE
	   [1.07] Called for processing	an "xsd:anyType" element.  Currently
	   only	supported for the reader.  By default, it returns a string
	   when	the element does not contains sub-elements, otherwise the XML
	   node.

SEE ALSO
       This module is part of XML-Compile distribution version 1.58, built on
       June 27,	2017. Website: http://perl.overmeer.net/xml-compile/

       Please post questions or	ideas to the mailinglist at
       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile .	For
       live contact with other developers, visit the "#xml-compile" channel on
       "irc.perl.org".

LICENSE
       Copyrights 2006-2017 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the Artistic license.  See
       http://dev.perl.org/licenses/artistic.html

perl v5.24.1			  2017-06-27	    XML::Compile::Translate(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Compile::Translate&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help