Name

Apache::FakeTable - Pure Perl implementation of the Apache::Table interface

Synopsis

  use Apache::FakeTable;

  my $table = Apache::FakeTable->new($r);

  $table->set(From => 'david@example.com');

  $table->add(Cookie => 'One Cookie');
  $table->add(Cookie => 'Another Cookie');

  while(my($key, $val) = each %$table) {
      print "$key: $val\n";
  }

Description

This class emulates the behavior of the Apache::Table class, and is designed to behave exactly like Apache::Table. This means that all keys are case-insensitive and may have multiple values. As a drop-in substitute for Apache::Table, you should be able to use it exactly like Apache::Table.

You can treat an Apache::FakeTable object much like any other hash. However, like Apache Table, those keys that contain multiple values will trigger slightly different behavior than a traditional hash. The variations in behavior are as follows:

keys

Will return the same key multiple times, once for each value stored for that key.

values

Will return the first value multiple times, once for each value stored for a given key. It'd be nice if it returned all the values for a given key, instead of the first value * the number of values, but that's not the way Apache::Table works, and I'm not sure I'd know how to implement it even if it did!

each

Will return the same key multiple times, pairing it with each of its values in turn.

Otherwise, things should be quite hash-like, particularly when a key has only a single value.

Interface

new()

  my $table = Apache::FakeTable->new($r);
  $table = Apache::FakeTable->new($r, $initial_size);

Returns a new Apache::FakeTable object. An Apache object is required as the first argument. An optional second argument sets the initial size of the table for storing values.

get()

  my $value = $table->get($key);
  my @values = $table->get($key);
  my $value = $table->{$key};

Gets the value stored for a given key in the table. If a key has multiple values, all will be returned when get() is called in an array context, and only the first value when it is called in a scalar context.

set()

  $table->set($key, $value);
  $table->{$key} = $value;

Takes key and value arguments and sets the value for that key. Previous values for that key will be discarded. The value must be a string, or set() will turn it into one. A value of undef will be converted to the null string ('') a warning will be issued if warnings are enabled.

unset()

  $table->unset($key);
  delete $table->{$key};

Takes a single key argument and deletes that key from the table, so that none of its values will be in the table any longer.

clear()

  $table->clear;
  %$table = ();

Clears the table of all values.

add()

  $table->add($key, $value);

Adds a new value to the table. This method is the sole interface for adding mutiple values for a single key.

merge()

  $table->merge($key, $value);

Merges a new value with an existing value by appending the new value to the existing. The result is a string with the old value separated from the new by a comma and a space. If $key contains multiple values, then only the first value will be used before appending the new value, and the remaining values will be discarded.

do()

  $table->do($coderef);

Pass a code reference to this method to have it iterate over all of the key/value pairs in the table. Keys with multiple values will trigger the execution of the code reference multiple times, once for each value. The code reference should expect two arguments: a key and a value. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every value in the table.

Support

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Please file bug reports via GitHub Issues or by sending mail to bug-Apache-FakeTable@rt.cpan.org.

See Also

Apache::Table.

Author

David E. Wheeler <david@justatheory.com>

Copyright and License

Copyright (c) 2003-2011, David E. Wheeler. Some Rights Reserved.

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

cpanm Apache::FakeTable

perl -MCPAN -e shell
install Apache::FakeTable