Denter(3) User Contributed Perl Documentation Denter(3)NAMEData::Denter - An (deprecated) alternative to Data::Dumper and
Storable.
NOTE NOTE NOTE
use YAML; # Instead!!!
"Data::Denter" was a good idea for many reasons. In May 2001, the
module got noticed by a couple of brilliant people who were working on
a project called YAML (YAML Ain't Markup Language). They asked me to
join them, and I did. Since then we have been working almost daily on
this new serialization language. For much more information, see
<http://www.yaml.org>.
YAML has all the nice qualities that "Data::Denter" does. You should
find that YAML actually improves upon "Data::Denter" in both
readability and completeness. YAML's number one design goal is human
readability.
Another large benefit of YAML is that it is a programming language
independent serialization language. Implementations currently exist for
Perl, Python, Ruby and Java. In addition, YAML is unicode based, has
extensible typing and allows stream based processing.
"Data::Denter" has served its purpose and is now being fully deprecated
in favor of "YAML.pm". I have made "YAML.pm" a module prerequisite for
"Data::Denter", so if you used the CPAN shell to install
"Data::Denter", you may actually already have "YAML.pm" installed. If
you really don't want YAML on your system, "Data::Denter" will run fine
without it.
This final release of "Data::Denter" contains all of the patches that
have been sent to me. If you really need this module patched further, I
will be happy to do so. But seriously consider switching to YAML.
SYNOPSIS
use Data::Denter;
use Data::Dumper;
my $hh = bless {Easter => "Bunny",
Christmas => ["Santa", "Grinch"],
}, "Holiday::Hackers";
print "*** Data::Denter #1 ***\n";
print Denter $hh;
print "*** Data::Dumper #1 ***\n";
print Dumper $hh;
my $dented = Indent([ qw(one two three), {one=>1}, [2], \3 ],
{"I\nLove\n" => undef});
process($dented);
sub process {
my $dented = shift;
my @data = Undent $dented;
print "\n*** Data::Denter #2 ***\n";
print $dented;
print "*** Data::Dumper #2 ***\n";
print Dumper @data;
}
SYNOPSIS OUTPUT
*** Data::Denter #1 ***
%Holiday::Hackers
Christmas => @
Santa
Grinch
Easter => Bunny
*** Data::Dumper #1 ***
$VAR1 = bless( {
'Easter' => 'Bunny',
'Christmas' => [
'Santa',
'Grinch'
]
}, 'Holiday::Hackers' );
*** Data::Denter #2 ***
@
one
two
three
%
one => 1
@
2
$
3
%
<<EOK => ?
I
Love
EOK
*** Data::Dumper #2 ***
$VAR1 = [
'one',
'two',
'three',
{
'one' => '1'
},
[
'2'
],
\'3'
];
$VAR2 = {
'I
Love
' => undef
};
DESCRIPTION
The main problem with Data::Dumper (one of my all-time favorite
modules) is that you have to use "eval()" to deserialize the data
you've dumped. This is great if you can trust the data you're evaling,
but horrible if you can't. A good alternative is Storable.pm. It can
safely thaw your frozen data. But if you want to read/edit the frozen
data, you're out of luck, because Storable uses a binary format. Even
Data::Dumper's output can be a little cumbersome for larger data
objects.
Enter Data::Denter.
Data::Denter is yet another Perl data serializer/deserializer. It
formats nested data structures in an indented fashion. It is optimized
for human readability/editability, safe deserialization, and
(eventually) speed.
NOTE: It may be optimized for Python programmers too, but please don't
hold that against me ;)
It exports 2 functions: "Indent()" and "Undent()" for serialization and
deserialization respectively. It also exports "Denter()" which is an
alias to "Indent()". (People who use Data::Dumper will appreciate
this). You can even import "Dumper()" (another "Indent" alias) for
easily toggling between Data::Dumper and Data::Denter style formatting.
Data::Denter handles all of the commonly serializable Perl data types,
including: scalars, hash refs, array refs, scalar refs, ref refs,
undef, and blessed references. Other references will simply be
formatted in their string forms. It can even properly handle circular
and duplicate references.
Data::Denter has 3 different forms of quoting string values depending
on their complexity: no quotes, double quotes, and here-doc quoting. It
also has a special symbol for undefined values.
UNDERSTANDING THE DENTER FORMATData::Denter uses it's own markup syntax, which is designed to be
minimal, yet complete. It borrows familiar symbols from Perl, and
structured indenting from Python. The following symbols are used:
% - a hash reference
@ - an array reference
$ - a scalar reference
\ - a reference of another reference
? - undef
" - used to quote string values that begin with other
markup characters, but do not contain newlines
<<EOV - quote values with embedded newlines using
a here-doc syntax
<<EOV- - same as above, but chomp final newline
<<EOK - quote hash keys with embedded newlines
=> - used to separate key value pairs
(REF#) - Indicates the first instance of a duplicate reference
(*REF#-#) - Indicates the dereference of a duplicate reference
Any of the data type references ( %, @, $ ) may be followed by a
classname if they were blessed. For instance:
print Indent( $h = bless { Name => 'Ingy', Rank => 'JAPH' }, "Hacker" );
would produce:
%Hacker
Name => Ingy
Rank => JAPH
If the data contains duplicate references, only the first one is
dumped. The rest use a reference marker. Continuing on with the above
code:
$h->{me} = $h;
$h->{myself} = \\$h;
$h->{I} = [ $h->{me}, $h->{myself} ];
print Indent $h;
would produce:
%Hacker(REF00001)
I => @
%Hacker(*REF00001-1)
\(REF00002)\%Hacker(*REF00001-2)
Name => Ingy
Rank => JAPH
me => %Hacker(*REF00001-3)
myself => \(*REF00002-1)
This is how Data::Denter can serialize and deserialize data with
circular references.
FUNCTIONS
Indent
$string = Indent(list of scalars or typeglob/scalar pairs);
This function will serialize a list of scalars. A typeglob like
'*myhash' may be specified before any scalar to give the scalar a name.
Undent
@list = Undent(serialized-data-string);
This function will deserialize an Indented data string into a list of
Perl scalars that are equivalent to the original pre-Indented objects.
OPTIONS
Sort
$Data::Denter::Sort tells Data::Denter whether or not to display hash
keys in a sorted order. Values are 0 and 1. Default is 1. (That's
right. The default is to sort the hash keys.)
MaxLines
$Data::Denter::MaxLines is an option for limiting the number of lines
to be displayed in a string value represented with the Here-Doc syntax.
Default is '0', which means "show all lines".
HashMode
$Data::Denter::HashMode turns "Hash Mode" on and off. Default is '0'.
This mode requires a bit of explanation:
"Hash Mode" is useful when you want to use Data::Denter for a config
file where you have named options. It assumes that the list of
arguments that you pass to the "Indent()" function is a set of
key/value pairs. This produces the same output that you would get if
you specified the data as typeglob/value pairs in non-HashMode. NOTE:
The keys are restricted to only containing word (\w) characters.
For example if you wanted to set up a config file with 3 options, you
might choose a format like this:
option1 => value1
option2 => value2
option3 => @
sub-value-a
sub-value-b
To read this into Perl you could say:
use Data::Dumper;
use Data::Denter;
$Data::Denter::HashMode = 1;
open CONFIG, 'config' or die $!;
my %config = Undent join '', <CONFIG>;
print Dumper \%config;
This produces:
$VAR1 = {
'option1' => 'value1',
'option2' => 'value2',
'option3' => [
'sub-value-a',
'sub-value-b'
]
};
Now you can use %config for your configuration information. To write
the configuration back to disk, simply do this:
open CONFIG, "> config" or die $!;
print CONFIG Indent(%config);
As a counter-example, with $Data::Denter::HashMode set to '0', the
above program would produce:
$VAR1 = {
'*main::option1' => 'value1',
'*main::option2' => 'value2',
'*main::option3' => [
'sub-value-a',
'sub-value-b'
]
};
Which is not what you want.
Comma
$Data::Denter::Comma is a string used to separate hash keys and values.
Default is ' => '.
Width
$Data::Denter::Width is the indentation width. Default is 4.
TabWidth
$Data::Denter::TabWidth is the number of spaces represented by leading
tabs that may have been introduced by editing a serialized file.
Default is 8.
Level
Experimental. Starting indent level. Default is 0.
OO-Style
print Data::Denter->new(width => 2)->indent($foo, $bar);
All methods and options use lowercase with the OO style syntax, as
opposed to TitleCase with the functional interface.
KNOWN BUGS & LIMITATIONS
1. Data::Denter handles a lot of strange data. One thing it does not
yet handle are refs blessed with strings containing characters that
are not allowed in package names. People who do this are strange.
2. Written in pure (unoptimized) Perl, so probably not so fast yet.
But since the Indented format can be parsed in one pass, with no
lookaheads, a C implementation would be extremely fast.
AUTHOR
Brian Ingerson <INGY@cpan.org>
COPYRIGHT
Copyright (c) 2001, 2002, Brian Ingerson. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
SEE ALSO
YAML
Data::Dumper
Storable
perl v5.14.1 2002-10-18 Denter(3)
