[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23 Loading Programs


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23.1 Loading Scheme file

Function: load file :key paths (error-if-not-found #t) environment ignore-coding

[R5RS+] Loads file, that is, read Scheme expressions in file and evaluates them. An extension “.scm” may be omitted from file.

If file doesn’t begin with “/” or “./” or “../”, it is searched from the system file search list, stored in a variable *load-path*. Or you can explicitly specify the search path by passing a list of directory names to the keyword argument paths.

On success, load returns #t. If the specified file is not found, an error is signalled unless the keyword argument error-if-not-found is #f, in which case load returns #f.

By default, load uses a coding-aware port (See section Coding-aware ports) so that the "coding:" magic comment at the beginning of the source file is effective. (See Multibyte scripts, for the details of the coding magic comment). If a true value is given to the keyword argument ignore-coding, load doesn’t create the coding-aware port and directly reads from the file port.

If a module is given to the keyword argument environment, load works as if the given module is selected at the beginning of the loaded file.

The current module is preserved; even select-module is called in file, the module in which load is called is restored afterwards.

If you want to load a library file, it’s better to use ‘use’ (See section Defining and selecting modules), or ‘require’ described below. See section Compilation, for difference between load and require.

Variable: *load-path*

Keeps a list of directories that are searched by load and require.

If you want to add other directories to the search path, do not modify this variable directly; use add-load-path, described below, instead.

Special Form: add-load-path path flag …

Adds a path path to the library load path list. If path is a relative path, it is resolved relative to the current working directory, unless :relative flag is given.

Each flag argument may be one of the followings.

:after

Append path to the end of the current list of load paths. By default, path is added in front of the load path list.

#t

The same as :after. This is for the backward compatibility.

:relative

Interpret path as a relative path to the directory of the current file, instead of the current working directory. If the current file can’t be determined (e.g. evaluated in REPL, or the expression is read from a socket), this flag is ignored.

Use this form instead of changing *load-path* directly. This form is a special form and recognized by the compiler; if you change *load-path*, it is in effect at run time, and that may be too late for “use” or “require”.

Furthermore, add-load-path looks for the architecture dependent directories under the specified path and if it exists, sets up the internal path list for dynamic loading correctly. Suppose you have your Scheme module in /home/yours/lib, and that requires a dynamic loadable library. You can put the library under /home/yours/lib/ARCH/, where ARCH is the value (gauche-architecture) returns (See section Environment Inquiry). Then you can have compiled libraries for multiple platforms and Gauche can still find the right library.

Function: load-from-port port

Reads Scheme expressions from an input port port and evaluates them, until EOF is read.

Note that unless you pass a coding-aware port to port, the "coding:" magic comment won’t be handled.

Function: current-load-port
Function: current-load-path
Function: current-load-history
Function: current-load-next

These procedures allows you to query the current context of loading. They returns the following values when called inside a file being loaded:

current-load-port

Returns the port object from which this form is being loaded.

current-load-path

Returns the pathname of the file from which this form is being loaded. Note that this may return #f if the source of load is not a file.

current-load-history

Returns a list of pairs of a port and a line number (integer), representing the nesting of loads. Suppose you load ‘foo.scm’, and from its line 7 it loads ‘bar.scm’, and from its line 18 it loads ‘baz.scm’. If you call current-load-history in the file ‘baz.scm’, you’ll get

 
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
current-load-next

Returns a list of remaining directories to be searched at the time this file is found. Suppose the *load-path* is ("." "../lib" "/home/gauche/lib" "/share/gauche/lib") and you load ‘foo.scm’, which happens to be in ‘../lib/’. Then, inside ‘foo.scm’, current-load-next returns:

 
("/home/gauche/lib" "/share/gauche/lib")

When called outside of load, these procedures returns #f, #f, () and (), respectively.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23.2 Load dynamic library

Function: dynamic-load file :key init-function export-symbols

Loads and links a dynamic loadable library (shared library) file. File shouldn’t contain the suffix (“.so” on most systems); dynamic-load adds it, for it may differ among platforms.

The keyword argument init-function specifies the initialization function name of the library in a string. By default, if the file basename (without extension) is “foo”, the initialization function name is “Scm_Init_foo”.

The keyword argument export-symbols tells whether the dynamic loader that the external symbols in file should be appended to the symbol table of the running process. (Note: I’m talking about C function and variable names, not Scheme symbols). By default, the symbols in file are not visible from other dynamically loaded libraries. If you want to allow other dynamically loaded libraries to call C function in your library, you should give #t to this argument. It sets RTLD_GLOBAL flag for dlopen().

Usually a dynamic loadable library is provided with wrapping Scheme module, so the user doesn’t have to call this function directly.

There’s no way to unload the loaded libraries.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23.3 Require and provide

Require and provide are a traditional Lisp way to ensure loading a library file only once. If you require a feature for the first time, a library file that provides it is loaded and the fact that the feature is provided is memorized. Subsequent request of the same feature doesn’t need to load the file.

In Gauche, the use syntax (See section Using modules) hides the require mechanism under the hood so you hardly need to see these forms. These are provided just in case if you want to do some non-trivial management of libraries and thus want to bypass Gauche’s standard mechanism.

Special Form: require feature

If feature is not loaded, load it. Feature must be a string, and it is taken as a file name (without suffix) to be loaded. This loading takes place at compile time.

If you load SLIB module, require is extended. See section slib - SLIB interface for details.

If the loaded file does not contain provide form at all, the feature is automatically provided, as if (provide feature) is called at the end of the loaded file. We call this autoprovide feature.

Function: provide feature

Adds feature to the system’s provided feature list, so that the subsequent require won’t load the same file again.

Because of the autoproviding, i.e. require automatically provides the required feature, you hardly need to use a provide form explcitily. There are a couple of scenarios that you may want to use a provide form:

Function: provided? feature

Returns #t if feature is already provided.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23.4 Autoload

Macro: autoload file/module item …

Sets up item … to be autoloaded. That is, when an item is referenced for the first time, file/module is loaded before the item is evaluated. This delays the loading of file/module until it is needed.

You can specify either a string file name or a symbol module name to file/module. If it is a string, the named file is loaded. If it is a symbol, the named module is loaded (using the same rule as of use), then the binding of item in the file/module is imported to the module used the autoload (See section Defining and selecting modules, for details of use).

Item can be either a variable name (symbol), or a form (:macro symbol). If it is a variable, the named file/module is loaded when the variable is about to be evaluated. If it is the latter form, the named file/module is loaded when a form (symbol arg …) is about to be compiled, which enables autoloading macros.

file/module must define symbol in it, or an error is signalled when file/module is autoloaded.

The following is an example of autoloading procedures.

 
(autoload "foo" foo0 foo1)
(autoload "bar" bar0 bar1)

(define (foobar x)
  (if (list? x)
      (map bar0 x)
      (foo0)))

(foobar '(1 2)) ; "bar" is loaded at this moment

(foobar #f)     ; "foo" is loaded at this moment

Note that if you set to autoload macro, the file/module is loaded immediately when such form that uses the macro is compiled, regardless of the piece of the code is executed or not.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.23.5 Operations on libraries

There are several procedures you can use to check if certain libraries and/or modules are installed in the system.

In the following descriptions, pattern is either a symbol or a string. If it is a symbol, it specifies a module name (e.g. foo.bar). If it is a string, it specifies a partial pathname of the library (e.g. "foo/bar"), which will be searched under library search paths. You can also use glob-like metacharacters ’*’ and ’?’ in pattern.

Function: library-fold pattern proc seed :key paths strict? allow-duplicates?

A basic iterator for library/module files. This procedure searches Scheme program files which matches pattern, under directories listed in paths (the default is the standard file load paths, *load-path*). For each matched file, it calls proc with three arguments: the matched module or library name, the full path of the program file, and the state value. Seed is used as the initial state value, and the value proc returns is used as the state value for the next call of proc. The value returned from the last proc becomes the return value of library-fold.

If pattern is a symbol and the keyword argument strict? is #t (which is the default), this procedure calls library-has-module? on the files whose name seems to match the given pattern of module name, in order to find out the file really implements the module. It can be a time consuming process if you try to match large number of modules; you can pass #f to strict? to avoid the extra check. If pattern is a string, matching is done only for file names so strict? is ignored.

By default, if there are more than one files that have the same name that matches pattern in paths, only the first one appears in paths is taken. This gives you the file you’ll get if you use require or use for that library. If you want to iterate all of matching files, pass #t to the allow-duplicates? keyword argument.

Here are some examples (the result may differ in your environment).

 
(library-fold 'srfi-1 acons '())
 ⇒ ((srfi-1 . "../lib/srfi-1.scm"))

(library-fold "srfi-1" acons '())
 ⇒ (("srfi-1" . "../lib/srfi-1.scm"))

;; Note the returned list is in a reverse order of
;; how acons is called.
(library-fold 'srfi-1 acons '() :allow-duplicates? #t)
 ⇒ ((srfi-1 . "/usr/share/gauche/0.7.1/lib/srfi-1.scm")
   (srfi-1 . "../lib/srfi-1.scm"))

;; In the following cases, the module name doesn't match,
;; but the filename does.
(library-fold 'srfi-19.* acons '())
 ⇒ ()

(library-fold "srfi-19/*" acons '())
 ⇒ (("srfi-19/read-tai" . "../lib/srfi-19/read-tai.scm")
   ("srfi-19/format" . "../lib/srfi-19/format.scm"))

;; Finds available dbm implementations
(library-fold 'dbm.* acons '())
 ⇒ ((dbm.cdb . "/usr/share/gauche/0.7.1/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
Function: library-map pattern proc :key paths allow-duplicates? strict?
Function: library-for-each pattern proc :key paths allow-duplicates? strict?

Map and for-each version of iterator over matched libraries/modules. See library-fold above for detailed operation of matching and the meanings of keyword arguments.

Proc receives two arguments, the matched module/library name and full path of the file. Library-map returns a list of results of proc. Library-for-each discards the results.

 
(library-map 'srfi-4 list :allow-duplicates? #t)
 ⇒ ((srfi-4 "../lib/srfi-4.scm")
            (srfi-4 "/usr/share/gauche/0.7.1/lib/srfi-4.scm"))

(library-map 'dbm.* (lambda (m p) m))
 ⇒ (dbm.odbm dbm.ndbm dbm.gdbm dbm.cdb)
Function: library-exists? mod/path :key paths force-search? strict?

Search a library or a module specified by mod/path, and returns a true value if it finds one. Paths and strict? keyword arguments have the same meaning as library-fold.

Unlike the iterator procedures above, this procedure first checks loaded libraries and modules in the calling process, and returns true if it finds mod/path in it, without looking into the filesystem. Passing #t to force-search? keyword arguments skips the checking of loaded libraries and modules.

Function: library-has-module? path module

Returns #t iff a file specified by path exists and appears to implement a module named by module. path must be an actual filename.

 
(library-has-module? "./test/foo/bar.scm" 'foo.bar)
 ⇒ #t ;; if ./test/foo/bar.scm implements module foo.bar.

This procedure assumes a typical layout of the source code to determine if the given file implements the module, i.e., it reads the first form of the code and see if it is a define-module form that is defining the given module.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Shiro Kawai on May 28, 2012 using texi2html 1.82.