Macro and Functions

Summary

Dump forms to a file in a binary format, which can then be loaded using load-data-file.

Package

hcl

Signature

with-output-to-fasl-file (fasl-stream-var pathname &key overwrite dump-standard-objects delete-on-error) &body body => nil

dump-form form fasl-stream => nil

dump-forms-to-file pathname forms &key overwrite dump-standard-objects delete-on-error => nil

Arguments

fasl-stream-var

A variable.

pathname

A pathname designator.

overwrite

A boolean.

dump-standard-objects

A boolean.

delete-on-error

A boolean.

body

Lisp code that calls dump-form.

form

A form.

fasl-stream

The value of fasl-stream-var.

forms

A list of forms.

Values

Each of these macros and functions returns nil.

Description

The macro with-output-to-fasl-file and the functions dump-form and dump-forms-to-file allow you to dump forms to a file in a binary format, which can then be loaded using load-data-file.

They provide these two ways to achieve the same thing:

• dump-forms-to-file simply dumps the forms in forms into the file specified by pathname.
• with-output-to-fasl-file binds fasl-stream-var to an opaque structure associated with pathname. Inside the body, dump-form is used to dump individual forms to the file.

overwrite specifies what to do if pathname already exists. If overwrite is non-nil, dump-forms-to-file and with-output-to-fasl-file overwrite the existing file, otherwise they signal an error. The default value of overwrite is t.

delete-on-error specifies what to in case of a non-local exit from the body of with-output-to-fasl-file or from dump-forms-to-file (typically abort after an error). By default, the file is deleted, but if delete-on-error is nil then the file is left as it is. The default value of delete-on-error is t.

dump-standard-objects specifies what to do when trying to dump a standard object (that is, an instance of a subclass of standard-object) which does not have a user-defined make-load-form. If dump-standard-objects is nil, an error is signaled. If dump-standard-objects is non-nil, the instance is dumped using make-load-form-saving-slots. The default value of dump-standard-objects is nil.

When the generated file is loaded by load-data-file, the forms are loaded and by default evaluated, though load-data-file can also load without evaluating. If callback is passed to load-data-file, it gets each of the results. Otherwise the results are discarded (except being printed when passing :print t). Hence to be useful, either load-data-file must be called with callback, or evaluation of the forms should have some side effect, for example setting the value of some special symbol or adding entries to some global table.

For a form which is not a list or an object with make-load-form, or is a quoted list, eval does nothing. Dumping such forms and then using using the callback in load-data-file to do some work with them is the natural way of using dump-forms-to-file or with-output-to-fasl-file and load-data-file to transfer large amounts of data.

Files generated by dump-forms-to-file or with-output-to-fasl-file can be loaded (by load-data-file) on any LispWorks platform with the same byte order. All x86/x64 architectures have the same byte order (little-endian), so load-data-file on any x86/x64 architecture can be used load a data file that was generated on any x86/x64 architecture. The ARM architecture has the same byte order as x86/x64. The reverse byte order (big-endian) is used by AIX and SPARC (old Solaris).

Notes

1. The dumping of objects is done the same way that compile-file dumps when it creates a fasl file, except for the treatment of standard objects when dump-standard-objects is non-nil.
2. Dumping means creating a deep copy of the form. The elements and slots of lists, arrays of element type t, structures (unless they have a make-load-form), and, when dump-standard-objects is non-nil, standard objects without make-load-form are dumped recursively.
3. dump-forms-to-file and with-output-to-fasl-file cope with cyclic structures.
4. If you want to dump parts of cyclic structures, you can stop the recursion by defining an appropriate make-load-form method for the objects at the nodes where the recursion should stop.
5. A fasl file created using with-output-to-fasl-file must be loaded only by load-data-file, and not by load.

Example

(dump-forms-to-file "my-forms.data"

                    '(#(1 2 3)

                      89

                      (* 7 7)

                      '(* 9 9)))

Note that the first * form lacks a quote while the second has a quote.

Then (potentially in a different LispWorks version and/or on a different architecture) this:

(load-data-file "my-forms.data"

                :callback 'print)

prints this:

#(1 2 3) 

89 

49 

(* 9 9)

In contrast, loading the same binary file without evaluation:

(load-data-file "my-forms.data"

                :callback 'print

                :eval nil)

prints this:

#(1 2 3) 

89 

(* 7 7) 

(QUOTE (* 9 9)) 

See also

load-data-file