Vicare Scheme: libutils libraries typedef

7.3.1 `<library>` object type

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

Record Type: <library>: Record type representing Scheme libraries.

Function: library? obj: Return #t if obj is an object of type <library>; otherwise return #f.

Accessor for <library>: library-uid lib

Return a gensym uniquely identifying this interned library; it also identifies the corresponding serialised library. This gensym is registered in:

The <library> object created by a vicare process at run–time.
The binary file containing this library in compiled and serialised form.
The binary files containing the compiled libraries that import this one.

Whenever a compiled library imports this one, the UID stored in the binary file is compared to this field: if they are eq? the compiled versions are in sync, otherwise the importing library must be recompiled.

Accessor for <library>: library-name lib

A library name as defined by R6RS; it is the symbolic expression:

(?identifier0 ?identifier ...)
(?identifier0 ?identifier ... ?version)

where the ?identifier are symbols and ?version is a list of non–negative fixnums representing the version numbers. Library names can be manipulated with appropriate functions, Library name utilities.

Accessor for <library>: library-imp-lib* lib: The list of <library> objects selected by the import clause in the source code of lib.

Accessor for <library>: library-vis-lib* lib: The list of <library> objects selecting libraries needed by the visit code.

Accessor for <library>: library-inv-lib* lib: The list of <library> objects selecting libraries needed by the invoke code.

Accessor for <library>: library-export-subst lib

Return the export-subst of lib: an alist representing the global bindings exported by the library. The cars of the alist are symbols representing the public names of the exported syntactic bindings. The cdrs of the alist are the label gensyms of the exported syntactic bindings.

The export-subst includes both syntactic bindings defined by the library itself and syntactic bindings imported and re–exported by the library. For example:

(define ell
  (expand-library->sexp
     '(library (demo)
        (options typed-language)
        (export display <fixnum>)
        (import (vicare))
        (define {x <fixnum>} 123))))

(cdr (assq 'export-subst ell))
⇒ ((<fixnum> . prim-label.<fixnum>) (display . g14256))

(cdr (assq 'global-env ell))
⇒ ((g9 . (global-typed . g8)))

notice that the re–exported bindings do not appear in the global-env.

Accessor for <library>: library-typed-locs lib: Return an alist having labels as keys and loc gensyms as values. The labels are the ones of the global-env whose descriptor has type global-typed or global-typed-mutable. The loc gensyms are the ones of the variables actually holding the typed values. This alist allows to map the public name of global typed variables to the loc gensyms holding the values.

Accessor for <library>: library-visit-state lib: When set to a procedure: it is the thunk to call to compile and evaluate the visit code. When set to something else: this library has been already visited.

Accessor for <library>: library-invoke-state lib: When set to a procedure: it is the thunk to call to compile and evaluate the invoke code. When set to something else: this library has been already invoked.

Accessor for <library>: library-visit-code lib: When lib is created from source code: this field is a core language symbolic expression representing the visit code. When lib is created from a binary file: this field is a thunk to evaluate to visit the library.

Accessor for <library>: library-invoke-code lib: When lib is created from source code: this field is a core language symbolic expression representing the invoke code. When lib is created from a binary file: this field is a thunk to evaluate to invoke the library.

Accessor for <library>: library-guard-code lib: When lib is created from source code: this field is a core language symbolic expression representing the guard code. When lib is created from a binary file: this field is a thunk to evaluate to run the stale-when composite test expression.

Accessor for <library>: library-guard-lib* lib: The list of <library> objects selecting libraries needed by the stale-when composite test expression.

NOTE These are the libraries accumulated by the inv-collector while expanding the stale-when test expressions.

Accessor for <library>: library-visible? lib

A boolean determining if the library is visible. This attribute is used by interned-libraries to select libraries to report as interned.

A library should be marked as visible if it is meant to be imported by client code in “normal” use; unsafe libraries in the hierarchy (vicare system ---)) should not be visible.

Accessor for <library>: library-source-file-name lib: The boolean #f or a string representing the pathname of the file from which the source code of the library was read.

Accessor for <library>: library-option* lib: A list of symbolic expressions holding library options.

Accessor for <library>: library-foreign-library* lib: A list of strings each representing the identifier of a foreign library that must be dynamically loaded for this lib object. These libraries are the ones especially written to interface Vicare with platform–specific services.

Function: library-loaded-from-source-file? lib: The argument lib must be a <library> object. Return #t if lib was loaded from a source file; otherwise return #f.

Function: library-loaded-from-binary-file? lib: The argument lib must be a <library> object. Return #t if lib was loaded from a binary file; otherwise return #f.

Function: library-descriptor lib: Given a <library> object return an object representing the library descriptor. Library descriptors are uniquely associated to a compiled library.

Function: library-descriptor? obj: Return #t if obj is a library descriptor object; otherwise return #f.

Function: library-descriptor-uid libdescr: Given a library descriptor object return the UID.

Function: library-descriptor-name libdescr: Given a library descriptor object return the R6RS library name.

As example of <library> fields, expanding the library:

(library (ciao)
  (export var fun mac etv)
  (import (vicare))
  (define var 1)
  (define (fun)
    2)
  (define-syntax (mac stx)
    3)
  (define-syntax etv
    (make-expand-time-value
     (+ 4 5))))

yields the invoke-code:

(library-letrec*
    ((lex.var loc.var '1)
     (lex.fun loc.fun (annotated-case-lambda fun (() '2))))
  ((primitive void)))

the visit-code:

(begin
  (set! loc.mac
        (annotated-case-lambda
            (#'lambda (#'stx) #'3)
          ((lex.stx) '3)))
  (set! loc.etv
        (annotated-call
            (make-expand-time-value (+ 4 5))
          (primitive make-expand-time-value)
          (annotated-call (+ 4 5) (primitive +) '4 '5))))

the export-subst:

((etv . lab.etv)
 (mac . lab.mac)
 (fun . lab.fun)
 (var . lab.var))

the global-env:

((lab.var global        . loc.var)
 (lab.fun global        . loc.fun)
 (lab.mac global-macro  . loc.mac)
 (lab.etv global-etv    . loc.etv))

Another example, for the library:

(library (ciao (1 2))
  (export doit)
  (import (vicare))
  (stale-when (< 1 2)
    (define a 123))
  (stale-when (< 2 3)
    (define b 123))
  (define (doit)
    123))

the guard-code is:

(if (if '#f
        '#t
       (annotated-call (< 1 2) (primitive <) '1 '2))
    '#t
  (annotated-call (< 2 3) (primitive <) '2 '3))

7.3.1 <library> object type

7.3.1 `<library>` object type