The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / BPM-XPDL-0.04 / lib / BPM / XPDL.pod 
=head1 NAME

BPM::XPDL - XPDL access

=head1 INHERITANCE

 BPM::XPDL
   is a XML::Compile::Cache
   is a XML::Compile::Schema
   is a XML::Compile

=head1 SYNOPSIS

  my $xpdl = BPM::XPDL->new(version => '2.1');
  $xpdl->importDefinitions(...);
  my $xml  = $xpdl->writer($sometype)->($doc, $perldata);

  my ($type, $data) = $xpdl->from('data.xml');
  my ($type, $data) = BPM::XPDL->from('data.xml');
  print "Root type: $type\n";
  print Dumper $data;    # from Data::Dumper

  $xpdl->addKeyRewrite('PREFIXED');
  my $xml = $xpdl->create($data);
  print $xml->toString(1);

=head1 DESCRIPTION

This module provides access to the Process Description Language, as
defined by the WfMC, the Workflow Management Coalition (F<wfmc.org>)
You can read and L<create()|BPM::XPDL/"Other"> these XPDL files with one simpe method.

All versions of the specification are supported. It will convert older
versions into newer versions if you want to.  See L<from()|BPM::XPDL/"Constructors">.

=head2 Limitiations

The XPDL files may contain additional external type definitions, which
are not imported/included in the specification.  You need to import
those explictly by hand.  See F<t/20sample.t>

TypeDeclarations are part of the interpretation of the messages which are
exchanged between the Applications, and therefore not interpreted by
this module.

=head1 METHODS

=head2 Constructors

$obj-E<gt>B<from>(XMLDATA, OPTIONS)

BPM::XPDL-E<gt>B<from>(XMLDATA, OPTIONS)

=over 4

Read an XML message, in any format supported by L<XML::Compile> method
C<dataToXML()>: string, file, filehandle, and more.  Returned is a list
of two: the type of the top-level element plus the data-structure.

When called as instance method, the data will automatically get converted
to the version of required by the object.  When called as class method,
the version of the top-level element will determine the returned version
automatically (which may give unpredictable versions as result).

When the method is called as class method, then a temporary instance is
created.  Creating an instance is (very) slow.

example: 

  my $xpdl          = BPM::XPDL->new(version => '2.1');
  my ($type, $data) = $xpdl->from('data.xml');

or

  my ($type, $data) = BPM::XPDL->from('data.xml');

=back

BPM::XPDL-E<gt>B<new>(OPTIONS)

=over 4

 Option            --Defined in     --Default
 allow_undeclared    XML::Compile::Cache  <false>
 any_element         XML::Compile::Cache  'SKIP_ALL'
 block_namespace     XML::Compile::Schema  []
 hook                XML::Compile::Schema  undef
 hooks               XML::Compile::Schema  []
 ignore_unused_tags  XML::Compile::Schema  <false>
 key_rewrite         XML::Compile::Schema  []
 opts_readers        XML::Compile::Cache  []
 opts_rw             XML::Compile::Cache  []
 opts_writers        XML::Compile::Cache  []
 prefix_keys                          <true>
 prefixes            XML::Compile::Cache  <smart>
 schema_dirs         XML::Compile     undef
 typemap             XML::Compile::Schema  {}

. allow_undeclared => BOOLEAN

. any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'

. block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY

. hook => ARRAY-WITH-HOOKDATA | HOOK

. hooks => ARRAY-OF-HOOK

. ignore_unused_tags => BOOLEAN|REGEXP

. key_rewrite => HASH|CODE|ARRAY-of-HASH-and-CODE

. opts_readers => HASH|ARRAY-of-PAIRS

. opts_rw => HASH|ARRAY-of-PAIRS

. opts_writers => HASH|ARRAY-of-PAIRS

. prefix_keys => BOOLEAN

=over 4

Enables the visibility of the various XPDL namespaces which can be merged
within one document.

=back

. prefixes => HASH|ARRAY-of-PAIRS

. schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

. typemap => HASH

=back

=head2 Accessors

$obj-E<gt>B<addHook>(HOOKDATA|HOOK|undef)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addHooks>(HOOK, [HOOK, ...])

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addKeyRewrite>(PREDEF|CODE|HASH, ...)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

BPM::XPDL-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

=over 4

See L<XML::Compile/"Accessors">

=back

$obj-E<gt>B<addSchemas>(XML, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addTypemap>(PAIR)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addTypemaps>(PAIRS)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<allowUndeclared>([BOOLEAN])

=over 4

See L<XML::Compile::Cache/"Accessors">

=back

$obj-E<gt>B<blockNamespace>(NAMESPACE|TYPE|HASH|CODE|ARRAY)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<hooks>

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<namespace>

=over 4

=back

$obj-E<gt>B<prefix>(PREFIX)

=over 4

See L<XML::Compile::Cache/"Accessors">

=back

$obj-E<gt>B<prefixFor>(URI)

=over 4

See L<XML::Compile::Cache/"Accessors">

=back

$obj-E<gt>B<prefixed>(TYPE)

=over 4

See L<XML::Compile::Cache/"Accessors">

=back

$obj-E<gt>B<prefixes>([PAIRS|ARRAY|HASH])

=over 4

See L<XML::Compile::Cache/"Accessors">

=back

$obj-E<gt>B<useSchema>(SCHEMA, [SCHEMA])

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<version>

=over 4

=back

=head2 Compilers

$obj-E<gt>B<compile>(('READER'|'WRITER'), TYPE, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Compilers">

=back

$obj-E<gt>B<compileAll>(['READER'|'WRITER'|'RW', [NAMESPACE]])

=over 4

See L<XML::Compile::Cache/"Compilers">

=back

BPM::XPDL-E<gt>B<dataToXML>(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

=over 4

See L<XML::Compile/"Compilers">

=back

$obj-E<gt>B<reader>(TYPE|NAME, OPTIONS)

=over 4

See L<XML::Compile::Cache/"Compilers">

=back

$obj-E<gt>B<template>('XML'|'PERL', TYPE, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Compilers">

=back

$obj-E<gt>B<writer>(TYPE|NAME)

=over 4

See L<XML::Compile::Cache/"Compilers">

=back

=head2 Administration

$obj-E<gt>B<declare>('READER'|'WRITER'|'RW', TYPE|ARRAY-of-TYPES, OPTIONS)

=over 4

See L<XML::Compile::Cache/"Administration">

=back

$obj-E<gt>B<elements>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<findName>(NAME)

=over 4

See L<XML::Compile::Cache/"Administration">

=back

$obj-E<gt>B<findSchemaFile>(FILENAME)

BPM::XPDL-E<gt>B<findSchemaFile>(FILENAME)

=over 4

See L<XML::Compile/"Administration">

=back

$obj-E<gt>B<importDefinitions>(XMLDATA, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

BPM::XPDL-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

=over 4

See L<XML::Compile/"Administration">

=back

$obj-E<gt>B<namespaces>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<printIndex>([FILEHANDLE], OPTIONS)

=over 4

See L<XML::Compile::Cache/"Administration">

=back

$obj-E<gt>B<types>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<walkTree>(NODE, CODE)

=over 4

See L<XML::Compile/"Administration">

=back

=head2 Other

$obj-E<gt>B<create>(DATA)

=over 4

Pass a correctly constructed Perl data-structure, which maps to a
xpdl:Package type, and it will produce XML for it (returns an
XML::LibXML::Document object).

Be warned that the output may contain deprecated constructs.
Accidentally, the non-deprecated versions usually match better on the
provided data.

  my $xml = $xpdl->create($data);
  print $xml->toString(1);

=back

=head1 DETAILS

=head1 SEE ALSO

This module is part of BPM-XPDL distribution version 0.04,
built on February 20, 2010. Website: F<http://perl.overmeer.net>

=head1 ACKNOWLEDGEMENTS

Interapy F<http://www.interapy.nl> sponsored the development of
this software.

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2009-2010 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>