Workflow::Validator::InEnumeratedType - Ensure a value is one of a declared set of values

This documentation describes version 1.04 of this package

 # Inline the enumeration...

 <action name="PlayGame">
   <validator name="InEnumeratedType">
      <value>Rock</value>
      <value>Scissors</value>
      <value>Paper</value>
      <arg value="$play"/>
   </validator>
 </action>

 # Or declare it in the validator to be more readable...
 <validator name="RSP"
            class="Validator::InEnumeratedType">
      <value>Rock</value>
      <value>Scissors</value>
      <value>Paper</value>
 </validator>

 # ...and use it in your action
 <action name="PlayGame">
    <validator name="RSP">
       <arg value="$play"/>
    </validator>
 </action>

This validator ensures that a value matches one of a set of values. You declare the values in the set (or enumerated type) in either the main validator declaration or in the declaration inside the action, then pass a single argument of the value in the context you would like to check.

Declaring the members of the enumerated type in the validator configuration makes for more readable (and brief) action configurations, as well as making the types more reusable, but it is really up to you.

Unlike some other validator classes this one is setup to be subclassable. It is usable as-is, of course, but many times you will find that you have need of more interesting types in your enumeration than simple strings. So this class provides the hooks for you to simply create your own.

For instance, in a trouble ticket system you may have the idea that tickets can only be assigned to particular users. Maybe they are in a 'worker' role, maybe they are some administrators, whatever. By creating a class to have these users as an enumerated type, combined with declaring the required Action fields, you make for a pretty powerful piece of reflection.

Onto the code. First we declare a field type of 'worker':

 <field type="worker"
        class="MyApp::Field::Worker"/>

Next a validator of this enumerated type:

 <validator name="IsWorker"
            class="MyApp::Validator::WorkerEnumeration"/>

We then associate this field type with a field in the action and the validator to ensure the user selects a worker from the right pool:

 <action name="AssignTicket">
    <field name="assignee"
           type="worker"
           is_required="yes"/>
   ...
   <validator name="IsWorker">
       <arg value="$assignee"/>
   </validator>

Note that the name of the field and the name used in the validator are the same. This allows external applications to query the action for its fields, get 'assignee' as the name and get a list of User objects (or something similar) as the types from which to choose a value, and checks that same field to ensure a correct choice was submitted.

The implementation for the validator might look like:

 package MyApp::Validator::WorkerEnumeration;

 sub validate {
     my ( $self, $wf, $worker_id ) = @_;
     my $ticket = $context->param( 'ticket' );
     unless ( $ticket ) {
         my $ticket_id = $context->param( 'ticket_id' );
         $ticket = Ticket->fetch( $ticket_id );
     }
     my $workers = $ticket->fetch_available_workers();
     my @worker_id = map { $_->id } @{ $workers };
     $self->add_enumerated_values( @worker_id );
     $self->SUPER::validate( $wf, $worker_id );
 }

This method initializes the class and the enumerated class.

It uses add_enumerated_values to add the set of values for enumeration.

The primary parameter is value, which should be used to specify the either a single value or a reference to array of values to be added.

The validator method is the public API. It encapulates is_enumerated:value and works with Workflow.

This method ads an array of values to be regarded as enumerations for the validator.

This method returns the defined enumerated values for the class as an array.

This is most often the single method you will want to modify.

The method offers assertion of a given value, as to whether it is an enumerated type as defined in the class.

* Validator 'InEnumeratedType' must be initialized with the values you wish to validate against using the parameter 'value'.

This Workflow::Exception is thrown from _init if the 'value' parameter is not set.

* Value '$value' must be one of: <@values>

This Workflow::Exception is thrown from _validator if the value to be asserted is not mathing any of the enumerated values defined as part of the set.

Copyright (c) 2003-2007 Chris Winters. All rights reserved.

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

Current maintainer Jonas B. Nielsen <jonasbn@cpan.org>

Original author Chris Winters <chris@cwinters.com>