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
10       structures which include PDLs, as ASCII strings and/or transportable
11       ASCII files.  It exports four functions into your namespace: sdump,
12       fdump, 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
24       output is for non-PDL expressions. To that end, small PDLs (up to 8
25       elements) are stored as inline perl expressions, midsized PDLs (up to
26       200 elements) are stored as perl expressions above the main data
27       structure, and large PDLs are stored as FITS files that are uuencoded
28       and included in the dump string.
29
30       No attempt is made to shrink the output string -- for example, inlined
31       PDL expressions all include explicit reshape() and typecast commands,
32       and uuencoding expands stuff by a factor of about 1.5.  So your data
33       structures will grow when you dump them.
34

Bugs

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

FUNCTIONS

55   sdump
56       Dump a data structure to a string.
57
58         use PDL::IO::Dumper;
59         $s = sdump(<VAR>);
60         ...
61         <VAR> = eval $s;
62
63       sdump dumps a single complex data structure into a string.  You restore
64       the data structure by eval-ing the string.  Since eval is a builtin, no
65       convenience routine exists to use it.
66
67   fdump
68       Dump a data structure to a file
69
70         use PDL::IO::Dumper;
71         fdump(<VAR>,$filename);
72         ...
73         <VAR> = frestore($filename);
74
75       fdump dumps a single complex data structure to a file.  You restore the
76       data structure by eval-ing the perl code put in the file.  A
77       convenience routine (frestore) exists to do it for you.
78
79       I suggest using the extension '.pld' or (for non-broken OS's) '.pdld'
80       to distinguish Dumper files.  That way they are reminiscent of .pl
81       files for perl, while still looking a little different so you can pick
82       them out.  You can certainly feed a dump file straight into perl (for
83       syntax checking) but it will not do much for you, just build your data
84       structure and exit.
85
86   frestore
87       Restore a dumped file
88
89         use PDL::IO::Dumper;
90         fdump(<VAR>,$filename);
91         ...
92         <VAR> = frestore($filename);
93
94       frestore() is a convenience function that just reads in the named file
95       and executes it in an eval.  It's paired with fdump().
96
97   deep_copy
98       Convenience function copies a complete perl data structure by the brute
99       force method of "eval sdump".
100
101   PDL::IO::Dumper::big_PDL
102       Identify whether a PDL is ``big'' [Internal routine]
103
104       Internal routine takes a PDL and returns a boolean indicating whether
105       it's small enough for direct insertion into the dump string.  If 0, it
106       can be inserted.  Larger numbers yield larger scopes of PDL.  1 implies
107       that it should be broken out but can be handled with a couple of perl
108       commands; 2 implies full uudecode treatment.
109
110       PDLs with Astro::FITS::Header objects as headers are taken to be FITS
111       files and are always treated as huge, regardless of size.
112
113   PDL::IO::Dumper::stringify_PDL
114       Turn a PDL into a 1-part perl expr [Internal routine]
115
116       Internal routine that takes a PDL and returns a perl string that evals
117       to the PDL.  It should be used with care because it doesn't dump
118       headers and it doesn't check number of elements.  The point here is
119       that numbers are dumped with the correct precision for their storage
120       class.  Things we don't know about get stringified element-by-element
121       by their builtin class, which is probably not a bad guess.
122
123   PDL::IO::Dumper::uudecode_PDL
124       Recover a PDL from a uuencoded string [Internal routine]
125
126       This routine encapsulates uudecoding of the dumped string for large
127       ndarrays.
128
129   PDL::IO::Dumper::dump_PDL
130       Generate 1- or 2-part expr for a PDL [Internal routine]
131
132       Internal routine that produces commands defining a PDL.  You supply
133       (<PDL>, <name>) and get back two strings: a prepended command string
134       and an expr that evaluates to the final PDL.  PDL is the PDL you want
135       to dump.  <inline> is a flag whether dump_PDL is being called inline or
136       before the inline dump string (0 for before; 1 for in).  <name> is the
137       name of the variable to be assigned (for medium and large PDLs, which
138       are defined before the dump string and assigned unique IDs).
139
140   PDL::IO::Dumper::find_PDLs
141       Walk a data structure and dump PDLs [Internal routine]
142
143       Walks the original data structure and generates appropriate exprs for
144       each PDL.  The exprs are inserted into the Data::Dumper output string.
145       You shouldn't call this unless you know what you're doing.  (see sdump,
146       above).
147

AUTHOR

149       Copyright 2002, Craig DeForest.
150
151       This code may be distributed under the same terms as Perl itself
152       (license available at <http://www.perl.org>).  Copying, reverse
153       engineering, distribution, and modification are explicitly allowed so
154       long as this notice is preserved intact and modified versions are
155       clearly marked as such.
156
157       This package comes with NO WARRANTY.
158
159
160
161perl v5.36.0                      2023-01-20                         Dumper(3)
Impressum