Tie::DxHash(3pm)

📦
version 1.05 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Tie::DxHash 💖

okay so bestie, this is part of the User Contributed Perl Documentation — a manual page, but make it cute. It's giving "the hash that remembers stuff and does NOT let order go", and honestly? iconic. Also, hi, this doc describes Tie::DxHash version 1.03. 💅

✨ NAME ✨

Tie::DxHash — keeps insertion order; allows duplicate keys 🎀

🌸 VERSION 🌸

This document describes Tie::DxHash version 1.03 ⭐

🦋 SYNOPSIS 🦋

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

like. LOOK at that. two RewriteConds and two RewriteRules in one plain hash literal. a normal hash could NEVER. 🙈

💜 DESCRIPTION 💜

So, the whole reason this module exists: it was written to let you use rewrite rules in Apache configuration files that were written with Perl Sections. that's the origin story. 🫶

BUT. plot twist. a potential user said he actually needs it so he can support multiple ScriptAlias directives inside a single Virtual Host — which, apparently, FrontPage requires. and if you find some completely different use for it, great, slay, do your thing. ✨

ngl the original purpose is not even as obscure as it sounds. here's the tea: Perl Sections bring the power of a general-purpose programming language straight into Apache configuration files, and once people have used them one time, a lot of them use them everywhere. (the author's approach, and honestly relatable: even in sections of the config where the flexibility isn't needed, a consistent syntax is easier. plus it makes the code easier for XEmacs to colour in ;-) ) and similarly, mod_rewrite is easily the most powerful way to do URL rewriting, and the author tends to use it exclusively — even when a simpler directive would do the trick — so that all the redirections stay grouped together and consistent. so, quite early on, he ran straight into the following problem.

the synopsis shows the kind of syntax you might need when using mod_rewrite inside a Perl Section. and clearly, an ordinary hash is just not going to do what you want. the two extra features we need are:

  1. preserve insertion order ✨
  2. allow duplicate keys ✨

when you retrieve an element from the hash by name, successive requests for the same name have to iterate through the duplicate entries — and presumably wrap around once the end of the chain is reached. and that, bestie, is where Tie::DxHash comes in. tie the offending hash and boom, the corresponding configuration directives work as expected. no cap. 🔥

running an Apache syntax check (with docroot check) on your configuration file (with httpd -t) and checking virtual host settings (with httpd -S) both succeed without complaint. incidentally, the author strongly recommends building your Apache configuration files with make (or equivalent) so those two checks get enforced, preceded by a Perl syntax check (with perl -cx). yes ma'am. 💅

🧚 SUBROUTINES/METHODS 🧚

this module is meant to be called through Perl's tie interface. for reference, here are the methods that have been defined:

CLEAR
DELETE
EXISTS
FETCH
FIRSTKEY
NEXTKEY
SCALAR
STORE
TIEHASH

nine methods. all iconic. all doing their little job. 🎀

💀 DIAGNOSTICS 💀

None.

like, nothing. zero drama. it's giving peace and quiet. 🌈

⭐ CONFIGURATION AND ENVIRONMENT ⭐

Tie::DxHash requires no configuration files or environment variables.

nothing to set up. just vibes. 🦋

🍓 DEPENDENCIES 🍓

None.

🙈 INCOMPATIBILITIES 🙈

None reported.

👑 INTERNALS 👑

for those of you who are nosy (affectionate), here's the mechanics: Tie::DxHash works by storing the hash data in an array of hash references (containing the key/value pairs). that's what preserves insertion order. 🌸

then there's a separate set of iterators — one per distinct key — keeping track of the last retrieved value for a given key, so that successively retrieving multiple values for the same key works the way you'd expect. it's giving organized. it's giving main character energy. ✨

😭 BUGS AND LIMITATIONS 😭

okay so. 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. seriously. 💀

that said, it's not a problem for the module's intended use. and if you find another use for the module that involves larger quantities of data, let the author know and he'll put some effort into optimising for speed. 🫶

also: the mod_rewrite directives this module was written for (primarily RewriteCond and RewriteRule) can occur in all four configuration file contexts — server config, virtual host, directory, .htaccess. BUT Tie::DxHash only helps when you're using a directive that's mapped onto a Perl hash. which limits you to directives that are block sections with begin and end tags (like <VirtualHost> and <Directory>). the workaround: stick your 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. problem solved, we move. 💅

🔥 SEE ALSO 🔥

💖 AUTHOR 💖

Kevin Ruscoe <kevin@sapphireoflondon.org> 👑

Copyright (c) 2006, Kevin Ruscoe <kevin@sapphireoflondon.org>. All rights reserved.

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 💅

okay bestie, this part is the legal bit and it means every word, so here it is, unedited and in all caps, exactly as the lawyers wrote it. read it. it's real. 💀

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 DAMAGES.

okay that's the whole page!! ✨ one last thing, the receipts at the bottom: this is perl v5.36.0, dated 2022-10-13, and the whole thing is Tie::DxHash(3pm). love that for us. go tie a hash, bestie, go crazy 🎀💖🦋

📦 where this page comes from