1Dumper(3) User Contributed Perl Documentation Dumper(3)
2
6 PDL::IO::Dumper -- data dumping for structs with PDLs
7
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 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 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 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. (You have to have access to either
29 uuencode(1) or the CPAN module Convert::UU for this to work).
30 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
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
39 external-hook variables aren't recognized (for that a more universal
40 Dumper would be needed) and will still exercise the Data::Dumper crash.
41 This is by choice: (A) it's difficult to recognize which objects are
42 actually external, and (B) most everyday objects are quite safe.
43 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
48 headers (see the rfits documentation in PDL::IO::Misc for details).
49 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
56 Copyright 2002, Craig DeForest.
57 This code may be distributed under the same terms as Perl itself
59 (license available at <http://ww.perl.org>). Copying, reverse
60 engineering, distribution, and modification are explicitly allowed so
61 long as this notice is preserved intact and modified versions are
62 clearly marked as such.
63 This package comes with NO WARRANTY.
65
67 • 1.0: initial release
68 • 1.1 (26-Feb-2002): Shorter form for short PDLs; more readability
70 • 1.2 (28-Feb-2002): Added deep_copy() -- exported convenience
72 function
73 for "eval sdump"
74 • 1.3 (15-May-2002): Added checking for tied objects in gethdr()
76 [workaround for hole in Data::Dumper]
77 • 1.4 (15-Jan-2003): Added support for Convert::UU as well as
79 command-line uu{en|de}code
80
82 sdump
83 Dump a data structure to a string.
84 use PDL::IO::Dumper;
86 $s = sdump(<VAR>);
87 ...
88 <VAR> = eval $s;
89 sdump dumps a single complex data structure into a string. You restore
91 the data structure by eval-ing the string. Since eval is a builtin, no
92 convenience routine exists to use it.
93 fdump
95 Dump a data structure to a file
96 use PDL::IO::Dumper;
98 fdump(<VAR>,$filename);
99 ...
100 <VAR> = frestore($filename);
101 fdump dumps a single complex data structure to a file. You restore the
103 data structure by eval-ing the perl code put in the file. A
104 convenience routine (frestore) exists to do it for you.
105 I suggest using the extension '.pld' or (for non-broken OS's) '.pdld'
107 to distinguish Dumper files. That way they are reminiscent of .pl
108 files for perl, while still looking a little different so you can pick
109 them out. You can certainly feed a dump file straight into perl (for
110 syntax checking) but it will not do much for you, just build your data
111 structure and exit.
112 frestore
114 Restore a dumped file
115 use PDL::IO::Dumper;
117 fdump(<VAR>,$filename);
118 ...
119 <VAR> = frestore($filename);
120 frestore() is a convenience function that just reads in the named file
122 and executes it in an eval. It's paired with fdump().
123 deep_copy
125 Convenience function copies a complete perl data structure by the brute
126 force method of "eval sdump".
127 PDL::IO::Dumper::big_PDL
129 Identify whether a PDL is ``big'' [Internal routine]
130 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 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 PDL::IO::Dumper::stringify_PDL
141 Turn a PDL into a 1-part perl expr [Internal routine]
142 Internal routine that takes a PDL and returns a perl string that evals
144 to the PDL. It should be used with care because it doesn't dump
145 headers and it doesn't check number of elements. The point here is
146 that numbers are dumped with the correct precision for their storage
147 class. Things we don't know about get stringified element-by-element
148 by their builtin class, which is probably not a bad guess.
149 PDL::IO::Dumper::uudecode_PDL
151 Recover a PDL from a uuencoded string [Internal routine]
152 This routine encapsulates uudecoding of the dumped string for large
154 ndarrays. It's separate to encapsulate the decision about which method
155 of uudecoding to try (both the built-in Convert::UU and the shell
156 command uudecode(1) are supported).
157 PDL::IO::Dumper::dump_PDL
159 Generate 1- or 2-part expr for a PDL [Internal routine]
160 Internal routine that produces commands defining a PDL. You supply
162 (<PDL>, <name>) and get back two strings: a prepended command string
163 and an expr that evaluates to the final PDL. PDL is the PDL you want
164 to dump. <inline> is a flag whether dump_PDL is being called inline or
165 before the inline dump string (0 for before; 1 for in). <name> is the
166 name of the variable to be assigned (for medium and large PDLs, which
167 are defined before the dump string and assigned unique IDs).
168 PDL::IO::Dumper::find_PDLs
170 Walk a data structure and dump PDLs [Internal routine]
171 Walks the original data structure and generates appropriate exprs for
173 each PDL. The exprs are inserted into the Data::Dumper output string.
174 You shouldn't call this unless you know what you're doing. (see sdump,
175 above).
176perl v5.34.0 2021-08-16 Dumper(3)