GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XML::PASTOR::GENERATOR (3)

.ds Aq ’

NAME

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

CONTENTS

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

<B>XML::Pastor::GeneratorB> 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)



<B>CONSTRUCTORB>.

The new() constructor method instantiates a new <B>XML::Pastor::GenertorB> 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 <B>modelB> (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.

<B>OPTIONSB>

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 <B>DefaultB>.

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 ’<B>makeB>’ process, where you have a set of XSD schemas and you generate your modules to be later installed by ’<B>make installB>’. 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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 XML::PASTOR::GENERATOR (3) 2008-08-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.