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.
29 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
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 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 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
55 sdump
56 Dump a data structure to a string.
57 use PDL::IO::Dumper;
59 $s = sdump(<VAR>);
60 ...
61 <VAR> = eval $s;
62 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 fdump
68 Dump a data structure to a file
69 use PDL::IO::Dumper;
71 fdump(<VAR>,$filename);
72 ...
73 <VAR> = frestore($filename);
74 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 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 frestore
87 Restore a dumped file
88 use PDL::IO::Dumper;
90 fdump(<VAR>,$filename);
91 ...
92 <VAR> = frestore($filename);
93 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 deep_copy
98 Convenience function copies a complete perl data structure by the brute
99 force method of "eval sdump".
100 PDL::IO::Dumper::big_PDL
102 Identify whether a PDL is ``big'' [Internal routine]
103 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 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 PDL::IO::Dumper::stringify_PDL
114 Turn a PDL into a 1-part perl expr [Internal routine]
115 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 PDL::IO::Dumper::uudecode_PDL
124 Recover a PDL from a uuencoded string [Internal routine]
125 This routine encapsulates uudecoding of the dumped string for large
127 ndarrays.
128 PDL::IO::Dumper::dump_PDL
130 Generate 1- or 2-part expr for a PDL [Internal routine]
131 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 PDL::IO::Dumper::find_PDLs
141 Walk a data structure and dump PDLs [Internal routine]
142 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
149 Copyright 2002, Craig DeForest.
150 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 This package comes with NO WARRANTY.
158perl v5.36.0 2023-01-20 Dumper(3)