.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.IX Title "Tie::DxHash 3"
.TH Tie::DxHash 3 "2001-06-15" "perl v5.8.0" "User Contributed Perl Documentation"
Tie::DxHash \- keeps insertion order; allows duplicate keys
\& tie %vhost, 'Tie::DxHash' [, LIST];
\& 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 \s-1URL\s0 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 \f(CW\*(C`httpd \-t\*(C'\fR) and checking virtual host settings (with \f(CW\*(C`httpd \-S\*(C'\fR) 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 \f(CW\*(C`perl \-cx\*(C'\fR).
For those interested, Tie::IxHash 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.
\&\fIperltie\fR\|(1), for information on ties generally.
\&\fITie::IxHash\fR\|(3), by Gurusamy Sarathy, if you need to preserve insertion order but
not allow duplicate keys.
For information on Ralf S. Engelschall's powerful \s-1URL\s0 rewriting module,
mod_rewrite, check out the reference documentation at
\&\*(L"http://httpd.apache.org/docs/mod/mod_rewrite.html\*(R" and the \s-1URL\s0 Rewriting Guide
at \*(L"http://httpd.apache.org/docs/misc/rewriteguide.html\*(R".
For help in using Perl Sections to configure Apache, take a look at the section
called \*(L"Apache Configuration in Perl\*(R" at
\&\*(L"http://perl.apache.org/guide/config.html#Apache_Configuration_in_Perl\*(R", part of
the mod_perl guide, by Stas Bekman. Alternatively, buy the O'Reilly book
Writing Apache Modules with Perl and C, by Lincoln Stein & Doug MacEachern, and
study Chapter 8: Customizing the Apache Configuration Process.
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 module's 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
projects / OpenSPARC-T2-DV / blob