NAME

IWL::Stash - Encapsulation of HTML form information

SYNOPSIS

  use IWL::Stash;

  my $state = IWL::Stash->new ({keywords => [ 'Movies',
                                              'Action'],
                                template => '911dvd'});

  my $keywords = $state->getValues ('keywords');

  $state->setValues (keywords => 'TV');

  $state->setValues (keywords => ['TV', 'Soap']);

  $state->setValues (keywords => ('TV', 'Soap'));

  $state->pushValues (keywords => 'Daily');

  $state->pushValues (keywords => ['Daily', 'Boring']);

  $state->pushValues (keywords => ('Daily', 'Boring'));

  # splice / pop
  $state->spliceValues (keywords => -1);

  # splice / push
  $state->spliceValues (keywords => (9, 0, ('new', 'values')));

  # splice / shift
  $state->spliceValues (keywords => (0, 1));

  # splice / unshift
  $state->spliceValues (keywords => (0, 0, ('new', 'values')));

  my $state_keys = $state->keys;

  my $dump = $state->dump;

DESCRIPTION

The IWL::Stash class encapsulates the information that can be carried by an HTML form.

CONSTRUCTORS

new [STATE]

Create a new instance of the class. It will be empty unless you provide a STATE argument that populates the IWL::Stash object with data. The STATE argument is autodetected, and according on its type, the correct constructor (either newFromCGI, newFromHash, newFromHashReference, or clone) is called.

If you call the constructor with an unsupported STATE argument, it is silently ignored, and an empty state object is created instead.

newFromCGI CGIOBJECT

Creates a new instance of the class, initialized with data retrieved from CGIOBJECT. That argument should be a reference to a CGI(3pm) object, and the data is extracted from that object with the method param().

newFromHash FORMHASH

Creates a new instance of the class from a hash where the values are either scalars or array references (the latter for multi-valued input fields). Example:

  my $state = IWL::Stash->new (keywords => ['Movies',
                                            'Action'],
                               template => '911dvd');

Note that a reference to the FORMHASH is used, and the array references possibly used as values are not dereferenced. If that is an issue for you, copy your freshly created object with the clone() constructor (see below).

newFromHashReference FORMHASH

Just like newFromHash(), but the argument is a reference to a hash as described above for newFromHash().

Example:

  my $state = IWL::Stash->new ({keywords => [ 'Movies',
                                              'Action' ],
                                template => '911dvd'});

Note all these references are not dereferenced. If that is an issue for you, copy your freshly created object with the clone() constructor (see below).

clone STATE

Copy constructor that creates a deep copy of the STATE argument.

PUBLIC METHODS

getValues KEY

Retrieves the corresponding values of input field KEY or undef if there is no information stored under that key.

In scalar context only the first value is returned which might come in handy if you are certain that there is only one associated value present. In array context the complete list of associated values is returned.

setValues KEY, VALUE[, VALUES]

This method can be used in various ways to set the information that should be stored under KEY. If more than one value is passed to the function (i. e. VALUES is defined and is either a list or a scalar) all values are stored in the object. If VALUE is a reference it is treated as an array reference, dereferenced and the retrieved values get stored. If VALUE is a scalar it will be stored as the sole value for KEY.

As the name already suggests the method will clobber any existing information stored under KEY

Will make the object dirty if the new content for KEY differs from the old content.

pushValues KEY, VALUE[, VALUES]

Same as setValues but the new values are appended to existing information. Note that you can safely call this method even if there is nothing stored under KEY.

deleteValues KEY

Removes all values associated with the specified KEY.

In array context, returns an array of all deleted values. In scalar context, returns the first deleted value.

Will make the object dirty unless there has been no data associated with KEY.

shiftValue KEY

Shifts the first value associated with KEY off and returns it, shortening the number of values associated with that key by 1. It returns false, if no value is associated with KEY.

popValue KEY

Pops the first value associated with KEY off and returns it, shortening the number of values associated with that key by 1. It returns false, if no value is associated with KEY.

spliceValues KEY, OFFSET, LENGTH, VALUE[, VALUES]

This method can be used in various ways to change the information stored under KEY. Have a look at perldoc -f splice for more information.

FIXME: Better documentation! At the moment, look at the source!

keys

Returns the list of keys.

values

Returns a list of array references, containing the values for all keys.

dump

Returns a copy of the internal hash.

dirty

Returns true if the object is dirty, i. e. its content has changed since creation.

setDirty FLAG

Sets resp. resets the object dirty state according to the boolean attribute FLAG.

mergeState MERGER

"Merges" the state MERGER into the state. That means, that input fields present in MERGER will unconditionally clobber the respecting fields in the original state object.

searchKey KEY, REG

Returns true if the corresponding values of the input field KEY matches the regular expression REG

searchAll REG

Returns true if any input field matches the regular expression REG.

existsKey KEY

Returns true if an input field with the name 'KEY' exists, false otherwise.

equals OTHER_STATE

Compares the object to another IWL::Stash(3pm). Returns true if the two objects are equal, false otherwise.

toURIParams

Converts the object into a string that can be used as URI parameters. All keys and values are properly URI escaped. The initial question mark that separates the parameters from the rest of the URI is not included.

The method cannot fail.

toHiddenInputs

Returns an IWL::Container(3pm) with hidden input fields that completely represents the object.

The method cannot fail.

PROTECTED METHODS

_numKeys

Returns the number of keys. Rationale: Do not copy memory if we only need the length of the list of keys.

_setStateTo

Sets the internal "__state" variable to the reference passed as a parameter of the function.

SEE ALSO

IWL::Object(3pm), CGI(3pm), perl(1)

LICENCE AND COPYRIGHT

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.