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 naming a file which must have been created by dump-forms-to-file or with-output-to-fasl-file.

load-args

Arguments which are passed to load, after removing the keyword-value pairs for :allow-any-type and :callback (if supplied).

allow-any-type

A generalized boolean. 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-type 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

A function of one argument which 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.

eval

A generalized boolean which controls whether the form is actually evaluated. When it is nil, the form as loaded from the file (without evaluation) is passed to the 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.

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.

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

• It cannot load a fasl generated by compile-file.
• It allows loading of fasls generated by dump-forms-to-file or with-output-to-fasl-file, including those generated by a previous version of LispWorks, or other architectures of LispWorks, provided they have the same byte order.
• It allows the option of a callback that is called on the result of loading the file.

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:

• pathname has a known type (either *binary-file-type* or in the list *binary-file-types*), or
• pathname has an unknown type and allow-any-type is non-nil, or
• pathname does not have a type and a matching file with the type matching *binary-file-type* is found.

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 Mac OS X) 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 the callback argument 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. 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*
Transferring large amounts of data