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

FreeBSD Manual Pages

  
 
  

home | help
XML::Pastor::GeneratorUser Contributed Perl DocumentaXML::Pastor::Generator(3)

NAME
       XML::Pastor::Generator -	Module used internally by XML::Pastor for
       generating Perl code from a schema model.

WARNING
       This module is used internally by XML::Pastor. You do not normally know
       much about this module to actually use XML::Pastor.  It is documented
       here for	completeness and for XML::Pastor developers. Do	not count on
       the interface of	this module. It	may change in any of the subsequent
       releases. You have been warned.

ISA
       This class descends from	Class::Accessor.

SYNOPSIS
	 my $parser = XML::Pastor::Schema::Parser->new();

	 my $model = $parser->parse(schema => '/tmp/schema.xsd');

	 my $generator = XML::Pastor::Generator->new();

	 $generator->generate (
			       model =>	$model,
			       mode => 'offline',
			       style =>	'multiple'
			       );

DESCRIPTION
       XML::Pastor::Generator is used internally by XML::Pastor	for generating
       Perl code from a	schema model (XML::Pastor::Schema::Model) that was
       produced	by XML::Pastor::Schema::Parser and properly resolved prior to
       code generation.

       In 'offline'  mode, it is possible to generate a	single module with all
       the generated clasess or	multiple modules one for each class. The
       typical use of the offline mode is during a 'make' process, where you
       have a set of XSD schemas and you generate your modules to be later
       installed by the	'make install'.	This is	very similar to	Java Castor's
       behaviour.  This	way your XSD schemas don't have	to be accessible
       during run-time and you don't have a performance	penalty.

       Perl philosophy dictates	however, that There Is More Than One Way To Do
       It. In 'eval' (run-time)	mode, the XSD schema is	processed at run-time
       giving much more	flexibility to the user. This added flexibility	has a
       price on	the other hand,	namely a performance penalty and the fact that
       the XSD schema needs to be accessible at	run-time. Note that the
       performance penalty applies only	to the code genereration (pastorize)
       phase; the generated classes perform the	same as	if they	were generated
       offline.

METHODS
   CONSTRUCTORS
       new()

	 XML::Pastor::Generator->new(%fields)

       CONSTRUCTOR.

       The new() constructor method instantiates a new XML::Pastor::Genertor
       object. It is inheritable.

       Any -named- fields that are passed as parameters	are initialized	to
       those values within the newly created object.

       .

   OTHER METHODS
       generate()

	       $generator->generate(%options);

       This is the heart of the	module.	This method will generate Perl code
       (either in a single module or multiple modules) and either write	the
       code to module file(s) on disk or evaluate the generated	code according
       to the parameters passed.

       The Perl	code will be generated from the	model
       (XML::Pastor::Schema::Model) that is passed as an argument. All the
       type and	element	definitions found in the model will have a
       corresponding generated Perl class.

       In "offline" mode, the generated	classes	will either all	be put in one
       "single"	big code block,	or in "multiple" module	files (one for each
       class) depending	on the "style" parameter. Again	in "offline" mode, the
       generated modules will be written to disk under the directory prefix
       given by	the "destination" parameter.

       OPTIONS

       This method expects the following parameters:

       model
	   This	is an object of	type XML::Pastor::Schema::Model	that
	   corresponds to the internal representation (info set) of the	parsed
	   schemas. The	model must have	been previously	resolved (see
	   "resolve()" in XML::Pastor::Schema::Model) before being passed to
	   this	method.

       mode
	   This	parameter effects what actuallly will be done by the method.
	   Either offline code generation, or run-time code evaluation,	or
	   just	returning the generated	code.

	   offline
	       Default.

	       In this mode, the code generation is done 'offline', that is,
	       similar to Java's Castor	way of doing things, the generated
	       code will be written to disk on module files under the path
	       given by	the "destination" parameter.

	       In 'offline'  mode, it is possible to generate a	single module
	       with all	the generated clasess or multiple modules one for each
	       class, depending	on the value of	the "style" parameter.

	       The typical use of the offline mode is during a 'make' process,
	       where you have a	set of XSD schemas and you generate your
	       modules to be later installed by	'make install'.	This is	very
	       similar to Java Castor's	behaviour.  This way your XSD schemas
	       don't have to be	accessible during run-time and you don't have
	       a performance penalty.

		 # Generate MULTIPLE modules, one module for each class, and put them under destination.
		 my $generator = XML::Pastor::Generator->new();
		 $generator->generate(
				       mode =>'offline',
				       style =>	'multiple',
				       model=>$model,
				       destination=>'/tmp/lib/perl/',
				       );

	   eval
	       In 'eval' (run-time) mode, the XSD schema is processed at run-
	       time giving much	more flexibility to the	user. In this mode, no
	       code will be written to disk. Instead, the generated code
	       (which is necessarily a "single"	block) will be evaluated
	       before returning	to the caller.

	       The added flexibility has a price on the	other hand, namely a
	       performance penalty and the fact	that the XSD schema needs to
	       be accessible at	run-time. Note that the	performance penalty
	       applies only to the code	genereration (pastorize) phase;	the
	       generated classes perform the same as if	they were generated
	       offline.

	       Note that 'eval'	mode forces the	"style"	parameter to have a
	       value of	'single';

		 # Generate classes in MEMORY, and EVALUATE the	generated code on the fly.
		 my $generator = XML::Pastor::Generator->new();
		 $pastor->generate(
			       mode =>'eval',
				       model=>$model,
				       );

	   return
	       In 'return'  mode, the XSD schema is processed but no code is
	       written to disk or evaluated. In	this mode, the method just
	       returns the generated block of code as a	string,	so that	you
	       may use it to your liking. You would typically be evaluating it
	       though.

	       Note that 'return' mode forces the "style" parameter to have a
	       value of	'single';

       style
	   This	parameter determines if	XML::Pastor will generate a single
	   module where	all classes reside ("single"), or multiple modules one
	   for each class ("multiple").

	   Some	modes (such as "eval" and "return")force the style argument to
	   be 'single'.

	   Possible values are :

	   single
	       One block of code containg all the generated classes will be
	       produced.

	   multiple
	       A separate piece	of code	for each class will be produced.

       destination
	   This	is the directory prefix	where the produced modules will	be
	   written in offline mode. In other modes (eval and return), it is
	   ignored.

	   Note	that the trailing slash	('/') is optional. The default value
	   for this parameter is '/tmp/lib/perl/'.

       module
	   This	parameter has sense only when generating one big chunk of code
	   ("style" => "single") in offline "mode".

	   It denotes the name of the module (without the .pm extension) that
	   will	be written to disk in this case.

       .

BUGS & CAVEATS
       There no	known bugs at this time, but this doesn't mean there are
       aren't any.  Note that, although	some testing was done prior to
       releasing the module, this should still be considered alpha code.  So
       use it at your own risk.

       Note that there may be other bugs or limitations	that the author	is not
       aware of.

AUTHOR
       Ayhan Ulusoy <dev(at)ulusoy(dot)name>

COPYRIGHT
	 Copyright (C) 2006-2007 Ayhan Ulusoy. All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       See also	XML::Pastor, XML::Pastor::ComplexType, XML::Pastor::SimpleType

       And if you are curious about the	implementation,	see
       XML::Pastor::Schema::Parser, XML::Pastor::Schema::Model

perl v5.32.0			  2008-08-02	     XML::Pastor::Generator(3)

NAME | WARNING | ISA | SYNOPSIS | DESCRIPTION | METHODS | BUGS & CAVEATS | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help