This is guile-ref.info, produced by Makeinfo version 3.12a from guile-ref.texi. INFO-DIR-SECTION Scheme Programming START-INFO-DIR-ENTRY * guile-ref: (guile-ref). The Guile Reference Manual. END-INFO-DIR-ENTRY Guile Reference Manual Copyright (C) 1996 Free Software Foundation Copyright (C) 1997 Free Software Foundation Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: guile-ref.info, Node: Calling Scheme procedures from C, Next: Mixing gh and scm APIs, Prev: Memory allocation and garbage collection, Up: Top Calling Scheme procedures from C ******************************** Many of the Scheme primitives are available in the `gh_' interface; they take and return objects of type SCM, and one could basically use them to write C code that mimics Scheme code. I will list these routines here without much explanation, since what they do is the same as documented in *Note R4RS: (r4rs)Standard Procedures. But I will point out that when a procedure takes a variable number of arguments (such as `gh_list'), you should pass the constant SCM_EOL from C to signify the end of the list. -- Function: SCM gh_define (char *NAME, SCM VAL) Corresponds to the Scheme `(define name val)': it binds a value to the given name (which is a C string). Returns the new object. Pairs and lists =============== -- Function: SCM gh_cons (SCM A, SCM B) -- Function: SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED) These correspond to the Scheme `(cons a b)' and `(list l0 l1 ...)' procedures. Note that `gh_list()' is a C macro that invokes `scm_listify()'. -- Function: SCM gh_set_car (SCM OBJ, SCM VAL) -- Function: SCM gh_set_cdr (SCM OBJ, SCM VAL) These correspond to the Scheme `(set-car! ...)' and `(set-cdr! ...)' procedures. -- Function: SCM gh_car (SCM OBJ) -- Function: SCM gh_cdr (SCM OBJ) ... -- Function: SCM gh_c[ad][ad][ad][ad]r (SCM OBJ) These correspond to the Scheme `(caadar ls)' procedures etc ... -- Function: SCM gh_set_car_x(SCM PAIR, SCM VALUE) Modifies the CAR of PAIR to be VALUE. This is equivalent to the Scheme procedure `(set-car! ...)'. -- Function: SCM gh_set_cdr_x(SCM PAIR, SCM VALUE) Modifies the CDR of PAIR to be VALUE. This is equivalent to the Scheme procedure `(set-cdr! ...)'. -- Function: unsigned long gh_length (SCM LS) Returns the length of the list. -- Function: SCM gh_append (SCM ARGS) -- Function: SCM gh_append2 (SCM L1, SCM L2) -- Function: SCM gh_append3 (SCM L1, SCM L2, L3) -- Function: SCM gh_append4 (SCM L1, SCM L2, L3, L4) `gh_append()' takes ARGS, which is a list of lists `(list1 list2 ...)', and returns a list containing all the elements of the individual lists. A typical invocation of `gh_append()' to append 5 lists together would be gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED)); The functions `gh_append2()', `gh_append2()', `gh_append3()' and `gh_append4()' are convenience routines to make it easier for C programs to form the list of lists that goes as an argument to `gh_append()'. -- Function: SCM gh_reverse (SCM LS) Returns a new list that has the same elements as LS but in the reverse order. Note that this is implemented as a macro which calls `scm_reverse()'. -- Function: SCM gh_list_tail (SCM LS, SCM K) Returns the sublist of LS with the last K elements. -- Function: SCM gh_list_ref (SCM LS, SCM K) Returns the Kth element of the list LS. -- Function: SCM gh_memq (SCM X, SCM LS) -- Function: SCM gh_memv (SCM X, SCM LS) -- Function: SCM gh_member (SCM X, SCM LS) These functions return the first sublist of LS whose CAR is X. They correspond to `(memq x ls)', `(memv x ls)' and `(member x ls)', and hence use (respectively) `eq?', `eqv?' and `equal?' to do comparisons. If X does not appear in LS, the value `SCM_BOOL_F' (not the empty list) is returned. Note that these functions are implemented as macros which call `scm_memq()', `scm_memv()' and `scm_member()' respectively. -- Function: SCM gh_assq (SCM X, SCM ALIST) -- Function: SCM gh_assv (SCM X, SCM ALIST) -- Function: SCM gh_assoc (SCM X, SCM ALIST) These functions search an "association list" (list of pairs) ALIST for the first pair whose CAR is X, and they return that pair. If no pair in ALIST has X as its CAR, the value `SCM_BOOL_F' (not the empty list) is returned. Note that these functions are implemented as macros which call `scm_assq()', `scm_assv()' and `scm_assoc()' respectively. Symbols ======= Vectors ======= -- Function: SCM gh_make_vector (SCM N, SCM FILL) -- Function: SCM gh_vector (SCM LS) -- Function: SCM gh_vector_ref (SCM V, SCM I) -- Function: SCM gh_vector_set (SCM V, SCM I, SCM VAL) -- Function: unsigned long gh_vector_length (SCM V) -- Function: SCM gh_list_to_vector (SCM LS) These correspond to the Scheme `(make-vector n fill)', `(vector a b c ...)' `(vector-ref v i)' `(vector-set v i value)' `(vector-length v)' `(list->vector ls)' procedures. The correspondence is not perfect for `gh_vector': this routine taks a list LS instead of the individual list elements, thus making it identical to `gh_list_to_vector'. There is also a difference in gh_vector_length: the value returned is a C `unsigned long' instead of an SCM object. Procedures ========== -- Function: SCM gh_apply (SCM proc, SCM args) Call the Scheme procedure PROC, with the elements of ARGS as arguments. ARGS must be a proper list. -- Function: SCM gh_call0 (SCM proc) -- Function: SCM gh_call1 (SCM proc, SCM arg) -- Function: SCM gh_call2 (SCM proc, SCM arg1, SCM arg2) -- Function: SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3) Call the Scheme procedure PROC with no arguments (`gh_call0'), one argument (`gh_call1'), and so on. You can get the same effect by wrapping the arguments up into a list, and calling `gh_apply'; Guile provides these functions for convenience. -- Function: SCM gh_catch (SCM key, SCM thunk, SCM handler) -- Function: SCM gh_throw (SCM key, SCM args) Corresponds to the Scheme `catch' and `throw' procedures, which in Guile are provided as primitives. -- Function: SCM gh_is_eq (SCM a, SCM b) -- Function: SCM gh_is_eqv (SCM a, SCM b) -- Function: SCM gh_is_equal (SCM a, SCM b) These correspond to the Scheme `eq?', `eqv?' and `equal?' predicates. -- Function: int gh_obj_length (SCM OBJ) Returns the raw object length. Data lookup =========== For now I just include Tim Pierce's comments from the `gh_data.c' file; it should be organized into a documentation of the two functions here. /* Data lookups between C and Scheme Look up a symbol with a given name, and return the object to which it is bound. gh_lookup examines the Guile top level, and gh_module_lookup checks the module namespace specified by the `vec' argument. The return value is the Scheme object to which SNAME is bound, or SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME: should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference? -twp] */  File: guile-ref.info, Node: Mixing gh and scm APIs, Next: Scheme data representation, Prev: Calling Scheme procedures from C, Up: Top Mixing gh and scm APIs **********************  File: guile-ref.info, Node: Scheme data representation, Next: Relationship between Scheme and C functions, Prev: Mixing gh and scm APIs, Up: Top Scheme data representation **************************  File: guile-ref.info, Node: Relationship between Scheme and C functions, Next: I/O internals, Prev: Scheme data representation, Up: Top Relationship between Scheme and C functions ******************************************* --- this is where we explain that all the functions marked as "Primitive Functions" are also accessible from C, and how to derive the C interface given the Scheme interface, when we don't spell it out. ... I think there's other stuff needed here ...  File: guile-ref.info, Node: I/O internals, Next: libguile error handling, Prev: Relationship between Scheme and C functions, Up: Top I/O internals *************  File: guile-ref.info, Node: libguile error handling, Next: snarfing, Prev: I/O internals, Up: Top libguile error handling *********************** Error handling is based on catch and throw. Errors are always thrown with a key and four arguments: key: a symbol which indicates the type of error. The symbols used by libguile are listed below. subr: the name of the procedure from which the error is thrown, or #f. message: a string (possibly language and system dependent) describing the error. The tokens %s and %S can be embedded within the message: they will be replaced with members of the args list when the message is printed. %s indicates an argument printed using "display", while %S indicates an argument printed using "write". message can also be #f, to allow it to be derived from the key by the error handler (may be useful if the key is to be thrown from both C and Scheme). args: a list of arguments to be used to expand %s and %S tokens in message. Can also be #f if no arguments are required. rest: a list of any additional objects required. e.g., when the key is 'system-error, this contains the C errno value. Can also be #f if no additional objects are required. In addition to catch and throw, the following Scheme facilities are available: (scm-error key subr message args rest): throw an error, with arguments as described above. (error msg arg ...) Throw an error using the key 'misc-error. The error message is created by displaying msg and writing the args. The following are the error keys defined by libguile and the situations in which they are used: error-signal: thrown after receiving an unhandled fatal signal such as SIGSEV, SIGBUS, SIGFPE etc. The "rest" argument in the throw contains the coded signal number (at present this is not the same as the usual Unix signal number). system-error: thrown after the operating system indicates an error condition. The "rest" argument in the throw contains the errno value. numerical-overflow: numerical overflow. out-of-range: the arguments to a procedure do not fall within the accepted domain. wrong-type-arg: an argument to a procedure has the wrong thpe. wrong-number-of-args: a procedure was called with the wrong number of arguments. memory-allocation-error: memory allocation error. stack-overflow: stack overflow error. regex-error: errors generated by the regular expression library. misc-error: other errors. C support ========= SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest) Throws an error, after converting the char * arguments to Scheme strings. subr is the Scheme name of the procedure, NULL is converted to #f. Likewise a NULL message is converted to #f. The following procedures invoke scm_error with various error keys and arguments. The first three call scm_error with the system-error key and automatically supply errno in the "rest" argument: scm_syserror generates messages using strerror, scm_sysmissing is used when facilities are not available. Care should be taken that the errno value is not reset (e.g., due to an interrupt.) void scm_syserror (char *subr); void scm_syserror_msg (char *subr, char *message, SCM args); void scm_sysmissing (char *subr); void scm_num_overflow (char *subr); void scm_out_of_range (char *subr, SCM bad_value); void scm_wrong_num_args (SCM proc); void scm_wrong_type_arg (char *subr, int pos, SCM bad_value); void scm_memory_error (char *subr); static void scm_regex_error (char *subr, int code); (only used in rgx.c). void (*scm_error_callback) (SCM key, char *subr, char *message, SCM args, SCM rest)); When a pointer to a C procedure is assigned to this variable, the procedure will be called whenever scm_error is invoked. It can be used by C code to retain control after a Scheme error occurs.  File: guile-ref.info, Node: snarfing, Next: Obtaining and Installing Guile, Prev: libguile error handling, Up: Top snarfing ********  File: guile-ref.info, Node: Obtaining and Installing Guile, Next: Reporting Bugs, Prev: snarfing, Up: Top Obtaining and Installing Guile ****************************** Here is the information you will need to get and install Guile and extra packages and documentation you might need or find interesting. * Menu: * The Basic Guile Package:: * Packages not shipped with Guile::  File: guile-ref.info, Node: The Basic Guile Package, Next: Packages not shipped with Guile, Up: Obtaining and Installing Guile The Basic Guile Package ======================= Guile can be obtained from the main GNU archive site or any of its mirrors. The file will be named guile-version.tar.gz. The current version is 1.2a, so the file you should grab is: To unbundle Guile use the instruction zcat guile-1.2a.tar.gz | tar xvf - which will create a directory called `guile-1.2a' with all the sources. You can look at the file `INSTALL' for detailed instructions on how to build and install Guile, but you should be able to just do cd guile-1.2a ./configure make install This will install the Guile executable `guile', the Guile library `libguile.a' and various associated header files and support libraries. It will also install the Guile tutorial and reference manual. Since this manual frequently refers to the Scheme ``standard'', also known as R4RS, or the ``Revised^4 Report on the Algorithmic Language Scheme'', we have included the report in the Guile distribution; *Note Introduction: (r4rs)Top. This will also be installed in your info directory.  File: guile-ref.info, Node: Packages not shipped with Guile, Prev: The Basic Guile Package, Up: Obtaining and Installing Guile Packages not shipped with Guile =============================== We ship the Guile tutorial and reference manual with the Guile distribution [FIXME: this is not currently true (Sat Sep 20 14:13:33 MDT 1997), but will be soon.] Since the Scheme standard (R4RS) is a stable document, we ship that too. Here are references (usually World Wide Web URLs) to some other freely redistributable documents and packages which you might find useful if you are using Guile. *SCSH* the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant chapter (*note The Scheme shell (scsh)::.) has references to the SCSH web page with all its documentation. *SLIB* a portable Scheme library maintained by Aubrey Jaffer. SLIB can be obtained by ftp from . The SLIB package should be unpacked somewhere in Guile's load path. It will typically be unpacked in `/usr/local/share/guile/site', so that it will be `/usr/local/share/guile/site/slib'. Guile might have been installed with a different prefix, in which case the load path can be checked from inside the interpreter with: guile> %load-path ("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".") The relevant chapter (*note SLIB::.) has details on how to use SLIB with Guile. *JACAL* a symbolic math package by Aubrey Jaffer. The latest version of Jacal can be obtained from , and should be unpacked in `/usr/local/share/guile/site/slib' so that it will be in `/usr/local/share/guile/site/slib/jacal'. The relevant section (*note JACAL::.) has details on how to use Jacal.  File: guile-ref.info, Node: Reporting Bugs, Next: Internals, Prev: Obtaining and Installing Guile, Up: Top Reporting Bugs ************** Any problems with the installation should be reported to [[how about an explanation of what makes a good bug report?]] [[don't complain to us about problems with contributed modules?]]  File: guile-ref.info, Node: Internals, Next: debugger user interface, Prev: Reporting Bugs, Up: Top Internals ********* This appendix describes many functions that may be used to inspect and modify Guile's internal structure. These will mainly be of interest to people interested in extending, modifying or debugging Guile. * Menu: * Symbols:: Manipulating the Scheme symbol table.  File: guile-ref.info, Node: Symbols, Up: Internals Symbols ======= Guile symbol tables are hash tables. Each hash table, also called an "obarray" (for `object array'), is a vector of association lists. Each entry in the alists is a pair (SYMBOL . VALUE). To "intern" a symbol in a symbol table means to return its (SYMBOL . VALUE) pair, adding a new entry to the symbol table (with an undefined value) if none is yet present. -- primitive: string->obarray-symbol obarray string [soft?] Intern a new symbol in OBARRAY, a symbol table, with name STRING. If OBARRAY is `#f', use the default system symbol table. If OBARRAY is `#t', the symbol should not be interned in any symbol table; merely return the pair (SYMBOL . #). The SOFT? argument determines whether new symbol table entries should be created when the specified symbol is not already present in OBARRAY. If SOFT? is specified and is a true value, then new entries should not be added for symbols not already present in the table; instead, simply return `#f'. -- primitive: intern-symbol obarray string Add a new symbol to OBARRAY with name STRING, bound to an unspecified initial value. The symbol table is not modified if a symbol with this name is already present. -- primitive: unintern-symbol obarray string Remove the symbol with name STRING from OBARRAY. This function returns `#t' if the symbol was present and `#f' otherwise. -- primitive: symbol-binding obarray string Look up in OBARRAY the symbol whose name is STRING, and return the value to which it is bound. If OBARRAY is `#f', use the global symbol table. If STRING is not interned in OBARRAY, an error is signalled. -- primitive: symbol-interned? obarray string Return #T if OBARRAY contains a symbol with name STRING, and #F otherwise. -- primitive: symbol-bound? obarray string Return #T if OBARRAY contains a symbol with name STRING bound to a defined value. This differs from SYMBOL-BOUND? in that the mere mention of a symbol usually causes it to be interned; `symbol-bound?' determines whether a symbol has been given any meaningful value. -- primitive: symbol-set! obarray string value Find the symbol in OBARRAY whose name is STRING, and rebind it to VALUE. An error is signalled if STRING is not present in OBARRAY. -- primitive: symbol-fref symbol Return the contents of SYMBOL's "function slot". -- primitive: symbol-pref symbol Return the "property list" currently associated with SYMBOL. -- primitive: symbol-fset! symbol Change the binding of SYMBOL's function slot. -- primitive: symbol-pset! symbol Change the binding of SYMBOL's property slot. -- primitive: symbol-hash symbol Return the hash value derived from SYMBOL's name, i.e. the integer index into SYMBOL's obarray at which it is stored. -- primitive: builtin-bindings Create and return a copy of the global symbol table, removing all unbound symbols. -- primitive: builtin-weak-bindings -- primitive: gensym [name [obarray]] Create a new, unique symbol in OBARRAY, using the global symbol table by default. If NAME is specified, it should be used as a prefix for the new symbol's name. The default prefix is `%%gensym'.  File: guile-ref.info, Node: debugger user interface, Next: Concept Index, Prev: Internals, Up: Top debugger user interface *********************** When debugging a program, programmers often find it helpful to examine the program's internal status while it runs: the values of internal variables, the choices made in `if' and `cond' statements, and so forth. Guile Scheme provides a debugging interface that programmers can use to single-step through Scheme functions and examine symbol bindings. This is different from the *Note Internal Debugging Interface::, which permits programmers to debug the Guile interpreter itself. Most programmers will be more interested in debugging their own Scheme programs than the interpreter which evaluates them. [FIXME: should we include examples of traditional debuggers and explain why they can't be used to debug interpreted Scheme or Lisp?] * Menu: * Single-Step:: Execute a program or function one step at a time. * Trace:: Print a report each time a given function is called. * Backtrace:: See a list of the statements that caused an error. * Stacks and Frames:: Examine the state of an interrupted program.  File: guile-ref.info, Node: Single-Step, Next: Trace, Up: debugger user interface Single-Step ===========  File: guile-ref.info, Node: Trace, Next: Backtrace, Prev: Single-Step, Up: debugger user interface Trace ===== When a function is "traced", it means that every call to that function is reported to the user during a program run. This can help a programmer determine whether a function is being called at the wrong time or with the wrong set of arguments. -- Function: trace function Enable debug tracing on `function'. While a program is being run, Guile will print a brief report at each call to a traced function, advising the user which function was called and the arguments that were passed to it. -- Function: untrace function Disable debug tracing for `function'. Example: (define (rev ls) (if (null? ls) '() (append (rev (cdr ls)) (cons (car ls) '())))) => rev (trace rev) => (rev) (rev '(a b c d e)) => [rev (a b c d e)] | [rev (b c d e)] | | [rev (c d e)] | | | [rev (d e)] | | | | [rev (e)] | | | | | [rev ()] | | | | | () | | | | (e) | | | (e d) | | (e d c) | (e d c b) (e d c b a) (e d c b a) Note the way Guile indents the output, illustrating the depth of execution at each function call. This can be used to demonstrate, for example, that Guile implements self-tail-recursion properly: (define (rev ls sl) (if (null? ls) sl (rev (cdr ls) (cons (car ls) sl)))) => rev (trace rev) => (rev) (rev '(a b c d e) '()) => [rev (a b c d e) ()] [rev (b c d e) (a)] [rev (c d e) (b a)] [rev (d e) (c b a)] [rev (e) (d c b a)] [rev () (e d c b a)] (e d c b a) (e d c b a) Since the tail call is effectively optimized to a `goto' statement, there is no need for Guile to create a new stack frame for each iteration. Using `trace' here helps us see why this is so.  File: guile-ref.info, Node: Backtrace, Next: Stacks and Frames, Prev: Trace, Up: debugger user interface Backtrace =========  File: guile-ref.info, Node: Stacks and Frames, Prev: Backtrace, Up: debugger user interface Stacks and Frames ================= When a running program is interrupted, usually upon reaching an error or breakpoint, its state is represented by a "stack" of suspended function calls, each of which is called a "frame". The programmer can learn more about the program's state at the point of interruption by inspecting and modifying these frames. -- primitive: stack? obj Return `#t' if OBJ is a calling stack. -- primitive: make-stack -- syntax: start-stack id exp Evaluate EXP on a new calling stack with identity ID. If EXP is interrupted during evaluation, backtraces will not display frames farther back than EXP's top-level form. This macro is a way of artificially limiting backtraces and stack procedures, largely as a convenience to the user. -- primitive: stack-id stack Return the identifier given to STACK by `start-stack'. -- primitive: stack-ref -- primitive: stack-length -- primitive: frame? -- primitive: last-stack-frame -- primitive: frame-number -- primitive: frame-source -- primitive: frame-procedure -- primitive: frame-arguments -- primitive: frame-previous -- primitive: frame-next -- primitive: frame-real? -- primitive: frame-procedure? -- primitive: frame-evaluating-args? -- primitive: frame-overflow  File: guile-ref.info, Node: Concept Index, Next: Procedure Index, Prev: debugger user interface, Up: Top Concept Index ************* * Menu: * converting data: Converting data between C and Scheme. * data conversion: Converting data between C and Scheme. * dynamic roots: Dynamic Roots. * emacs regexp: Regular Expressions. * encapsulation: Modules. * error handling: Exceptions. * error messages in libguile: Error messages. * exception handling: Exceptions. * executing Scheme: Executing Scheme code. * extending Guile: A Portable C to Scheme Interface. * finite automaton: Rx Interface. * gh: A Portable C to Scheme Interface. * gh - headers: gh preliminaries. * gh - linking: gh preliminaries. * gh - reference manual: A Portable C to Scheme Interface. * gh_ interface: A Portable C to Scheme Interface. * Green, Anthony: Threads. * Guile - extending: A Portable C to Scheme Interface. * Guile threads: Threads. * information encapsulation: Modules. * Jaffer, Aubrey <1>: JACAL. * Jaffer, Aubrey: A Portable C to Scheme Interface. * libguile - converting data: Converting data between C and Scheme. * libguile - data types: Data types and constants defined by gh. * libguile - error messages: Error messages. * libguile - executing Scheme: Executing Scheme code. * libguile - gh: A Portable C to Scheme Interface. * libguile - new procedures: Defining new Scheme procedures in C. * libguile - start interpreter: Starting and controlling the interpreter. * libguile interface: A Portable C to Scheme Interface. * Lord, Tom: Threads. * match structures: Match Structures. * math -- symbolic: JACAL. * modules: Modules. * name space: Modules. * name space - private: Modules. * new primitives: Defining new Scheme procedures in C. * new procedures: Defining new Scheme procedures in C. * options - read: Reader options. * options interface: Guile options interface. * posix threads: Threads. * primitives, new: Defining new Scheme procedures in C. * procedures, new: Defining new Scheme procedures in C. * read eval print loop -- from the gh_ interface: Starting and controlling the interpreter. * read options: Reader options. * regex: Regular Expressions. * regular expressions: Regular Expressions. * REPL -- from the gh_ interface: Starting and controlling the interpreter. * rx: Rx Interface. * SCM data type: Data types and constants defined by gh. * SCM internals: A Portable C to Scheme Interface. * SCM interpreter: A Portable C to Scheme Interface. * symbolic math: JACAL. * threads: Threads.