code:
# Automatically generated, do not edit.
standard_library_scm_files = $(top_srcdir)/module/statprof.scm $(top_srcdir)/module/sxml/apply-templates.scm $(top_srcdir)/module/sxml/fold.scm $(top_srcdir)/module/sxml/simple.scm $(top_srcdir)/module/sxml/ssax.scm $(top_srcdir)/module/sxml/ssax/input-parse.scm $(top_srcdir)/module/sxml/transform.scm $(top_srcdir)/module/sxml/xpath.scm $(top_srcdir)/module/texinfo.scm $(top_srcdir)/module/texinfo/docbook.scm $(top_srcdir)/module/texinfo/html.scm $(top_srcdir)/module/texinfo/indexing.scm $(top_srcdir)/module/texinfo/string-utils.scm $(top_srcdir)/module/texinfo/plain-text.scm $(top_srcdir)/module/texinfo/serialize.scm $(top_srcdir)/module/texinfo/reflection.scm

license: mit


code:
;; The modules to document
(define *modules*
  '(((statprof)
     "Statistical profiler")
    ((sxml apply-templates)
     "A more XSLT-like approach to SXML transformations")
    ((sxml fold)
     "Fold-based SXML transformation operators")
    ((sxml simple)
     "Convenient XML parsing and serializing")
    ((sxml ssax)
     "Functional-style XML parsing for Scheme")
    ((sxml ssax input-parse)
     "The SSAX tokenizer, optimized for Guile")
    ((sxml transform)
     "A higher-order SXML transformation operator, "
     (code "pre-post-order"))
    ((sxml xpath)
     "XPath for SXML")
    ((texinfo)
     "Parse texinfo files or fragments into " (code "stexi") ", a "
     "scheme representation")
    ((texinfo docbook)
     "Transform a subset of docbook into " (code "stexi"))
    ((texinfo html)
     "Transform " (code "stexi") " into HTML")
    ((texinfo indexing)
     "Extract an index from a piece of " (code "stexi"))
    ((texinfo string-utils)
     "String utility functions used by the texinfo processor")
    ((texinfo plain-text)
     "Render " (code "stexi") " as plain text")
    ((texinfo serialize)
     "Render " (code "stexi") " as texinfo")
    ((texinfo reflection)
     "Enable texinfo across Guile's help system")))

(define *module-sources*
  '(((sxml ssax) . "http://ssax.sourceforge.net/")
    ((sxml xpath) . "http://ssax.sourceforge.net/")
    ((sxml transform) . "http://ssax.sourceforge.net/")
    ((sxml apply-templates) . "http://ssax.sourceforge.net/")
    ((sxml ssax input-parse) . "http://ssax.sourceforge.net/")
    ((htmlprag) . "http://neilvandyke.org/htmlprag/")))

(define *scripts* '())

;; arch-tag: e493ad42-ad58-451c-a2d6-b17ba6c1d1d0


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 2010  Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@c
@c Based on the documentation at
@c <http://planet.plt-scheme.org/package-source/jim/sxml-match.plt/1/1/doc.txt>,
@c copyright 2005 Jim Bender, and released under the MIT/X11 license (like the
@c rest of `sxml-match'.)
@c
@c Converted to Texinfo and modified by Ludovic Courtès, 2010.

@node sxml-match
@section @code{sxml-match}: Pattern Matching of SXML

@cindex pattern matching (SXML)
@cindex SXML pattern matching

The @code{(sxml match)} module provides syntactic forms for pattern matching of
SXML trees, in a ``by example'' style reminiscent of the pattern matching of the
@code{syntax-rules} and @code{syntax-case} macro systems.  @xref{sxml simple,
the @code{(sxml simple)} module}, for more information on SXML.

The following example@footnote{This example is taken from a paper by
Krishnamurthi et al.  Their paper was the first to show the usefulness of the
@code{syntax-rules} style of pattern matching for transformation of XML, though
the language described, XT3D, is an XML language.} provides a brief
illustration, transforming a music album catalog language into HTML.

@lisp
(define (album->html x)
  (sxml-match x
    [(album (@@ (title ,t)) (catalog (num ,n) (fmt ,f)) ...)
     `(ul (li ,t)
          (li (b ,n) (i ,f)) ...)]))
@end lisp

Three macros are provided: @code{sxml-match}, @code{sxml-match-let}, and
@code{sxml-match-let*}.

Compared to a standard s-expression pattern matcher, @code{sxml-match} provides
the following benefits:

@itemize
@item
matching of SXML elements does not depend on any degree of normalization of the
SXML;
@item
matching of SXML attributes (within an element) is under-ordered; the order of
the attributes specified within the pattern need not match the ordering with the
element being matched;
@item
all attributes specified in the pattern must be present in the element being
matched; in the spirit that XML is 'extensible', the element being matched may
include additional attributes not specified in the pattern.
@end itemize

The present module is a descendant of WebIt!, and was inspired by an
s-expression pattern matcher developed by Erik Hilsdale, Dan Friedman, and Kent
Dybvig at Indiana University.

@unnumberedsubsec Syntax

@code{sxml-match} provides @code{case}-like form for pattern matching of XML
nodes.

@deffn {Scheme Syntax} sxml-match input-expression clause ...
Match @var{input-expression}, an SXML tree, according to the given @var{clause}s
(one or more), each consisting of a pattern and one or more expressions to be
evaluated if the pattern match succeeds.  Optionally, each @var{clause} within
@code{sxml-match} may include a @dfn{guard expression}.
@end deffn

The pattern notation is based on that of Scheme's @code{syntax-rules} and
@code{syntax-case} macro systems.  The grammar for the @code{sxml-match} syntax
is given below:

@verbatim
match-form ::= (sxml-match input-expression
                 clause+)

clause ::= [node-pattern action-expression+]
         | [node-pattern (guard expression*) action-expression+]

node-pattern ::= literal-pattern
               | pat-var-or-cata
               | element-pattern
               | list-pattern

literal-pattern ::= string
                  | character
                  | number
                  | #t
                  | #f

attr-list-pattern ::= (@ attribute-pattern*)
                    | (@ attribute-pattern* . pat-var-or-cata)

attribute-pattern ::= (tag-symbol attr-val-pattern)

attr-val-pattern ::= literal-pattern
                   | pat-var-or-cata
                   | (pat-var-or-cata default-value-expr)

element-pattern ::= (tag-symbol attr-list-pattern?)
                  | (tag-symbol attr-list-pattern? nodeset-pattern)
                  | (tag-symbol attr-list-pattern?
                                nodeset-pattern? . pat-var-or-cata)

list-pattern ::= (list nodeset-pattern)
               | (list nodeset-pattern? . pat-var-or-cata)
               | (list)

nodeset-pattern ::= node-pattern
                  | node-pattern ...
                  | node-pattern nodeset-pattern
                  | node-pattern ... nodeset-pattern

pat-var-or-cata ::= (unquote var-symbol)
                  | (unquote [var-symbol*])
                  | (unquote [cata-expression -> var-symbol*])
@end verbatim

Within a list or element body pattern, ellipses may appear only once, but may be
followed by zero or more node patterns.

Guard expressions cannot refer to the return values of catamorphisms.

Ellipses in the output expressions must appear only in an expression context;
ellipses are not allowed in a syntactic form.

The sections below illustrate specific aspects of the @code{sxml-match} pattern
matcher.

@unnumberedsubsec Matching XML Elements

The example below illustrates the pattern matching of an XML element:

@lisp
(sxml-match '(e (@@ (i 1)) 3 4 5)
  [(e (@@ (i ,d)) ,a ,b ,c) (list d a b c)]
  [,otherwise #f])
@end lisp

Each clause in @code{sxml-match} contains two parts: a pattern and one or more
expressions which are evaluated if the pattern is successfully match.  The
example above matches an element @code{e} with an attribute @code{i} and three
children.

Pattern variables are must be ``unquoted'' in the pattern.  The above expression
binds @var{d} to @code{1}, @var{a} to @code{3}, @var{b} to @code{4}, and @var{c}
to @code{5}.

@unnumberedsubsec Ellipses in Patterns

As in @code{syntax-rules}, ellipses may be used to specify a repeated pattern.
Note that the pattern @code{item ...} specifies zero-or-more matches of the
pattern @code{item}.

The use of ellipses in a pattern is illustrated in the code fragment below,
where nested ellipses are used to match the children of repeated instances of an
@code{a} element, within an element @code{d}.

@lisp
(define x '(d (a 1 2 3) (a 4 5) (a 6 7 8) (a 9 10)))

(sxml-match x
  [(d (a ,b ...) ...)
   (list (list b ...) ...)])
@end lisp

The above expression returns a value of @code{((1 2 3) (4 5) (6 7 8) (9 10))}.

@unnumberedsubsec Ellipses in Quasiquote'd Output

Within the body of an @code{sxml-match} form, a slightly extended version of
quasiquote is provided, which allows the use of ellipses.  This is illustrated
in the example below.

@lisp
(sxml-match '(e 3 4 5 6 7)
  [(e ,i ... 6 7) `("start" ,(list 'wrap i) ... "end")]
  [,otherwise #f])
@end lisp

The general pattern is that @code{`(something ,i ...)} is rewritten as
@code{`(something ,@@i)}.

@unnumberedsubsec Matching Nodesets

A nodeset pattern is designated by a list in the pattern, beginning the
identifier list.  The example below illustrates matching a nodeset.

@lisp
(sxml-match '("i" "j" "k" "l" "m")
  [(list ,a ,b ,c ,d ,e)
   `((p ,a) (p ,b) (p ,c) (p ,d) (p ,e))])
@end lisp

This example wraps each nodeset item in an HTML paragraph element.  This example
can be rewritten and simplified through using ellipsis:

@lisp
(sxml-match '("i" "j" "k" "l" "m")
  [(list ,i ...)
   `((p ,i) ...)])
@end lisp

This version will match nodesets of any length, and wrap each item in the
nodeset in an HTML paragraph element.

@unnumberedsubsec Matching the ``Rest'' of a Nodeset

Matching the ``rest'' of a nodeset is achieved by using a @code{. rest)} pattern
at the end of an element or nodeset pattern.

This is illustrated in the example below:

@lisp
(sxml-match '(e 3 (f 4 5 6) 7)
  [(e ,a (f . ,y) ,d)
   (list a y d)])
@end lisp

The above expression returns @code{(3 (4 5 6) 7)}.

@unnumberedsubsec Matching the Unmatched Attributes

Sometimes it is useful to bind a list of attributes present in the element being
matched, but which do not appear in the pattern.  This is achieved by using a
@code{. rest)} pattern at the end of the attribute list pattern.  This is
illustrated in the example below:

@lisp
(sxml-match '(a (@@ (z 1) (y 2) (x 3)) 4 5 6)
  [(a (@@ (y ,www) . ,qqq) ,t ,u ,v)
   (list www qqq t u v)])
@end lisp

The above expression matches the attribute @code{y} and binds a list of the
remaining attributes to the variable @var{qqq}.  The result of the above
expression is @code{(2 ((z 1) (x 3)) 4 5 6)}.

This type of pattern also allows the binding of all attributes:

@lisp
(sxml-match '(a (@@ (z 1) (y 2) (x 3)))
  [(a (@@ . ,qqq))
   qqq])
@end lisp

@unnumberedsubsec Default Values in Attribute Patterns

It is possible to specify a default value for an attribute which is used if the
attribute is not present in the element being matched.  This is illustrated in
the following example:

@lisp
(sxml-match '(e 3 4 5)
  [(e (@@ (z (,d 1))) ,a ,b ,c) (list d a b c)])
@end lisp

The value @code{1} is used when the attribute @code{z} is absent from the
element @code{e}.

@unnumberedsubsec Guards in Patterns

Guards may be added to a pattern clause via the @code{guard} keyword.  A guard
expression may include zero or more expressions which are evaluated only if the
pattern is matched.  The body of the clause is only evaluated if the guard
expressions evaluate to @code{#t}.

The use of guard expressions is illustrated below:

@lisp
(sxml-match '(a 2 3)
  ((a ,n) (guard (number? n)) n)
  ((a ,m ,n) (guard (number? m) (number? n)) (+ m n)))
@end lisp

@unnumberedsubsec Catamorphisms

The example below illustrates the use of explicit recursion within an
@code{sxml-match} form.  This example implements a simple calculator for the
basic arithmetic operations, which are represented by the XML elements
@code{plus}, @code{minus}, @code{times}, and @code{div}.

@lisp
(define simple-eval
  (lambda (x)
    (sxml-match x
      [,i (guard (integer? i)) i]
      [(plus ,x ,y) (+ (simple-eval x) (simple-eval y))]
      [(times ,x ,y) (* (simple-eval x) (simple-eval y))]
      [(minus ,x ,y) (- (simple-eval x) (simple-eval y))]
      [(div ,x ,y) (/ (simple-eval x) (simple-eval y))]
      [,otherwise (error "simple-eval: invalid expression" x)])))
@end lisp

Using the catamorphism feature of @code{sxml-match}, a more concise version of
@code{simple-eval} can be written.  The pattern @code{,[x]} recusively invokes
the pattern matcher on the value bound in this position.

@lisp
(define simple-eval
  (lambda (x)
    (sxml-match x
      [,i (guard (integer? i)) i]
      [(plus ,[x] ,[y]) (+ x y)]
      [(times ,[x] ,[y]) (* x y)]
      [(minus ,[x] ,[y]) (- x y)]
      [(div ,[x] ,[y]) (/ x y)]
      [,otherwise (error "simple-eval: invalid expression" x)])))
@end lisp

@unnumberedsubsec Named-Catamorphisms

It is also possible to explicitly name the operator in the ``cata'' position.
Where @code{,[id*]} recurs to the top of the current @code{sxml-match},
@code{,[cata -> id*]} recurs to @code{cata}.  @code{cata} must evaluate to a
procedure which takes one argument, and returns as many values as there are
identifiers following @code{->}.

Named catamorphism patterns allow processing to be split into multiple, mutually
recursive procedures.  This is illustrated in the example below: a
transformation that formats a ``TV Guide'' into HTML.

@lisp
(define (tv-guide->html g)
  (define (cast-list cl)
    (sxml-match cl
      [(CastList (CastMember (Character (Name ,ch)) (Actor (Name ,a))) ...)
       `(div (ul (li ,ch ": " ,a) ...))]))
  (define (prog p)
    (sxml-match p
      [(Program (Start ,start-time) (Duration ,dur) (Series ,series-title)
                (Description ,desc ...))
       `(div (p ,start-time
                (br) ,series-title
                (br) ,desc ...))]
      [(Program (Start ,start-time) (Duration ,dur) (Series ,series-title)
                (Description ,desc ...)
                ,[cast-list -> cl])
       `(div (p ,start-time
                (br) ,series-title
                (br) ,desc ...)
             ,cl)]))
  (sxml-match g
    [(TVGuide (@@ (start ,start-date)
                 (end ,end-date))
              (Channel (Name ,nm) ,[prog -> p] ...) ...)
     `(html (head (title "TV Guide"))
            (body (h1 "TV Guide")
                  (div (h2 ,nm) ,p ...) ...))]))
@end lisp

@unnumberedsubsec @code{sxml-match-let} and @code{sxml-match-let*}

@deffn {Scheme Syntax} sxml-match-let ((pat expr) ...) expression0 expression ...)
@deffnx {Scheme Syntax} sxml-match-let* ((pat expr) ...) expression0 expression ...)
These forms generalize the @code{let} and @code{let*} forms of Scheme to allow
an XML pattern in the binding position, rather than a simple variable.
@end deffn

For example, the expression below:

@lisp
(sxml-match-let ([(a ,i ,j) '(a 1 2)])
  (+ i j))
@end lisp

binds the variables @var{i} and @var{j} to @code{1} and @code{2} in the XML
value given.

@c Local Variables:
@c coding: utf-8
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Miscellaneous Tools
@chapter Miscellaneous Tools

Programming is more fun with a good tools.  This chapter describes snarfing
tools, and the @code{guile-tools} program which can be used to invoke the rest
of the tools (which are self-documenting).  Some of these are used in Guile
development, too.  Imagine that!

@menu
* Snarfing::                    Grepping the source in various ways.
* Executable Modules::          Modules callable via guile-tools.
@end menu

@c ---------------------------------------------------------------------------
@node Snarfing
@section Snarfing
@cindex snarfing

Because it's easier to maintain documentation, code, and other metainfo in one
source file than in many files, there have evolved many methods for grepping
source to lift and separate these kinds of info, in the process generating
docs or fragments of source or what have you.  This is known generally as
@dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to
unceremoniously extract information from a somewhat unwilling source.''

This section documents the installed program @code{guile-snarf} which does
@dfn{init snarfing}, and also touches upon guile's doc snarfing process which
is not yet finalized (i.e., doc snarfing programs are not installed at this
time).

@menu
* Init Snarfing with guile-snarf::      Exposing C subrs and friends to Scheme.
* Doc Snarfing::                        Generating GDFv2 or texi from source.
@end menu

@c ---------------------------------------------------------------------------
@node Init Snarfing with guile-snarf
@subsection Init Snarfing with guile-snarf
@c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi.
@cindex snarfing, init
@cindex primitive functions
@cindex subrs, defining

When writing C code for use with Guile, you typically define a set of C
functions, and then make some of them visible to the Scheme world by
calling the @code{scm_c_define_gsubr} function; a C function published in
this way is called a @dfn{subr}.  If you have many subrs to publish, it
can sometimes be annoying to keep the list of calls to
@code{scm_c_define_gsubr} in sync with the list of function definitions.
Frequently, a programmer will define a new subr in C, recompile the
application, and then discover that the Scheme interpreter cannot see
the subr, because of a missed call to @code{scm_c_define_gsubr}.

Guile provides the @code{guile-snarf} command to manage this problem.
Using this tool, you can keep all the information needed to define the
subr alongside the function definition itself; @code{guile-snarf} will
extract this information from your source code, and automatically
generate a file of calls to @code{scm_c_define_gsubr} which you can
@code{#include} into an initialization function.

@menu
* How guile-snarf works::           Using @code{guile-snarf}, with example.
* Macros guile-snarf recognizes::   How to mark up code for @code{guile-snarf}.
* Writing your own snarfing macros:: How to define new things to snarf.
@end menu

@c ---------------------------------------------------------------------------
@node How guile-snarf works
@subsubsection How guile-snarf works
@cindex guile-snarf invocation
@cindex guile-snarf example

Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]

The @code{guile-snarf} program will extract initialization actions to
@var{outfile} or to standard output when no @var{outfile} has been
specified or when @var{outfile} is @code{-}.  The C preprocessor is
called with @var{cpp-args} (which usually include an input file) and
the output is filtered to extract the initialization actions.

If there are errors during processing, @var{outfile} is deleted and the
program exits with non-zero status.

During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
defined.  You could use this to avoid including snarfer output files
that don't yet exist by writing code like this:

@smallexample
#ifndef SCM_MAGIC_SNARFER
#include "foo.x"
#endif
@end smallexample

If the environment variable @code{CPP} is set, use its value instead of the
C pre-processor determined at Guile configure-time.

@xref{Macros guile-snarf recognizes}, for a list of the special (some would
say magic) cpp macros you can use, including the list of deprecated macros.

For example, here is how you might define a new subr called
@code{clear-image}, implemented by the C function @code{clear_image}:

@example
@group
#include <libguile.h>

SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
            (SCM image_smob),
            "Clear the image.")
#define FUNC_NAME s_clear_image
@{
  /* C code to clear the image in @code{image_smob}... */
@}
#undef FUNC_NAME

void
init_image_type ()
@{
#include "image-type.x"
@}
@end group
@end example

The @code{SCM_DEFINE} declaration says that the C function
@code{clear_image} implements a Scheme subr called @code{clear-image},
which takes one required argument (of type @code{SCM} and named
@code{image_smob}), no optional arguments, and no rest argument.
@xref{Doc Snarfing}, for info on the docstring.

This works in concert with @code{FUNC_NAME} to also define a static
array of characters named @code{s_clear_image}, initialized to the
string "clear-image".  The body of @code{clear_image} may use the array
in error messages, instead of writing out the literal string; this may
save string space on some systems.

Assuming the text above lives in a file named @file{image-type.c}, you will
need to execute the following command to prepare this file for compilation:

@example
guile-snarf -o image-type.x image-type.c
@end example

This scans @file{image-type.c} for @code{SCM_DEFINE}
declarations, and writes to @file{image-type.x} the output:

@example
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
@end example

When compiled normally, @code{SCM_DEFINE} is a macro which expands to
a declaration of the @code{s_clear_image} string and the function
header for @code{clear_image}.

Note that the output file name matches the @code{#include} from the
input file.  Also, you still need to provide all the same information
you would if you were using @code{scm_c_define_gsubr} yourself, but you
can place the information near the function definition itself, so it is
less likely to become incorrect or out-of-date.

If you have many files that @code{guile-snarf} must process, you should
consider using a fragment like the following in your Makefile:

@example
snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
.SUFFIXES: .x
.c.x:
	guile-snarf -o $@@ $< $(snarfcppopts)
@end example

This tells make to run @code{guile-snarf} to produce each needed
@file{.x} file from the corresponding @file{.c} file.

The program @code{guile-snarf} passes its command-line arguments
directly to the C preprocessor, which it uses to extract the
information it needs from the source code. this means you can pass
normal compilation flags to @code{guile-snarf} to define preprocessor
symbols, add header file directories, and so on.

@c ---------------------------------------------------------------------------
@node Macros guile-snarf recognizes
@subsubsection Macros guile-snarf recognizes
@cindex guile-snarf recognized macros
@cindex guile-snarf deprecated macros

Here are the macros you can use in your source code from which
@code{guile-snarf} can construct initialization code:

@example
/* procedures */
SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)

SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)

SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)

/* everything else */
SCM_SYMBOL (c_name, scheme_name)
SCM_GLOBAL_SYMBOL (c_name, scheme_name)

SCM_KEYWORD (c_name, scheme_name)
SCM_GLOBAL_KEYWORD (c_name, scheme_name)

SCM_VARIABLE (c_name, scheme_name)
SCM_GLOBAL_VARIABLE (c_name, scheme_name)

SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
@end example

@c i like things dense, but maybe someone else will reformat this
@c into an easier-to-read list.  also, all-upcase to me is a form
@c of quoting, so @var{} is not necessary there. --ttn
REQ and OPT are numbers indicating required and optional argument
counts, respectively; VAR is a number that, if non-zero, means the
function will accept any remaining arguments as a list; DOCSTRING is a
string (use @code{\n\} at eol for multi-line); FNAME is a C-language
identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
denoting the name available to Scheme code, STR and @var{scheme_name}
likewise; RANAME is the name of the static string (must match that
declared by the associated definition of cpp macro @var{FUNC_NAME});
ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
is a expression suitable for initializing a new variable.

For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use
@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
want to be bothered with docstrings.  Use @code{SCM_GPROC} for generic
functions (@pxref{Creating Generic Functions}).  All procedures are
declared with return type @code{SCM}.

For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
symbols, and so on).  Without "_GLOBAL_", the declarations are
@code{static}.

All these macros should be used at top-level, outside function bodies.
Also, it's a good idea to define @var{FUNC_NAME} immediately after using
@code{SCM_DEFINE} (and similar), and then the function body, and then
@code{#undef FUNC_NAME}.

@xref{How guile-snarf works}, and also libguile source, for examples.
@xref{Subrs}, for details on argument passing and how to write C
functions.

@c ---------------------------------------------------------------------------
@node Writing your own snarfing macros
@subsubsection Writing your own snarfing macros

When you want to use the general snarfing machanism, but none of the
provided macros fits your need, you can use the macro
@code{SCM_SNARF_INIT}.

For example, the @code{SCM_SYMBOL} macro can be defined like this:

@example
#define SCM_SYMBOL(c_name, scheme_name) \
static SCM c_name \
SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
@end example

@defmac SCM_SNARF_INIT (code)
When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
when processed by the snarfer, it causes @var{code} to be included in
the initialization action file, followed by a semicolon.
@end defmac

@c ---------------------------------------------------------------------------
@node Doc Snarfing
@subsection Doc Snarfing

In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
the libguile sources are also subject to doc snarfing, by programs that
are included in the distribution (but not installed at this time).  The
output is the file @file{guile-procedures.txt} which is installed, and
subsequently used by module @code{(ice-9 documentation)}.

Here is a list of what does what according to @file{libguile/Makefile.am}:

@itemize
@item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
@item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
@item ../scripts/snarf-check-and-output-texi makes guile.texi
@item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
@item guile-func-name-check checks source snarf-syntax integrity (optional?)
@end itemize

Note that for guile-1.4, a completely different approach was used!  All this
is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.

[fixme: Document further once doc snarfing is tamed somewhat. --ttn]

@c ---------------------------------------------------------------------------
@node Executable Modules
@section Executable Modules
@cindex guile-tools
@cindex modules, executable
@cindex executable modules
@cindex scripts

When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
Each is a regular Scheme module that has some additional packaging so
that it can be called as a program in its own right, from the shell.  For this
reason, we sometimes use the term @dfn{script} in this context to mean the
same thing.

@c wow look at this hole^!  variable-width font users eat your heart out.

As a convenience, the @code{guile-tools} wrapper program is installed along w/
@code{guile}; it knows where a particular module is installed and calls it
passing its args to the program.  The result is that you need not augment your
PATH.  Usage is straightforward:

@example
guile-tools --help
guile-tools --version
guile-tools [OPTION] PROGRAM [ARGS ...]

If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
PROGRAM is run w/ ARGS.  Options (only one of which may be used at a time):
 --scriptsdir DIR    -- Look in DIR for scripts
 --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
 --source            -- Display PROGRAM source (ignore ARGS) to stdout
@end example

The modules are self-documenting.  For example, to see the documentation for
@code{lint}, use one (or both) of the shell commands:

@example
guile-tools display-commentary '(scripts lint)'
guile-tools --source lint
@end example

The rest of this section describes the packaging that goes into creating an
executable module.  Feel free to skip to the next chapter.

@subsection Writing Executable Modules

@c adapted from scripts/README

See template file @code{PROGRAM} for a quick start.

Programs must follow the @dfn{executable module} convention, documented here:

@itemize

@item
The file name must not end in ".scm".

@item
The file must be executable (chmod +x).

@item
The module name must be "(scripts PROGRAM)".  A procedure named PROGRAM w/
signature "(PROGRAM . args)" must be exported.  Basically, use some variant
of the form:

@example
(define-module (scripts PROGRAM)
  #:export (PROGRAM))
@end example

Feel free to export other definitions useful in the module context.

@item
There must be the alias:

@example
(define main PROGRAM)
@end example

However, `main' must NOT be exported.

@item
The beginning of the file must use the following invocation sequence:

@example
#!/bin/sh
main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
!#
@end example

@end itemize

Following these conventions allows the program file to be used as module
@code{(scripts PROGRAM)} in addition to as a standalone executable.  Please
also include a helpful Commentary section w/ some usage info.

@c tools.texi ends here


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@raisesections

@node Hello Guile!
@section Hello Guile!

This chapter presents a quick tour of all the ways that Guile can be
used.  There are additional examples in the @file{examples/}
directory in the Guile source distribution.  It also explains how best to report
any problems that you find.

The following examples assume that Guile has been installed in
@code{/usr/local/}.

@menu
* Running Guile Interactively::
* Running Guile Scripts::
* Linking Guile into Programs::
* Writing Guile Extensions::
* Using the Guile Module System::
* Reporting Bugs::
@end menu

@node Running Guile Interactively
@subsection Running Guile Interactively

In its simplest form, Guile acts as an interactive interpreter for the
Scheme programming language, reading and evaluating Scheme expressions
the user enters from the terminal.  Here is a sample interaction between
Guile and a user; the user's input appears after the @code{$} and
@code{scheme@@(guile-user)>} prompts:

@example
$ guile
scheme@@(guile-user)> (+ 1 2 3)                ; add some numbers
$1 = 6
scheme@@(guile-user)> (define (factorial n)    ; define a function
                       (if (zero? n) 1 (* n (factorial (- n 1)))))
scheme@@(guile-user)> (factorial 20)
$2 = 2432902008176640000
scheme@@(guile-user)> (getpwnam "root")        ; look in /etc/passwd
$3 = #("root" "x" 0 0 "root" "/root" "/bin/bash")
scheme@@(guile-user)> @kbd{C-d}
$
@end example

@node Running Guile Scripts
@subsection Running Guile Scripts

Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile
script is simply a file of Scheme code with some extra information at
the beginning which tells the operating system how to invoke Guile, and
then tells Guile how to handle the Scheme code.

Here is a trivial Guile script, for more details @xref{Guile Scripting}.

@example
#!/usr/local/bin/guile -s
!#
(display "Hello, world!")
(newline)
@end example

@node Linking Guile into Programs
@subsection Linking Guile into Programs

The Guile interpreter is available as an object library, to be linked
into applications using Scheme as a configuration or extension
language.

Here is @file{simple-guile.c}, source code for a program that will
produce a complete Guile interpreter.  In addition to all usual
functions provided by Guile, it will also offer the function
@code{my-hostname}.

@example
#include <stdlib.h>
#include <libguile.h>

static SCM
my_hostname (void)
@{
  char *s = getenv ("HOSTNAME");
  if (s == NULL)
    return SCM_BOOL_F;
  else
    return scm_from_locale_string (s);
@}

static void
inner_main (void *data, int argc, char **argv)
@{
  scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
  scm_shell (argc, argv);
@}

int
main (int argc, char **argv)
@{
  scm_boot_guile (argc, argv, inner_main, 0);
  return 0; /* never reached */
@}
@end example

When Guile is correctly installed on your system, the above program
can be compiled and linked like this:

@example
$ gcc -o simple-guile simple-guile.c \
    `pkg-config --cflags --libs guile-2.0`
@end example

When it is run, it behaves just like the @code{guile} program except
that you can also call the new @code{my-hostname} function.

@example
$ ./simple-guile
scheme@@(guile-user)> (+ 1 2 3)
$1 = 6
scheme@@(guile-user)> (my-hostname)
"burns"
@end example

@node Writing Guile Extensions
@subsection Writing Guile Extensions

You can link Guile into your program and make Scheme available to the
users of your program.  You can also link your library into Guile and
make its functionality available to all users of Guile.

A library that is linked into Guile is called an @dfn{extensions}, but
it really just is an ordinary object library.

The following example shows how to write a simple extension for Guile
that makes the @code{j0} function available to Scheme code.

@smallexample
#include <math.h>
#include <libguile.h>

SCM
j0_wrapper (SCM x)
@{
  return scm_make_real (j0 (scm_num2dbl (x, "j0")));
@}

void
init_bessel ()
@{
  scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
@}
@end smallexample

This C source file needs to be compiled into a shared library.  Here is
how to do it on GNU/Linux:

@smallexample
gcc -shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample

For creating shared libraries portably, we recommend the use of GNU
Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).

A shared library can be loaded into a running Guile process with the
function @code{load-extension}.  The @code{j0} is then immediately
available:

@smallexample
$ guile
scheme@@(guile-user)> (load-extension "./libguile-bessel" "init_bessel")
scheme@@(guile-user)> (j0 2)
$1 = 0.223890779141236
@end smallexample

@node Using the Guile Module System
@subsection Using the Guile Module System

Guile has support for dividing a program into @dfn{modules}.  By using
modules, you can group related code together and manage the
composition of complete programs from largely independent parts.

(Although the module system implementation is in flux, feel free to use it
anyway.  Guile will provide reasonable backwards compatibility.)

Details on the module system beyond this introductory material can be found in
@xref{Modules}.

@menu
* Using Modules::
* Writing new Modules::
* Putting Extensions into Modules::
@end menu

@node Using Modules
@subsubsection Using Modules

Guile comes with a lot of useful modules, for example for string
processing or command line parsing.  Additionally, there exist many
Guile modules written by other Guile hackers, but which have to be
installed manually.

Here is a sample interactive session that shows how to use the
@code{(ice-9 popen)} module which provides the means for communicating
with other processes over pipes together with the @code{(ice-9
rdelim)} module that provides the function @code{read-line}.

@smallexample
$ guile
scheme@@(guile-user)> (use-modules (ice-9 popen))
scheme@@(guile-user)> (use-modules (ice-9 rdelim))
scheme@@(guile-user)> (define p (open-input-pipe "ls -l"))
scheme@@(guile-user)> (read-line p)
$1 = "total 30"
scheme@@(guile-user)> (read-line p)
$2 = "drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"
@end smallexample

@node Writing new Modules
@subsubsection Writing new Modules

You can create new modules using the syntactic form
@code{define-module}.  All definitions following this form until the
next @code{define-module} are placed into the new module.

One module is usually placed into one file, and that file is installed
in a location where Guile can automatically find it.  The following
session shows a simple example.

@smallexample
$ cat /usr/local/share/guile/foo/bar.scm

(define-module (foo bar))
(export frob)

(define (frob x) (* 2 x))

$ guile
scheme@@(guile-user)> (use-modules (foo bar))
scheme@@(guile-user)> (frob 12)
$1 = 24
@end smallexample

@node Putting Extensions into Modules
@subsubsection Putting Extensions into Modules

In addition to Scheme code you can also put things that are defined in
C into a module.

You do this by writing a small Scheme file that defines the module and
call @code{load-extension} directly in the body of the module.

@smallexample
$ cat /usr/local/share/guile/math/bessel.scm

(define-module (math bessel))
(export j0)

(load-extension "libguile-bessel" "init_bessel")

$ file /usr/local/lib/libguile-bessel.so
@dots{} ELF 32-bit LSB shared object @dots{}
$ guile
scheme@@(guile-user)> (use-modules (math bessel))
scheme@@(guile-user)> (j0 2)
$1 = 0.223890779141236
@end smallexample

There is also a way to manipulate the module system from C but only
Scheme files can be autoloaded.  Thus, we recommend that you define
your modules in Scheme.

@lowersections

@node Reporting Bugs
@section Reporting Bugs

Any problems with the installation should be reported to
@email{bug-guile@@gnu.org}.

If you find a bug in Guile, please report it to the Guile developers, so
they can fix it.  They may also be able to suggest workarounds when it
is not possible for you to apply the bug-fix or install a new version of
Guile yourself.

Before sending in bug reports, please check with the following list that
you really have found a bug.

@itemize @bullet
@item
Whenever documentation and actual behavior differ, you have certainly
found a bug, either in the documentation or in the program.

@item
When Guile crashes, it is a bug.

@item
When Guile hangs or takes forever to complete a task, it is a bug.

@item
When calculations produce wrong results, it is a bug.

@item
When Guile signals an error for valid Scheme programs, it is a bug.

@item
When Guile does not signal an error for invalid Scheme programs, it may
be a bug, unless this is explicitly documented.

@item
When some part of the documentation is not clear and does not make sense
to you even after re-reading the section, it is a bug.
@end itemize

Before reporting the bug, check whether any programs you have loaded
into Guile, including your @file{.guile} file, set any variables that
may affect the functioning of Guile.  Also, see whether the problem
happens in a freshly started Guile without loading your @file{.guile}
file (start Guile with the @code{-q} switch to prevent loading the init
file).  If the problem does @emph{not} occur then, you must report the
precise contents of any programs that you must load into Guile in order
to cause the problem to occur.

When you write a bug report, please make sure to include as much of the
information described below in the report.  If you can't figure out some
of the items, it is not a problem, but the more information we get, the
more likely we can diagnose and fix the bug.

@itemize @bullet
@item
The version number of Guile. You can get this information from invoking
@samp{guile --version} at your shell, or calling @code{(version)} from
within Guile.

@item
Your machine type, as determined by the @code{config.guess} shell
script. If you have a Guile checkout, this file is located in
@code{build-aux}; otherwise you can fetch the latest version from
@uref{http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD}.

@example
$ build-aux/config.guess
x86_64-unknown-linux-gnu
@end example

@item
If you installed Guile from a binary package, the version of that
package. On systems that use RPM, use @code{rpm -qa | grep guile}. On systems
that use DPKG, @code{dpkg -l | grep guile}.

@item
If you built Guile yourself, the build configuration that you used:

@example
$ ./config.status --config
'--enable-error-on-warning' '--disable-deprecated' '--prefix=/opt/guile' '--libdir=/opt/guile/lib64' 'CC=ccache gcc'
@end example

@item
A complete description of how to reproduce the bug.

If you have a Scheme program that produces the bug, please include it in
the bug report. If your program is too big to include. please try to
reduce your code to a minimal test case.

If you can reproduce your problem at the REPL, that is best. Give a
transcript of the expressions you typed at the REPL.

@item
A description of the incorrect behavior.  For example, "The Guile
process gets a fatal signal," or, "The resulting output is as follows,
which I think is wrong."

If the manifestation of the bug is a Guile error message, it is
important to report the precise text of the error message, and a
backtrace showing how the Scheme program arrived at the error. This can
be done using the @code{,backtrace} command in Guile's debugger.
@end itemize

If your bug causes Guile to crash, additional information from a
low-level debugger such as GDB might be helpful. If you have built Guile
yourself, you can run Guile under GDB via the
@code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
usual, invoke the wrapper script, type @code{run} to start the process,
then @code{backtrace} when the crash comes. Include that backtrace in
your report.

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  2008,2009,2010
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node A Virtual Machine for Guile
@section A Virtual Machine for Guile

Guile has both an interpreter and a compiler. To a user, the difference
is transparent---interpreted and compiled procedures can call each other
as they please.

The difference is that the compiler creates and interprets bytecode
for a custom virtual machine, instead of interpreting the
S-expressions directly. Loading and running compiled code is faster
than loading and running source code.

The virtual machine that does the bytecode interpretation is a part of
Guile itself. This section describes the nature of Guile's virtual
machine.

@menu
* Why a VM?::
* VM Concepts::
* Stack Layout::
* Variables and the VM::
* VM Programs::
* Instruction Set::
@end menu

@node Why a VM?
@subsection Why a VM?

@cindex interpreter
For a long time, Guile only had an interpreter. Guile's interpreter
operated directly on the S-expression representation of Scheme source
code.

But while the interpreter was highly optimized and hand-tuned, it still
performs many needless computations during the course of evaluating an
expression. For example, application of a function to arguments
needlessly consed up the arguments in a list. Evaluation of an
expression always had to figure out what the car of the expression is --
a procedure, a memoized form, or something else. All values have to be
allocated on the heap. Et cetera.

The solution to this problem was to compile the higher-level language,
Scheme, into a lower-level language for which all of the checks and
dispatching have already been done---the code is instead stripped to
the bare minimum needed to ``do the job''.

The question becomes then, what low-level language to choose? There
are many options. We could compile to native code directly, but that
poses portability problems for Guile, as it is a highly cross-platform
project.

So we want the performance gains that compilation provides, but we
also want to maintain the portability benefits of a single code path.
The obvious solution is to compile to a virtual machine that is
present on all Guile installations.

The easiest (and most fun) way to depend on a virtual machine is to
implement the virtual machine within Guile itself. This way the
virtual machine provides what Scheme needs (tail calls, multiple
values, @code{call/cc}) and can provide optimized inline instructions
for Guile (@code{cons}, @code{struct-ref}, etc.).

So this is what Guile does. The rest of this section describes that VM
that Guile implements, and the compiled procedures that run on it.

Before moving on, though, we should note that though we spoke of the
interpreter in the past tense, Guile still has an interpreter. The
difference is that before, it was Guile's main evaluator, and so was
implemented in highly optimized C; now, it is actually implemented in
Scheme, and compiled down to VM bytecode, just like any other program.
(There is still a C interpreter around, used to bootstrap the compiler,
but it is not normally used at runtime.)

The upside of implementing the interpreter in Scheme is that we preserve
tail calls and multiple-value handling between interpreted and compiled
code. The downside is that the interpreter in Guile 2.0 is slower than
the interpreter in 1.8. We hope the that the compiler's speed makes up
for the loss!

Also note that this decision to implement a bytecode compiler does not
preclude native compilation. We can compile from bytecode to native
code at runtime, or even do ahead of time compilation. More
possibilities are discussed in @ref{Extending the Compiler}.

@node VM Concepts
@subsection VM Concepts

Compiled code is run by a virtual machine (VM). Each thread has its own
VM. When a compiled procedure is run, Guile looks up the virtual machine
for the current thread and executes the procedure using that VM.

Guile's virtual machine is a stack machine---that is, it has few
registers, and the instructions defined in the VM operate by pushing
and popping values from a stack.

Stack memory is exclusive to the virtual machine that owns it. In
addition to their stacks, virtual machines also have access to the
global memory (modules, global bindings, etc) that is shared among
other parts of Guile, including other VMs.

A VM has generic instructions, such as those to reference local
variables, and instructions designed to support Guile's languages --
mathematical instructions that support the entire numerical tower, an
inlined implementation of @code{cons}, etc.

The registers that a VM has are as follows:

@itemize
@item ip - Instruction pointer
@item sp - Stack pointer
@item fp - Frame pointer
@end itemize

In other architectures, the instruction pointer is sometimes called
the ``program counter'' (pc). This set of registers is pretty typical
for stack machines; their exact meanings in the context of Guile's VM
are described in the next section.

@c wingo: The following is true, but I don't know in what context to
@c describe it. A documentation FIXME.

@c A VM may have one of three engines: reckless, regular, or debugging.
@c Reckless engine is fastest but dangerous.  Regular engine is normally
@c fail-safe and reasonably fast.  Debugging engine is safest and
@c functional but very slow.

@c (Actually we have just a regular and a debugging engine; normally
@c we use the latter, it's almost as fast as the ``regular'' engine.)

@node Stack Layout
@subsection Stack Layout

While not strictly necessary to understand how to work with the VM, it
is instructive and sometimes entertaining to consider the structure of
the VM stack.

Logically speaking, a VM stack is composed of ``frames''. Each frame
corresponds to the application of one compiled procedure, and contains
storage space for arguments, local variables, intermediate values, and
some bookkeeping information (such as what to do after the frame
computes its value).

While the compiler is free to do whatever it wants to, as long as the
semantics of a computation are preserved, in practice every time you
call a function, a new frame is created. (The notable exception of
course is the tail call case, @pxref{Tail Calls}.)

Within a frame, you have the data associated with the function
application itself, which is of a fixed size, and the stack space for
intermediate values. Sometimes only the former is referred to as the
``frame'', and the latter is the ``stack'', although all pending
application frames can have some intermediate computations interleaved
on the stack.

The structure of the fixed part of an application frame is as follows:

@example
             Stack
   | ...              |
   | Intermed. val. 0 | <- fp + bp->nargs + bp->nlocs = SCM_FRAME_UPPER_ADDRESS (fp)
   +==================+
   | Local variable 1 |
   | Local variable 0 | <- fp + bp->nargs
   | Argument 1       |
   | Argument 0       | <- fp
   | Program          | <- fp - 1
   +------------------+
   | Return address   |
   | MV return address|
   | Dynamic link     | <- fp - 4 = SCM_FRAME_DATA_ADDRESS (fp) = SCM_FRAME_LOWER_ADDRESS (fp)
   +==================+
   |                  |
@end example

In the above drawing, the stack grows upward. The intermediate values
stored in the application of this frame are stored above
@code{SCM_FRAME_UPPER_ADDRESS (fp)}. @code{bp} refers to the
@code{struct scm_objcode} data associated with the program at
@code{fp - 1}. @code{nargs} and @code{nlocs} are properties of the
compiled procedure, which will be discussed later.

The individual fields of the frame are as follows:

@table @asis
@item Return address
The @code{ip} that was in effect before this program was applied. When
we return from this activation frame, we will jump back to this
@code{ip}.

@item MV return address
The @code{ip} to return to if this application returns multiple
values. For continuations that only accept one value, this value will
be @code{NULL}; for others, it will be an @code{ip} that points to a
multiple-value return address in the calling code. That code will
expect the top value on the stack to be an integer---the number of
values being returned---and that below that integer there are the
values being returned.

@item Dynamic link
This is the @code{fp} in effect before this program was applied. In
effect, this and the return address are the registers that are always
``saved''. The dynamic link links the current frame to the previous
frame; computing a stack trace involves traversing these frames.

@item Local variable @var{n}
Lambda-local variables that are all allocated as part of the frame.
This makes access to variables very cheap.

@item Argument @var{n}
The calling convention of the VM requires arguments of a function
application to be pushed on the stack, and here they are. References
to arguments dispatch to these locations on the stack.

@item Program
This is the program being applied. For more information on how
programs are implemented, @xref{VM Programs}.
@end table

@node Variables and the VM
@subsection Variables and the VM

Consider the following Scheme code as an example:

@example
  (define (foo a)
    (lambda (b) (list foo a b)))
@end example

Within the lambda expression, @code{foo} is a top-level variable, @code{a} is a
lexically captured variable, and @code{b} is a local variable.

Another way to refer to @code{a} and @code{b} is to say that @code{a}
is a ``free'' variable, since it is not defined within the lambda, and
@code{b} is a ``bound'' variable. These are the terms used in the
@dfn{lambda calculus}, a mathematical notation for describing
functions. The lambda calculus is useful because it allows one to
prove statements about functions. It is especially good at describing
scope relations, and it is for that reason that we mention it here.

Guile allocates all variables on the stack. When a lexically enclosed
procedure with free variables---a @dfn{closure}---is created, it copies
those variables into its free variable vector. References to free
variables are then redirected through the free variable vector.

If a variable is ever @code{set!}, however, it will need to be
heap-allocated instead of stack-allocated, so that different closures
that capture the same variable can see the same value. Also, this
allows continuations to capture a reference to the variable, instead
of to its value at one point in time. For these reasons, @code{set!}
variables are allocated in ``boxes''---actually, in variable cells.
@xref{Variables}, for more information. References to @code{set!}
variables are indirected through the boxes.

Thus perhaps counterintuitively, what would seem ``closer to the
metal'', viz @code{set!}, actually forces an extra memory allocation
and indirection.

Going back to our example, @code{b} may be allocated on the stack, as
it is never mutated.

@code{a} may also be allocated on the stack, as it too is never
mutated. Within the enclosed lambda, its value will be copied into
(and referenced from) the free variables vector.

@code{foo} is a top-level variable, because @code{foo} is not
lexically bound in this example.

@node VM Programs
@subsection Compiled Procedures are VM Programs

By default, when you enter in expressions at Guile's REPL, they are
first compiled to VM object code, then that VM object code is executed
to produce a value. If the expression evaluates to a procedure, the
result of this process is a compiled procedure.

A compiled procedure is a compound object, consisting of its bytecode,
a reference to any captured lexical variables, an object array, and
some metadata such as the procedure's arity, name, and documentation.
You can pick apart these pieces with the accessors in @code{(system vm
program)}. @xref{Compiled Procedures}, for a full API reference.

@cindex object table
@cindex object array
The object array of a compiled procedure, also known as the
@dfn{object table}, holds all Scheme objects whose values are known
not to change across invocations of the procedure: constant strings,
symbols, etc. The object table of a program is initialized right
before a program is loaded with @code{load-program}.
@xref{Loading Instructions}, for more information.

Variable objects are one such type of constant object: when a global
binding is defined, a variable object is associated to it and that
object will remain constant over time, even if the value bound to it
changes. Therefore, toplevel bindings only need to be looked up once.
Thereafter, references to the corresponding toplevel variables from
within the program are then performed via the @code{toplevel-ref}
instruction, which uses the object vector, and are almost as fast as
local variable references.

We can see how these concepts tie together by disassembling the
@code{foo} function we defined earlier to see what is going on:

@smallexample
scheme@@(guile-user)> (define (foo a) (lambda (b) (list foo a b)))
scheme@@(guile-user)> ,x foo
   0    (assert-nargs-ee/locals 1)
   2    (object-ref 1)                  ;; #<procedure 8ebec20 at <current input>:0:17 (b)>
   4    (local-ref 0)                   ;; `a'
   6    (make-closure 0 1)
   9    (return)

----------------------------------------
Disassembly of #<procedure 8ebec20 at <current input>:0:17 (b)>:

   0    (assert-nargs-ee/locals 1)
   2    (toplevel-ref 1)                ;; `foo'
   4    (free-ref 0)                    ;; (closure variable)
   6    (local-ref 0)                   ;; `b'
   8    (list 0 3)                      ;; 3 elements         at (unknown file):0:29
  11    (return)
@end smallexample

First there's some prelude, where @code{foo} checks that it was called with only
1 argument. Then at @code{ip} 2, we load up the compiled lambda. @code{Ip} 4
loads up `a', so that it can be captured into a closure by at @code{ip}
6---binding code (from the compiled lambda) with data (the free-variable
vector). Finally we return the closure.

The second stanza disassembles the compiled lambda. After the prelude, we note
that toplevel variables are resolved relative to the module that was current
when the procedure was created. This lookup occurs lazily, at the first time the
variable is actually referenced, and the location of the lookup is cached so
that future references are very cheap. @xref{Top-Level Environment Instructions},
for more details.

Then we see a reference to a free variable, corresponding to @code{a}. The
disassembler doesn't have enough information to give a name to that variable, so
it just marks it as being a ``closure variable''. Finally we see the reference
to @code{b}, then the @code{list} opcode, an inline implementation of the
@code{list} scheme routine.

@node Instruction Set
@subsection Instruction Set

There are about 180 instructions in Guile's virtual machine. These
instructions represent atomic units of a program's execution. Ideally,
they perform one task without conditional branches, then dispatch to
the next instruction in the stream.

Instructions themselves are one byte long. Some instructions take
parameters, which follow the instruction byte in the instruction
stream.

Sometimes the compiler can figure out that it is compiling a special
case that can be run more efficiently. So, for example, while Guile
offers a generic test-and-branch instruction, it also offers specific
instructions for special cases, so that the following cases all have
their own test-and-branch instructions:

@example
(if pred then else)
(if (not pred) then else)
(if (null? l) then else)
(if (not (null? l)) then else)
@end example

In addition, some Scheme primitives have their own inline
implementations, e.g. @code{cons}, and @code{list}, as we saw in the
previous section.

So Guile's instruction set is a @emph{complete} instruction set, in
that it provides the instructions that are suited to the problem, and
is not concerned with making a minimal, orthogonal set of
instructions. More instructions may be added over time.

@menu
* Lexical Environment Instructions::
* Top-Level Environment Instructions::
* Procedure Call and Return Instructions::
* Function Prologue Instructions::
* Trampoline Instructions::
* Branch Instructions::
* Data Constructor Instructions::
* Loading Instructions::
* Dynamic Environment Instructions::
* Miscellaneous Instructions::
* Inlined Scheme Instructions::
* Inlined Mathematical Instructions::
* Inlined Bytevector Instructions::
@end menu

@node Lexical Environment Instructions
@subsubsection Lexical Environment Instructions

These instructions access and mutate the lexical environment of a
compiled procedure---its free and bound variables.

Some of these instructions have @code{long-} variants, the difference
being that they take 16-bit arguments, encoded in big-endianness,
instead of the normal 8-bit range.

@xref{Stack Layout}, for more information on the format of stack frames.

@deffn Instruction local-ref index
@deffnx Instruction long-local-ref index
Push onto the stack the value of the local variable located at
@var{index} within the current stack frame.

Note that arguments and local variables are all in one block. Thus the
first argument, if any, is at index 0, and local bindings follow the
arguments.
@end deffn

@deffn Instruction local-set index
@deffnx Instruction long-local-set index
Pop the Scheme object located on top of the stack and make it the new
value of the local variable located at @var{index} within the current
stack frame.
@end deffn

@deffn Instruction box index
Pop a value off the stack, and set the @var{index}nth local variable
to a box containing that value. A shortcut for @code{make-variable}
then @code{local-set}, used when binding boxed variables.
@end deffn

@deffn Instruction empty-box index
Set the @var{indext}h local variable to a box containing a variable
whose value is unbound. Used when compiling some @code{letrec}
expressions.
@end deffn

@deffn Instruction local-boxed-ref index
@deffnx Instruction local-boxed-ref index
Get or set the value of the variable located at @var{index} within the
current stack frame. A shortcut for @code{local-ref} then
@code{variable-ref} or @code{variable-set}, respectively.
@end deffn

@deffn Instruction free-ref index
Push the value of the captured variable located at position
@var{index} within the program's vector of captured variables.
@end deffn

@deffn Instruction free-boxed-ref index
@deffnx Instruction free-boxed-set index
Get or set a boxed free variable. A shortcut for @code{free-ref} then
@code{variable-ref} or @code{variable-set}, respectively.

Note that there is no @code{free-set} instruction, as variables that are
@code{set!} must be boxed.
@end deffn

@deffn Instruction make-closure num-free-vars
Pop @var{num-free-vars} values and a program object off the stack in
that order, and push a new program object closing over the given free
variables. @var{num-free-vars} is encoded as a two-byte big-endian
value.

The free variables are stored in an array, inline to the new program
object, in the order that they were on the stack (not the order they are
popped off). The new closure shares state with the original program. At
the time of this writing, the space overhead of closures is 3 words,
plus one word for each free variable.
@end deffn

@deffn Instruction fix-closure index
Fix up the free variables array of the closure stored in the
@var{index}th local variable. @var{index} is a two-byte big-endian
integer.

This instruction will pop as many values from the stack as are in the
corresponding closure's free variables array. The topmost value on the
stack will be stored as the closure's last free variable, with other
values filling in free variable slots in order.

@code{fix-closure} is part of a hack for allocating mutually recursive
procedures. The hack is to store the procedures in their corresponding
local variable slots, with space already allocated for free variables.
Then once they are all in place, this instruction fixes up their
procedures' free variable bindings in place. This allows most
@code{letrec}-bound procedures to be allocated unboxed on the stack.
@end deffn

@deffn Instruction local-bound? index
@deffnx Instruction long-local-bound? index
Push @code{#t} on the stack if the @code{index}th local variable has
been assigned, or @code{#f} otherwise. Mostly useful for handling
optional arguments in procedure prologues.
@end deffn

@node Top-Level Environment Instructions
@subsubsection Top-Level Environment Instructions

These instructions access values in the top-level environment: bindings
that were not lexically apparent at the time that the code in question
was compiled.

The location in which a toplevel binding is stored can be looked up once
and cached for later. The binding itself may change over time, but its
location will stay constant.

Currently only toplevel references within procedures are cached, as only
procedures have a place to cache them, in their object tables.

@deffn Instruction toplevel-ref index
@deffnx Instruction long-toplevel-ref index
Push the value of the toplevel binding whose location is stored in at
position @var{index} in the current procedure's object table. The
@code{long-} variant encodes the index over two bytes.

Initially, a cell in a procedure's object table that is used by
@code{toplevel-ref} is initialized to one of two forms. The normal case
is that the cell holds a symbol, whose binding will be looked up
relative to the module that was current when the current program was
created.

Alternately, the lookup may be performed relative to a particular
module, determined at compile-time (e.g. via @code{@@} or
@code{@@@@}). In that case, the cell in the object table holds a list:
@code{(@var{modname} @var{sym} @var{public?})}. The symbol @var{sym}
will be looked up in the module named @var{modname} (a list of
symbols). The lookup will be performed against the module's public
interface, unless @var{public?} is @code{#f}, which it is for example
when compiling @code{@@@@}.

In any case, if the symbol is unbound, an error is signalled.
Otherwise the initial form is replaced with the looked-up variable, an
in-place mutation of the object table. This mechanism provides for
lazy variable resolution, and an important cached fast-path once the
variable has been successfully resolved.

This instruction pushes the value of the variable onto the stack.
@end deffn

@deffn Instruction toplevel-set index
@deffnx Instruction long-toplevel-set index
Pop a value off the stack, and set it as the value of the toplevel
variable stored at @var{index} in the object table. If the variable
has not yet been looked up, we do the lookup as in
@code{toplevel-ref}.
@end deffn

@deffn Instruction define
Pop a symbol and a value from the stack, in that order. Look up its
binding in the current toplevel environment, creating the binding if
necessary. Set the variable to the value.
@end deffn

@deffn Instruction link-now
Pop a value, @var{x}, from the stack. Look up the binding for @var{x},
according to the rules for @code{toplevel-ref}, and push that variable
on the stack. If the lookup fails, an error will be signalled.

This instruction is mostly used when loading programs, because it can
do toplevel variable lookups without an object table.
@end deffn

@deffn Instruction variable-ref
Dereference the variable object which is on top of the stack and
replace it by the value of the variable it represents.
@end deffn

@deffn Instruction variable-set
Pop off two objects from the stack, a variable and a value, and set
the variable to the value.
@end deffn

@deffn Instruction variable-bound?
Pop off the variable object from top of the stack and push @code{#t} if
it is bound, or @code{#f} otherwise. Mostly useful in procedure
prologues for defining default values for boxed optional variables.
@end deffn

@deffn Instruction make-variable
Replace the top object on the stack with a variable containing it.
Used in some circumstances when compiling @code{letrec} expressions.
@end deffn

@node Procedure Call and Return Instructions
@subsubsection Procedure Call and Return Instructions

@c something about the calling convention here?

@deffn Instruction new-frame
Push a new frame on the stack, reserving space for the dynamic link,
return address, and the multiple-values return address. The frame
pointer is not yet updated, because the frame is not yet active -- it
has to be patched by a @code{call} instruction to get the return
address.
@end deffn

@deffn Instruction call nargs
Call the procedure located at @code{sp[-nargs]} with the @var{nargs}
arguments located from @code{sp[-nargs + 1]} to @code{sp[0]}.

This instruction requires that a new frame be pushed on the stack before
the procedure, via @code{new-frame}. @xref{Stack Layout}, for more
information. It patches up that frame with the current @code{ip} as the
return address, then dispatches to the first instruction in the called
procedure, relying on the called procedure to return one value to the
newly-created continuation. Because the new frame pointer will point to
@code{sp[-nargs + 1]}, the arguments don't have to be shuffled around --
they are already in place.
@end deffn

@deffn Instruction tail-call nargs
Transfer control to the procedure located at @code{sp[-nargs]} with the
@var{nargs} arguments located from @code{sp[-nargs + 1]} to
@code{sp[0]}.

Unlike @code{call}, which requires a new frame to be pushed onto the
stack, @code{tail-call} simply shuffles down the procedure and arguments
to the current stack frame. This instruction implements tail calls as
required by RnRS.
@end deffn

@deffn Instruction apply nargs
@deffnx Instruction tail-apply nargs
Like @code{call} and @code{tail-call}, except that the top item on the
stack must be a list. The elements of that list are then pushed on the
stack and treated as additional arguments, replacing the list itself,
then the procedure is invoked as usual.
@end deffn

@deffn Instruction call/nargs
@deffnx Instruction tail-call/nargs
These are like @code{call} and @code{tail-call}, except they take the
number of arguments from the stack instead of the instruction stream.
These instructions are used in the implementation of multiple value
returns, where the actual number of values is pushed on the stack.
@end deffn

@deffn Instruction mv-call nargs offset
Like @code{call}, except that a multiple-value continuation is created
in addition to a single-value continuation.

The offset (a three-byte value) is an offset within the instruction
stream; the multiple-value return address in the new frame (@pxref{Stack
Layout}) will be set to the normal return address plus this offset.
Instructions at that offset will expect the top value of the stack to be
the number of values, and below that values themselves, pushed
separately.
@end deffn

@deffn Instruction return
Free the program's frame, returning the top value from the stack to
the current continuation. (The stack should have exactly one value on
it.)

Specifically, the @code{sp} is decremented to one below the current
@code{fp}, the @code{ip} is reset to the current return address, the
@code{fp} is reset to the value of the current dynamic link, and then
the returned value is pushed on the stack.
@end deffn

@deffn Instruction return/values nvalues
@deffnx Instruction return/nvalues
Return the top @var{nvalues} to the current continuation. In the case of
@code{return/nvalues}, @var{nvalues} itself is first popped from the top
of the stack.

If the current continuation is a multiple-value continuation,
@code{return/values} pushes the number of values on the stack, then
returns as in @code{return}, but to the multiple-value return address.

Otherwise if the current continuation accepts only one value, i.e. the
multiple-value return address is @code{NULL}, then we assume the user
only wants one value, and we give them the first one. If there are no
values, an error is signaled.
@end deffn

@deffn Instruction return/values* nvalues
Like a combination of @code{apply} and @code{return/values}, in which
the top value on the stack is interpreted as a list of additional
values. This is an optimization for the common @code{(apply values
...)} case.
@end deffn

@deffn Instruction truncate-values nbinds nrest
Used in multiple-value continuations, this instruction takes the
values that are on the stack (including the number-of-values marker)
and truncates them for a binding construct.

For example, a call to @code{(receive (x y . z) (foo) ...)} would,
logically speaking, pop off the values returned from @code{(foo)} and
push them as three values, corresponding to @code{x}, @code{y}, and
@code{z}. In that case, @var{nbinds} would be 3, and @var{nrest} would
be 1 (to indicate that one of the bindings was a rest argument).

Signals an error if there is an insufficient number of values.
@end deffn

@deffn Instruction call/cc
@deffnx Instruction tail-call/cc
Capture the current continuation, and then call (or tail-call) the
procedure on the top of the stack, with the continuation as the
argument.

@code{call/cc} does not require a @code{new-frame} to be pushed on the
stack, as @code{call} does, because it needs to capture the stack
before the frame is pushed.

Both the VM continuation and the C continuation are captured.
@end deffn

@node Function Prologue Instructions
@subsubsection Function Prologue Instructions

A function call in Guile is very cheap: the VM simply hands control to
the procedure. The procedure itself is responsible for asserting that it
has been passed an appropriate number of arguments. This strategy allows
arbitrarily complex argument parsing idioms to be developed, without
harming the common case.

For example, only calls to keyword-argument procedures ``pay'' for the
cost of parsing keyword arguments. (At the time of this writing, calling
procedures with keyword arguments is typically two to four times as
costly as calling procedures with a fixed set of arguments.)

@deffn Instruction assert-nargs-ee n
@deffnx Instruction assert-nargs-ge n
Assert that the current procedure has been passed exactly @var{n}
arguments, for the @code{-ee} case, or @var{n} or more arguments, for
the @code{-ge} case. @var{n} is encoded over two bytes.

The number of arguments is determined by subtracting the frame pointer
from the stack pointer (@code{sp - (fp -1)}). @xref{Stack Layout}, for
more details on stack frames.
@end deffn

@deffn Instruction br-if-nargs-ne n offset
@deffnx Instruction br-if-nargs-gt n offset
@deffnx Instruction br-if-nargs-lt n offset
Jump to @var{offset} if the number of arguments is not equal to, greater
than, or less than @var{n}. @var{n} is encoded over two bytes, and
@var{offset} has the normal three-byte encoding.

These instructions are used to implement muliple arities, as in
@code{case-lambda}. @xref{Case-lambda}, for more information.
@end deffn

@deffn Instruction bind-optionals n
If the procedure has been called with fewer than @var{n} arguments, fill
in the remaining arguments with an unbound value (@code{SCM_UNDEFINED}).
@var{n} is encoded over two bytes.

The optionals can be later initialized conditionally via the
@code{local-bound?} instruction.
@end deffn

@deffn Instruction push-rest n
Pop off excess arguments (more than @var{n}), collecting them into a
list, and push that list. Used to bind a rest argument, if the procedure
has no keyword arguments. Procedures with keyword arguments use
@code{bind-rest} instead.
@end deffn

@deffn Instruction bind-rest n idx
Pop off excess arguments (more than @var{n}), collecting them into a
list. The list is then assigned to the @var{idx}th local variable.
@end deffn

@deffn Instruction bind-optionals/shuffle nreq nreq-and-opt ntotal
Shuffle keyword arguments to the top of the stack, filling in the holes
with @code{SCM_UNDEFINED}. Each argument is encoded over two bytes.

This instruction is used by procedures with keyword arguments.
@var{nreq} is the number of required arguments to the procedure, and
@var{nreq-and-opt} is the total number of positional arguments (required
plus optional). @code{bind-optionals/shuffle} will scan the stack from
the @var{nreq}th argument up to the @var{nreq-and-opt}th, and start
shuffling when it sees the first keyword argument or runs out of
positional arguments.

Shuffling simply moves the keyword arguments past the total number of
arguments, @var{ntotal}, which includes keyword and rest arguments. The
free slots created by the shuffle are filled in with
@code{SCM_UNDEFINED}, so they may be conditionally initialized later in
the function's prologue.
@end deffn

@deffn Instruction bind-kwargs idx ntotal flags
Parse keyword arguments, assigning their values to the corresponding
local variables. The keyword arguments should already have been shuffled
above the @var{ntotal}th stack slot by @code{bind-optionals/shuffle}.

The parsing is driven by a keyword arguments association list, looked up
from the @var{idx}th element of the procedures object array. The alist
is a list of pairs of the form @code{(@var{kw} . @var{index})}, mapping
keyword arguments to their local variable indices.

There are two bitflags that affect the parser, @code{allow-other-keys?}
(@code{0x1}) and @code{rest?} (@code{0x2}). Unless
@code{allow-other-keys?} is set, the parser will signal an error if an
unknown key is found. If @code{rest?} is set, errors parsing the the
keyword arguments will be ignored, as a later @code{bind-rest}
instruction will collect all of the tail arguments, including the
keywords, into a list. Otherwise if the keyword arguments are invalid,
an error is signalled.

@var{idx} and @var{ntotal} are encoded over two bytes each, and
@var{flags} is encoded over one byte.
@end deffn

@deffn Instruction reserve-locals n
Resets the stack pointer to have space for @var{n} local variables,
including the arguments. If this operation increments the stack pointer,
as in a push, the new slots are filled with @code{SCM_UNBOUND}. If this
operation decrements the stack pointer, any excess values are dropped.

@code{reserve-locals} is typically used after argument parsing to
reserve space for local variables.
@end deffn

@deffn Instruction assert-nargs-ee/locals n
@deffnx Instruction assert-nargs-ge/locals n
A combination of @code{assert-nargs-ee} and @code{reserve-locals}. The
number of arguments is encoded in the lower three bits of @var{n}, a
one-byte value. The number of additional local variables is take from
the upper 5 bits of @var{n}.
@end deffn

@node Trampoline Instructions
@subsubsection Trampoline Instructions

Though most applicable objects in Guile are procedures implemented
in bytecode, not all are. There are primitives, continuations, and other
procedure-like objects that have their own calling convention. Instead
of adding special cases to the @code{call} instruction, Guile wraps
these other applicable objects in VM trampoline procedures, then
provides special support for these objects in bytecode.

Trampoline procedures are typically generated by Guile at runtime, for
example in response to a call to @code{scm_c_make_gsubr}. As such, a
compiler probably shouldn't emit code with these instructions. However,
it's still interesting to know how these things work, so we document
these trampoline instructions here.

@deffn Instruction subr-call nargs
Pop off a foreign pointer (which should have been pushed on by the
trampoline), and call it directly, with the @var{nargs} arguments from
the stack. Return the resulting value or values to the calling
procedure.
@end deffn

@deffn Instruction foreign-call nargs
Pop off an internal foreign object (which should have been pushed on by
the trampoline), and call that foreign function with the @var{nargs}
arguments from the stack. Return the resulting value to the calling
procedure.
@end deffn

@deffn Instruction smob-call nargs
Pop off the smob object from the stack (which should have been pushed on
by the trampoline), and call its descriptor's @code{apply} function with
the @var{nargs} arguments from the stack. Return the resulting value or
values to the calling procedure.
@end deffn

@deffn Instruction continuation-call
Pop off an internal continuation object (which should have been pushed
on by the trampoline), and reinstate that continuation. All of the
procedure's arguments are passed to the continuation. Does not return.
@end deffn

@deffn Instruction partial-cont-call
Pop off two objects from the stack: the dynamic winds associated with
the partial continuation, and the VM continuation object. Unroll the
continuation onto the stack, rewinding the dynamic environment and
overwriting the current frame, and pass all arguments to the
continuation. Control flow proceeds where the continuation was captured.
@end deffn

@node Branch Instructions
@subsubsection Branch Instructions

All the conditional branch instructions described below work in the
same way:

@itemize
@item They pop off Scheme object(s) located on the stack for use in the
branch condition
@item If the condition is true, then the instruction pointer is
increased by the offset passed as an argument to the branch
instruction;
@item Program execution proceeds with the next instruction (that is,
the one to which the instruction pointer points).
@end itemize

Note that the offset passed to the instruction is encoded as three 8-bit
integers, in big-endian order, effectively giving Guile a 24-bit
relative address space.

@deffn Instruction br offset
Jump to @var{offset}. No values are popped.
@end deffn

@deffn Instruction br-if offset
Jump to @var{offset} if the object on the stack is not false.
@end deffn

@deffn Instruction br-if-not offset
Jump to @var{offset} if the object on the stack is false.
@end deffn

@deffn Instruction br-if-eq offset
Jump to @var{offset} if the two objects located on the stack are
equal in the sense of @var{eq?}.  Note that, for this instruction, the
stack pointer is decremented by two Scheme objects instead of only
one.
@end deffn

@deffn Instruction br-if-not-eq offset
Same as @var{br-if-eq} for non-@code{eq?} objects.
@end deffn

@deffn Instruction br-if-null offset
Jump to @var{offset} if the object on the stack is @code{'()}.
@end deffn

@deffn Instruction br-if-not-null offset
Jump to @var{offset} if the object on the stack is not @code{'()}.
@end deffn

@node Data Constructor Instructions
@subsubsection Data Constructor Instructions

These instructions push simple immediate values onto the stack,
or constructo compound data structures from values the stack.

@deffn Instruction make-int8 value
Push @var{value}, an 8-bit integer, onto the stack.
@end deffn

@deffn Instruction make-int8:0
Push the immediate value @code{0} onto the stack.
@end deffn

@deffn Instruction make-int8:1
Push the immediate value @code{1} onto the stack.
@end deffn

@deffn Instruction make-int16 value
Push @var{value}, a 16-bit integer, onto the stack.
@end deffn

@deffn Instruction make-uint64 value
Push @var{value}, an unsigned 64-bit integer, onto the stack. The
value is encoded in 8 bytes, most significant byte first (big-endian).
@end deffn

@deffn Instruction make-int64 value
Push @var{value}, a signed 64-bit integer, onto the stack. The value
is encoded in 8 bytes, most significant byte first (big-endian), in
twos-complement arithmetic.
@end deffn

@deffn Instruction make-false
Push @code{#f} onto the stack.
@end deffn

@deffn Instruction make-true
Push @code{#t} onto the stack.
@end deffn

@deffn Instruction make-nil
Push @code{#nil} onto the stack.
@end deffn

@deffn Instruction make-eol
Push @code{'()} onto the stack.
@end deffn

@deffn Instruction make-char8 value
Push @var{value}, an 8-bit character, onto the stack.
@end deffn

@deffn Instruction make-char32 value
Push @var{value}, an 32-bit character, onto the stack. The value is
encoded in big-endian order.
@end deffn

@deffn Instruction make-symbol
Pops a string off the stack, and pushes a symbol.
@end deffn

@deffn Instruction make-keyword value
Pops a symbol off the stack, and pushes a keyword.
@end deffn

@deffn Instruction list n
Pops off the top @var{n} values off of the stack, consing them up into
a list, then pushes that list on the stack. What was the topmost value
will be the last element in the list. @var{n} is a two-byte value,
most significant byte first.
@end deffn

@deffn Instruction vector n
Create and fill a vector with the top @var{n} values from the stack,
popping off those values and pushing on the resulting vector. @var{n}
is a two-byte value, like in @code{vector}.
@end deffn

@deffn Instruction make-struct n
Make a new struct from the top @var{n} values on the stack. The values
are popped, and the new struct is pushed.

The deepest value is used as the vtable for the struct, and the rest are
used in order as the field initializers. Tail arrays are not supported
by this instruction.
@end deffn

@deffn Instruction make-array n
Pop an array shape from the stack, then pop the remaining @var{n}
values, pushing a new array. @var{n} is encoded over three bytes.

The array shape should be appropriate to store @var{n} values.
@xref{Array Procedures}, for more information on array shapes.
@end deffn

Many of these data structures are constant, never changing over the
course of the different invocations of the procedure. In that case it is
often advantageous to make them once when the procedure is created, and
just reference them from the object table thereafter. @xref{Variables
and the VM}, for more information on the object table.

@deffn Instruction object-ref n
@deffnx Instruction long-object-ref n
Push @var{n}th value from the current program's object vector. The
``long'' variant has a 16-bit index instead of an 8-bit index.
@end deffn

@node Loading Instructions
@subsubsection Loading Instructions

In addition to VM instructions, an instruction stream may contain
variable-length data embedded within it. This data is always preceded
by special loading instructions, which interpret the data and advance
the instruction pointer to the next VM instruction.

All of these loading instructions have a @code{length} parameter,
indicating the size of the embedded data, in bytes. The length itself
is encoded in 3 bytes.

@deffn Instruction load-number length
Load an arbitrary number from the instruction stream. The number is
embedded in the stream as a string.
@end deffn
@deffn Instruction load-string length
Load a string from the instruction stream. The string is assumed to be
encoded in the ``latin1'' locale.
@end deffn
@deffn Instruction load-wide-string length
Load a UTF-32 string from the instruction stream. @var{length} is the
length in bytes, not in codepoints
@end deffn
@deffn Instruction load-symbol length
Load a symbol from the instruction stream. The symbol is assumed to be
encoded in the ``latin1'' locale. Symbols backed by wide strings may
be loaded via @code{load-wide-string} then @code{make-symbol}.
@end deffn
@deffn Instruction load-array length
Load a uniform array from the instruction stream. The shape and type
of the array are popped off the stack, in that order.
@end deffn

@deffn Instruction load-program
Load bytecode from the instruction stream, and push a compiled
procedure.

This instruction pops one value from the stack: the program's object
table, as a vector, or @code{#f} in the case that the program has no
object table. A program that does not reference toplevel bindings and
does not use @code{object-ref} does not need an object table.

This instruction is unlike the rest of the loading instructions,
because instead of parsing its data, it directly maps the instruction
stream onto a C structure, @code{struct scm_objcode}. @xref{Bytecode
and Objcode}, for more information.

The resulting compiled procedure will not have any free variables
captured, so it may be loaded only once but used many times to create
closures.
@end deffn

@node Dynamic Environment Instructions
@subsubsection Dynamic Environment Instructions

Guile's virtual machine has low-level support for @code{dynamic-wind},
dynamic binding, and composable prompts and aborts.

@deffn Instruction wind
Pop an unwind thunk and a wind thunk from the stack, in that order, and
push them onto the ``dynamic stack''. The unwind thunk will be called on
nonlocal exits, and the wind thunk on reentries. Used to implement
@code{dynamic-wind}.

Note that neither thunk is actually called; the compiler should emit
calls to wind and unwind for the normal dynamic-wind control flow.
@xref{Dynamic Wind}.
@end deffn

@deffn Instruction unwind
Pop off the top entry from the ``dynamic stack'', for example, a
wind/unwind thunk pair. @code{unwind} instructions should be properly
paired with their winding instructions, like @code{wind}.
@end deffn

@deffn Instruction wind-fluids n
Pop off @var{n} values and @var{n} fluids from the stack, in that order.
Set the fluids to the values by creating a with-fluids object and
pushing that object on the dynamic stack. @xref{Fluids and Dynamic
States}.
@end deffn

@deffn Instruction unwind-fluids
Pop a with-fluids object from the dynamic stack, and swap the current
values of its fluids with the saved values of its fluids. In this way,
the dynamic environment is left as it was before the corresponding
@code{wind-fluids} instruction was processed.
@end deffn

@deffn Instruction fluid-ref
Pop a fluid from the stack, and push its current value.
@end deffn

@deffn Instruction fluid-set
Pop a value and a fluid from the stack, in that order, and set the fluid
to the value.
@end deffn

@deffn Instruction prompt escape-only? offset
Establish a dynamic prompt. @xref{Prompts}, for more information on
prompts.

The prompt will be pushed on the dynamic stack. The normal control flow
should ensure that the prompt is popped off at the end, via
@code{unwind}.

If an abort is made to this prompt, control will jump to @var{offset}, a
three-byte relative address. The continuation and all arguments to the
abort will be pushed on the stack, along with the total number of
arguments (including the continuation. If control returns to the
handler, the prompt is already popped off by the abort mechanism.
(Guile's @code{prompt} implements Felleisen's @dfn{--F--} operator.)

If @var{escape-only?} is nonzero, the prompt will be marked as
escape-only, which allows an abort to this prompt to avoid reifying the
continuation.
@end deffn

@deffn Instruction abort n
Abort to a dynamic prompt.

This instruction pops one tail argument list, @var{n} arguments, and a
prompt tag from the stack. The dynamic environment is then searched for
a prompt having the given tag. If none is found, an error is signalled.
Otherwise all arguments are passed to the prompt's handler, along with
the captured continuation, if necessary.

If the prompt's handler can be proven to not reference the captured
continuation, no continuation is allocated. This decision happens
dynamically, at run-time; the general case is that the continuation may
be captured, and thus resumed. A reinstated continuation will have its
arguments pushed on the stack, along with the number of arguments, as in
the multiple-value return convention. Therefore an @code{abort}
instruction should be followed by code ready to handle the equivalent of
a multiply-valued return.
@end deffn

@node Miscellaneous Instructions
@subsubsection Miscellaneous Instructions

@deffn Instruction nop
Does nothing! Used for padding other instructions to certain
alignments.
@end deffn

@deffn Instruction halt
Exits the VM, returning a SCM value. Normally, this instruction is
only part of the ``bootstrap program'', a program run when a virtual
machine is first entered; compiled Scheme procedures will not contain
this instruction.

If multiple values have been returned, the SCM value will be a
multiple-values object (@pxref{Multiple Values}).
@end deffn

@deffn Instruction break
Does nothing, but invokes the break hook.
@end deffn

@deffn Instruction drop
Pops off the top value from the stack, throwing it away.
@end deffn

@deffn Instruction dup
Re-pushes the top value onto the stack.
@end deffn

@deffn Instruction void
Pushes ``the unspecified value'' onto the stack.
@end deffn

@node Inlined Scheme Instructions
@subsubsection Inlined Scheme Instructions

The Scheme compiler can recognize the application of standard Scheme
procedures. It tries to inline these small operations to avoid the
overhead of creating new stack frames.

Since most of these operations are historically implemented as C
primitives, not inlining them would entail constantly calling out from
the VM to the interpreter, which has some costs---registers must be
saved, the interpreter has to dispatch, called procedures have to do
much typechecking, etc. It's much more efficient to inline these
operations in the virtual machine itself.

All of these instructions pop their arguments from the stack and push
their results, and take no parameters from the instruction stream.
Thus, unlike in the previous sections, these instruction definitions
show stack parameters instead of parameters from the instruction
stream.

@deffn Instruction not x
@deffnx Instruction not-not x
@deffnx Instruction eq? x y
@deffnx Instruction not-eq? x y
@deffnx Instruction null?
@deffnx Instruction not-null?
@deffnx Instruction eqv? x y
@deffnx Instruction equal? x y
@deffnx Instruction pair? x y
@deffnx Instruction list? x
@deffnx Instruction set-car! pair x
@deffnx Instruction set-cdr! pair x
@deffnx Instruction cons x y
@deffnx Instruction car x
@deffnx Instruction cdr x
@deffnx Instruction vector-ref x y
@deffnx Instruction vector-set x n y
@deffnx Instruction struct? x
@deffnx Instruction struct-ref x n
@deffnx Instruction struct-set x n v
@deffnx Instruction struct-vtable x
@deffnx Instruction class-of x
@deffnx Instruction slot-ref struct n
@deffnx Instruction slot-set struct n x
Inlined implementations of their Scheme equivalents.
@end deffn

Note that @code{caddr} and friends compile to a series of @code{car}
and @code{cdr} instructions.

@node Inlined Mathematical Instructions
@subsubsection Inlined Mathematical Instructions

Inlining mathematical operations has the obvious advantage of handling
fixnums without function calls or allocations. The trick, of course,
is knowing when the result of an operation will be a fixnum, and there
might be a couple bugs here.

More instructions could be added here over time.

As in the previous section, the definitions below show stack
parameters instead of instruction stream parameters.

@deffn Instruction add x y
@deffnx Instruction add1 x
@deffnx Instruction sub x y
@deffnx Instruction sub1 x
@deffnx Instruction mul x y
@deffnx Instruction div x y
@deffnx Instruction quo x y
@deffnx Instruction rem x y
@deffnx Instruction mod x y
@deffnx Instruction ee? x y
@deffnx Instruction lt? x y
@deffnx Instruction gt? x y
@deffnx Instruction le? x y
@deffnx Instruction ge? x y
@deffnx Instruction ash x n
@deffnx Instruction logand x y
@deffnx Instruction logior x y
@deffnx Instruction logxor x y
Inlined implementations of the corresponding mathematical operations.
@end deffn

@node Inlined Bytevector Instructions
@subsubsection Inlined Bytevector Instructions

Bytevector operations correspond closely to what the current hardware
can do, so it makes sense to inline them to VM instructions, providing
a clear path for eventual native compilation. Without this, Scheme
programs would need other primitives for accessing raw bytes -- but
these primitives are as good as any.

As in the previous section, the definitions below show stack
parameters instead of instruction stream parameters.

The multibyte formats (@code{u16}, @code{f64}, etc) take an extra
endianness argument. Only aligned native accesses are currently
fast-pathed in Guile's VM.

@deffn Instruction bv-u8-ref bv n
@deffnx Instruction bv-s8-ref bv n
@deffnx Instruction bv-u16-native-ref bv n
@deffnx Instruction bv-s16-native-ref bv n
@deffnx Instruction bv-u32-native-ref bv n
@deffnx Instruction bv-s32-native-ref bv n
@deffnx Instruction bv-u64-native-ref bv n
@deffnx Instruction bv-s64-native-ref bv n
@deffnx Instruction bv-f32-native-ref bv n
@deffnx Instruction bv-f64-native-ref bv n
@deffnx Instruction bv-u16-ref bv n endianness
@deffnx Instruction bv-s16-ref bv n endianness
@deffnx Instruction bv-u32-ref bv n endianness
@deffnx Instruction bv-s32-ref bv n endianness
@deffnx Instruction bv-u64-ref bv n endianness
@deffnx Instruction bv-s64-ref bv n endianness
@deffnx Instruction bv-f32-ref bv n endianness
@deffnx Instruction bv-f64-ref bv n endianness
@deffnx Instruction bv-u8-set bv n val
@deffnx Instruction bv-s8-set bv n val
@deffnx Instruction bv-u16-native-set bv n val
@deffnx Instruction bv-s16-native-set bv n val
@deffnx Instruction bv-u32-native-set bv n val
@deffnx Instruction bv-s32-native-set bv n val
@deffnx Instruction bv-u64-native-set bv n val
@deffnx Instruction bv-s64-native-set bv n val
@deffnx Instruction bv-f32-native-set bv n val
@deffnx Instruction bv-f64-native-set bv n val
@deffnx Instruction bv-u16-set bv n val endianness
@deffnx Instruction bv-s16-set bv n val endianness
@deffnx Instruction bv-u32-set bv n val endianness
@deffnx Instruction bv-s32-set bv n val endianness
@deffnx Instruction bv-u64-set bv n val endianness
@deffnx Instruction bv-s64-set bv n val endianness
@deffnx Instruction bv-f32-set bv n val endianness
@deffnx Instruction bv-f64-set bv n val endianness
Inlined implementations of the corresponding bytevector operations.
@end deffn


code:
2001-08-27  Neil Jerram  <neil@ossau.uklinux.net>

	The change log for files in this directory continues backwards
	from 2001-08-27 in ../ChangeLog, as all the Guile documentation
	prior to this date was contained in a single directory.


code:
# -*- Makefile -*-

EXTRA_DIST = libguile-overview.texi snarf.texi contributors.texi    	           \
             libguile-tools.texi strings.texi data-rep.texi new-types.texi tk.texi \
             debug-c.texi old-intro.texi unix-other.texi debug-scheme.texi	   \
             sample-APIs.texi unix.texi guile-slib.texi scheme-concepts.texi	   \
             jimb-org.texi scm-ref.texi ChangeLog-2008


code:
@node Contributors to Guile
@appendix Contributors to Guile

This Guile Manual was written by Mark Galassi, Jim Blandy and Gary
Houston.

Guile was developed over many years by the following people:

@table @strong
@item George Carrette
Wrote files present in Siod version 2.3, released in December of 1989.

@item Aubrey Jaffer
Wrote substantial portions of guile.texi, and surely others.
Changes to: eval.c, ioext.c, posix.c, gscm.c, scm.h, socket.c,
gsubr.c, sys.c, test.scm, stime.c, and unif.c.

@item Gary Houston
changes to many files in libguile.

wrote: libguile/socket.c, ice-9/expect.scm

@item Tom Lord
Many changes throughout.
In the subdirectory ctax, wrote:
    Makefile.in   configure.in  hashtabs.scm  macros.scm    scm-ops.scm
    c-ops.scm     grammar.scm   lexer.scm     reader.scm
In the subdirectory gtcltk-lib, wrote:
    Makefile.in   guile-tcl.c   guile-tk.c
    configure.in  guile-tcl.h   guile-tk.h
In the subdirectory guile, wrote:
    Makefile.in   getopt.c      getopt1.c
    configure.in  getopt.h      guile.c
In the subdirectory ice-9, wrote:
    Makefile.in   configure.in  lineio.scm    poe.scm
    boot-9.scm    hcons.scm     mapping.scm
In the subdirectory lang, wrote:
    Makefile.in   grammar.scm   lr0.scm       pp.scm
    configure.in  lex.scm       lr1.scm
In the subdirectory rx, wrote:
    Makefile.in     runtests.c      rxbitset.h      rxnfa.c         rxspencer.c
    TESTS           rx.c            rxcontext.h     rxnfa.h         rxspencer.h
    TESTS2C.sed     rx.h            rxcset.c        rxnode.c        rxstr.c
    _rx.h           rxall.h         rxcset.h        rxnode.h        rxstr.h
    configure.in    rxanal.c        rxdbug.c        rxposix.c       rxsuper.c
    hashrexp.c      rxanal.h        rxgnucomp.c     rxposix.h       rxsuper.h
    inst-rxposix.h  rxbasic.c       rxgnucomp.h     rxproto.h       rxunfa.c
    rgx.c           rxbasic.h       rxhash.c        rxsimp.c        rxunfa.h
    rgx.h           rxbitset.c      rxhash.h        rxsimp.h        testcases.h
In the subdirectory doc, wrote:
    ctax.texi    gtcltk.texi  in.texi      lang.texi
and portions of guile.texi.

@item Anthony Green
wrote the original code in the 'threads' directory, and
ice-9/threads.scm.

@item Mikael Djurfeldt
@example
In the subdirectory libguile, wrote:
    backtrace.c  debug.c      options.c    root.c       srcprop.c    stacks.c
    backtrace.h  debug.h      options.h    root.h       srcprop.h    stacks.h
In the subdirectory threads, rewrote:
    coop-threads.c  coop.c          mit-pthreads.c  threads.c
    coop-threads.h  fsu-pthreads.h  mit-pthreads.h  threads.h
Many other changes throughout.
@end example

@item Mark Galassi
@example
Designed and implemented the high-level libguile API (the @code{gh_}
interface), based largely on the defunct @code{gscm_} interface.  In the
subdirectory gh, wrote:
gh.c             gh_eval.c        gh_io.c          gh_test_c.c
gh.h             gh_funcs.c       gh_list.c        gh_test_repl.c
gh_data.c        gh_init.c        gh_predicates.c
@end example

@end table


code:
@node Debugging libguile
@chapter Debugging libguile


code:
@node Debugging Scheme programs
@chapter Debugging Scheme programs