dump-forms-to-file Function

Summary

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

Package

hcl

Signature

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

Arguments

pathname⇩	A pathname designator.
forms⇩	A list of forms.
overwrite⇩	A boolean.
dump-standard-objects⇩
	A boolean.
delete-on-error⇩	A boolean.

Description

The function dump-forms-to-file allows you to dump each item in forms to a file pathname in a binary format, which can then be loaded using load-data-file.

It is equivalent to using with-output-to-fasl-file and calling dump-form on each item in forms.

overwrite specifies what to do if pathname already exists. If overwrite is non-nil, then the existing file is overwritten, 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 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 and load-data-file to transfer large amounts of data.

Files generated by dump-forms-to-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 architectures have 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 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 dump-forms-to-file must be loaded only by load-data-file, and not by load.

Examples

(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)) 

If you have evaluate following code:

(defclass my-class () ((a :initarg :a :accessor my-a)))
(defmethod make-load-form ((self my-class) &optional environment)
  (declare (ignore environment))
  `(make-instance ',(class-name (class-of self))
                  :a ',(my-a self)))
(setq *my-instance* (make-instance 'my-class :a 42))
(dump-forms-to-file 
  (compile-file-pathname "my-instance")
  (list `(setq *my-instance* ,*my-instance*)))

then in another session, with the same definition of my-class, loading the file "my-instance" using load-data-file will create an equivalent instance of my-class and set *my-instance* to it:

(sys:load-data-file
  (compile-file-pathname "my-instance"))

See also

load-data-file