Creating Your Own Parser

1.

subclass Workflow::Config

2.

implement the required methods (listed below)

3.

register your parser with Workflow::Config.

For instance, if you wanted to use YAML for configuration files you would do something like:

 # just a convention, you can use any namespace you want
 package Workflow::Config::YAML;

 use strict;

 # Requirement 1: Subclass Workflow::Config
 use base qw( Workflow::Config );

 # Requirement 2: Implement required methods
 sub parse { ... }

The third requirement is registration, which just tells Workflow::Config which parser to use for a particular type. To do this you have two options.

Registration option one

Register yourself in your own class, adding the following call anywhere the end:

 # Option 1: Register ourselves by name
 Workflow::Config->register_factory_type( yaml => 'Workflow::Config::YAML' );

Now you just need to include the configuration class in your workflow invocation script:

 use strict;
 use Workflow::Factory qw( FACTORY );
 use Workflow::Config::YAML; # <-- brings in the registration

Registration option two

You can also just explicitly add the registration from your workflow invocation script:

 use strict;
 use Workflow::Factory qw( FACTORY );
 use Workflow::Config;

 # Option 2: explicitly register your configuration parser
 Workflow::Config->register_factory_type( yaml => 'Workflow::Config::YAML' );

Whichever one you choose you can now parse (in this example) YAML files alongside the built-in parsers for XML and Perl files:

 FACTORY->add_config_from_file(
     workflow  => 'workflow.yaml',
     action    => [ 'my_actions.yaml', 'other_actions.xml' ],
     validator => 'validators.yaml',
     condition => [ 'my_conditions.yaml', 'other_conditions.xml' ]
     persister => 'persister.perl',
 );

Inherited Methods

Instantiates an object of the correct type -- see Class::Factory for how this is implemented:

 # Parser of type 'Workflow::Config::XML'
 my $xml_parser  = Workflow::Config->new( 'xml' );

 # Parser of type 'Workflow::Config::Perl
 my $perl_parser = Workflow::Config->new( 'perl' );

is_valid_config_type( $config_type )

Returns true if $config_type is a valid configuration type, false if not. Valid configuration types are: 'action', 'condition', 'validator', 'workflow'.

get_valid_config_types()

Returns list of strings representing the valid configuration types.

get_config_type_tag( $class, $type )

Returns string representing a valid configuration type, looking up the type parameter in a lookuptable defined in Workflow::Config class.

Required Object Methods

Parse each item in @items to a hash reference based on the configuration type $config_type which must pass the "is_valid_config_type()" test. An 'item' is either a filename or a scalar reference with the contents of a file. (You can mix and match as seen in the SYNOPSIS.)

Should throw an exception if:

• You pass an invalid workflow configuration type. Valid workflow configuration types are registered in Workflow::Config and are available from "get_valid_config_types()"; you can check whether a particular type is valid with "is_valid_config_type()". (See above for descriptions.)
• You pass in a file that cannot be read or parsed because of permissions, malformed XML, incorrect Perl data structure, etc. It does not do a validation check (e.g., to ensure that every 'action' within a workflow state has a 'resulting_state' key).

Returns: one hash reference for each member of @items

workflow

   workflow
      class         $
      type          $
      description   $
      persister     $
      initial_state $
      observer    \@
          sub           $
          class         $
      state       \@
          name          $
          description   $
          action        \@
              name            $
              resulting_state $
              condition       \@
                  name              $

• the 'class', 'type' and 'description' keys are at the top level
• 'persister' key holds a string declaring the name of a persister as declared in the array of persisters
• 'initial_state' key holds a string declaring the name of the initial state. by default, this value is 'INIITAL'.
• 'state' key holds array of one or more 'state' declarations; one of them must be 'INITIAL' (or the value of initial_state, if it's defined)
• each 'state' declaration holds 'description' and 'name' keys and multiple 'action' declarations
• each 'action' declaration holds 'name' and 'resulting_state' keys and may hold a 'condition' key with one or more named conditions

condition

 conditions:

     condition \@
        name  $
        class $
        param \@
            name  $
            value $

•

array of one or more hashrefs with 'name' and 'class' keys

validator

 validators:

     validator \@
        name  $
        class $
        param \@
            name  $
            value $

•

array of one or more hashrefs with 'name' and 'class' keys, plus possibly one or more 'param' hashrefs each with 'name' and 'value' keys

action

 actions:

    action \@
       name        $
       class       $
       description $
       type        $
       field      \@
          name         $
          is_required  yes|no
          type         $
          source_list  \@ of $
          source_class $
          param        \@
              name  $
              value $
       validator \@
           name $
           arg  \@
               value $

• array of one or more action hashrefs with 'name', 'class' and 'description' keys
• each 'action' may specify a 'type' (default value: 'default'); in case a workflow specifies a 'type', actions specifying the same 'type' will be preferred over actions with the 'default' type when multiple actions by the same name exist.
• each 'action' may have zero or more values used to fill it; each value has a 'name', 'description' and 'necessity' ('required' or 'optional')
• each 'action' may have any number of 'param' hashrefs, each with 'name' and 'value'
• each 'action' may have any number of 'validator' hashrefs, each with a 'name' key and array of 'arg' declarations

persister

 persister:
   name           $        # all persister classes
   class          $        # all persister classes
   use_random     yes|no   # all persister classes
   use_uuid       yes|no   # all persister classes

   driver         $   # DBI persisters
   dsn            $   # DBI persisters
   user           $   # DBI persisters
   password       $   # DBI persisters
   workflow_table $   # DBI persisters
   history_table  $   # DBI persisters
   autocommit     $   # DBI persisters
   date_format    $   # DBI persisters

   table          $   # DBI/ExtraData persisters
   data_field     $   # DBI/ExtraData persisters
   context_key    $   # DBI/ExtraData persisters

   path           $   # File persisters

• 'name' key holds a string declaring the name by which workflows may refer to this persister configuration
• 'class' key names a Perl class name to use when instantiating the persister
• 'use_random' key holds a string declaring (through 'yes'/'no' value) to use random values for the workflow identifier
• 'use_uuid' key holds a string declaring (through 'yes'/'no' value) to use UUID (universally unique ID) values for the workflow identifier; UUIDs take preference over random IDs

For documentation of the other keys, please refer to the respective classes.