Manual Reference Pages - TIE::DXHASH (3)
Tie::DxHash - keeps insertion order; allows duplicate keys
This document describes Tie::DxHash version 1.03
tie %vhost, Tie::DxHash [, LIST];
%vhost = (
ServerName => foo,
RewriteCond => bar,
RewriteRule => bletch,
RewriteCond => phooey,
RewriteRule => squelch,
This module was written to allow the use of rewrite rules in Apache
configuration files written with Perl Sections. However, a potential user has
stated that he needs it to support the use of multiple ScriptAlias directives
within a single Virtual Host (which is required by FrontPage, apparently). If
you find a completely different use for it, great.
The original purpose of this module is not quite so obscure as it might sound.
Perl Sections bring the power of a general-purpose programming language to
Apache configuration files and, having used them once, many people use them
throughout. (I take this approach since, even in sections of the configuration
where I do not need the flexibility, I find it easier to use a consistent
syntax. This also makes the code easier for XEmacs to colour in ;-) Similarly,
mod_rewrite is easily the most powerful way to perform URL rewriting and I tend
to use it exclusively, even when a simpler directive would do the trick, in
order to group my redirections together and keep them consistent. So, I came up
against the following problem quite early on.
The synopsis shows some syntax which might be needed when using mod_rewrite
within a Perl Section. Clearly, using an ordinary hash will not do what you
want. The two additional features we need are to preserve insertion order and
to allow duplicate keys. When retrieving an element from the hash by name,
successive requests for the same name must iterate through the duplicate entries
(and, presumably, wrap around when the end of the chain is reached). This is
where Tie::DxHash comes in. Simply by tying the offending hash, the
corresponding configuration directives work as expected.
Running an Apache syntax check (with docroot check) on your configuration file
(with httpd -t) and checking virtual host settings (with httpd -S) succeed
without complaint. Incidentally, I strongly recommend building your Apache
configuration files with make (or equivalent) in order to enforce the above two
checks, preceded by a Perl syntax check (with perl -cx).
This module is intended to be called through Perls tie interface. For
reference, the following methods have been defined:
CONFIGURATION AND ENVIRONMENT
Tie::DxHash requires no configuration files or environment variables.
For those interested, Tie::DxHash works by storing the hash data in an array of
hash references (containing the key/value pairs). This preserves insertion
order. A separate set of iterators (one per distinct key) keeps track of the
last retrieved value for a given key, thus allowing the successive retrieval of
multiple values for the same key to work as expected.
BUGS AND LIMITATIONS
The algorithms used to retrieve and delete elements by key run in O(N) time, so
do not expect this module to work well on large data sets. This is not a
problem for the modules intended use. If you find another use for the module
which involves larger quantities of data, let me know and I will put some effort
into optimising for speed.
The mod_rewrite directives for which this module was written (primarily
RewriteCond and RewriteRule) can occur in all four configuration file contexts
(i.e. server config, virtual host, directory, .htaccess). However, Tie::DxHash
only helps when you are using a directive which is mapped onto a Perl hash.
This limits you to directives which are block sections with begin and end tags
(like <VirtualHost> and <Directory>). I get round this by sticking my
mod_rewrite directives in a name-based virtual host container (as shown in the
synopsis) even in the degenerate case where the web server only has one virtual
perltie(1), for information on ties generally.
Tie::IxHash(3), by Gurusamy Sarathy, if you need to preserve insertion order but
not allow duplicate keys.
For information on Ralf S. Engelschalls powerful URL rewriting module,
mod_rewrite, check out the reference documentation at
http://httpd.apache.org/docs/mod/mod_rewrite.html and the URL Rewriting Guide
For help in using Perl Sections to configure Apache, take a look at the section
called Apache Configuration in Perl at
http://perl.apache.org/guide/config.html#Apache_Configuration_in_Perl, part of
the mod_perl guide, by Stas Bekman. Alternatively, buy the OReilly book
Writing Apache Modules with Perl and C, by Lincoln Stein & Doug MacEachern, and
study Chapter 8: Customizing the Apache Configuration Process.
Kevin Ruscoe <firstname.lastname@example.org>
LICENSE AND COPYRIGHT
Copyright (c) 2006, Kevin Ruscoe <email@example.com>. All rights
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
SOFTWARE AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE,
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS
OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN
IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
|perl v5.20.3 ||TIE::DXHASH (3) ||2009-02-17 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.