1Denter(3) User Contributed Perl Documentation Denter(3)
2
6 Data::Denter - An (deprecated) alternative to Data::Dumper and
7 Storable.
8
10 use YAML; # Instead!!!
11 "Data::Denter" was a good idea for many reasons. In May 2001, the
13 module got noticed by a couple of brilliant people who were working on
14 a project called YAML (YAML Ain't Markup Language). They asked me to
15 join them, and I did. Since then we have been working almost daily on
16 this new serialization language. For much more information, see
17 <http://www.yaml.org>.
18 YAML has all the nice qualities that "Data::Denter" does. You should
20 find that YAML actually improves upon "Data::Denter" in both
21 readability and completeness. YAML's number one design goal is human
22 readability.
23 Another large benefit of YAML is that it is a programming language
25 independent serialization language. Implementations currently exist for
26 Perl, Python, Ruby and Java. In addition, YAML is unicode based, has
27 extensible typing and allows stream based processing.
28 "Data::Denter" has served its purpose and is now being fully deprecated
30 in favor of "YAML.pm". I have made "YAML.pm" a module prerequisite for
31 "Data::Denter", so if you used the CPAN shell to install
32 "Data::Denter", you may actually already have "YAML.pm" installed. If
33 you really don't want YAML on your system, "Data::Denter" will run fine
34 without it.
35 This final release of "Data::Denter" contains all of the patches that
37 have been sent to me. If you really need this module patched further, I
38 will be happy to do so. But seriously consider switching to YAML.
39
41 use Data::Denter;
42 use Data::Dumper;
43 my $hh = bless {Easter => "Bunny",
45 Christmas => ["Santa", "Grinch"],
46 }, "Holiday::Hackers";
47 print "*** Data::Denter #1 ***\n";
49 print Denter $hh;
50 print "*** Data::Dumper #1 ***\n";
51 print Dumper $hh;
52 my $dented = Indent([ qw(one two three), {one=>1}, [2], \3 ],
54 {"I\nLove\n" => undef});
55 process($dented);
56 sub process {
58 my $dented = shift;
59 my @data = Undent $dented;
60 print "\n*** Data::Denter #2 ***\n";
61 print $dented;
62 print "*** Data::Dumper #2 ***\n";
63 print Dumper @data;
64 }
65
67 *** Data::Denter #1 ***
68 %Holiday::Hackers
69 Christmas => @
70 Santa
71 Grinch
72 Easter => Bunny
73 *** Data::Dumper #1 ***
74 $VAR1 = bless( {
75 'Easter' => 'Bunny',
76 'Christmas' => [
77 'Santa',
78 'Grinch'
79 ]
80 }, 'Holiday::Hackers' );
81 *** Data::Denter #2 ***
83 @
84 one
85 two
86 three
87 %
88 one => 1
89 @
90 2
91 $
92 3
93 %
94 <<EOK => ?
95 I
96 Love
97 EOK
98 *** Data::Dumper #2 ***
99 $VAR1 = [
100 'one',
101 'two',
102 'three',
103 {
104 'one' => '1'
105 },
106 [
107 '2'
108 ],
109 \'3'
110 ];
111 $VAR2 = {
112 'I
113 Love
114 ' => undef
115 };
116
118 The main problem with Data::Dumper (one of my all-time favorite
119 modules) is that you have to use "eval()" to deserialize the data
120 you've dumped. This is great if you can trust the data you're evaling,
121 but horrible if you can't. A good alternative is Storable.pm. It can
122 safely thaw your frozen data. But if you want to read/edit the frozen
123 data, you're out of luck, because Storable uses a binary format. Even
124 Data::Dumper's output can be a little cumbersome for larger data
125 objects.
126 Enter Data::Denter.
128 Data::Denter is yet another Perl data serializer/deserializer. It
130 formats nested data structures in an indented fashion. It is optimized
131 for human readability/editability, safe deserialization, and
132 (eventually) speed.
133 NOTE: It may be optimized for Python programmers too, but please don't
135 hold that against me ;)
136 It exports 2 functions: "Indent()" and "Undent()" for serialization and
138 deserialization respectively. It also exports "Denter()" which is an
139 alias to "Indent()". (People who use Data::Dumper will appreciate
140 this). You can even import "Dumper()" (another "Indent" alias) for
141 easily toggling between Data::Dumper and Data::Denter style formatting.
142 Data::Denter handles all of the commonly serializable Perl data types,
144 including: scalars, hash refs, array refs, scalar refs, ref refs,
145 undef, and blessed references. Other references will simply be
146 formatted in their string forms. It can even properly handle circular
147 and duplicate references.
148 Data::Denter has 3 different forms of quoting string values depending
150 on their complexity: no quotes, double quotes, and here-doc quoting. It
151 also has a special symbol for undefined values.
152
154 Data::Denter uses it's own markup syntax, which is designed to be
155 minimal, yet complete. It borrows familiar symbols from Perl, and
156 structured indenting from Python. The following symbols are used:
157 % - a hash reference
159 @ - an array reference
160 $ - a scalar reference
161 \ - a reference of another reference
162 ? - undef
163 " - used to quote string values that begin with other
164 markup characters, but do not contain newlines
165 <<EOV - quote values with embedded newlines using
166 a here-doc syntax
167 <<EOV- - same as above, but chomp final newline
168 <<EOK - quote hash keys with embedded newlines
169 => - used to separate key value pairs
170 (REF#) - Indicates the first instance of a duplicate reference
171 (*REF#-#) - Indicates the dereference of a duplicate reference
172 Any of the data type references ( %, @, $ ) may be followed by a
174 classname if they were blessed. For instance:
175 print Indent( $h = bless { Name => 'Ingy', Rank => 'JAPH' }, "Hacker" );
177 would produce:
179 %Hacker
181 Name => Ingy
182 Rank => JAPH
183 If the data contains duplicate references, only the first one is
185 dumped. The rest use a reference marker. Continuing on with the above
186 code:
187 $h->{me} = $h;
189 $h->{myself} = \\$h;
190 $h->{I} = [ $h->{me}, $h->{myself} ];
191 print Indent $h;
192 would produce:
194 %Hacker(REF00001)
196 I => @
197 %Hacker(*REF00001-1)
198 \(REF00002)\%Hacker(*REF00001-2)
199 Name => Ingy
200 Rank => JAPH
201 me => %Hacker(*REF00001-3)
202 myself => \(*REF00002-1)
203 This is how Data::Denter can serialize and deserialize data with
205 circular references.
206
208 Indent
209 $string = Indent(list of scalars or typeglob/scalar pairs);
210 This function will serialize a list of scalars. A typeglob like
212 '*myhash' may be specified before any scalar to give the scalar a name.
213 Undent
215 @list = Undent(serialized-data-string);
216 This function will deserialize an Indented data string into a list of
218 Perl scalars that are equivalent to the original pre-Indented objects.
219
221 Sort
222 $Data::Denter::Sort tells Data::Denter whether or not to display hash
223 keys in a sorted order. Values are 0 and 1. Default is 1. (That's
224 right. The default is to sort the hash keys.)
225 MaxLines
227 $Data::Denter::MaxLines is an option for limiting the number of lines
228 to be displayed in a string value represented with the Here-Doc syntax.
229 Default is '0', which means "show all lines".
230 HashMode
232 $Data::Denter::HashMode turns "Hash Mode" on and off. Default is '0'.
233 This mode requires a bit of explanation:
234 "Hash Mode" is useful when you want to use Data::Denter for a config
236 file where you have named options. It assumes that the list of
237 arguments that you pass to the "Indent()" function is a set of
238 key/value pairs. This produces the same output that you would get if
239 you specified the data as typeglob/value pairs in non-HashMode. NOTE:
240 The keys are restricted to only containing word (\w) characters.
241 For example if you wanted to set up a config file with 3 options, you
243 might choose a format like this:
244 option1 => value1
246 option2 => value2
247 option3 => @
248 sub-value-a
249 sub-value-b
250 To read this into Perl you could say:
252 use Data::Dumper;
254 use Data::Denter;
255 $Data::Denter::HashMode = 1;
256 open CONFIG, 'config' or die $!;
257 my %config = Undent join '', <CONFIG>;
258 print Dumper \%config;
259 This produces:
261 $VAR1 = {
263 'option1' => 'value1',
264 'option2' => 'value2',
265 'option3' => [
266 'sub-value-a',
267 'sub-value-b'
268 ]
269 };
270 Now you can use %config for your configuration information. To write
272 the configuration back to disk, simply do this:
273 open CONFIG, "> config" or die $!;
275 print CONFIG Indent(%config);
276 As a counter-example, with $Data::Denter::HashMode set to '0', the
278 above program would produce:
279 $VAR1 = {
281 '*main::option1' => 'value1',
282 '*main::option2' => 'value2',
283 '*main::option3' => [
284 'sub-value-a',
285 'sub-value-b'
286 ]
287 };
288 Which is not what you want.
290 Comma
292 $Data::Denter::Comma is a string used to separate hash keys and values.
293 Default is ' => '.
294 Width
296 $Data::Denter::Width is the indentation width. Default is 4.
297 TabWidth
299 $Data::Denter::TabWidth is the number of spaces represented by leading
300 tabs that may have been introduced by editing a serialized file.
301 Default is 8.
302 Level
304 Experimental. Starting indent level. Default is 0.
305
307 print Data::Denter->new(width => 2)->indent($foo, $bar);
308 All methods and options use lowercase with the OO style syntax, as
310 opposed to TitleCase with the functional interface.
311
313 1. Data::Denter handles a lot of strange data. One thing it does not
314 yet handle are refs blessed with strings containing characters that
315 are not allowed in package names. People who do this are strange.
316 2. Written in pure (unoptimized) Perl, so probably not so fast yet.
318 But since the Indented format can be parsed in one pass, with no
319 lookaheads, a C implementation would be extremely fast.
320
322 Brian Ingerson <INGY@cpan.org>
323
325 Copyright (c) 2001, 2002, Brian Ingerson. All rights reserved.
326 This program is free software; you can redistribute it and/or modify it
328 under the same terms as Perl itself.
329 See http://www.perl.com/perl/misc/Artistic.html
331
333 YAML
334 Data::Dumper
336 Storable
338perl v5.32.0 2020-07-28 Denter(3)