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.