NAME

Keystone::Resolver::Utils - Simple utility functions for Keystone Resolver

SYNOPSIS

 use Keystone::Resolver::Utils qw(encode_hash decode_hash);
 $string = encode_hash(%foo);
 %bar = decode_hash($string);

DESCRIPTION

This module consists of standalone functions -- yes, that's right, functions: not classes, not methods, functions. These are provided for the use of Keystone Resolver.

FUNCTIONS

encode_hash(), decode_hash()

 $string = encode_hash(%foo);
 %bar = decode_hash($string);

encode_hash() encodes a hash into a single scalar string, which may then be stored in a database, specified as a URL parameters, etc. decode_hash() decodes a string created by encode_hash() back into a hash identical to the original.

These two functions constitute a tiny subset of the functionality of the Storable module, but have the pleasant property that the encoded form is human-readable and therefore useful in logging. In theory, the encoding is secret, but I may as well admit that the hash is encoded as a URL query.

utf8param()

 $unicodeString = utf8param($r, $key);
 @unicodeKeys = utf8param($r);

Returns the value associated with the parameter named $key in the Apache Request (or similar object) $r, on the assumption that the encoded value was a sequence of UTF-8 octets. These octets are decoded into Unicode characters, and it is a string of these that is returned.

If called with no $key parameter, returns a list of the names of all parameters available in $r, each such key returned as a string of Unicode characters.

apache_request()

 my $r = apache_request($cgi);

Because the Apache/Perl project people saw fit to totally change the API between mod_perl versions 1 and 2, and because the environment variables that might tell you what version is in use are undocumented and obscure, it is pretty painful getting hold of the Apache request object in a portable way -- which you need for things like setting the content-type. apache_request() does this, returning the Apache 1 or 2 request object if running under Apache, and otherwise returning the fallback object which is passed in, if any.

mod_perl_version()

 $ver = mod_perl_version();

Returns the major API version number of the version mod_perl in effect, or an undefined value if not running under mod_perl (e.g. as an external CGI script or from the command-line).

 apache_non_moronic_logging()

I hate the world.

For reasons which no rational being could ever fathom, one of the differences between Apache 1.x/mod_perl and Apache 2.x/mod_perl2 is that in the latter, calls to warn() result in the output going to the global error-log of the server rather than the the error-log of the virtual site. I know, I know, it is truly astonishing. I will not meditate on this further. See the section entitled Virtual Hosts in the Apache2::Log manual for details, or see the online version at http://perl.apache.org/docs/2.0/api/Apache2/Log.html#Virtual_Hosts

Anyway, call apache_non_moronic_logging() to globally fix this by aliasing CORE::warn() to the non-braindead Apache2 logging function of the same name. Calling under mod_perl 1, or not under mod_perl at all, will no-op.

### except -- it turns out -- this doesn't actually work, even though it is the very code from the Apache2::Log manual. Or rather, it works intermittently. So I think you will just have to read the global log as well as the resolver log. Nice.