1Denter(3)             User Contributed Perl Documentation            Denter(3)
2
3
4

NAME

6       Data::Denter - An (deprecated) alternative to Data::Dumper and
7       Storable.
8

NOTE NOTE NOTE

10           use YAML; # Instead!!!
11
12       "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
19       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
24       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
29       "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
36       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

SYNOPSIS

41           use Data::Denter;
42           use Data::Dumper;
43
44           my $hh = bless {Easter => "Bunny",
45                           Christmas => ["Santa", "Grinch"],
46                          }, "Holiday::Hackers";
47
48           print "*** Data::Denter #1 ***\n";
49           print Denter $hh;
50           print "*** Data::Dumper #1 ***\n";
51           print Dumper $hh;
52
53           my $dented = Indent([ qw(one two three), {one=>1}, [2], \3 ],
54                               {"I\nLove\n" => undef});
55           process($dented);
56
57           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

SYNOPSIS OUTPUT

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
82           *** 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

DESCRIPTION

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
127       Enter Data::Denter.
128
129       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
134       NOTE: It may be optimized for Python programmers too, but please don't
135       hold that against me ;)
136
137       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
143       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
149       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

UNDERSTANDING THE DENTER FORMAT

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
158           %         - 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
173       Any of the data type references ( %, @, $ ) may be followed by a
174       classname if they were blessed. For instance:
175
176           print Indent( $h = bless { Name => 'Ingy', Rank => 'JAPH' }, "Hacker" );
177
178       would produce:
179
180           %Hacker
181               Name => Ingy
182               Rank => JAPH
183
184       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
188            $h->{me} = $h;
189            $h->{myself} = \\$h;
190            $h->{I} = [ $h->{me}, $h->{myself} ];
191            print Indent $h;
192
193       would produce:
194
195           %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
204       This is how Data::Denter can serialize and deserialize data with
205       circular references.
206

FUNCTIONS

208   Indent
209           $string = Indent(list of scalars or typeglob/scalar pairs);
210
211       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
214   Undent
215           @list = Undent(serialized-data-string);
216
217       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

OPTIONS

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
226   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
231   HashMode
232       $Data::Denter::HashMode turns "Hash Mode" on and off. Default is '0'.
233       This mode requires a bit of explanation:
234
235       "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
242       For example if you wanted to set up a config file with 3 options, you
243       might choose a format like this:
244
245           option1 => value1
246           option2 => value2
247           option3 => @
248               sub-value-a
249               sub-value-b
250
251       To read this into Perl you could say:
252
253           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
260       This produces:
261
262           $VAR1 = {
263                     'option1' => 'value1',
264                     'option2' => 'value2',
265                     'option3' => [
266                                    'sub-value-a',
267                                    'sub-value-b'
268                                  ]
269                   };
270
271       Now you can use %config for your configuration information. To write
272       the configuration back to disk, simply do this:
273
274           open CONFIG, "> config" or die $!;
275           print CONFIG Indent(%config);
276
277       As a counter-example, with $Data::Denter::HashMode set to '0', the
278       above program would produce:
279
280           $VAR1 = {
281                     '*main::option1' => 'value1',
282                     '*main::option2' => 'value2',
283                     '*main::option3' => [
284                                           'sub-value-a',
285                                           'sub-value-b'
286                                         ]
287                   };
288
289       Which is not what you want.
290
291   Comma
292       $Data::Denter::Comma is a string used to separate hash keys and values.
293       Default is ' => '.
294
295   Width
296       $Data::Denter::Width is the indentation width. Default is 4.
297
298   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
303   Level
304       Experimental. Starting indent level. Default is 0.
305

OO-Style

307           print Data::Denter->new(width => 2)->indent($foo, $bar);
308
309       All methods and options use lowercase with the OO style syntax, as
310       opposed to TitleCase with the functional interface.
311

KNOWN BUGS & LIMITATIONS

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
317       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

AUTHOR

322       Brian Ingerson <INGY@cpan.org>
323
325       Copyright (c) 2001, 2002, Brian Ingerson. All rights reserved.
326
327       This program is free software; you can redistribute it and/or modify it
328       under the same terms as Perl itself.
329
330       See http://www.perl.com/perl/misc/Artistic.html
331

SEE ALSO

333       YAML
334
335       Data::Dumper
336
337       Storable
338
339
340
341perl v5.34.0                      2022-01-21                         Denter(3)
Impressum