1% Copyright 2005-2017 Cisco Systems, Inc. 2% 3% Licensed under the Apache License, Version 2.0 (the "License"); 4% you may not use this file except in compliance with the License. 5% You may obtain a copy of the License at 6% 7% http://www.apache.org/licenses/LICENSE-2.0 8% 9% Unless required by applicable law or agreed to in writing, software 10% distributed under the License is distributed on an "AS IS" BASIS, 11% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12% See the License for the specific language governing permissions and 13% limitations under the License. 14\chapter{Libraries and Top-level Programs\label{CHPTLIBRARIES}} 15 16\index{libraries}% 17\index{top-level-programs}% 18The Revised$^6$ Report describes two units of portable code: 19libraries and top-level programs. 20A library is a named collection of bindings with a declared set of 21explicitly exported bindings, a declared set of imported libraries, and a 22body that initializes its bindings. 23A top-level program is a stand-alone program with a declared set of 24imported libraries and a body that is run when the top-level program is 25run. 26The bindings in a library are created and its initialization code run only 27if the library is used, directly or indirectly, by a top-level program. 28 29\index{\scheme{import}}% 30The \scheme{import} declarations appearing within libraries and top-level 31programs serve two purposes: first, they cause the imported libraries to 32be loaded, and second, they cause the bindings of the imported libraries 33to become visible in the importing library or top-level program. 34Libraries are typically stored in the file system, with one library per 35file, and the library name typically identifies the file-system path to 36the library, possibly relative to a default or programmer-specified set of 37library locations. 38The exact mechanism by which top-level programs are run and libraries are 39loaded is implementation-dependent. 40 41This chapter describes the mechanisms by which libraries and programs are 42loaded in {\ChezScheme} along with various features for controlling and 43tracking this process. 44It also describes the set of built-in libraries and syntactic forms for 45defining new libraries and top-level programs outside of a library or 46top-level program file. 47 48% \section{Locating Libraries\label{SECTLOCATINGLIBRARIES}} 49% 50% In {\ChezScheme}, a library to be loaded implicitly by \scheme{import} 51% must reside in a file whose name reflects the name of the library. 52% For example, if the library's name is \scheme{(tools sorting)}, the 53% base name of the file must be \scheme{sorting} with a valid extension, and 54% the file must be in a directory named \scheme{tools} which itself resides 55% in one of the directories searched by \scheme{import}. 56% The set of directories searched by \scheme{import} is determined by 57% the 58% \index{\scheme{library-directories}}\scheme{library-directories} 59% parameter, and the set of 60% extensions is determined by the 61% \index{\scheme{library-extensions}}\scheme{library-extensions} 62% parameter. 63% So, if \scheme{(library-directories)} contains the pathnames 64% \scheme{"/usr/lib/scheme/libraries"} and \scheme{"."}, and 65% \scheme{(library-extensions)} contains the extensions \scheme{.ss} 66% and \scheme{.sls}, the path of the \scheme{(tools sorting)} 67% library must be one of the following. 68% 69% \schemedisplay 70% /usr/lib/scheme/libraries/tools/sorting.ss 71% /usr/lib/scheme/libraries/tools/sorting.sls 72% ./tools/sorting.ss 73% ./tools/sorting.sls 74% \endschemedisplay 75% 76% A file containing a library or set of libraries can be explicitly loaded 77% via \scheme{load}, in which case the file may have any name and may reside 78% anywhere in the file system. 79% 80% \index{\scheme{compile-library}}% 81% \index{\scheme{compile-imported-libraries}}% 82% A file containing a library may be compiled with \scheme{compile-file} 83% or \scheme{compile-library}. 84% The only difference between the two is that the latter treats the source 85% file as if it were prefixed by an implicit \scheme{#!r6rs}. 86% Any libraries upon which the library depends must be compiled first. 87% This can be done manually or by setting the parameter 88% \scheme{compile-imported-libraries} to \scheme{#t} before compiling 89% the importing library. 90% If one of the libraries imported by the library is subsequently 91% recompiled (say because it was modified), the importing library must also 92% be recompiled. 93 94 95\section{Built-in Libraries\label{SECTBUILTINLIBRARIES}} 96 97In addition to the RNRS libraries mandated by the Revised$^6$ Report: 98 99\schemedisplay 100 (rnrs base (6)) 101 (rnrs arithmetic bitwise (6)) 102 (rnrs arithmetic fixnums (6)) 103 (rnrs arithmetic flonums (6)) 104 (rnrs bytevectors (6)) 105 (rnrs conditions (6)) 106 (rnrs control (6)) 107 (rnrs enums (6)) 108 (rnrs eval (6)) 109 (rnrs exceptions (6)) 110 (rnrs files (6)) 111 (rnrs hashtables (6)) 112 (rnrs io ports (6)) 113 (rnrs io simple (6)) 114 (rnrs lists (6)) 115 (rnrs mutable-pairs (6)) 116 (rnrs mutable-strings (6)) 117 (rnrs programs (6)) 118 (rnrs r5rs (6)) 119 (rnrs records procedural (6)) 120 (rnrs records syntactic (6)) 121 (rnrs records inspection (6)) 122 (rnrs sorting (6)) 123 (rnrs syntax-case (6)) 124 (rnrs unicode (6)) 125\endschemedisplay 126 127\index{\scheme{(chezscheme)} library}% 128\index{\scheme{(chezscheme csv7)} library}% 129\index{\scheme{(scheme)} library}% 130\index{\scheme{(scheme csv7)} library}% 131{\ChezScheme} also provides two additional libraries: \scheme{(chezscheme)} 132and \scheme{(chezscheme csv7)}. 133The former can also be referenced as \scheme{(scheme)} and the latter can 134also be referenced as \scheme{(scheme csv7)}. 135 136The \scheme{(chezscheme)} library exports bindings for every identifier whose 137binding is described in this document, including those for keywords like 138\scheme{lambda}, auxiliary keywords like \scheme{else}, module names 139like \scheme{scheme}, and procedure names like \scheme{cons}. 140In most cases where an identifier exported from the 141\scheme{(chezscheme)} library corresponds to an identifier exported from 142one of the RNRS libraries, the bindings are identical. 143In some cases, however, the \scheme{(chezscheme)} bindings extend the 144\scheme{rnrs} bindings in some way. 145For example, the \scheme{(chezscheme)} \scheme{syntax-rules} form allows 146its clauses to have fenders (Section~\ref{SECTSYNTAXRULES}), while the 147\scheme{(rnrs)} \scheme{syntax-rules} form does not. 148Similarly, the \scheme{(chezscheme)} \scheme{current-input-port} procedure 149accepts an optional \var{port} argument that, when specified, sets the 150current input port to \var{port} (Section~\ref{SECTIOINPUT}), while the 151\scheme{(rnrs)} \scheme{current-input-port} procedure does not. 152When the \scheme{(chezscheme)} library extends an RNRS binding in some 153way, the \scheme{(chezscheme)} library also exports the RNRS version, 154with the name prefixed by \scheme{r6rs:}, e.g., \scheme{r6rs:syntax-rules} 155or \scheme{r6rs:current-input-port}. 156 157The \scheme{(chezscheme csv7)} Version~7 backward compatibility library 158contains bindings for a set of syntactic forms and procedures whose syntax 159or semantics directly conflicts with the RNRS bindings for the same 160identifiers. 161The following identifiers are exported from \scheme{(chezscheme csv7)}. 162 163\schemedisplay 164record-field-accessible? 165record-field-accessor 166record-field-mutable? 167record-field-mutator 168record-type-descriptor 169record-type-field-decls 170record-type-field-names 171record-type-name 172record-type-symbol 173\endschemedisplay 174 175The bindings of this library should be used only for old code; new 176code should use the RNRS variants. 177Each of these is also available in the \scheme{(chezscheme)} library with 178the prefix \scheme{csv7:}, e.g., \scheme{csv7:record-type-name}. 179 180The interaction environment in which code outside of a library or 181RNRS top-level program is scoped contains all of the bindings of the 182\scheme{(chezscheme)} library, as described in 183Section~\ref{SECTUSEINTERACTIONENVIRONMENT}. 184 185 186\section{Running Top-level Programs\label{SECTRUNNINGTOPLEVELPROGRAMS}} 187 188\index{\scheme{scheme-script}}% 189\index{\scheme{--program} command-line option}% 190\index{\scheme{load-program}}% 191A top-level program must reside in its own file, which may have any 192name and may reside anywhere in the file system. 193A top-level program residing in a file is run by one of three mechanisms: 194the \scheme{scheme-script} command, the \scheme{--program} command-line 195argument, or the \scheme{load-program} procedure. 196 197The \scheme{scheme-script} command is used as follows: 198 199\schemedisplay 200scheme-script \var{program-filename} \var{arg} \dots 201\endschemedisplay 202 203It may also be run implicitly on Unix-based systems by placing the line 204 205\schemedisplay 206#! /usr/bin/env scheme-script 207\endschemedisplay 208 209at the front of the file containing the top-level program, making the 210top-level program file executable, and executing the file. 211This line may be replaced with 212 213\schemedisplay 214#! /usr/bin/scheme-script 215\endschemedisplay 216 217with \scheme{/usr/bin} replaced by the absolute path to the directory 218containing \scheme{scheme-script} if it is not in \scheme{/usr/bin}. 219The first form is recommended in the nonnormative appendices to the 220Revised$^6$ Report~\cite{r6rsapps}, and works wherever 221\scheme{scheme-script} appears in the path. 222 223The \scheme{--program} command is used similarly with the \scheme{scheme} 224or \scheme{petite} executables, either by running: 225 226\schemedisplay 227scheme --program \var{program-filename} \var{arg} \dots 228petite --program \var{program-filename} \var{arg} \dots 229\endschemedisplay 230 231or by including 232 233\schemedisplay 234#! /usr/bin/scheme --script 235\endschemedisplay 236 237or 238 239\schemedisplay 240#! /usr/bin/petite --script 241\endschemedisplay 242 243at the front of the top-level program file, making the file executable, 244and executing the file. 245Again, \scheme{/usr/bin} should be replaced with the absolute path to 246the actual directory in which \scheme{scheme} and/or \scheme{petite} 247resides, if not \scheme{/usr/bin}. 248 249The \scheme{load-program} procedure, described in 250Section~\ref{SECTMISCCOMPILEEVAL}, is used like \scheme{load}: 251 252\schemedisplay 253(load-program \var{string}) 254\endschemedisplay 255 256where \var{string} names the file in which the top-level program resides. 257 258Regardless of the mechanism used, if the opening line is in one of the 259forms described above, or more generally, consists of 260\scheme{#!} followed by a space or a forward slash, the opening line 261is not considered part of the program and is ignored once the Scheme 262system starts up and begins to run the program. 263Thus, the line may be present even in a file loaded by \scheme{load-program}. 264In fact, \scheme{load-program} is ultimately used by the other two 265mechanisms described above, via the value of the \scheme{scheme-program} 266parameter described in Section~\ref{SECTMISCWAITERS}, and it is 267\scheme{load-program} that scans past the \scheme{#!} line, if present, 268before evaluating the program. 269 270A top-level program may be compiled with the 271\index{\scheme{compile-program}}\scheme{compile-program} 272procedure described in Section~\ref{SECTMISCCOMPILEEVAL}. 273\scheme{compile-program} copies the \scheme{#!} line from the source 274file to the object file, followed by a compiled version of the source 275code. 276Any libraries upon which the top-level program depends, other than 277built-in libraries, must be compiled first via \scheme{compile-file} 278or \scheme{compile-library}. 279This can be done manually or by setting the parameter 280\scheme{compile-imported-libraries} to \scheme{#t} before compiling 281the program. 282The program must be recompiled if any of the libraries upon which 283it depends are recompiled. 284A compiled top-level program can be run just like a source top-level 285program via each of the mechanisms described above. 286 287\index{\scheme{load-library}}% 288In {\ChezScheme}, a library may also be defined in the REPL or placed in a 289file to be loaded via \scheme{load} or \scheme{load-library}. 290The syntax for a library is the same whether the library is placed in 291its own file and implicitly loaded via \scheme{import}, entered into 292the REPL, or placed in a file along with other top-level expressions to 293be evaluated by \scheme{load}. 294A top-level program may also be defined in the REPL or placed in a file 295to be loaded via \scheme{load}, but in this case, the syntax is slightly 296different. 297In the language of the Revised$^6$ Report, a top-level program is merely 298an unwrapped sequence of subforms consisting of an \scheme{import} form 299and a body, delimited only by the boundaries of the file in which it 300resides. 301In order for a top-level program to be entered in the REPL or placed in 302a file to be evaluated by \scheme{load}, {\ChezScheme} allows top-level 303programs to be enclosed in a 304\index{\scheme{top-level-program}}\scheme{top-level-program} form. 305 306\section{Library and Top-level Program Forms\label{SECTLIBRARYFORMS}} 307 308%---------------------------------------------------------------------------- 309\noskipentryheader 310\formdef{library}{\categorysyntax}{(library \var{name} \var{exports} \var{imports} \var{library-body})} 311\returns unspecified 312\listlibraries 313\endnoskipentryheader 314 315The \scheme{library} form defines a new library with the specified 316name, exports, imports, and body. 317Details on the syntax and semantics of the library form are given in 318Section~\ref{TSPL:SECTLIBPROGRAMS} of {\TSPLFOUR} and in the Revised$^6$ 319Report. 320 321Only one version of a library can be loaded at any given time, and an 322exception is raised if a library is implicitly loaded via \scheme{import} 323when another version of the library has already been loaded. 324{\ChezScheme} permits a different version of the library, or a new 325instance of the same version, to be entered explicitly into the REPL 326or loaded explicitly from a file, to facilitate interactive testing 327and debugging. 328The programmer should take care to make sure that any code that uses 329the library is also reentered or reloaded, to make sure that code 330accesses the bindings of the new instance of the library. 331 332\schemedisplay 333(library (test (1)) (export x) (import (rnrs)) (define x 3)) 334(import (test)) 335(define f (lambda () x)) 336(f) ;=> 3 337 338(library (test (1)) (export x) (import (rnrs)) (define x 4)) 339(import (test)) 340(f) ;=> 3 ; oops---forgot to redefine f 341(define f (lambda () x)) 342(f) ;=> 4 343 344(library (test (2)) (export x) (import (rnrs)) (define x 5)) 345(import (test)) 346(define f (lambda () x)) 347(f) ;=> 5 348\endschemedisplay 349 350As with module imports (Section~\ref{SECTSYNTAXMODULES}), a library 351\scheme{import} may appear anywhere a definition may appear, including at 352top level in the REPL, in a file to be loaded by \scheme{load}, or within 353a \scheme{lambda}, \scheme{let}, \scheme{letrec}, \scheme{letrec*}, 354etc., body. 355The same \scheme{import} form may be used to import from both libraries 356and modules. 357 358\schemedisplay 359(library (foo) (export a) (import (rnrs)) (define a 'a-from-foo)) 360(module bar (b) (define b 'b-from-bar)) 361(let () (import (foo) bar) (list a b)) ;=> (a-from-foo b-from-bar) 362\endschemedisplay 363 364The \scheme{import} keyword is not visible within a library body 365unless the library imports it from the \scheme{(chezscheme)} library. 366 367%---------------------------------------------------------------------------- 368\entryheader 369\formdef{top-level-program}{\categorysyntax}{(top-level-program \var{imports} \var{body})} 370\returns unspecified 371\listlibraries 372\endentryheader 373 374\index{top-level-programs}% 375A \scheme{top-level-program} form may be entered into the REPL or placed 376in a file to be loaded via \scheme{load}, where it behaves as if its 377subforms were placed in a file and loaded via \scheme{load-program}. 378Details on the syntax and semantics of a top-level program are given in 379Section~\ref{TSPL:SECTLIBPROGRAMS} of {\TSPLFOUR} and in the Revised$^6$ 380Report. 381 382The following transcript illustrates a \scheme{top-level-program} being 383tested in the REPL. 384 385\schemedisplay 386> (top-level-program (import (rnrs)) 387 (display "hello!\n")) 388hello! 389\endschemedisplay 390 391\section{Standalone import and export forms\label{SECTLIBRARYIMPORTEXPORTFORMS}} 392 393Although not required by the Revised$^6$ Report, 394{\ChezScheme} supports the use of standalone import and 395export forms. 396The import forms can appear anywhere other definitions 397can appear, including within a \scheme{library} body, 398\scheme{module} (Section~\ref{SECTSYNTAXMODULES}) body, 399\scheme{lambda} or other local body, and at top level. 400The export forms can appear within the definitions of a 401\scheme{library} or \scheme{module} body to specify additional 402exports for the library or module. 403 404Within a library or top-level program, the keywords for 405these forms must be imported from the \scheme{(chezscheme)} 406library to be available for use, since they are not 407defined in any of the Revised$^6$ Report libraries. 408 409%---------------------------------------------------------------------------- 410\entryheader 411\formdef{import}{\categorysyntax}{(import \var{import-spec} \dots)} 412\formdef{import-only}{\categorysyntax}{(import-only \var{import-spec} \dots)} 413\returns unspecified 414\listlibraries 415\endentryheader 416 417An \scheme{import} or \scheme{import-only} form is a definition and can 418appear anywhere other definitions can appear, including 419at the top level of a program, nested within the bodies of 420\scheme{lambda} expressions, and nested within modules 421and libraries. 422 423Each \var{import-spec} must take one of the following forms. 424 425\schemedisplay 426\var{import-set} 427(for \var{import-set} \var{import-level} \dots) 428\endschemedisplay 429 430\noindent 431The \scheme{for} wrapper and \var{import-level} are described in 432Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR}. 433They are ignored by {\ChezScheme}, which determines 434automatically the levels at which identifiers must 435be imported, as permitted by the Revised$^6$ Report. 436This frees the programmer from the obligation 437to do so and results in more generality as well as more 438precision in the set of libraries actually imported 439at compile and run time~\cite{Ghuloum:libraries,Ghuloum:phd}. 440 441An \var{import-set} must take one of the following forms: 442 443\schemedisplay 444\var{library-spec} 445\var{module-name} 446(only \var{import-set} \var{identifier} \dots) 447(except \var{import-set} \var{identifier} \dots) 448(prefix \var{import-set} \var{prefix}) 449(add-prefix \var{import-set} \var{prefix}) 450(drop-prefix \var{import-set} \var{prefix}) 451(rename \var{import-set} (\var{import-name} \var{internal-name}) \dots) 452(alias \var{import-set} (\var{import-name} \var{internal-name}) \dots) 453\endschemedisplay 454 455Several of these are specified by the Revised$^6$ Report; the remainder 456are {\ChezScheme} extensions, including \var{module-name} and the 457\scheme{add-prefix}, \scheme{drop-prefix}, and \scheme{alias} forms. 458 459An \scheme{import} or \scheme{import-only} form makes the specified bindings 460visible in the scope in which they appear. 461Except at top level, they differ in that \scheme{import} leaves all bindings 462except for those shadowed by the imported names visible, whereas \scheme{import-only} 463hides all existing bindings, i.e., makes only the imported names visible. 464At top level, \scheme{import-only} behaves like \scheme{import}. 465 466Each \var{import-set} identifies a set of names to make visible 467as follows. 468 469\begin{description} 470\item[\scheme{\var{library-spec}}:] 471all exports of the library identified by the Revised$^6$ Report \var{library-spec} 472(Chapter~\ref{TSPL:CHPTLIBRARIES}). 473 474\item[\scheme{\var{module-name}}:] 475all exports of module named by the identifier \var{module-name} 476 477\item[\scheme{(only \var{import-set} \var{identifier} \dots)}:] 478of those specified by \var{import-set}, just \scheme{\var{identifier} \dots} 479 480\item[\scheme{(except \var{import-set} \var{identifier} \dots)}:] 481all specified by \var{import-set} except \scheme{\var{identifier} \dots} 482 483\item[\scheme{(prefix \var{import-set} \var{prefix})}:] 484all specified by \var{import-set}, each prefixed by \var{prefix} 485 486\item[\scheme{(add-prefix \var{import-set} \var{prefix})}:] 487all specified by \var{import-set}, each prefixed by \var{prefix} 488(just like \scheme{prefix}) 489 490\item[\scheme{(drop-prefix \var{import-set} \var{prefix})}:] 491all specified by \var{import-set}, with prefix \var{prefix} removed 492 493\item[\scheme{(rename \var{import-set} (\var{import-name} \var{internal-name}) \dots)}:] 494all specified by \var{import-set}, with each identifier \var{import-name} 495renamed to the corresponding identifier \var{internal-name} 496 497\item[\scheme{(alias \var{import-set} (\var{import-name} \var{internal-name}) \dots)}:] 498all specified by \var{import-set}, with each \var{internal-name} as an alias 499for \var{import-name} 500\end{description} 501 502The \scheme{alias} form differs from the \scheme{rename} form in that both 503\var{import-name} and \var{internal-name} are in the resulting set, 504rather than just \var{internal-name}. 505 506It is a syntax violation if the 507given selection or transformation cannot be made because of a missing 508export or prefix. 509 510An identifier made visible via an import of a module or library is scoped as if its 511definition appears where the import occurs. 512The following example illustrates these scoping rules, using a local 513module \scheme{m}. 514 515\schemedisplay 516(library (A) (export x) (import (rnrs)) (define x 0)) 517(let ([x 1]) 518 (module m (x setter) 519 (define-syntax x (identifier-syntax z)) 520 (define setter (lambda (x) (set! z x))) 521 (define z 2)) 522 (let ([y x] [z 3]) 523 (import m (prefix (A) a:)) 524 (setter 4) 525 (list x a:x y z))) ;=> (4 0 1 3) 526\endschemedisplay 527 528\noindent 529The inner \scheme{let} expression binds \scheme{y} to the value of 530the \scheme{x} bound by the outer \scheme{let}. 531The import of \scheme{m} makes the definitions of \scheme{x} 532and \scheme{setter} visible within the inner \scheme{let}. 533The import of \scheme{(A)} makes the variable \scheme{x} exported 534from \scheme{(A)} visible as \scheme{a:x} within the body of the 535inner \scheme{let}. 536Thus, in the expression \scheme{(list x a:x y z)}, \scheme{x} refers to the 537identifier macro exported from \scheme{m} while \scheme{a:x} refers to the 538variable \scheme{x} exported from \scheme{(A)} and \scheme{y} and \scheme{z} 539refer to the bindings established by the inner \scheme{let}. 540The identifier macro \scheme{x} expands into a reference to 541the variable \scheme{z} defined within the module. 542 543With local import forms, it is rarely necessary to use the extended 544import specifiers. 545For example, an abstraction that encapsulates the import and reference 546can easily be defined and used as follows. 547 548\schemedisplay 549(define-syntax from 550 (syntax-rules () 551 [(_ m id) (let () (import-only m) id)])) 552 553(library (A) (export x) (import (rnrs)) (define x 1)) 554(let ([x 10]) 555 (module M (x) (define x 2)) 556 (cons (from (A) x) (from M x))) ;=> (1 . 2) 557\endschemedisplay 558 559\noindent 560The definition of \scheme{from} could use \scheme{import} rather than 561\scheme{import-only}, but by using \scheme{import-only} we get feedback 562if an attempt is made to import an identifier from a library or 563module that does not export the identifier. 564With \scheme{import} instead of \scheme{import-only}, the current binding, 565if any, would be visible if the library or module does not export the 566specified name. 567 568\schemedisplay 569(define-syntax lax-from 570 (syntax-rules () 571 [(_ m id) (let () (import m) id)])) 572 573(library (A) (export x) (import (rnrs)) (define x 1)) 574 575(let ([x 10]) 576 (module M (x) (define x 2)) 577 (+ (from (A) x) (from M y))) ;=> \var{exception: unbound identifier y} 578 579(let ([x 10] [y 20]) 580 (module M (x) (define x 2)) 581 (+ (lax-from (A) x) (lax-from M y))) ;=> 21 582\endschemedisplay 583 584Import visibility interacts with hygienic macro expansion in such a 585way that, as one might expect, 586an identifier \var{x} imported from a module \var{M} is treated in 587the importing context as if the corresponding export identifier had 588been present in the import form along with \var{M}. 589 590The \scheme{from} abstraction above works because both \var{M} and \var{id} 591appear in the input to the abstraction, so the imported \var{id} captures 592the reference to \var{id}. 593 594The following variant of \var{from} also works, because both names are 595introduced into the output by the transformer. 596 597\schemedisplay 598(module M (x) (define x 'x-of-M)) 599(define-syntax x-from-M 600 (syntax-rules () 601 [(_) (let () (import M) x)])) 602 603(let ([x 'local-x]) (x-from-M)) ;=> x-of-M 604\endschemedisplay 605 606On the other hand, imports of introduced module names do not capture 607free references. 608 609\schemedisplay 610(let ([x 'local-x]) 611 (define-syntax alpha 612 (syntax-rules () 613 [(_ var) (let () (import M) (list x var))])) 614 615 (alpha x)) ;=> (x-of-M local-x) 616\endschemedisplay 617 618Similarly, imports from free module names do not capture references 619to introduced variables. 620 621\schemedisplay 622(let ([x 'local-x]) 623 (define-syntax beta 624 (syntax-rules () 625 [(_ m var) (let () (import m) (list x var))])) 626 627 (beta M x)) ;=> (local-x x-of-M) 628\endschemedisplay 629 630This semantics extends to prefixed, renamed, and aliased bindings 631created by the extended \scheme{import} specifiers \scheme{prefix}, 632\scheme{rename}, and \scheme{alias}. 633 634The \scheme{from} abstraction 635works for variables but not for exported keywords, record names, 636or module names, since the output is an expression and may thus appear only where 637expressions may appear. 638A generalization of this technique is used in the following definition 639of \scheme{import*}, which supports renaming of imported bindings and 640selective import of specific bindings---without the use of the built-in 641\scheme{import} subforms for selecting and renaming identifiers 642 643\schemedisplay 644(define-syntax import* 645 (syntax-rules () 646 [(_ m) (begin)] 647 [(_ m (new old)) 648 (module (new) 649 (module (tmp) 650 (import m) 651 (alias tmp old)) 652 (alias new tmp))] 653 [(_ m id) (module (id) (import m))] 654 [(_ m spec0 spec1 ...) 655 (begin (import* m spec0) (import* m spec1 ...))])) 656\endschemedisplay 657 658\noindent 659To selectively import an identifier from module or library \scheme{m}, the 660\scheme{import*} form expands into an anonymous module that first 661imports all exports of \scheme{m} then re-exports only the selected 662identifier. 663To rename on import the macro expands into an anonymous module that 664instead exports an alias (Section~\ref{SECTSYNTAXALIAS}) bound to the new name. 665 666If the output placed the definition of \scheme{new} in the same 667scope as the import of \scheme{m}, a naming conflict would arise 668whenever \scheme{new} is also present in the interface 669of \scheme{m}. 670To prevent this, the output instead places the import within a nested 671anonymous module and links \scheme{old} and \scheme{new} 672by means of an alias for the introduced identifier \scheme{tmp}. 673 674The macro expands recursively to handle multiple import specifications. 675Each of the following examples imports \scheme{cons} as \scheme{+} and \scheme{+} as 676\scheme{cons}, which is probably not a very good idea. 677 678\schemedisplay 679(let () 680 (import* scheme (+ cons) (cons +)) 681 (+ (cons 1 2) (cons 3 4))) ;=> (3 . 7) 682 683(let () 684 (import* (rnrs) (+ cons) (cons +)) 685 (+ (cons 1 2) (cons 3 4))) ;=> (3 . 7) 686\endschemedisplay 687 688% for testing 689% (module m (x y z) 690% (define x 'x) 691% (define y 'y) 692% (define z 'z)) 693 694%---------------------------------------------------------------------------- 695\entryheader 696\formdef{export}{\categorysyntax}{(export \var{export-spec} \dots)} 697\returns unspecified 698\listlibraries 699\endentryheader 700 701An \scheme{export} form is a definition and can appear with other 702definitions at the front of a \scheme{library} or \scheme{module}. 703It is a syntax error for an \scheme{export} form to appear in other 704contexts, including at top level or among the definitions of a 705top-level program or \scheme{lambda} body. 706 707Each \var{export-spec} must take one of the following forms. 708 709\schemedisplay 710\var{identifier} 711(rename (\var{internal-name} \var{export-name}) \dots) 712(import \var{import-spec} \dots) 713\endschemedisplay 714 715\noindent 716where each \var{internal-name} and \var{export-name} is an identifier. 717The first two are syntactically identical to \scheme{library} 718\var{export-spec}s, while the third is syntactically 719identical to a {\ChezScheme} \scheme{import} form, which is an extension of the 720R6RS library \scheme{import} subform. 721The first form names a single export, \var{identifier}, whose export 722name is the same as its internal name. 723The second names a set of exports, each of whose export name is 724given explicitly and may differ from its internal name. 725 726For the third, the identifiers identified by the \scheme{import} form 727become exports, with aliasing, renaming, prefixing, etc., as specified by the 728\var{import-spec}s. 729The module or library whose bindings are exported by an \scheme{import} 730form appearing within an \scheme{export} form can 731be defined within or outside the exporting module or library and need 732not be imported elsewhere within the exporting module or library. 733 734The following library exports a two-armed-only variant of \scheme{if} 735along with all remaining bindings of the \scheme{(rnrs)} library. 736 737\schemedisplay 738(library (rnrs-no-one-armed-if) (export) (import (except (chezscheme) if)) 739 (export if (import (except (rnrs) if))) 740 (define-syntax if 741 (let () 742 (import (only (rnrs) if)) 743 (syntax-rules () 744 [(_ tst thn els) (if tst thn els)])))) 745 746(import (rnrs-no-one-armed-if)) 747(if #t 3 4) ;=> 3 748(if #t 3) ;=> \var{exception: invalid syntax} 749\endschemedisplay 750 751Another way to define the same library would be to define the 752two-armed-only \scheme{if} with a different internal name and use 753\scheme{rename} to export it under the name \scheme{if}: 754 755\schemedisplay 756(library (rnrs-no-one-armed-if) (export) (import (chezscheme)) 757 (export (rename (two-armed-if if)) (import (except (rnrs) if))) 758 (define-syntax two-armed-if 759 (syntax-rules () 760 [(_ tst thn els) (if tst thn els)]))) 761 762(import (rnrs-no-one-armed-if)) 763(if #t 3 4) ;=> 3 764(if #t 3) ;=> \var{exception: invalid syntax} 765\endschemedisplay 766 767The placement of the \scheme{export} form in the library body is 768irrelevant, e.g., the \scheme{export} form can appear after the 769definition in the examples above. 770 771 772%---------------------------------------------------------------------------- 773\entryheader 774\formdef{indirect-export}{\categorysyntax}{(indirect-export \var{id} \var{indirect-id} \dots)} 775\returns unspecified 776\listlibraries 777\endentryheader 778 779This form is a definition and can appear wherever any other definition 780can appear. 781 782An \scheme{indirect-export} form declares that the named 783\var{indirect-id}s are indirectly exported to top level if \var{id} 784is exported to top level. 785 786In general, if an identifier is not directly exported by a library or 787module, it can be referenced outside of the library or module only in 788the expansion of a macro defined within and exported from the library 789or module. 790Even this cannot occur for libraries or modules defined at top level 791(or nested within other libraries or modules), unless either (1) 792the library or module has been set up to implicitly export all 793identifiers as indirect exports, or (2) each indirectly exported 794identifier is explicitly declared as an indirect export of some 795other identifier that is exported, either directly or indirectly, from 796the library or module, via an \scheme{indirect-export} or the built-in 797indirect export feature of a \scheme{module} export subform. 798By default, (1) is true for a library and false for a module, but the 799default can be overridden via the \scheme{implicit-exports} 800form, which is described below. 801 802This form is meaningful only within a top-level library, top-level module, 803or module enclosed within a library or top-level module, although it 804has no effect if the library or module already implicitly exports all 805bindings. 806It is allowed anywhere else definitions can appear, however, so macros 807that expand into indirect export forms can be used in any definition 808context. 809 810Indirect exports are listed so the compiler can determine the 811exact set of bindings (direct and indirect) that must be inserted 812into the top-level environment, and conversely, the set of bindings 813that may be treated more efficiently as local bindings (and 814perhaps discarded, if they are not used). 815 816In the example below, \scheme{indirect-export} is used to indirectly 817export \scheme{count} to top level when \scheme{current-count} is 818exported to top level. 819 820\schemedisplay 821(module M (bump-count current-count) 822 (define-syntax current-count (identifier-syntax count)) 823 (indirect-export current-count count) 824 (define count 0) 825 (define bump-count 826 (lambda () 827 (set! count (+ count 1))))) 828 829(import M) 830(bump-count) 831current-count ;=> 1 832count ;=> \var{exception: unbound identifier count} 833\endschemedisplay 834 835An \scheme{indirect-export} form is not required to make \scheme{count} 836visible for \scheme{bump-count}, since it is a procedure whose code 837is contained within the module rather than a macro that might expand 838into a reference to \scheme{count} somewhere outside the module. 839 840It is often useful to use \scheme{indirect-export} in the output 841of a macro that expands into another macro named \var{a} if 842\var{a} expands into references to identifiers that might not 843be directly exported, as illustrated by the alternative definition 844of module \scheme{M} above. 845 846\schemedisplay 847(define-syntax define-counter 848 (syntax-rules () 849 [(_ getter bumper init incr) 850 (begin 851 (define count init) 852 (define-syntax getter (identifier-syntax count)) 853 (indirect-export getter count) 854 (define bumper 855 (lambda () 856 (set! count (incr count)))))])) 857 858(module M (bump-count current-count) 859 (define-counter current-count bump-count 0 add1)) 860\endschemedisplay 861 862%---------------------------------------------------------------------------- 863\entryheader 864\formdef{implicit-exports}{\categorysyntax}{(implicit-exports #t)} 865\formdef{implicit-exports}{\categorysyntax}{(implicit-exports #f)} 866\returns unspecified 867\listlibraries 868\endentryheader 869 870An \scheme{implicit-exports} form is a definition and can appear with other 871definitions at the front of a \scheme{library} or \scheme{module}. 872It is a syntax error for an \scheme{implicit-exports} form to appear in other 873contexts, including at top level or among the definitions of a 874top-level program or \scheme{lambda} body. 875 876The \scheme{implicit-exports} form determines whether identifiers 877not directly exported from a module or library are automatically 878indirectly exported to the top level if any meta-binding (keyword, meta 879definition, or property definition) is directly exported to top level 880from the library or module. 881The default for libraries is \scheme{#t}, to match the behavior required 882by the Revised$^6$ Report, while the default for modules is \scheme{#f}. 883The \scheme{implicit-exports} form is meaningful only within a library, 884top-level module, or module enclosed within a library or top-level module. 885It is allowed in a module enclosed within a \scheme{lambda}, \scheme{let}, 886or similar body, but ignored there because none of that module's bindings 887can be exported to top level. 888 889The advantage of \scheme{(implicit-exports #t)} is that indirect exports 890need not be listed explicitly, which is convenient. 891A disadvantage is that it often results in more bindings than necessary 892being elevated to top level where they cannot be discarded as useless 893by the optimizer. 894For modules, another disadvantage is such bindings 895cannot be proven immutable, which inhibits important optimizations such 896as procedure inlining. 897This can result in significantly lower run-time performance. 898 899\section{Explicitly invoking libraries\label{SECTLIBRARYINVOCATION}} 900 901%---------------------------------------------------------------------------- 902\noskipentryheader 903\formdef{invoke-library}{\categoryprocedure}{(invoke-library \var{libref})} 904\returns unspecified 905\listlibraries 906\endnoskipentryheader 907 908\var{libref} must be an s-expression in the form of a library reference. 909The syntax for library references is given in 910Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR} and in the Revised$^6$ 911Report. 912 913A library is implicitly invoked when or before some expression 914outside the library (e.g., in another library or in a top-level 915program) evaluates a reference to one of the library's exported 916variables. 917When the library is invoked, its body expressions (the right-hand-sides 918of the library's variable definitions and its initialization 919expressions) are evaluated. 920Once invoked, the library is not invoked again within the same process, 921unless it is first explicitly redefined or reloaded. 922 923\scheme{invoke-library} explicitly invokes the library specified 924by \var{libref} if it has not already been invoked or has since 925been redefined or reloaded. 926If the library has not yet been loaded, \scheme{invoke-library} 927first loads the library via the process described in 928Section~\ref{SECTUSELIBRARIES}. 929 930\scheme{invoke-library} is typically only useful for libraries whose 931body expressions have side effects. 932It is useful to control when the side effects occur and to force 933invocation of a library that has no exported variables. 934Invoking a library does not force the compile-time code (macro 935transformer expressions and meta definitions) to be loaded or 936evaluated, nor does it cause the library's bindings to become 937visible. 938 939It is good practice to avoid externally visible side effects in 940library bodies so the library can be used equally well at compile 941time and run time. 942When feasible, consider moving the side effects of a library body 943to an initialization routine and adding a top-level program that 944imports the library and calls the initialization routine. 945With this structure, calls to \scheme{invoke-library} on the 946library can be replaced by calls to 947\index{\scheme{load-program}}\scheme{load-program} on the 948top-level program. 949 950\section{Library Parameters\label{SECTLIBRARYPARAMETERS}} 951 952\index{\scheme{import}}% 953The parameters described below control where \scheme{import} looks 954when attempting to load a library, whether it compiles the libraries 955it loads, and whether it displays tracking messages as it performs its 956search. 957 958%---------------------------------------------------------------------------- 959\entryheader 960\formdef{library-directories}{\categorythreadparameter}{library-directories} 961\formdef{library-extensions}{\categorythreadparameter}{library-extensions} 962\listlibraries 963\endentryheader 964 965The parameter \scheme{library-directories} determines where the files 966containing library source and object code are located in the file system, 967and the parameter \scheme{library-extensions} determines the filename 968extensions for the files holding the code, as described in 969section~\ref{SECTUSELIBRARIES}. 970The values of both parameters are lists of pairs of strings. 971The first string in each \scheme{library-directories} pair identifies a 972source-file root directory, and the second identifies the corresponding 973object-file root directory. 974Similarly, the first string in each \scheme{library-extensions} pair 975identifies a source-file extension, and the second identifies the 976corresponding object-file extension. 977The full path of a library source or object file consists of the source or 978object root followed by the components of the library name prefixed by 979slashes, with the library extension added on the end. 980For example, for root \scheme{/usr/lib/scheme}, library name 981\scheme{(app lib1)}, and extension \scheme{.sls}, the full path is 982\scheme{/usr/lib/scheme/app/lib1.sls}. 983If the library name portion forms an absolute pathname, e.g., 984\scheme{~/.myappinit}, the \scheme{library-directories} parameter is 985ignored and no prefix is added. 986 987The initial values of these parameters are shown below. 988 989\schemedisplay 990(library-directories) ;=> (("." . ".")) 991 992(library-extensions) ;=> ((".chezscheme.sls" . ".chezscheme.so") 993 ;== (".ss" . ".so") 994 ;== (".sls" . ".so") 995 ;== (".scm" . ".so") 996 ;== (".sch" . ".so")) 997\endschemedisplay 998 999As a convenience, when either of these parameters is set, any element of 1000the list can be specified as a single source string, in which case the 1001object string is determined automatically. 1002For \scheme{library-directories}, the object string is the same as 1003the source string, effectively naming the 1004same directory as a source- and object-code root. 1005For \scheme{library-extensions}, the object string is the result of 1006removing the last (or only) extension from the string and appending 1007\scheme{".so"}. 1008The \scheme{library-directories} and \scheme{library-extensions} 1009parameters also accept as input strings in the format described 1010in Section~\ref{SECTUSESCRIPTING} 1011for the 1012\index{\scheme{--libdirs} command-line option}\scheme{--libdirs} and 1013\index{\scheme{--libexts} command-line option}\scheme{--libexts} command-line 1014options. 1015 1016%---------------------------------------------------------------------------- 1017\entryheader 1018\formdef{compile-imported-libraries}{\categorythreadparameter}{compile-imported-libraries} 1019\listlibraries 1020\endentryheader 1021 1022When the value of this parameter is \scheme{#t}, \scheme{import} 1023automatically calls the value of the \scheme{compile-library-handler} parameter (which defaults 1024to a procedure that simply calls \scheme{compile-library}) on any imported library if 1025the object file is missing, older than the corresponding source file, 1026older than any source files included (via \index{\scheme{include}}\scheme{include}) when the 1027object file was created, or itself requires a library that has or must 1028be recompiled, as described in Section~\ref{SECTUSELIBRARIES}. 1029The default initial value of this parameter is \scheme{#f}. 1030It can be set to \scheme{#t} via the command-line option 1031\index{\scheme{--compile-imported-libraries} command-line option}\scheme{--compile-imported-libraries}. 1032 1033When \scheme{import} compiles a library via this mechanism, it does not 1034also load the compiled library, because this would cause portions of 1035library to be reevaluated. 1036Because of this, run-time expressions in the file outside of a 1037\scheme{library} form will not be evaluated. 1038If such expressions are present and should be evaluated, the library 1039should be loaded explicitly. 1040 1041%---------------------------------------------------------------------------- 1042\entryheader 1043\formdef{import-notify}{\categorythreadparameter}{import-notify} 1044\listlibraries 1045\endentryheader 1046 1047When the new parameter \scheme{import-notify} is set to a true value, 1048\scheme{import} displays messages to the console-output port as it 1049searches for the file containing each library it needs to load. 1050The default value of this parameter is \scheme{#f}. 1051 1052%---------------------------------------------------------------------------- 1053\entryheader 1054\formdef{library-search-handler}{\categorythreadparameter}{library-search-handler} 1055\listlibraries 1056\endentryheader 1057 1058The value of parameter must be a procedure that follows the protocol described 1059below for \scheme{default-library-search-handler}, which is the default value 1060of this parameter. 1061 1062The value of this parameter is invoked to locate the source or object code for 1063a library during \scheme{import}, \scheme{compile-whole-program}, or 1064\scheme{compile-whole-library}. 1065 1066%---------------------------------------------------------------------------- 1067\entryheader 1068\formdef{default-library-search-handler}{\categoryprocedure}{(default-library-search-handler \var{who} \var{library} \var{directories} \var{extensions})} 1069\returns see below 1070\listlibraries 1071\endentryheader 1072 1073This procedure is the default value of the \scheme{library-search-handler}, 1074which is 1075called to locate the source or object code for a library 1076during \scheme{import}, 1077\scheme{compile-whole-program}, or \scheme{compile-whole-library}. 1078\var{who} is a symbol that provides context in \scheme{import-notify} messages. 1079\var{library} is the name of the desired library. 1080\var{directories} is a list of source and object directory pairs in 1081the form returned by \scheme{library-directories}. 1082\var{extensions} is a list of source and object extension pairs in the form 1083returned by \scheme{library-extensions}. 1084 1085This procedure searches the specified directories until it finds a library source or 1086object file with one of the specified extensions. 1087If it finds the source file first, it constructs the corresponding 1088object file path and checks whether the file exists. 1089If it finds the object file first, the procedure looks for a corresponding 1090source file with one of the given source extensions in a source directory paired 1091with that object directory. 1092The procedure returns three values: 1093the file-system path of the library source file or \scheme{#f} if not found, 1094the file-system path of the corresponding object file, which may be \scheme{#f}, 1095and a boolean that is true if the object file exists. 1096 1097\section{Library Inspection\label{SECTLIBRARYINSPECTION}} 1098 1099%---------------------------------------------------------------------------- 1100\noskipentryheader 1101\formdef{library-list}{\categoryprocedure}{(library-list)} 1102\returns a list of the libraries currently defined 1103\listlibraries 1104\endnoskipentryheader 1105 1106The set of libraries initially defined includes those listed in 1107Section~\ref{SECTBUILTINLIBRARIES} above. 1108 1109%---------------------------------------------------------------------------- 1110\entryheader 1111\formdef{library-version}{\categoryprocedure}{(library-version \var{libref})} 1112\returns the version of the specified library 1113\formdef{library-exports}{\categoryprocedure}{(library-exports \var{libref})} 1114\returns a list of the exports of the specified library 1115\formdef{library-requirements}{\categoryprocedure}{(library-requirements \var{libref})} 1116\returns a list of libraries required by the specified library 1117\formdef{library-requirements}{\categoryprocedure}{(library-requirements \var{libref} \var{options})} 1118\returns a list of libraries required by the specified library, filtered by \var{options} 1119\formdef{library-object-filename}{\categoryprocedure}{(library-object-filename \var{libref})} 1120\returns the name of the object file holding the specified library, if any 1121\listlibraries 1122\endentryheader 1123 1124Information can be obtained only for built-in libraries or libraries 1125previously loaded into the system. 1126\var{libref} must be an s-expression in the form of a library reference. 1127The syntax for library references is given in 1128Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR} and in the Revised$^6$ 1129Report. 1130 1131The \scheme{library-version} return value is a list of numbers 1132(possibly empty) representing the library's version. 1133 1134The list of exports returned by \scheme{library-exports} is a list of 1135symbols, each identifying one of the library's exports. 1136The order in which the elements appear is unspecified. 1137 1138When the optional \var{options} argument is supplied, it must be 1139an enumeration set over the symbols constituting 1140valid library-requirements options, as described in the 1141\scheme{library-requirements-options} entry below. 1142It defaults to a set containing all of the options. 1143Each element of the list of libraries returned by 1144\scheme{library-requirements} is an s-expression form of a library 1145reference. 1146The library reference includes the actual version of the library that is 1147present in the system (if nonempty), even if a version was not specified 1148when it was imported. 1149The order in which the libraries appear in the list returned by 1150\scheme{library-requirements} is unspecified. 1151 1152\scheme{library-object-filename} returns a string naming the object 1153file if the specified library was loaded from or compiled to an object 1154file. 1155Otherwise, it returns \scheme{#f}. 1156 1157 1158\schemedisplay 1159(with-output-to-file "A.ss" 1160 (lambda () 1161 (pretty-print 1162 '(library (A (1 2)) (export x z) 1163 (import (rnrs)) 1164 (define x 'ex) 1165 (define y 23) 1166 (define-syntax z 1167 (syntax-rules () 1168 [(_ e) (+ y e)]))))) 1169 'replace) 1170(with-output-to-file "B.ss" 1171 (lambda () 1172 (pretty-print 1173 '(library (B) (export x w) 1174 (import (rnrs) (A)) 1175 (define w (cons (z 12) x))))) 1176 'replace) 1177(compile-imported-libraries #t) 1178(import (B)) 1179(library-exports '(A)) ;=> (x z) ; or (z x) 1180(library-exports '(A (1 2))) ;=> (x z) ; or (z x) 1181(library-exports '(B)) ;=> (x w) ; or (w x) 1182(library-version '(A)) ;=> (1 2) 1183(library-version '(B)) ;=> () 1184(library-requirements '(A)) ;=> ((rnrs (6))) 1185(library-requirements '(B)) ;=> ((rnrs (6)) (A (1 2))) 1186(library-object-filename '(A)) ;=> "A.so" 1187(library-object-filename '(B)) ;=> "B.so" 1188\endschemedisplay 1189 1190%---------------------------------------------------------------------------- 1191\entryheader 1192\formdef{library-requirements-options}{\categorysyntax}{(library-requirements-options \var{symbol} \dots)} 1193\returns a library-requirements-options enumeration set 1194\listlibraries 1195\endentryheader 1196 1197\noindent 1198Library-requirements-options enumeration sets are passed to 1199\scheme{library-requirements} to determine the library requirements 1200to be listed. The available options are described below. 1201 1202\begin{description} 1203\item[\scheme{import}:] 1204Include the libraries that must be imported when the specified library 1205is imported. 1206 1207\item[\scheme{visit@visit}:] 1208Includes the libraries that must be visited when the specified library 1209is visited. 1210 1211\item[\scheme{invoke@visit}:] 1212Include the libraries that must be invoked when the specified library 1213is visited. 1214 1215\item[\scheme{invoke}:] 1216Includes the libraries that must be invoked when the specified library 1217is invoked. 1218\end{description} 1219 1220