7.7 Locating libraries

The function default-library-loader is the default value of the parameter current-library-loader, which is used to intern libraries; default-library-loader. Such default procedure makes use of the function referenced by the parameter current-library-locator to find libraries in some external repository.

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

Parameter: current-library-locator

Hold a function used to locate a library from its R6RS library reference. The selected locator function must accept as single argument a R6RS library reference and it must return a thunk as single value.

When invoked, the returned thunk must return two values:

• When a matching source library is found:
  1. A textual input port from which the library can be read.
  2. A thunk to be called to continue the search in case the source library is rejected.
• When a matching binary library is found:
  1. A binary input port from which the library can be read.
  2. A thunk to be called to continue the search in case the binary library is rejected.
• When a matching library is found and interned by the thunk itself:
  1. The boolean #t.
  2. A thunk to be called to continue the search in case the library is rejected.
• When no matching library is found:
  1. The boolean #f.
  2. The boolean #f.

When an input port is returned as first value: it is responsibility of the caller to close the returned port when no more needed; the thunk discharges any responsibility.

When a thunk is returned as second value: it must have the same API of the thunk returned by the locator function; the possibility to continue the search allows the caller to reject a library if it does not meet some additional constraint.

The parameter is meant to be used as in the following pseudo–code:

(let loop
    ((next-locator-search ((current-library-locator) libref)))
  (receive (rv further-locator-search)
      (next-locator-search)
    (cond ((binary-port?  rv)
           (read-validate-intern-binary-library rv
              (lambda ()
                (loop further-locator-search))))
          ((textual-port? rv)
           (read-validate-intern-source-library rv
              (lambda ()
                (loop further-locator-search))))
          ((and (boolean? rv) rv)
           (library-already-interned))
          ((not rv)
           (no-matching-library-was-found))
          (else
           (assertion-violation __who__
             "invalid return values from library locator" rv)))))

Usually the locator function visits the host file system in search of a file whose pathname matches the given library reference; other possibilities are: programmatically fabricating the library on the spot; downloading the library from a remote site.