view release on metacpan or  search on metacpan

lib/Apache2/Translation/_base.pod  view on Meta::CPAN

A change conducted via the WEB interface is a sequence of C<update>, C<insert>
or C<delete> operations. Before it is started C<begin> is called. If there
has no error occured C<commit> is called otherwise C<rollback>. C<commit> must
save the changes to the storage. C<rollback> must cancel all changes.

=item B<update( [@old], [@new] )>

=item B<insert( [@new] )>

=item B<delete( [@old] )>

All these functions return something >0 on success. C<@old> is a list of
C<KEY, URI, BLOCK, ORDER, ID> that specifies an existing action. If there
is no such action the functions must return C<0>. C<@new> is a list of
C<KEY, URI, BLOCK, ORDER, ACTION> that is to be inserted or has to replace
an existing action.

=back

The following interface is optional.

=over 4

=item B<clear>

deletes all entries from the provider. Is to be called within a C<begin> -
C<commit> wrapper. Returns boolean.

=item B<iterator>

returns a function reference that can be used the following way to step
all entries currently hold by the provider. Lists of blocks are traversed
in ascending alphabetical order with C<KEY> as the major ordering element and
C<URI> the minor. Within a block list elements are traversed in ascending
numerical order with C<BLOCK> as the major ordering element and C<ORDER> the
minor.

 my $iterator=$other->iterator;
 while( my $el=$iterator->() ) {
   # $el is an array ref as expected by insert().
 }

=back

The following interface is implemented by C<Apache2::Translation::_base>
itself and can be used.

=over 4

=item B<append( $other_provider, %options )>

Expects a provider object that implements the C<iterator> function. C<append>
then C<insert()>s all elements of C<$other_provider>.

If C<drop_notes> is passed as a true value in C<%options> then notes are not
copied.

=item B<diff( $other_provider, %options )>

If L<Algorithm::Diff> and L<JSON::XS> are installed this method computes
a difference between 2 providers. If C<key> or C<uri> are given in
C<%options> they act as filters.
The difference is calculated only for elements that pass that filter.
The value of C<key> or C<uri> can either be a string in which case the
matching operation is a simple C<eq> or a C<Regexp> object (C<qr/.../>).

If C<notes> is specified in C<%options> as a false value differences
in notes only are disregarded.

If C<numbers> is specified in C<%options> as a false value differences
in C<BLOCK> and C<ORDER> numbers only are disregarded.

For more information about the output format see C<diff()> in
L<Algorithm::Diff>.

=item B<sdiff( $other_provider, %options )>

Does the same as the C<diff> method but differs in the output format.

For more information see C<sdiff()> in L<Algorithm::Diff>.

=item B<dump( $format, $filehandle )>

Requires the C<iterator> function to be implemented and dumps all elements
formatted according to C<$format> to C<$filehandle>.

Both parameters are optional. Standard C<$filehandle> is C<STDOUT>, standard
format is:

 ######################################################################
 %{KEY} & %{URI} %{BLOCK}/%{ORDER}/%{ID}
 %{paction> ;ACTION}
 %{pnote> ;NOTE}

C<$format> is an arbitrary string that contains substrings of the form

  %{flags NAME}

where C<NAME> is on of C<KEY>, C<URI>, C<BLOCK>, C<ORDER>, C<ACTION>,
C<NOTE> or C<ID>. These substrings are then replaced by the values for
KEY, etc.

C<flags> is optional. It is a semicolon separated list of strings. If given
it must also be separated from C<NAME> by a semicolon.

Currently 2 flags are known:

=over 4

=item * p string

Trailing spaces are cut from the current value. Then all occurences of
C<\r?\n> are replaced by C<\nstring>. Also, C<string> is inserted at
start if the current value.

Example:

Suppose an ACTION holds a multilined value:

 PerlHandler: sub {