.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" 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. \*(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<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . 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 . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . 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 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Tie::DxHash 3pm" .TH Tie::DxHash 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Tie::DxHash \- keeps insertion order; allows duplicate keys .SH "VERSION" .IX Header "VERSION" This document describes Tie::DxHash version 1.03 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& use Tie::DxHash; \& my(%vhost); \& tie %vhost, \*(AqTie::DxHash\*(Aq [, LIST]; \& %vhost = ( \& ServerName => \*(Aqfoo\*(Aq, \& RewriteCond => \*(Aqbar\*(Aq, \& RewriteRule => \*(Aqbletch\*(Aq, \& RewriteCond => \*(Aqphooey\*(Aq, \& RewriteRule => \*(Aqsquelch\*(Aq, \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" 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. .PP 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. .PP 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. .PP 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). .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" This module is intended to be called through Perl's tie interface. For reference, the following methods have been defined: .PP .Vb 9 \& CLEAR \& DELETE \& EXISTS \& FETCH \& FIRSTKEY \& NEXTKEY \& SCALAR \& STORE \& TIEHASH .Ve .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" None. .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" Tie::DxHash requires no configuration files or environment variables. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" None. .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "INTERNALS" .IX Header "INTERNALS" 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. .SH "BUGS AND LIMITATIONS" .IX Header "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 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. .PP 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 and ). 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 host. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBperltie\fR\|(1), for information on ties generally. .PP \&\fBTie::IxHash\fR\|(3), by Gurusamy Sarathy, if you need to preserve insertion order but not allow duplicate keys. .PP 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". .PP 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. .SH "AUTHOR" .IX Header "AUTHOR" Kevin Ruscoe \f(CW\*(C`\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2006, Kevin Ruscoe \f(CW\*(C`\*(C'\fR. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" \&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE\s0 \s-1OF CHARGE, THERE IS\s0 \s-1NO WARRANTY FOR THE SOFTWARE,\s0 \s-1TO THE EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE LAW.\s0 \s-1EXCEPT WHEN\s0 \s-1OTHERWISE STATED IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0 \s-1PROVIDE THE SOFTWARE \*(L"AS\s0 \s-1IS\*(R" WITHOUT WARRANTY\s0 \s-1OF ANY\s0 \s-1KIND,\s0 \s-1EITHER EXPRESSED OR\s0 \s-1IMPLIED, INCLUDING, BUT NOT\s0 \s-1LIMITED TO, THE\s0 \s-1IMPLIED WARRANTIES OF MERCHANTABILITY\s0 \s-1AND FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR PURPOSE.\s0 \s-1THE\s0 \s-1ENTIRE\s0 \s-1RISK AS\s0 \s-1TO THE\s0 \s-1QUALITY\s0 \s-1AND PERFORMANCE OF THE\s0 \s-1SOFTWARE IS WITH\s0 \s-1YOU. SHOULD THE SOFTWARE\s0 \s-1PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0 .PP \&\s-1IN NO EVENT UNLESS REQUIRED\s0 \s-1BY APPLICABLE LAW OR AGREED\s0 \s-1TO IN WRITING WILL ANY COPYRIGHT HOLDER,\s0 \s-1OR ANY OTHER PARTY\s0 \s-1WHO\s0 \s-1MAY MODIFY\s0 \s-1AND/OR REDISTRIBUTE THE SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED BY THE\s0 \s-1ABOVE\s0 \s-1LICENCE,\s0 \s-1BE LIABLE\s0 \s-1TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO\s0 \s-1USE THE SOFTWARE\s0 (\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA\s0 \s-1BEING RENDERED INACCURATE OR LOSSES\s0 \s-1SUSTAINED BY YOU\s0 \s-1OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE\s0 \s-1TO OPERATE WITH\s0 \s-1ANY OTHER SOFTWARE\s0), \s-1EVEN IF SUCH HOLDER\s0 \s-1OR\s0 \s-1OTHER PARTY HAS\s0 \s-1BEEN\s0 \s-1ADVISED OF THE POSSIBILITY\s0 \s-1OF SUCH DAMAGES.\s0