.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Dumper 3pm" .TH Dumper 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PDL::IO::Dumper \-\- data dumping for structs with PDLs .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package allows you cleanly to save and restore complex data structures which include PDLs, as \s-1ASCII\s0 strings and/or transportable \s-1ASCII\s0 files. It exports four functions into your namespace: sdump, fdump, frestore, and deep_copy. .PP PDL::IO::Dumper traverses the same types of structure that Data::Dumper knows about, because it uses a call to Data::Dumper. Unlike Data::Dumper it doesn't crash when accessing PDLs. .PP The PDL::IO::Dumper routines have a slightly different syntax than Data::Dumper does: you may only dump a single scalar perl expression rather than an arbitrary one. Of course, the scalar may be a ref to whatever humongous pile of spaghetti you want, so that's no big loss. .PP The output string is intended to be about as readable as Dumper's output is for non-PDL expressions. To that end, small PDLs (up to 8 elements) are stored as inline perl expressions, midsized PDLs (up to 200 elements) are stored as perl expressions above the main data structure, and large PDLs are stored as \s-1FITS\s0 files that are uuencoded and included in the dump string. .PP No attempt is made to shrink the output string \*(-- for example, inlined \&\s-1PDL\s0 expressions all include explicit \fBreshape()\fR and typecast commands, and uuencoding expands stuff by a factor of about 1.5. So your data structures will grow when you dump them. .SH "Bugs" .IX Header "Bugs" It's still possible to break this code and cause it to dump core, for the same reason that Data::Dumper crashes. In particular, other external-hook variables aren't recognized (for that a more universal Dumper would be needed) and will still exercise the Data::Dumper crash. This is by choice: (A) it's difficult to recognize which objects are actually external, and (B) most everyday objects are quite safe. .PP Another shortfall of Data::Dumper is that it doesn't recognize tied objects. This might be a Good Thing or a Bad Thing depending on your point of view, but it means that PDL::IO::Dumper includes a kludge to handle the tied Astro::FITS::Header objects associated with \s-1FITS\s0 headers (see the rfits documentation in PDL::IO::Misc for details). .PP There's currently no reference recursion detection, so a non-treelike reference topology will cause Dumper to buzz forever. That will likely be fixed in a future version. Meanwhile a warning message finds likely cases. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "sdump" .IX Subsection "sdump" Dump a data structure to a string. .PP .Vb 4 \& use PDL::IO::Dumper; \& $s = sdump(); \& ... \& = eval $s; .Ve .PP sdump dumps a single complex data structure into a string. You restore the data structure by eval-ing the string. Since eval is a builtin, no convenience routine exists to use it. .SS "fdump" .IX Subsection "fdump" Dump a data structure to a file .PP .Vb 4 \& use PDL::IO::Dumper; \& fdump(,$filename); \& ... \& = frestore($filename); .Ve .PP fdump dumps a single complex data structure to a file. You restore the data structure by eval-ing the perl code put in the file. A convenience routine (frestore) exists to do it for you. .PP I suggest using the extension '.pld' or (for non-broken \s-1OS\s0's) '.pdld' to distinguish Dumper files. That way they are reminiscent of .pl files for perl, while still looking a little different so you can pick them out. You can certainly feed a dump file straight into perl (for syntax checking) but it will not do much for you, just build your data structure and exit. .SS "frestore" .IX Subsection "frestore" Restore a dumped file .PP .Vb 4 \& use PDL::IO::Dumper; \& fdump(,$filename); \& ... \& = frestore($filename); .Ve .PP \&\fBfrestore()\fR is a convenience function that just reads in the named file and executes it in an eval. It's paired with \fBfdump()\fR. .SS "deep_copy" .IX Subsection "deep_copy" Convenience function copies a complete perl data structure by the brute force method of \*(L"eval sdump\*(R". .SS "PDL::IO::Dumper::big_PDL" .IX Subsection "PDL::IO::Dumper::big_PDL" Identify whether a \s-1PDL\s0 is ``big'' [Internal routine] .PP Internal routine takes a \s-1PDL\s0 and returns a boolean indicating whether it's small enough for direct insertion into the dump string. If 0, it can be inserted. Larger numbers yield larger scopes of \s-1PDL.\s0 1 implies that it should be broken out but can be handled with a couple of perl commands; 2 implies full uudecode treatment. .PP PDLs with Astro::FITS::Header objects as headers are taken to be \s-1FITS\s0 files and are always treated as huge, regardless of size. .SS "PDL::IO::Dumper::stringify_PDL" .IX Subsection "PDL::IO::Dumper::stringify_PDL" Turn a \s-1PDL\s0 into a 1\-part perl expr [Internal routine] .PP Internal routine that takes a \s-1PDL\s0 and returns a perl string that evals to the \&\s-1PDL.\s0 It should be used with care because it doesn't dump headers and it doesn't check number of elements. The point here is that numbers are dumped with the correct precision for their storage class. Things we don't know about get stringified element-by-element by their builtin class, which is probably not a bad guess. .SS "PDL::IO::Dumper::uudecode_PDL" .IX Subsection "PDL::IO::Dumper::uudecode_PDL" Recover a \s-1PDL\s0 from a uuencoded string [Internal routine] .PP This routine encapsulates uudecoding of the dumped string for large ndarrays. .SS "PDL::IO::Dumper::dump_PDL" .IX Subsection "PDL::IO::Dumper::dump_PDL" Generate 1\- or 2\-part expr for a \s-1PDL\s0 [Internal routine] .PP Internal routine that produces commands defining a \s-1PDL.\s0 You supply (<\s-1PDL\s0>, ) and get back two strings: a prepended command string and an expr that evaluates to the final \s-1PDL.\s0 \s-1PDL\s0 is the \s-1PDL\s0 you want to dump. is a flag whether dump_PDL is being called inline or before the inline dump string (0 for before; 1 for in). is the name of the variable to be assigned (for medium and large PDLs, which are defined before the dump string and assigned unique IDs). .SS "PDL::IO::Dumper::find_PDLs" .IX Subsection "PDL::IO::Dumper::find_PDLs" Walk a data structure and dump PDLs [Internal routine] .PP Walks the original data structure and generates appropriate exprs for each \s-1PDL.\s0 The exprs are inserted into the Data::Dumper output string. You shouldn't call this unless you know what you're doing. (see sdump, above). .SH "AUTHOR" .IX Header "AUTHOR" Copyright 2002, Craig DeForest. .PP This code may be distributed under the same terms as Perl itself (license available at ). Copying, reverse engineering, distribution, and modification are explicitly allowed so long as this notice is preserved intact and modified versions are clearly marked as such. .PP This package comes with \s-1NO WARRANTY.\s0