All Manuals > LispWorks® User Guide and Reference Manual > 37 The HCL Package

load-data-file Function

Summary

Loads a binary data file created by dump-forms-to-file or with-output-to-fasl-file.

Package

hcl

Signature

load-data-file pathname &rest load-args &key eval allow-any-type callback => result

Arguments
pathname
A pathname designator.
load-args
All of the arguments.
eval
A generalized boolean.
allow-any-type
A generalized boolean.
callback
A function of one argument.
Values
result
A generalized boolean.
Description

The function load-data-file loads a fasl file created by dump-forms-to-file or with-output-to-fasl-file.

pathname names a file which must have been created by dump-forms-to-file or with-output-to-fasl-file.

eval controls whether the form is actually evaluated. When eval is nil, the form as loaded from the file (without evaluation) is passed to callback (if supplied) and printed (if :print t is supplied). When eval is non-nil, the form is evaluated before being passed to the callback and/or printed. The default value of eval is t.

When allow-any-type is true and the supplied pathname has a type, load-data-file tries to load it as a binary file without checking whether the type is known. When allow-any-type is nil, load-data-file tries to load only pathnames with known binary types (that is, either *binary-file-type* or in the list *binary-file-types*), exactly like load. The default value of allow-any-type is t.

callback is called with the result of the evaluation of each form in the file (or the form itself if eval is nil). When callback is supplied, the keyword :print (which normally would be processed by load) has no effect. Note: callback works only when the file was generated by LispWorks 7.0 or later.

The other arguments in load-args are passed to load.

load-data-file has similar semantics to load, but treats fasl files differently:

Fasl files generated by dump-forms-to-file or with-output-to-fasl-file must only be loaded using load-data-file.

load-data-file never loads a file as a text file, only files that are recognized as binary, which can be one of these possibilities:

If load-data-file ends up trying to load a file that is not a proper binary file, it signals an error of type fasl-error.

During the load, each form is loaded and, if eval is true, evaluated. If there is a callback, it is called with the result of the evaluation. Otherwise, the result may be printed if :print t was passed, and is then discarded.

Notes
  1. The default value of eval is t to give the same behavior as in LispWorks 6.1 and earlier versions. Passing eval as nil and using a callback is probably a better way of transferring data around, because it avoids the calls to eval. If needed, callback can call eval explicitly.
  2. All x86/x64 and ARM architectures have the same byte order, so load-data-file on any x86/x64 or ARM architecture can be used to load a data file that was generated on any x86/x64 or ARM architecture. The reverse byte order is used by Power architecture (IBM AIX and old PowerPC Macs) and SPARC (old Solaris).
  3. load-data-file returns the same value as load. In particular, the return value has nothing to do with the forms in the file. To actually have an effect, either the forms themselves have side effects, or callback is used to perform any required side effects.
  4. load-data-file does not do any read operation, but if the forms in the file contain symbols (except nil) such symbols need to be interned.
Compatibility notes
  1. In LispWorks 6.1 and earlier versions load-data-file was in the SYSTEM package. It is still exported from SYSTEM for backwards compatibility.
  2. In LispWorks 6.1 and earlier versions load-data-file gave errors if the type was not recognized, but now by default it allows any type.
  3. In LispWorks 6.1 and earlier versions load-data-file, when given a plain lisp file, would load it the same way that load does. In LispWorks 7.0 or later it signals an error of type fasl-error.
  4. callback works only when the fasl file was generated by LispWorks 7.0 or later.
Examples

For a simple example see dump-forms-to-file.

See also

dump-forms-to-file
with-output-to-fasl-file
fasl-error
*binary-file-type*
*binary-file-types*
28.3 Transferring large amounts of data


LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:35