9 Including source files at expand–time

Include files are loaded at expand–time by the syntax include. Here is a usage example with the default configuration for searching and loading files:

1. Let’s create a source file in the current directory:

   ;; demo.scm --
   ;;
   
   (define (doit)
     (display "hello world!\n"))
   
   ;;; end of file
   

2. Let’s create a library file in the current directory, including the source file:

   ;; demo.sls --
   ;;
   
   (library (demo)
     (export doit)
     (import (vicare))
     (include "demo.scm" #t))
   
   ;;; end of file
   

3. Let’s enter the REPL, adding the current directory to the search path for source files:

   $ vicare --source-path $PWD --option print-loaded-libraries
   ...
   vicare> (import (demo))
   vicare: searching include file: demo.scm
   vicare: including file: /tmp/demo.scm
   vicare: loaded library "(demo)" from: /tmp/demo.sls
   vicare> (doit)
   hello world!
   vicare>
   

   the syntax include makes uses the same search path selected for source libraries.

4. Now we can compile the library:

   $ vicare --source-path $PWD --option print-loaded-libraries \
      --compile-library demo.sls --output demo.fasl
   vicare: compile-source-library: loading library: demo.sls
   vicare: searching include file: demo.scm
   vicare: including file: /tmp/demo.scm
   vicare: serialising library: demo.fasl
   vicare: library serialisation done
   

   and remember that include is and expand–time thing, so the compiled library will not perform any inclusion.

5. Finally we enter the REPL adding the current directory to the search path for binary libraries:

   $ vicare -L $PWD --option print-loaded-libraries
   ...
   vicare> (import (demo))
   vicare: loaded library "(demo)" from: /tmp/demo.fasl
   vicare> (doit)
   hello world!
   vicare>
   

The following syntactic bindings are exported by the library (vicare).

Syntax: include ?filename

Syntax: include ?filename #t

Include in the enclosing source file the contents of the file selected by the pathname ?filename, which must be a string. Everything happens as if the code was present in place of the include form. When the optional #t argument is given: print a message on the current error port describing the include operation.

Customisation of include operation

Parameter: current-include-loader

Hold a function used to load an include file. The referenced function is called as follows:

((current-include-loader) ?include-pathname ?verbose ?synner)

where: ?include-pathname must be a string representing an absolute or relative pathname; ?verbose can be any value; ?synner must be a procedure used to raise an exception when an error occurs:

(?synner ?message-string ?irritants)

When successful, the referenced function must return two values: the absolute pathname from which the file was loaded, a symbolic expression representing the file contents (usually such expression is generated by the reader). When an error occurs: call the procedure ?synner, which is meant to raise an exception.

If ?verbose is non–false: the referenced function must display verbose messages on the current error port describing the including process.

Function: default-include-loader include-pathname verbose? synner

Default value for the parameter current-include-loader. Load the file with pathname include-pathname. When successful return two values: the absolute pathname from which the file was loaded, a symbolic expression representing the file contents. When an error occurs: call the procedure synner, which is meant to raise an exception.

If verbose? is non–false: display verbose messages on the current error port describing the including process.

The include file is searched using the procedure referenced by the parameter current-include-file-locator. The file is loaded using the procedure referenced by the parameter current-include-file-loader.

Locating the file to be included

Parameter: current-include-file-locator

Hold a function used to convert an include file name into the corresponding file pathname. The referenced function must accept three arguments: a string representing the include file name; a boolean, true if the process of loading must display verbose messages on the current error port; a synner function used to report errors.

The synner function is called as:

(synner ?error-message ?irritants)

Function: default-include-file-locator include-pathname synner

Default value for the parameter current-include-file-locator. Given a string include-pathname, which must represent an absolute or relative file pathname, convert it into the absolute pathname of an existing file, as string. Return the absolute string pathname.

If include-pathname is a relative pathname: the file is searched in the search path represented by library-source-search-path, by appending include-pathname to the directories in the search path; Search path for source libraries.

synner must be a procedure used to raise an exception when an error occurs.

Loading the file to be included

Parameter: current-include-file-loader

Hold a function used to load an include file. The referenced function must accept two arguments: a string representing an existent file pathname; a synner function used to report errors.

The synner function is called as:

(synner ?error-message ?irritants)

Function: default-include-file-loader include-pathname synner

Default value for the parameter current-include-file-loader. Open the file include-pathname, read all the datums and return them. If an error occurs call synner. The returned value is a list of annotated symbolic expressions as generated by Vicare’s source code reader.