Tie::DxHash(3)						User Contributed Perl Documentation					    Tie::DxHash(3)

NAME

       Tie::DxHash - keeps insertion order; allows duplicate keys

SYNOPSIS

	use Tie::DxHash;
	my(%vhost);
	tie %vhost, 'Tie::DxHash' [, LIST];
	%vhost = (
	  ServerName  => 'foo',
	  RewriteCond => 'bar',
	  RewriteRule => 'bletch',
	  RewriteCond => 'phooey',
	  RewriteRule => 'squelch',
	);

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.

       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  offend-
       ing   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").

INTERNALS

       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.

SEE ALSO

       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.  Engelschall's   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 at
       "http://httpd.apache.org/docs/misc/rewriteguide.html".

       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	O'Reilly book Writing Apache Modules with Perl and C, by Lincoln  Stein & Doug MacEachern, and study Chapter 8:
       Customizing the Apache Configuration Process.

BUGS

       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 con-
       figuration 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 host.

AUTHOR

       Kevin Ruscoe

perl v5.8.0							    2001-06-15							    Tie::DxHash(3)