projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tie::DxHash.3
CommitLineData
86530b38
AT		 1.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
24.fi
25..
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
58..
59. nr % 0
60. rr F
61.\}
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "Tie::DxHash 3"
132.TH Tie::DxHash 3 "2001-06-15" "perl v5.8.0" "User Contributed Perl Documentation"
133.SH "NAME"
134Tie::DxHash \- keeps insertion order; allows duplicate keys
135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS"
137.Vb 10
138\& use Tie::DxHash;
139\& my(%vhost);
140\& tie %vhost, 'Tie::DxHash' [, LIST];
141\& %vhost = (
142\& ServerName => 'foo',
143\& RewriteCond => 'bar',
144\& RewriteRule => 'bletch',
145\& RewriteCond => 'phooey',
146\& RewriteRule => 'squelch',
147\& );
148.Ve
149.SH "DESCRIPTION"
150.IX Header "DESCRIPTION"
151This module was written to allow the use of rewrite rules in Apache
152configuration files written with Perl Sections. However, a potential user has
153stated that he needs it to support the use of multiple ScriptAlias directives
154within a single Virtual Host (which is required by FrontPage, apparently). If
155you find a completely different use for it, great.
156.PP
157The original purpose of this module is not quite so obscure as it might sound.
158Perl Sections bring the power of a general-purpose programming language to
159Apache configuration files and, having used them once, many people use them
160throughout. (I take this approach since, even in sections of the configuration
161where I do not need the flexibility, I find it easier to use a consistent
162syntax. This also makes the code easier for XEmacs to colour in ;\-) Similarly,
163mod_rewrite is easily the most powerful way to perform \s-1URL\s0 rewriting and I tend
164to use it exclusively, even when a simpler directive would do the trick, in
165order to group my redirections together and keep them consistent. So, I came up
166against the following problem quite early on.
167.PP
168The synopsis shows some syntax which might be needed when using mod_rewrite
169within a Perl Section. Clearly, using an ordinary hash will not do what you
170want. The two additional features we need are to preserve insertion order and
171to allow duplicate keys. When retrieving an element from the hash by name,
172successive requests for the same name must iterate through the duplicate entries
173(and, presumably, wrap around when the end of the chain is reached). This is
174where Tie::DxHash comes in. Simply by tying the offending hash, the
175corresponding configuration directives work as expected.
176.PP
177Running an Apache syntax check (with docroot check) on your configuration file
178(with \f(CW\*(C`httpd \-t\*(C'\fR) and checking virtual host settings (with \f(CW\*(C`httpd \-S\*(C'\fR) succeed
179without complaint. Incidentally, I strongly recommend building your Apache
180configuration files with make (or equivalent) in order to enforce the above two
181checks, preceded by a Perl syntax check (with \f(CW\*(C`perl \-cx\*(C'\fR).
182.SH "INTERNALS"
183.IX Header "INTERNALS"
184For those interested, Tie::IxHash works by storing the hash data in an array of
185hash references (containing the key/value pairs). This preserves insertion
186order. A separate set of iterators (one per distinct key) keeps track of the
187last retrieved value for a given key, thus allowing the successive retrieval of
188multiple values for the same key to work as expected.
189.SH "SEE ALSO"
190.IX Header "SEE ALSO"
191\&\fIperltie\fR\|(1), for information on ties generally.
192.PP
193\&\fITie::IxHash\fR\|(3), by Gurusamy Sarathy, if you need to preserve insertion order but
194not allow duplicate keys.
195.PP
196For information on Ralf S. Engelschall's powerful \s-1URL\s0 rewriting module,
197mod_rewrite, check out the reference documentation at
198\&\*(L"http://httpd.apache.org/docs/mod/mod_rewrite.html\*(R" and the \s-1URL\s0 Rewriting Guide
199at \*(L"http://httpd.apache.org/docs/misc/rewriteguide.html\*(R".
200.PP
201For help in using Perl Sections to configure Apache, take a look at the section
202called \*(L"Apache Configuration in Perl\*(R" at
203\&\*(L"http://perl.apache.org/guide/config.html#Apache_Configuration_in_Perl\*(R", part of
204the mod_perl guide, by Stas Bekman. Alternatively, buy the O'Reilly book
205Writing Apache Modules with Perl and C, by Lincoln Stein & Doug MacEachern, and
206study Chapter 8: Customizing the Apache Configuration Process.
207.SH "BUGS"
208.IX Header "BUGS"
209The algorithms used to retrieve and delete elements by key run in O(N) time, so
210do not expect this module to work well on large data sets. This is not a
211problem for the module's intended use. If you find another use for the module
212which involves larger quantities of data, let me know and I will put some effort
213into optimising for speed.
214.PP
215The mod_rewrite directives for which this module was written (primarily
216RewriteCond and RewriteRule) can occur in all four configuration file contexts
217(i.e. server config, virtual host, directory, .htaccess). However, Tie::DxHash
218only helps when you are using a directive which is mapped onto a Perl hash.
219This limits you to directives which are block sections with begin and end tags
220(like <VirtualHost> and <Directory>). I get round this by sticking my
221mod_rewrite directives in a name-based virtual host container (as shown in the
222synopsis) even in the degenerate case where the web server only has one virtual
223host.
224.SH "AUTHOR"
225.IX Header "AUTHOR"
226Kevin Ruscoe
Full OpenSPARC design & verification tarball including full HDL.