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

NAME

6       PDL::IO::Dumper -- data dumping for structs with PDLs
7

DESCRIPTION

9       This package allows you cleanly to save and restore complex data struc‐
10       tures which include PDLs, as ASCII strings and/or transportable ASCII
11       files.  It exports four functions into your namespace: sdump, fdump,
12       frestore, and deep_copy.
13
14       PDL::IO::Dumper traverses the same types of structure that Data::Dumper
15       knows about, because it uses a call to Data::Dumper.  Unlike
16       Data::Dumper it doesn't crash when accessing PDLs.
17
18       The PDL::IO::Dumper routines have a slightly different syntax than
19       Data::Dumper does: you may only dump a single scalar perl expression
20       rather than an arbitrary one.  Of course, the scalar may be a ref to
21       whatever humongous pile of spaghetti you want, so that's no big loss.
22
23       The output string is intended to be about as readable as Dumper's out‐
24       put is for non-PDL expressions. To that end, small PDLs (up to 8 ele‐
25       ments) are stored as inline perl expressions, midsized PDLs (up to 200
26       elements) are stored as perl expressions above the main data structure,
27       and large PDLs are stored as FITS files that are uuencoded and included
28       in the dump string. (You have to have access to either uuencode(1) or
29       the CPAN module Convert::UU for this to work).
30
31       No attempt is made to shrink the output string -- for example, inlined
32       PDL expressions all include explicit reshape() and typecast commands,
33       and uuencoding expands stuff by a factor of about 1.5.  So your data
34       structures will grow when you dump them.
35

Bugs

37       It's still possible to break this code and cause it to dump core, for
38       the same reason that Data::Dumper crashes.  In particular, other exter‐
39       nal-hook variables aren't recognized (for that a more universal Dumper
40       would be needed) and will still exercise the Data::Dumper crash.  This
41       is by choice:  (A) it's difficult to recognize which objects are actu‐
42       ally external, and (B) most everyday objects are quite safe.
43
44       Another shortfall of Data::Dumper is that it doesn't recognize tied
45       objects.  This might be a Good Thing or a Bad Thing depending on your
46       point of view, but it means that PDL::IO::Dumper includes a kludge to
47       handle the tied Astro::FITS::Header objects associated with FITS head‐
48       ers (see the rfits documentation in PDL::IO::Misc for details).
49
50       There's currently no reference recursion detection, so a non-treelike
51       reference topology will cause Dumper to buzz forever.  That will likely
52       be fixed in a future version.  Meanwhile a warning message finds likely
53       cases.
54

Author, copyright, no warranty

56       Copyright 2002, Craig DeForest.
57
58       This code may be distributed under the same terms as Perl itself
59       (license available at http://ww.perl.org).  Copying, reverse engineer‐
60       ing, distribution, and modification are explicitly allowed so long as
61       this notice is preserved intact and modified versions are clearly
62       marked as such.
63
64       This package comes with NO WARRANTY.
65

HISTORY

67       * 1.0: initial release
68       * 1.1 (26-Feb-2002): Shorter form for short PDLs; more readability
69       * 1.2 (28-Feb-2002): Added deep_copy() -- exported convenience function
70       for "eval sdump"
71       * 1.3 (15-May-2002): Added checking for tied objects in gethdr() [work‐
72       around for hole in Data::Dumper]
73       * 1.4 (15-Jan-2003): Added support for Convert::UU as well as command-
74       line uu{en⎪de}code
75

FUNCTIONS

77       sdump
78
79       Dump a data structure to a string.
80
81         use PDL::IO::Dumper;
82         $s = sdump(<VAR>);
83         ...
84         <VAR> = eval $s;
85
86       sdump dumps a single complex data structure into a string.  You restore
87       the data structure by eval-ing the string.  Since eval is a builtin, no
88       convenience routine exists to use it.
89
90       fdump
91
92       Dump a data structure to a file
93
94         use PDL::IO::Dumper;
95         fdump(<VAR>,$filename);
96         ...
97         <VAR> = frestore($filename);
98
99       fdump dumps a single complex data structure to a file.  You restore the
100       data structure by eval-ing the perl code put in the file.  A conve‐
101       nience routine (frestore) exists to do it for you.
102
103       I suggest using the extension '.pld' or (for non-broken OS's) '.pdld'
104       to distinguish Dumper files.  That way they are reminiscent of .pl
105       files for perl, while still looking a little different so you can pick
106       them out.  You can certainly feed a dump file straight into perl (for
107       syntax checking) but it will not do much for you, just build your data
108       structure and exit.
109
110       frestore
111
112       Restore a dumped file
113
114         use PDL::IO::Dumper;
115         fdump(<VAR>,$filename);
116         ...
117         <VAR> = frestore($filename);
118
119       frestore() is a convenience function that just reads in the named file
120       and executes it in an eval.  It's paired with fdump().
121
122       deep_copy
123
124       Convenience function copies a complete perl data structure by the brute
125       force method of "eval sdump".
126
127       PDL::IO::Dumper::big_PDL
128
129       Identify whether a PDL is ``big'' [Internal routine]
130
131       Internal routine takes a PDL and returns a boolean indicating whether
132       it's small enough for direct insertion into the dump string.  If 0, it
133       can be inserted.  Larger numbers yield larger scopes of PDL.  1 implies
134       that it should be broken out but can be handled with a couple of perl
135       commands; 2 implies full uudecode treatment.
136
137       PDLs with Astro::FITS::Header objects as headers are taken to be FITS
138       files and are always treated as huge, regardless of size.
139
140       PDL::IO::Dumper::stringify_PDL
141
142       Turn a PDL into a 1-part perl expr [Internal routine]
143
144       Internal routine that takes a PDL and returns a perl string that evals
145       to the PDL.  It should be used with care because it doesn't dump head‐
146       ers and it doesn't check number of elements.  The point here is that
147       numbers are dumped with the correct precision for their storage class.
148       Things we don't know about get stringified element-by-element by their
149       builtin class, which is probably not a bad guess.
150
151       PDL::IO::Dumper::uudecode_PDL
152
153       Recover a PDL from a uuencoded string [Internal routine]
154
155       This routine encapsulates uudecoding of the dumped string for large
156       piddles.  It's separate to encapsulate the decision about which method
157       of uudecoding to try (both the built-in Convert::UU and the shell com‐
158       mand uudecode(1) are supported).
159
160       PDL::IO::Dumper::dump_PDL
161
162       Generate 1- or 2-part expr for a PDL [Internal routine]
163
164       Internal routine that produces commands defining a PDL.  You supply
165       (<PDL>, <name>) and get back two strings: a prepended command string
166       and an expr that evaluates to the final PDL.  PDL is the PDL you want
167       to dump.  <inline> is a flag whether dump_PDL is being called inline or
168       before the inline dump string (0 for before; 1 for in).  <name> is the
169       name of the variable to be assigned (for medium and large PDLs, which
170       are defined before the dump string and assigned unique IDs).
171
172       PDL::IO::Dumper::find_PDLs
173
174       Walk a data structure and dump PDLs [Internal routine]
175
176       Walks the original data structure and generates appropriate exprs for
177       each PDL.  The exprs are inserted into the Data::Dumper output string.
178       You shouldn't call this unless you know what you're doing.  (see sdump,
179       above).
180
181
182
183perl v5.8.8                       2006-12-02                         Dumper(3)
Impressum