summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/Makefile.am7
-rw-r--r--doc/ref/api-data.texi40
-rw-r--r--doc/ref/api-evaluation.texi57
-rw-r--r--doc/ref/api-foreign.texi53
-rw-r--r--doc/ref/api-io.texi8
-rw-r--r--doc/ref/api-modules.texi65
-rw-r--r--doc/ref/api-options.texi13
-rw-r--r--doc/ref/api-procedures.texi29
-rw-r--r--doc/ref/autoconf.texi16
-rw-r--r--doc/ref/goops.texi850
-rw-r--r--doc/ref/history.texi12
-rw-r--r--doc/ref/libguile-extensions.texi7
-rw-r--r--doc/ref/libguile-linking.texi77
-rw-r--r--doc/ref/libguile-smobs.texi8
-rw-r--r--doc/ref/r6rs.texi55
-rw-r--r--doc/ref/scheme-scripts.texi5
-rw-r--r--doc/ref/scheme-using.texi60
-rw-r--r--doc/ref/srfi-modules.texi15
-rw-r--r--doc/ref/tools.texi33
-rw-r--r--doc/ref/tour.texi7
-rw-r--r--doc/ref/vm.texi6
-rw-r--r--doc/ref/web.texi35
22 files changed, 770 insertions, 688 deletions
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index c154f428d..0359380c2 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -111,8 +111,6 @@ noinst_DATA = $(PICTURES)
EXTRA_DIST = ChangeLog-2008 $(PICTURES)
-include $(top_srcdir)/am/pre-inst-guile
-
# Automated snarfing
autoconf.texi: autoconf-macros.texi
@@ -129,7 +127,8 @@ snarf_doc = standard-library
$(snarf_doc).am: $(snarf_doc).scm
GUILE_AUTO_COMPILE=0 ; \
variable="`echo $(snarf_doc) | tr - _`_scm_files" ; \
- "$(preinstguile)" -l "$(srcdir)/$(snarf_doc).scm" -c " \
+ "$(top_builddir_absolute)/meta/guile" -l "$(srcdir)/$(snarf_doc).scm" \
+ -c " \
(format #t \"# Automatically generated, do not edit.~%\") \
(format #t \"$$variable = \") \
(for-each (lambda (m) \
@@ -143,7 +142,7 @@ include standard-library.am
$(snarf_doc).texi: $(standard_library_scm_files)
GUILE_AUTO_COMPILE=0 \
- "$(preinstguile)" "$(srcdir)/make-texinfo.scm" \
+ "$(top_builddir_absolute)/meta/guile" "$(srcdir)/make-texinfo.scm" \
"$(abs_srcdir)/$(snarf_doc).scm" > "$@.tmp"
mv "$@.tmp" "$@"
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index e519cab60..760039a32 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -959,6 +959,18 @@ Return @var{n} raised to the integer exponent
@end lisp
@end deffn
+@deftypefn {Scheme Procedure} {} exact-integer-sqrt @var{k}
+@deftypefnx {C Function} void scm_exact_integer_sqrt (SCM @var{k}, SCM *@var{s}, SCM *@var{r})
+Return two exact non-negative integers @var{s} and @var{r}
+such that @math{@var{k} = @var{s}^2 + @var{r}} and
+@math{@var{s}^2 <= @var{k} < (@var{s} + 1)^2}.
+An error is raised if @var{k} is not an exact non-negative integer.
+
+@lisp
+(exact-integer-sqrt 10) @result{} 3 and 1
+@end lisp
+@end deftypefn
+
@node Comparison
@subsubsection Comparison Predicates
@rnindex zero?
@@ -1308,7 +1320,7 @@ both @var{q} and @var{r}, and is more efficient than computing each
separately. Note that @var{r}, if non-zero, will have the same sign
as @var{y}.
-When @var{x} and @var{y} are exact integers, @code{floor-remainder} is
+When @var{x} and @var{y} are integers, @code{floor-remainder} is
equivalent to the R5RS integer-only operator @code{modulo}.
@lisp
@@ -1365,7 +1377,7 @@ both @var{q} and @var{r}, and is more efficient than computing each
separately. Note that @var{r}, if non-zero, will have the same sign
as @var{x}.
-When @var{x} and @var{y} are exact integers, these operators are
+When @var{x} and @var{y} are integers, these operators are
equivalent to the R5RS integer-only operators @code{quotient} and
@code{remainder}.
@@ -4171,8 +4183,7 @@ using @code{scm_dynwind_free} inside an appropriate dynwind context,
@deftypefn {C Function} SCM scm_from_locale_string (const char *str)
@deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len)
Creates a new Scheme string that has the same contents as @var{str} when
-interpreted in the locale character encoding of the
-@code{current-input-port}.
+interpreted in the character encoding of the current locale.
For @code{scm_from_locale_string}, @var{str} must be null-terminated.
@@ -4201,9 +4212,9 @@ can then use @var{str} directly as its internal representation.
@deftypefn {C Function} {char *} scm_to_locale_string (SCM str)
@deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp)
-Returns a C string with the same contents as @var{str} in the locale
-encoding of the @code{current-output-port}. The C string must be freed
-with @code{free} eventually, maybe by using @code{scm_dynwind_free},
+Returns a C string with the same contents as @var{str} in the character
+encoding of the current locale. The C string must be freed with
+@code{free} eventually, maybe by using @code{scm_dynwind_free},
@xref{Dynamic Wind}.
For @code{scm_to_locale_string}, the returned string is
@@ -4217,13 +4228,14 @@ returned string will not be null-terminated in this case. If
@var{lenp} is @code{NULL}, @code{scm_to_locale_stringn} behaves like
@code{scm_to_locale_string}.
-If a character in @var{str} cannot be represented in the locale encoding
-of the current output port, the port conversion strategy of the current
-output port will determine the result, @xref{Ports}. If output port's
-conversion strategy is @code{error}, an error will be raised. If it is
-@code{substitute}, a replacement character, such as a question mark, will
-be inserted in its place. If it is @code{escape}, a hex escape will be
-inserted in its place.
+If a character in @var{str} cannot be represented in the character
+encoding of the current locale, the default port conversion strategy is
+used. @xref{Ports}, for more on conversion strategies.
+
+If the conversion strategy is @code{error}, an error will be raised. If
+it is @code{substitute}, a replacement character, such as a question
+mark, will be inserted in its place. If it is @code{escape}, a hex
+escape will be inserted in its place.
@end deftypefn
@deftypefn {C Function} size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len)
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index b976715db..682e84498 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -426,7 +426,9 @@ Modify the print options.
@node Fly Evaluation
@subsection Procedures for On the Fly Evaluation
-@xref{Environments}.
+Scheme has the lovely property that its expressions may be represented
+as data. The @code{eval} procedure takes a Scheme datum and evaluates
+it as code.
@rnindex eval
@c ARGFIXME environment/environment specifier
@@ -451,19 +453,46 @@ return the environment in which the implementation would
evaluate expressions dynamically typed by the user.
@end deffn
-@deffn {Scheme Procedure} eval-string string [module]
-@deffnx {C Function} scm_eval_string (string)
+@xref{Environments}, for other environments.
+
+One does not always receive code as Scheme data, of course, and this is
+especially the case for Guile's other language implementations
+(@pxref{Other Languages}). For the case in which all you have is a
+string, we have @code{eval-string}. There is a legacy version of this
+procedure in the default environment, but you really want the one from
+@code{(ice-9 eval-string)}, so load it up:
+
+@example
+(use-modules (ice-9 eval-string))
+@end example
+
+@deffn {Scheme Procedure} eval-string string [module=#f] [file=#f] [line=#f] [column=#f] [lang=(current-language)] [compile?=#f]
+Parse @var{string} according to the current language, normally Scheme.
+Evaluate or compile the expressions it contains, in order, returning the
+last expression.
+
+If the @var{module} keyword argument is set, save a module excursion
+(@pxref{Module System Reflection}) and set the current module to
+@var{module} before evaluation.
+
+The @var{file}, @var{line}, and @var{column} keyword arguments can be
+used to indicate that the source string begins at a particular source
+location.
+
+Finally, @var{lang} is a language, defaulting to the current language,
+and the expression is compiled if @var{compile?} is true or there is no
+evaluator for the given language.
+@end deffn
+
+@deffn {C Function} scm_eval_string (string)
@deffnx {C Function} scm_eval_string_in_module (string, module)
-Evaluate @var{string} as the text representation of a Scheme form or
-forms, and return whatever value they produce. Evaluation takes place
-in the given module, or in the current module when no module is given.
-While the code is evaluated, the given module is made the current one.
-The current module is restored when this procedure returns.
+These C bindings call @code{eval-string} from @code{(ice-9
+eval-string)}, evaluating within @var{module} or the current module.
@end deffn
@deftypefn {C Function} SCM scm_c_eval_string (const char *string)
-@code{scm_eval_string}, but taking a C string instead of an
-@code{SCM}.
+@code{scm_eval_string}, but taking a C string in locale encoding instead
+of an @code{SCM}.
@end deftypefn
@deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
@@ -493,9 +522,17 @@ then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
@deffnx {C Function} scm_call_2 (proc, arg1, arg2)
@deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
@deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
+@deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
+@deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
Call @var{proc} with the given arguments.
@end deffn
+@deffn {C Function} scm_call_n (proc, argv, nargs)
+Call @var{proc} with the array of arguments @var{argv}, as a
+@code{SCM*}. The length of the arguments should be passed in
+@var{nargs}, as a @code{size_t}.
+@end deffn
+
@deffn {Scheme Procedure} apply:nconc2last lst
@deffnx {C Function} scm_nconc2last (lst)
@var{lst} should be a list (@var{arg1} @dots{} @var{argN}
diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index fa65d6821..2dd691675 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -79,6 +79,12 @@ Normally, @var{library} is just the name of some shared library file
that will be searched for in the places where shared libraries usually
reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
+@var{library} should not contain an extension such as @code{.so}. The
+correct file name extension for the host operating system is provided
+automatically, according to libltdl's rules (@pxref{Libltdl interface,
+lt_dlopenext, @code{lt_dlopenext}, libtool, Shared Library Support for
+GNU}).
+
When @var{library} is omitted, a @dfn{global symbol handle} is returned. This
handle provides access to the symbols available to the program at run-time,
including those exported by the program itself and the shared libraries already
@@ -196,12 +202,13 @@ In that case, you would statically link your program with the desired
library, and register its init function right after Guile has been
initialized.
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
+As for @code{dynamic-link}, @var{lib} should not contain any suffix such
+as @code{.so} (@pxref{Foreign Libraries, dynamic-link}). It
should also not contain any directory components. Libraries that
implement Guile Extensions should be put into the normal locations for
shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
+@file{libguile-bla-blum} for a extension related to a module @code{(bla
+blum)}.
The normal way for a extension to be used is to write a small Scheme
file that defines a module, and to load the extension into this
@@ -360,8 +367,8 @@ When loaded with @code{(use-modules (foo bar))}, the
@code{load-extension} call looks for the @file{foobar-c-code.so} (etc)
object file in Guile's @code{extensiondir}, which is usually a
subdirectory of the @code{libdir}. For example, if your libdir is
-@file{/usr/lib}, the @code{extensiondir} for the Guile 2.0.@var{x}
-series will be @file{/usr/lib/guile/2.0/}.
+@file{/usr/lib}, the @code{extensiondir} for the Guile @value{EFFECTIVE-VERSION}.@var{x}
+series will be @file{/usr/lib/guile/@value{EFFECTIVE-VERSION}/}.
The extension path includes the major and minor version of Guile (the
``effective version''), because Guile guarantees compatibility within a
@@ -399,7 +406,7 @@ with the following in a @file{Makefile}, using @command{sed}
@example
foo.scm: foo.scm.in
- sed 's|XXextensiondirXX|$(libdir)/guile/2.0|' <foo.scm.in >foo.scm
+ sed 's|XXextensiondirXX|$(libdir)/guile/@value{EFFECTIVE-VERSION}|' <foo.scm.in >foo.scm
@end example
The actual pattern @code{XXextensiondirXX} is arbitrary, it's only something
@@ -561,6 +568,20 @@ A foreign pointer whose value is 0.
Return @code{#t} if @var{pointer} is the null pointer, @code{#f} otherwise.
@end deffn
+For the purpose of passing SCM values directly to foreign functions, and
+allowing them to return SCM values, Guile also supports some unsafe
+casting operators.
+
+@deffn {Scheme Procedure} scm->pointer scm
+Return a foreign pointer object with the @code{object-address}
+of @var{scm}.
+@end deffn
+
+@deffn {Scheme Procedure} pointer->scm pointer
+Unsafely cast @var{pointer} to a Scheme object.
+Cross your fingers!
+@end deffn
+
@node Void Pointers and Byte Access
@subsubsection Void Pointers and Byte Access
@@ -605,20 +626,22 @@ Assuming @var{pointer} points to a memory region that holds a pointer,
return this pointer.
@end deffn
-@deffn {Scheme Procedure} string->pointer string
+@deffn {Scheme Procedure} string->pointer string [encoding]
Return a foreign pointer to a nul-terminated copy of @var{string} in the
-current locale encoding. The C string is freed when the returned
-foreign pointer becomes unreachable.
+given @var{encoding}, defaulting to the current locale encoding. The C
+string is freed when the returned foreign pointer becomes unreachable.
-This is the Scheme equivalent of @code{scm_to_locale_string}.
+This is the Scheme equivalent of @code{scm_to_stringn}.
@end deffn
-@deffn {Scheme Procedure} pointer->string pointer
-Return the string representing the C nul-terminated string
-pointed to by @var{pointer}. The C string is assumed to be
-in the current locale encoding.
+@deffn {Scheme Procedure} pointer->string pointer [length] [encoding]
+Return the string representing the C string pointed to by @var{pointer}.
+If @var{length} is omitted or @code{-1}, the string is assumed to be
+nul-terminated. Otherwise @var{length} is the number of bytes in memory
+pointed to by @var{pointer}. The C string is assumed to be in the given
+@var{encoding}, defaulting to the current locale encoding.
-This is the Scheme equivalent of @code{scm_from_locale_string}.
+This is the Scheme equivalent of @code{scm_from_stringn}.
@end deffn
@cindex wrapped pointer types
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 52dfdd4fe..02c184986 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -949,9 +949,8 @@ used only during port creation are not retained.
@deffn {Scheme Procedure} port-filename port
@deffnx {C Function} scm_port_filename (port)
-Return the filename associated with @var{port}. This function returns
-the strings "standard input", "standard output" and "standard error"
-when called on the current input, output and error ports respectively.
+Return the filename associated with @var{port}, or @code{#f} if no
+filename is associated with the port.
@var{port} must be open, @code{port-filename} cannot be used once the
port is closed.
@@ -1156,8 +1155,7 @@ string I/O, that complement or refine Guile's historical port API
presented above (@pxref{Input and Output}).
@c FIXME: Update description when implemented.
-@emph{Note}: The implementation of this R6RS API is currently far from
-complete, notably due to the lack of support for Unicode I/O and strings.
+@emph{Note}: The implementation of this R6RS API is not complete yet.
@menu
* R6RS End-of-File:: The end-of-file object.
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index e0c10ae51..3feced4be 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -935,6 +935,62 @@ value of @code{scm_c_call_with_current_module} is the return value of
@var{func}.
@end deftypefn
+@deftypefn SCM scm_public_variable (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_public_variable (const char * @var{module_name}, const char * @var{name})
+Find a the variable bound to the symbol @var{name} in the public
+interface of the module named @var{module_name}.
+
+ @var{module_name} should be a list of symbols, when represented as a
+Scheme object, or a space-separated string, in the @code{const char *}
+case. See @code{scm_c_define_module} below, for more examples.
+
+Signals an error if no module was found with the given name. If
+@var{name} is not bound in the module, just returns @code{#f}.
+@end deftypefn
+
+@deftypefn SCM scm_private_variable (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_private_variable (const char * @var{module_name}, const char * @var{name})
+Like @code{scm_public_variable}, but looks in the internals of the
+module named @var{module_name} instead of the public interface.
+Logically, these procedures should only be called on modules you write.
+@end deftypefn
+
+@deftypefn SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_public_lookup (const char * @var{module_name}, const char * @var{name})
+@deftypefnx SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_private_lookup (const char * @var{module_name}, const char * @var{name})
+Like @code{scm_public_variable} or @code{scm_private_variable}, but if
+the @var{name} is not bound in the module, signals an error. Returns a
+variable, always.
+
+@example
+SCM my_eval_string (SCM str)
+@{
+ static SCM eval_string_var = SCM_BOOL_F;
+
+ if (scm_is_false (eval_string_var))
+ eval_string_var =
+ scm_c_public_lookup ("ice-9 eval-string", "eval-string");
+
+ return scm_call_1 (scm_variable_ref (eval_string_var), str);
+@}
+@end example
+@end deftypefn
+
+@deftypefn SCM scm_public_ref (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_public_ref (const char * @var{module_name}, const char * @var{name})
+@deftypefnx SCM scm_private_ref (SCM @var{module_name}, SCM @var{name})
+@deftypefnx SCM scm_c_private_ref (const char * @var{module_name}, const char * @var{name})
+Like @code{scm_public_lookup} or @code{scm_private_lookup}, but
+additionally dereferences the variable. If the variable object is
+unbound, signals an error. Returns the value bound to @var{name} in
+@var{module}.
+@end deftypefn
+
+In addition, there are a number of other lookup-related procedures. We
+suggest that you use the @code{scm_public_} and @code{scm_private_}
+family of procedures instead, if possible.
+
@deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
Return the variable bound to the symbol indicated by @var{name} in the
current module. If there is no such binding or the symbol is not
@@ -951,6 +1007,13 @@ Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
module is used instead of the current one.
@end deftypefn
+@deftypefn {C Procedure} SCM scm_module_variable (SCM @var{module}, SCM @var{name})
+Like @code{scm_module_lookup}, but if the binding does not exist, just
+returns @code{#f} instead of raising an error.
+@end deftypefn
+
+To define a value, use @code{scm_define}:
+
@deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
Bind the symbol indicated by @var{name} to a variable in the current
module and set that variable to @var{val}. When @var{name} is already
diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index 4813864e7..6f7568bee 100644
--- a/doc/ref/api-options.texi
+++ b/doc/ref/api-options.texi
@@ -171,13 +171,14 @@ guileversion, libguileinterface, buildstamp
@end table
Values are all strings. The value for @code{LIBS} is typically found
-also as a part of "guile-config link" output. The value for
+also as a part of @code{pkg-config --libs
+guile-@value{EFFECTIVE-VERSION}} output. The value for
@code{guileversion} has form X.Y.Z, and should be the same as returned
-by @code{(version)}. The value for @code{libguileinterface} is
-libtool compatible and has form CURRENT:REVISION:AGE
-(@pxref{Versioning,, Library interface versions, libtool, GNU
-Libtool}). The value for @code{buildstamp} is the output of the
-command @samp{date -u +'%Y-%m-%d %T'} (UTC).
+by @code{(version)}. The value for @code{libguileinterface} is libtool
+compatible and has form CURRENT:REVISION:AGE (@pxref{Versioning,,
+Library interface versions, libtool, GNU Libtool}). The value for
+@code{buildstamp} is the output of the command @samp{date -u +'%Y-%m-%d
+%T'} (UTC).
In the source, @code{%guile-build-info} is initialized from
libguile/libpath.h, which is completely generated, so deleting this file
diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index 02889c45c..5c6d38024 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -16,6 +16,7 @@
* Higher-Order Functions:: Function that take or return functions.
* Procedure Properties:: Procedure properties and meta-information.
* Procedures with Setters:: Procedures with setters.
+* Inlinable Procedures:: Procedures that can be inlined.
@end menu
@@ -797,6 +798,32 @@ Return the setter of @var{proc}, which must be either a procedure with
setter or an operator struct.
@end deffn
+@node Inlinable Procedures
+@subsection Inlinable Procedures
+
+You can define an @dfn{inlinable procedure} by using
+@code{define-inlinable} instead of @code{define}. An inlinable
+procedure behaves the same as a regular procedure, but direct calls will
+result in the procedure body being inlined into the caller.
+
+Procedures defined with @code{define-inlinable} are @emph{always}
+inlined, at all direct call sites. This eliminates function call
+overhead at the expense of an increase in code size. Additionally, the
+caller will not transparently use the new definition if the inline
+procedure is redefined. It is not possible to trace an inlined
+procedures or install a breakpoint in it (@pxref{Traps}). For these
+reasons, you should not make a procedure inlinable unless it
+demonstrably improves performance in a crucial way.
+
+In general, only small procedures should be considered for inlining, as
+making large procedures inlinable will probably result in an increase in
+code size. Additionally, the elimination of the call overhead rarely
+matters for for large procedures.
+
+@deffn {Scheme Syntax} define-inlinable (name parameter ...) body ...
+Define @var{name} as a procedure with parameters @var{parameter}s and
+body @var{body}.
+@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
diff --git a/doc/ref/autoconf.texi b/doc/ref/autoconf.texi
index 1e334c0d1..6edee5425 100644
--- a/doc/ref/autoconf.texi
+++ b/doc/ref/autoconf.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -97,25 +97,25 @@ to instantiate macros at top-level.
We now include two examples, one simple and one complicated.
-The first example is for a package that uses libguile, and thus needs to know
-how to compile and link against it. So we use @code{GUILE_FLAGS} to set the
-vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
-substituted in the Makefile.
+The first example is for a package that uses libguile, and thus needs to
+know how to compile and link against it. So we use
+@code{PKG_CHECK_MODULES} to set the vars @code{GUILE_CFLAGS} and
+@code{GUILE_LIBS}, which are automatically substituted in the Makefile.
@example
In configure.ac:
- GUILE_FLAGS
+ PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
In Makefile.in:
GUILE_CFLAGS = @@GUILE_CFLAGS@@
- GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
+ GUILE_LIBS = @@GUILE_LIBS@@
myprog.o: myprog.c
$(CC) -o $@ $(GUILE_CFLAGS) $<
myprog: myprog.o
- $(CC) -o $@ $< $(GUILE_LDFLAGS)
+ $(CC) -o $@ $< $(GUILE_LIBS)
@end example
The second example is for a package of Guile Scheme modules that uses an
diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 452c88b6b..362a6e371 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -48,7 +48,6 @@ module. You can do this at the Guile REPL by evaluating:
* GOOPS Error Handling::
* GOOPS Object Miscellany::
* The Metaobject Protocol::
-* Class Options::
* Redefining a Class::
* Changing the Class of an Instance::
@end menu
@@ -94,8 +93,8 @@ that class --- like ``fields'' or ``member variables'' in other object
oriented systems. Each @var{slot-description} gives the name of a slot
and optionally some ``properties'' of this slot; for example its initial
value, the name of a function which will access its value, and so on.
-Slot descriptions and inheritance are discussed more below. For class
-options, see @ref{Class Options}.
+Class options, slot descriptions and inheritance are discussed more
+below.
@cindex slot
@deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
@@ -140,8 +139,28 @@ the predefined class @code{<complex>}; @code{<complex>} is the
superclass of @code{<real>}, and @code{<real>} is the superclass of
@code{<integer>}.}
-The possible slot and class options are described in the following
-sections.
+Slot options are described in the next section. The possible class
+options are as follows.
+
+@deffn {class option} #:metaclass metaclass
+The @code{#:metaclass} class option specifies the metaclass of the class
+being defined. @var{metaclass} must be a class that inherits from
+@code{<class>}. For the use of metaclasses, see @ref{Metaobjects and
+the Metaobject Protocol} and @ref{Metaclasses}.
+
+If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
+metaclass for the new class by calling @code{ensure-metaclass}
+(@pxref{Class Definition Protocol,, ensure-metaclass}).
+@end deffn
+
+@deffn {class option} #:name name
+The @code{#:name} class option specifies the new class's name. This
+name is used to identify the class whenever related objects - the class
+itself, its instances and its subclasses - are printed.
+
+If the @code{#:name} option is absent, GOOPS uses the first argument to
+@code{define-class} as the class name.
+@end deffn
@node Instance Creation
@@ -1756,7 +1775,7 @@ as the Guile primitive @code{write} and @code{display} functions.
In addition to the cases mentioned, you can of course define
@code{write} and @code{display} methods for your own classes, to
-customize how they are printed.
+customize how instances of those classes are printed.
@node The Metaobject Protocol
@@ -1775,24 +1794,21 @@ So let's plunge in. GOOPS is based on a ``metaobject protocol'' (aka
System), tiny-clos (a small Scheme implementation of a subset of CLOS
functionality) and STKlos.
-GOOPS can be used by application authors at a basic level without any
-need to understand what the MOP is and how it works. On the other hand,
-the MOP underlies even very simple customizations --- such as defining
-an @code{initialize} method to customize the initialization of instances
-of an application-defined class --- and an understanding of the MOP
-makes it much easier to explain such customizations in a precise way.
-And in the long run, understanding the MOP is the key both to
-understanding GOOPS at a deeper level and to taking full advantage of
-GOOPS' power, by customizing the behaviour of GOOPS itself.
+The MOP underlies many possible GOOPS customizations --- such as
+defining an @code{initialize} method to customize the initialization of
+instances of an application-defined class --- and an understanding of
+the MOP makes it much easier to explain such customizations in a precise
+way. And at a deeper level, understanding the MOP is a key part of
+understanding GOOPS, and of taking full advantage of GOOPS' power, by
+customizing the behaviour of GOOPS itself.
@menu
* Metaobjects and the Metaobject Protocol::
-* Terminology::
+* Metaclasses::
* MOP Specification::
-* Class Definition Internals::
+* Instance Creation Protocol::
+* Class Definition Protocol::
* Customizing Class Definition::
-* Customizing Instance Creation::
-* Class Redefinition::
* Method Definition::
* Method Definition Internals::
* Generic Function Internals::
@@ -1826,7 +1842,7 @@ as regards accessibility and protection from garbage collection.
Instances are of course objects in the usual sense, and there is no
benefit from thinking of them as metaobjects.)
-The ``metaobject protocol'' (aka ``MOP'') is the specification of the
+The ``metaobject protocol'' (or ``MOP'') is the specification of the
generic functions which determine the behaviour of these metaobjects and
the circumstances in which these generic functions are invoked.
@@ -1852,7 +1868,7 @@ superclasses, slot definitions and class options that were specified in
the @code{define-class} form.
@item
-@code{make} allocates memory for the new instance, and then invokes the
+@code{make} allocates memory for the new instance, and invokes the
@code{initialize} generic function to initialize the new instance's
slots.
@@ -1863,8 +1879,8 @@ performs the slot calculation.
@end itemize
In other words, rather than being hardcoded in @code{define-class}, the
-behaviour of class definition is encapsulated by generic function
-methods that are specialized for the class @code{<class>}.
+default behaviour of class definition is encapsulated by generic
+function methods that are specialized for the class @code{<class>}.
It is possible to create a new class that inherits from @code{<class>},
which is called a ``metaclass'', and to write a new @code{initialize}
@@ -1895,19 +1911,8 @@ Each following section covers a particular area of GOOPS functionality,
and describes the generic functions that are relevant for customization
of that area.
-@node Terminology
-@subsection Terminology
-
-It is assumed that the reader is already familiar with standard object
-orientation concepts such as classes, objects/instances,
-inheritance/subclassing, generic functions and methods, encapsulation
-and polymorphism.
-
-This section explains some of the less well known concepts and
-terminology that GOOPS uses, which are assumed by the following sections
-of the reference manual.
-
-@subsubheading Metaclass
+@node Metaclasses
+@subsection Metaclasses
A @dfn{metaclass} is the class of an object which represents a GOOPS
class. Put more succinctly, a metaclass is a class's class.
@@ -1923,30 +1928,29 @@ at what happens when a new class is created using @code{define-class}:
(define-class <my-class> (<object>) . slots)
@end example
-GOOPS actually expands the @code{define-class} form to something like
-this
+@noindent
+Guile expands this to something like:
@example
(define <my-class> (class (<object>) . slots))
@end example
-and thence to
+@noindent
+which in turn expands to:
@example
(define <my-class>
(make <class> #:supers (list <object>) #:slots slots))
@end example
-In other words, the value of @code{<my-class>} is in fact an instance of
-the class @code{<class>} with slot values specifying the superclasses
-and slot definitions for the class @code{<my-class>}. (@code{#:supers}
-and @code{#:slots} are initialization keywords for the @code{dsupers}
-and @code{dslots} slots of the @code{<class>} class.)
+As this expansion makes clear, the resulting value of @code{<my-class>}
+is an instance of the class @code{<class>} with slot values specifying
+the superclasses and slot definitions for the class @code{<my-class>}.
+(@code{#:supers} and @code{#:slots} are initialization keywords for the
+@code{dsupers} and @code{dslots} slots of the @code{<class>} class.)
-In order to take advantage of the full power of the GOOPS metaobject
-protocol (@pxref{MOP Specification}), it is sometimes desirable to
-create a new class with a metaclass other than the default
-@code{<class>}. This is done by writing:
+Now suppose that you want to define a new class with a metaclass other
+than the default @code{<class>}. This is done by writing:
@example
(define-class <my-class2> (<object>)
@@ -1954,7 +1958,8 @@ create a new class with a metaclass other than the default
#:metaclass <my-metaclass>)
@end example
-GOOPS expands this to something like:
+@noindent
+and Guile expands @emph{this} to something like:
@example
(define <my-class2>
@@ -1991,91 +1996,12 @@ relationships between @code{my-object}, @code{<my-class2>},
The class of @code{my-object} is @code{<my-class2>}.
@item
-The metaclass of @code{my-object} is @code{<my-metaclass>}.
-
-@item
The class of @code{<my-class2>} is @code{<my-metaclass>}.
@item
-The metaclass of @code{<my-class2>} is @code{<class>}.
-
-@item
The class of @code{<my-metaclass>} is @code{<class>}.
-
-@item
-The metaclass of @code{<my-metaclass>} is @code{<class>}.
-
-@item
-@code{<my-class2>} is not a metaclass, since it is does not inherit from
-@code{<class>}.
-
-@item
-@code{<my-metaclass>} is a metaclass, since it inherits from
-@code{<class>}.
@end itemize
-@subsubheading Class Precedence List
-
-The @dfn{class precedence list} of a class is the list of all direct and
-indirect superclasses of that class, including the class itself.
-
-In the absence of multiple inheritance, the class precedence list is
-ordered straightforwardly, beginning with the class itself and ending
-with @code{<top>}.
-
-For example, given this inheritance hierarchy:
-
-@example
-(define-class <invertebrate> (<object>) @dots{})
-(define-class <echinoderm> (<invertebrate>) @dots{})
-(define-class <starfish> (<echinoderm>) @dots{})
-@end example
-
-the class precedence list of <starfish> would be
-
-@example
-(<starfish> <echinoderm> <invertebrate> <object> <top>)
-@end example
-
-With multiple inheritance, the algorithm is a little more complicated.
-A full description is provided by the GOOPS Tutorial: see @ref{Class
-Precedence List}.
-
-``Class precedence list'' is often abbreviated, in documentation and
-Scheme variable names, to @dfn{cpl}.
-
-@subsubheading Accessor
-
-An @dfn{accessor} is a generic function with both reference and setter
-methods.
-
-@example
-(define-accessor perimeter)
-@end example
-
-Reference methods for an accessor are defined in the same way as generic
-function methods.
-
-@example
-(define-method (perimeter (s <square>))
- (* 4 (side-length s)))
-@end example
-
-Setter methods for an accessor are defined by specifying ``(setter
-<accessor-name>)'' as the first parameter of the @code{define-method}
-call.
-
-@example
-(define-method ((setter perimeter) (s <square>) (n <number>))
- (set! (side-length s) (/ n 4)))
-@end example
-
-Once an appropriate setter method has been defined in this way, it can
-be invoked using the generalized @code{set!} syntax, as in:
-
-@example
-(set! (perimeter s1) 18.3)
-@end example
@node MOP Specification
@subsection MOP Specification
@@ -2085,22 +2011,17 @@ customizable generic function invocations that can be made by the standard
GOOPS syntax, procedures and methods, and to explain the protocol for
customizing such invocations.
-A generic function invocation is customizable if the types of the arguments
-to which it is applied are not all determined by the lexical context in
-which the invocation appears. For example,
+A generic function invocation is customizable if the types of the
+arguments to which it is applied are not completely determined by the
+lexical context in which the invocation appears. For example, the
+@code{(initialize @var{instance} @var{initargs})} invocation in the
+default @code{make-instance} method is customizable, because the type of
+the @code{@var{instance}} argument is determined by the class that was
+passed to @code{make-instance}.
-@itemize @bullet
-@item
-the @code{(initialize @var{instance} @var{initargs})} invocation in the
-default @code{make-instance} method is customizable, because the type of the
-@code{@var{instance}} argument is determined by the class that was passed to
-@code{make-instance}.
-
-@item
-the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
-is not customizable, because all of its arguments have lexically determined
-types.
-@end itemize
+(Whereas --- to give a counter-example --- the @code{(make <generic>
+#:name ',name)} invocation in @code{define-generic} is not customizable,
+because all of its arguments have lexically determined types.)
When using this rule to decide whether a given generic function invocation
is customizable, we ignore arguments that are expected to be handled in
@@ -2121,140 +2042,174 @@ effects
what the caller expects to get as the applied method's return value.
@end itemize
-@node Class Definition Internals
-@subsection Class Definition Internals
-@code{define-class} (syntax)
+@node Instance Creation Protocol
+@subsection Instance Creation Protocol
+
+@code{make <class> . @var{initargs}} (method)
@itemize @bullet
@item
-@code{class} (syntax)
+@code{allocate-instance @var{class} @var{initargs}} (generic)
+
+The applied @code{allocate-instance} method should allocate storage for
+a new instance of class @var{class} and return the uninitialized instance.
-@itemize @bullet
@item
-@code{make-class} (procedure)
+@code{initialize @var{instance} @var{initargs}} (generic)
+
+@var{instance} is the uninitialized instance returned by
+@code{allocate-instance}. The applied method should initialize the new
+instance in whatever sense is appropriate for its class. The method's
+return value is ignored.
+@end itemize
+
+@code{make} itself is a generic function. Hence the @code{make}
+invocation itself can be customized in the case where the new instance's
+metaclass is more specialized than the default @code{<class>}, by
+defining a @code{make} method that is specialized to that metaclass.
+
+Normally, however, the method for classes with metaclass @code{<class>}
+will be applied. This method calls two generic functions:
@itemize @bullet
@item
-@code{make @var{metaclass} @dots{}} (generic)
+(allocate-instance @var{class} . @var{initargs})
-@var{metaclass} is the metaclass of the class being defined, either
-taken from the @code{#:metaclass} class option or computed by
-@code{ensure-metaclass}. The applied method must create and return the
-fully initialized class metaobject for the new class definition.
+@item
+(initialize @var{instance} . @var{initargs})
@end itemize
-@end itemize
+@code{allocate-instance} allocates storage for and returns the new
+instance, uninitialized. You might customize @code{allocate-instance},
+for example, if you wanted to provide a GOOPS wrapper around some other
+object programming system.
+
+To do this, you would create a specialized metaclass, which would act as
+the metaclass for all classes and instances from the other system. Then
+define an @code{allocate-instance} method, specialized to that
+metaclass, which calls a Guile primitive C function (or FFI code), which
+in turn allocates the new instance using the interface of the other
+object system.
+
+In this case, for a complete system, you would also need to customize a
+number of other generic functions like @code{make} and
+@code{initialize}, so that GOOPS knows how to make classes from the
+other system, access instance slots, and so on.
+
+@code{initialize} initializes the instance that is returned by
+@code{allocate-instance}. The standard GOOPS methods perform
+initializations appropriate to the instance class.
+
+@itemize @bullet
+@item
+At the least specialized level, the method for instances of type
+@code{<object>} performs internal GOOPS instance initialization, and
+initializes the instance's slots according to the slot definitions and
+any slot initialization keywords that appear in @var{initargs}.
@item
-@code{class-redefinition @var{old-class} @var{new-class}} (generic)
+The method for instances of type @code{<class>} calls
+@code{(next-method)}, then performs the class initializations described
+in @ref{Class Definition Protocol}.
-@code{define-class} calls @code{class-redefinition} if the variable
-specified by its first argument already held a GOOPS class definition.
-@var{old-class} and @var{new-class} are the old and new class metaobjects.
-The applied method should perform whatever is necessary to handle the
-redefinition, and should return the class metaobject that is to be bound
-to @code{define-class}'s variable. The default class redefinition
-protocol is described in @ref{Class Redefinition}.
+@item
+and so on for generic functions, methods, operator classes @dots{}
@end itemize
-The @code{(make @var{metaclass} @dots{})} invocation above will create
-an class metaobject with metaclass @var{metaclass}. By default, this
-metaobject will be initialized by the @code{initialize} method that is
-specialized for instances of type @code{<class>}.
+Similarly, you can customize the initialization of instances of any
+application-defined class by defining an @code{initialize} method
+specialized to that class.
-@code{initialize <class> @var{initargs}} (method)
+Imagine a class whose instances' slots need to be initialized at
+instance creation time by querying a database. Although it might be
+possible to achieve this a combination of @code{#:init-thunk} keywords
+and closures in the slot definitions, it may be neater to write an
+@code{initialize} method for the class that queries the database once
+and initializes all the dependent slot values according to the results.
+
+
+@node Class Definition Protocol
+@subsection Class Definition Protocol
+
+Here is a summary diagram of the syntax, procedures and generic
+functions that may be involved in class definition.
+
+@noindent
+@code{define-class} (syntax)
@itemize @bullet
@item
-@code{compute-cpl @var{class}} (generic)
+@code{class} (syntax)
-The applied method should compute and return the class precedence list
-for @var{class} as a list of class metaobjects. When @code{compute-cpl}
-is called, the following @var{class} metaobject slots have all been
-initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
-@code{direct-subclasses} (empty), @code{direct-methods}. The value
-returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
+@itemize @bullet
+@item
+@code{make-class} (procedure)
+@itemize @bullet
@item
-@code{compute-slots @var{class}} (generic)
+@code{ensure-metaclass} (procedure)
-The applied method should compute and return the slots (union of direct
-and inherited) for @var{class} as a list of slot definitions. When
-@code{compute-slots} is called, all the @var{class} metaobject slots
-mentioned for @code{compute-cpl} have been initialized, plus the
-following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
-The value returned by @code{compute-slots} will be stored in the
-@code{slots} slot.
+@item
+@code{make @var{metaclass} @dots{}} (generic)
+@itemize @bullet
@item
-@code{compute-get-n-set @var{class} @var{slot-def}} (generic)
+@code{allocate-instance} (generic)
-@code{initialize} calls @code{compute-get-n-set} for each slot computed
-by @code{compute-slots}. The applied method should compute and return a
-pair of closures that, respectively, get and set the value of the specified
-slot. The get closure should have arity 1 and expect a single argument
-that is the instance whose slot value is to be retrieved. The set closure
-should have arity 2 and expect two arguments, where the first argument is
-the instance whose slot value is to be set and the second argument is the
-new value for that slot. The closures should be returned in a two element
-list: @code{(list @var{get} @var{set})}.
+@item
+@code{initialize} (generic)
-The closures returned by @code{compute-get-n-set} are stored as part of
-the value of the @var{class} metaobject's @code{getters-n-setters} slot.
-Specifically, the value of this slot is a list with the same number of
-elements as there are slots in the class, and each element looks either like
+@itemize @bullet
+@item
+@code{compute-cpl} (generic)
-@example
-@code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
-@end example
+@itemize @bullet
+@item
+@code{compute-std-cpl} (procedure)
+@end itemize
-or like
+@item
+@code{compute-slots} (generic)
-@example
-@code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
-@end example
+@item
+@code{compute-get-n-set} (generic)
-Where the get and set closures are replaced by @var{index}, the slot is
-an instance slot and @var{index} is the slot's index in the underlying
-structure: GOOPS knows how to get and set the value of such slots and so
-does not need specially constructed get and set closures. Otherwise,
-@var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
+@item
+@code{compute-getter-method} (generic)
-The structure of the @code{getters-n-setters} slot value is important when
-understanding the next customizable generic functions that @code{initialize}
-calls@dots{}
+@item
+@code{compute-setter-method} (generic)
+@end itemize
+@end itemize
+@end itemize
+@end itemize
@item
-@code{compute-getter-method @var{class} @var{gns}} (generic)
+@code{class-redefinition} (generic)
-@code{initialize} calls @code{compute-getter-method} for each of the class's
-slots (as determined by @code{compute-slots}) that includes a
-@code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
-element of the @var{class} metaobject's @code{getters-n-setters} slot that
-specifies how the slot in question is referenced and set, as described
-above under @code{compute-get-n-set}. The applied method should create
-and return a method that is specialized for instances of type @var{class}
-and uses the get closure to retrieve the slot's value. [ *fixme Need
-to insert something here about checking that the value is not unbound. ]
-@code{initialize} uses @code{add-method!} to add the returned method to
-the generic function named by the slot definition's @code{#:getter} or
-@code{#:accessor} option.
+@itemize @bullet
+@item
+@code{remove-class-accessors} (generic)
@item
-@code{compute-setter-method @var{class} @var{gns}} (generic)
+@code{update-direct-method!} (generic)
-@code{compute-setter-method} is invoked with the same arguments as
-@code{compute-getter-method}, for each of the class's slots that includes
-a @code{#:setter} or @code{#:accessor} slot option. The applied method
-should create and return a method that is specialized for instances of
-type @var{class} and uses the set closure to set the slot's value.
-@code{initialize} then uses @code{add-method!} to add the returned method
-to the generic function named by the slot definition's @code{#:setter}
-or @code{#:accessor} option.
+@item
+@code{update-direct-subclass!} (generic)
@end itemize
+@end itemize
+
+Wherever a step above is marked as ``generic'', it can be customized,
+and the detail shown below it is only ``correct'' insofar as it
+describes what the default method of that generic function does. For
+example, if you write an @code{initialize} method, for some metaclass,
+that does not call @code{next-method} and does not call
+@code{compute-cpl}, then @code{compute-cpl} will not be called when a
+class is defined with that metaclass.
-@code{define-class} expands to an expression which
+A @code{(define-class ...)} form (@pxref{Class Definition}) expands to
+an expression which
@itemize @bullet
@item
@@ -2264,8 +2219,7 @@ checks that it is being evaluated only at top level
defines any accessors that are implied by the @var{slot-definition}s
@item
-uses @code{class} to create the new class (@pxref{Class Definition
-Internals,, class})
+uses @code{class} to create the new class
@item
checks for a previous class definition for @var{name} and, if found,
@@ -2316,8 +2270,7 @@ class precedence list
defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
options, if they are not specified by @var{options}, to the current
top-level environment, the unbound value, and @code{(ensure-metaclass
-@var{supers})} respectively (@pxref{Class Definition Internals,,
-ensure-metaclass})
+@var{supers})} respectively
@item
checks for duplicate classes in @var{supers} and duplicate slot names in
@@ -2353,55 +2306,113 @@ has to be created once.
The @code{env} parameter is ignored.
@end deffn
-@deffn procedure ensure-metaclass-with-supers meta-supers
-@code{ensure-metaclass-with-supers} is an internal procedure used by
-@code{ensure-metaclass} (@pxref{Class Definition Internals,,
-ensure-metaclass}). It returns a metaclass that is the union by
-inheritance of the metaclasses in @var{meta-supers}.
+@deffn generic make metaclass @dots{}
+@var{metaclass} is the metaclass of the class being defined, either
+taken from the @code{#:metaclass} class option or computed by
+@code{ensure-metaclass}. The applied method must create and return the
+fully initialized class metaobject for the new class definition.
@end deffn
-The internals of @code{make}, which is ultimately used to create the new
-class object, are described in @ref{Customizing Instance Creation},
-which covers the creation and initialization of instances in general.
+The @code{(make @var{metaclass} @dots{})} invocation is a particular
+case of the instance creation protocol covered in the previous section.
+It will create an class metaobject with metaclass @var{metaclass}. By
+default, this metaobject will be initialized by the @code{initialize}
+method that is specialized for instances of type @code{<class>}.
-@node Customizing Class Definition
-@subsection Customizing Class Definition
-
-During the initialization of a new class, GOOPS calls a number of generic
-functions with the newly allocated class instance as the first
-argument. Specifically, GOOPS calls the generic function
+The @code{initialize} method for classes (signature @code{(initialize
+<class> initargs)}) calls the following generic functions.
@itemize @bullet
@item
-(initialize @var{class} @dots{})
-@end itemize
+@code{compute-cpl @var{class}} (generic)
-where @var{class} is the newly allocated class instance, and the default
-@code{initialize} method for arguments of type @code{<class>} calls the
-generic functions
+The applied method should compute and return the class precedence list
+for @var{class} as a list of class metaobjects. When @code{compute-cpl}
+is called, the following @var{class} metaobject slots have all been
+initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
+@code{direct-subclasses} (empty), @code{direct-methods}. The value
+returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
-@itemize @bullet
@item
-(compute-cpl @var{class})
+@code{compute-slots @var{class}} (generic)
-@item
-(compute-slots @var{class})
+The applied method should compute and return the slots (union of direct
+and inherited) for @var{class} as a list of slot definitions. When
+@code{compute-slots} is called, all the @var{class} metaobject slots
+mentioned for @code{compute-cpl} have been initialized, plus the
+following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
+The value returned by @code{compute-slots} will be stored in the
+@code{slots} slot.
@item
-(compute-get-n-set @var{class} @var{slot-def}), for each of the slot
-definitions returned by @code{compute-slots}
+@code{compute-get-n-set @var{class} @var{slot-def}} (generic)
+
+@code{initialize} calls @code{compute-get-n-set} for each slot computed
+by @code{compute-slots}. The applied method should compute and return a
+pair of closures that, respectively, get and set the value of the specified
+slot. The get closure should have arity 1 and expect a single argument
+that is the instance whose slot value is to be retrieved. The set closure
+should have arity 2 and expect two arguments, where the first argument is
+the instance whose slot value is to be set and the second argument is the
+new value for that slot. The closures should be returned in a two element
+list: @code{(list @var{get} @var{set})}.
+
+The closures returned by @code{compute-get-n-set} are stored as part of
+the value of the @var{class} metaobject's @code{getters-n-setters} slot.
+Specifically, the value of this slot is a list with the same number of
+elements as there are slots in the class, and each element looks either like
+
+@example
+@code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
+@end example
+
+or like
+
+@example
+@code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
+@end example
+
+Where the get and set closures are replaced by @var{index}, the slot is
+an instance slot and @var{index} is the slot's index in the underlying
+structure: GOOPS knows how to get and set the value of such slots and so
+does not need specially constructed get and set closures. Otherwise,
+@var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
+
+The structure of the @code{getters-n-setters} slot value is important when
+understanding the next customizable generic functions that @code{initialize}
+calls@dots{}
@item
-(compute-getter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
-@code{#:getter} or @code{#:accessor} slot option
+@code{compute-getter-method @var{class} @var{gns}} (generic)
+
+@code{initialize} calls @code{compute-getter-method} for each of the
+class's slots (as determined by @code{compute-slots}) that includes a
+@code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
+element of the @var{class} metaobject's @code{getters-n-setters} slot
+that specifies how the slot in question is referenced and set, as
+described above under @code{compute-get-n-set}. The applied method
+should create and return a method that is specialized for instances of
+type @var{class} and uses the get closure to retrieve the slot's value.
+@code{initialize} uses @code{add-method!} to add the returned method to
+the generic function named by the slot definition's @code{#:getter} or
+@code{#:accessor} option.
@item
-(compute-setter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
-@code{#:setter} or @code{#:accessor} slot option.
+@code{compute-setter-method @var{class} @var{gns}} (generic)
+
+@code{compute-setter-method} is invoked with the same arguments as
+@code{compute-getter-method}, for each of the class's slots that includes
+a @code{#:setter} or @code{#:accessor} slot option. The applied method
+should create and return a method that is specialized for instances of
+type @var{class} and uses the set closure to set the slot's value.
+@code{initialize} then uses @code{add-method!} to add the returned method
+to the generic function named by the slot definition's @code{#:setter}
+or @code{#:accessor} option.
@end itemize
+@node Customizing Class Definition
+@subsection Customizing Class Definition
+
If the metaclass of the new class is something more specialized than the
default @code{<class>}, then the type of @var{class} in the calls above
is more specialized than @code{<class>}, and hence it becomes possible
@@ -2419,8 +2430,7 @@ customized in order to modify the CPL ordering algorithm for all classes
with a special metaclass.
The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
-procedure, which is in turn called by the default @code{compute-cpl}
-method.
+procedure, which is called by the default @code{compute-cpl} method.
@deffn procedure compute-std-cpl class
Compute and return the class precedence list for @var{class} according
@@ -2489,7 +2499,7 @@ allocation to do this.
@end example
The usage of @code{compute-getter-method} and @code{compute-setter-method}
-is described in @ref{MOP Specification}.
+is described in @ref{Class Definition Protocol}.
@code{compute-cpl} and @code{compute-get-n-set} are called by the
standard @code{initialize} method for classes whose metaclass is
@@ -2500,152 +2510,6 @@ behaviour, by not calling @code{(next-method)} at all, but more
typically it would perform additional class initialization steps before
and/or after calling @code{(next-method)} for the standard behaviour.
-@node Customizing Instance Creation
-@subsection Customizing Instance Creation
-
-@code{make <class> . @var{initargs}} (method)
-
-@itemize @bullet
-@item
-@code{allocate-instance @var{class} @var{initargs}} (generic)
-
-The applied @code{allocate-instance} method should allocate storage for
-a new instance of class @var{class} and return the uninitialized instance.
-
-@item
-@code{initialize @var{instance} @var{initargs}} (generic)
-
-@var{instance} is the uninitialized instance returned by
-@code{allocate-instance}. The applied method should initialize the new
-instance in whatever sense is appropriate for its class. The method's
-return value is ignored.
-@end itemize
-
-@code{make} itself is a generic function. Hence the @code{make}
-invocation itself can be customized in the case where the new instance's
-metaclass is more specialized than the default @code{<class>}, by
-defining a @code{make} method that is specialized to that metaclass.
-
-Normally, however, the method for classes with metaclass @code{<class>}
-will be applied. This method calls two generic functions:
-
-@itemize @bullet
-@item
-(allocate-instance @var{class} . @var{initargs})
-
-@item
-(initialize @var{instance} . @var{initargs})
-@end itemize
-
-@code{allocate-instance} allocates storage for and returns the new
-instance, uninitialized. You might customize @code{allocate-instance},
-for example, if you wanted to provide a GOOPS wrapper around some other
-object programming system.
-
-To do this, you would create a specialized metaclass, which would act as
-the metaclass for all classes and instances from the other system. Then
-define an @code{allocate-instance} method, specialized to that
-metaclass, which calls a Guile primitive C function, which in turn
-allocates the new instance using the interface of the other object
-system.
-
-In this case, for a complete system, you would also need to customize a
-number of other generic functions like @code{make} and
-@code{initialize}, so that GOOPS knows how to make classes from the
-other system, access instance slots, and so on.
-
-@code{initialize} initializes the instance that is returned by
-@code{allocate-instance}. The standard GOOPS methods perform
-initializations appropriate to the instance class.
-
-@itemize @bullet
-@item
-At the least specialized level, the method for instances of type
-@code{<object>} performs internal GOOPS instance initialization, and
-initializes the instance's slots according to the slot definitions and
-any slot initialization keywords that appear in @var{initargs}.
-
-@item
-The method for instances of type @code{<class>} calls
-@code{(next-method)}, then performs the class initializations described
-in @ref{Customizing Class Definition}.
-
-@item
-and so on for generic functions, method, operator classes @dots{}
-@end itemize
-
-Similarly, you can customize the initialization of instances of any
-application-defined class by defining an @code{initialize} method
-specialized to that class.
-
-Imagine a class whose instances' slots need to be initialized at
-instance creation time by querying a database. Although it might be
-possible to achieve this a combination of @code{#:init-thunk} keywords
-and closures in the slot definitions, it is neater to write an
-@code{initialize} method for the class that queries the database once
-and initializes all the dependent slot values according to the results.
-
-@node Class Redefinition
-@subsection Class Redefinition
-
-The default @code{class-redefinition} method, specialized for classes
-with the default metaclass @code{<class>}, has the following internal
-protocol.
-
-@code{class-redefinition (@var{old <class>}) (@var{new <class>})}
-(method)
-
-@itemize @bullet
-@item
-@code{remove-class-accessors! @var{old}} (generic)
-
-@item
-@code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
-
-@item
-@code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
-@end itemize
-
-This protocol cleans up things that the definition of the old class
-once changed and modifies things to work with the new class.
-
-The default @code{remove-class-accessors!} method removes the
-accessor methods of the old class from all classes which they
-specialize.
-
-The default @code{update-direct-method!} method substitutes the new
-class for the old in all methods specialized to the old class.
-
-The default @code{update-direct-subclass!} method invokes
-@code{class-redefinition} recursively to handle the redefinition of
-subclasses.
-
-When a class is redefined, any existing instance of the redefined class
-will be modified for the new class definition before the next time that
-any of the instance's slot is referenced or set. GOOPS modifies each
-instance by calling the generic function @code{change-class}.
-
-The default @code{change-class} method copies slot values from the old
-to the modified instance, and initializes new slots, as described in
-@ref{Changing the Class of an Instance}. After doing so, it makes a
-generic function invocation that can be used to customize the instance
-update algorithm.
-
-@code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
-
-@itemize @bullet
-@item
-@code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
-
-@code{change-class} invokes @code{update-instance-for-different-class}
-as the last thing that it does before returning. The applied method can
-make any further adjustments to @var{new-instance} that are required to
-complete or modify the change of class. The return value from the
-applied method is ignored.
-
-The default @code{update-instance-for-different-class} method does
-nothing.
-@end itemize
@node Method Definition
@subsection Method Definition
@@ -2655,7 +2519,9 @@ nothing.
@itemize @bullet
@item
@code{add-method! @var{target} @var{method}} (generic)
+@end itemize
+@noindent
@code{define-method} invokes the @code{add-method!} generic function to
handle adding the new method to a variety of possible targets. GOOPS
includes methods to handle @var{target} as
@@ -2673,12 +2539,12 @@ a primitive generic (@pxref{Extending Primitives})
By defining further methods for @code{add-method!}, you can
theoretically handle adding methods to further types of target.
-@end itemize
+
@node Method Definition Internals
@subsection Method Definition Internals
-@code{define-method}
+@code{define-method}:
@itemize @bullet
@item
@@ -2708,7 +2574,8 @@ The @var{parameter} and @var{body} parameters should be as for
define-method}).
@end deffn
-@code{method}
+@noindent
+@code{method}:
@itemize @bullet
@item
@@ -2734,6 +2601,7 @@ parameter combinations to which this method will be applicable.
function parameters when this method is invoked.
@end deffn
+@noindent
@code{make-method} is a simple wrapper around @code{make} with metaclass
@code{<method>}.
@@ -2834,71 +2702,47 @@ accessor, passing the setter generic function as the value of the
@node Generic Function Invocation
@subsection Generic Function Invocation
-[ *fixme* Description required here. ]
+There is a detailed and customizable protocol involved in the process of
+invoking a generic function --- i.e., in the process of deciding which
+of the generic function's methods are applicable to the current
+arguments, and which one of those to apply. Here is a summary diagram
+of the generic functions involved.
-@code{apply-generic}
+@noindent
+@code{apply-generic} (generic)
@itemize @bullet
@item
-@code{no-method}
+@code{no-method} (generic)
@item
-@code{compute-applicable-methods}
+@code{compute-applicable-methods} (generic)
@item
-@code{sort-applicable-methods}
-
-@item
-@code{apply-methods}
+@code{sort-applicable-methods} (generic)
+@itemize @bullet
@item
-@code{no-applicable-method}
+@code{method-more-specific?} (generic)
@end itemize
-@code{sort-applicable-methods}
+@item
+@code{apply-methods} (generic)
@itemize @bullet
@item
-@code{method-more-specific?}
-@end itemize
+@code{apply-method} (generic)
-@code{apply-methods}
-
-@itemize @bullet
@item
-@code{apply-method}
+@code{no-next-method} (generic)
@end itemize
-@code{next-method}
-
-@itemize @bullet
@item
-@code{no-next-method}
+@code{no-applicable-method}
@end itemize
-
-@node Class Options
-@section Class Options
-
-@deffn {class option} #:metaclass metaclass
-The @code{#:metaclass} class option specifies the metaclass of the class
-being defined. @var{metaclass} must be a class that inherits from
-@code{<class>}. For the use of metaclasses, see @ref{Metaobjects and
-the Metaobject Protocol} and @ref{Terminology}.
-
-If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
-metaclass for the new class by calling @code{ensure-metaclass}
-(@pxref{Class Definition Internals,, ensure-metaclass}).
-@end deffn
-
-@deffn {class option} #:name name
-The @code{#:name} class option specifies the new class's name. This
-name is used to identify the class whenever related objects - the class
-itself, its instances and its subclasses - are printed.
-
-If the @code{#:name} option is absent, GOOPS uses the first argument to
-@code{define-class} as the class name.
-@end deffn
+We do not yet have full documentation for these. Please refer to the
+code (@file{oop/goops.scm}) for details.
@node Redefining a Class
@@ -2972,8 +2816,8 @@ be customized@dots{}
@node Customizing Class Redefinition
@subsection Customizing Class Redefinition
-When @code{define-class} notices that a class is being redefined,
-it constructs the new class metaobject as usual, and then invokes the
+When @code{define-class} notices that a class is being redefined, it
+constructs the new class metaobject as usual, then invokes the
@code{class-redefinition} generic function with the old and new classes
as arguments. Therefore, if the old or new classes have metaclasses
other than the default @code{<class>}, class redefinition behaviour can
@@ -2992,6 +2836,26 @@ Implements GOOPS' default class redefinition behaviour, as described in
for the new class definition.
@end deffn
+The default @code{class-redefinition} method, for classes with the
+default metaclass @code{<class>}, calls the following generic functions,
+which could of course be individually customized.
+
+@deffn generic remove-class-accessors! old
+The default @code{remove-class-accessors!} method removes the accessor
+methods of the old class from all classes which they specialize.
+@end deffn
+
+@deffn generic update-direct-method! method old new
+The default @code{update-direct-method!} method substitutes the new
+class for the old in all methods specialized to the old class.
+@end deffn
+
+@deffn generic update-direct-subclass! subclass old new
+The default @code{update-direct-subclass!} method invokes
+@code{class-redefinition} recursively to handle the redefinition of
+subclasses.
+@end deffn
+
An alternative class redefinition strategy could be to leave all
existing instances as instances of the old class, but accepting that the
old class is now ``nameless'', since its name has been taken over by the
@@ -3015,34 +2879,18 @@ is specialized for this metaclass:
When customization can be as easy as this, aren't you glad that GOOPS
implements the far more difficult strategy as its default!
-Finally, note that, if @code{class-redefinition} itself is not customized,
-the default @code{class-redefinition} method invokes three further
-generic functions that could be individually customized:
-
-@itemize @bullet
-@item
-(remove-class-accessors! @var{old-class})
-
-@item
-(update-direct-method! @var{method} @var{old-class} @var{new-class})
-
-@item
-(update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
-@end itemize
-
-and the default methods for these generic functions invoke further
-generic functions, and so on@dots{} The detailed protocol for all of these
-is described in @ref{MOP Specification}.
@node Changing the Class of an Instance
@section Changing the Class of an Instance
-You can change the class of an existing instance by invoking the
-generic function @code{change-class} with two arguments: the instance
-and the new class.
+When a class is redefined, any existing instance of the redefined class
+will be modified for the new class definition before the next time that
+any of the instance's slots is referenced or set. GOOPS modifies each
+instance by calling the generic function @code{change-class}.
-@deffn generic change-class
-@end deffn
+More generally, you can change the class of an existing instance at any
+time by invoking the generic function @code{change-class} with two
+arguments: the instance and the new class.
The default method for @code{change-class} decides how to implement the
change of class by looking at the slot definitions for the instance's
@@ -3053,6 +2901,9 @@ discarded. Slots that are present only in the new class are initialized
using the corresponding slot definition's init function (@pxref{Classes,,
slot-init-function}).
+@deffn generic change-class instance new-class
+@end deffn
+
@deffn {method} change-class (obj <object>) (new <class>)
Modify instance @var{obj} to make it an instance of class @var{new}.
@@ -3064,11 +2915,20 @@ pre-existing slots are initialized according to @var{new}'s slot definitions'
init functions.
@end deffn
+The default @code{change-class} method also invokes another generic
+function, @code{update-instance-for-different-class}, as the last thing
+that it does before returning. The applied
+@code{update-instance-for-different-class} method can make any further
+adjustments to @var{new-instance} that are required to complete or
+modify the change of class. The return value from the applied method is
+ignored.
+
+@deffn generic update-instance-for-different-class old-instance new-instance
+A generic function that can be customized to put finishing touches to an
+instance whose class has just been changed. The default
+@code{update-instance-for-different-class} method does nothing.
+@end deffn
+
Customized change of class behaviour can be implemented by defining
@code{change-class} methods that are specialized either by the class
of the instances to be modified or by the metaclass of the new class.
-
-When a class is redefined (@pxref{Redefining a Class}), and the default
-class redefinition behaviour is not overridden, GOOPS (eventually)
-invokes the @code{change-class} generic function for each existing
-instance of the redefined class.
diff --git a/doc/ref/history.texi b/doc/ref/history.texi
index 62b637d81..970ec014b 100644
--- a/doc/ref/history.texi
+++ b/doc/ref/history.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2008, 2010
+@c Copyright (C) 2008, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -214,15 +214,15 @@ user-space threading was removed in favor of POSIX pre-emptive
threads, providing true multiprocessing. Gettext support was added,
and Guile's C API was cleaned up and orthogonalized in a massive way.
-@item 2.0 --- April 2010
+@item 2.0 --- 16 February 2010
A virtual machine was added to Guile, along with the associated compiler
and toolchain. Support for internationalization was finally
reimplemented, in terms of unicode, locales, and libunistring. Running
Guile instances became controllable and debuggable from within Emacs,
-via GDS and Geiser. Guile caught up to features found in a number of
-other Schemes: SRFI-18 threads, including thread cancellation,
-module-hygienic macros, a profiler, tracer, and debugger, SSAX XML
-integration, bytevectors, module versions, and partial support for R6RS.
+via Geiser. Guile caught up to features found in a number of other
+Schemes: SRFI-18 threads, module-hygienic macros, a profiler, tracer,
+and debugger, SSAX XML integration, bytevectors, a dynamic FFI,
+delimited continuations, module versions, and partial support for R6RS.
@end table
@node Status
diff --git a/doc/ref/libguile-extensions.texi b/doc/ref/libguile-extensions.texi
index 78871c6ca..95f92cac6 100644
--- a/doc/ref/libguile-extensions.texi
+++ b/doc/ref/libguile-extensions.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -64,7 +64,7 @@ Consider the following file @file{bessel.c}.
SCM
j0_wrapper (SCM x)
@{
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
+ return scm_from_double (j0 (scm_to_double (x)));
@}
void
@@ -78,7 +78,8 @@ 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
+gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
+ -shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample
For creating shared libraries portably, we recommend the use of GNU
diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi
index b6a88556e..3a90208be 100644
--- a/doc/ref/libguile-linking.texi
+++ b/doc/ref/libguile-linking.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -16,16 +16,24 @@ head of any C source file that uses identifiers described in this
manual. Once you've compiled your source files, you need to link them
against the Guile object code library, @code{libguile}.
-On most systems, you should not need to tell the compiler and linker
-explicitly where they can find @file{libguile.h} and @file{libguile}.
-When Guile has been installed in a peculiar way, or when you are on a
-peculiar system, things might not be so easy and you might need to pass
-additional @code{-I} or @code{-L} options to the compiler. Guile
-provides the utility program @code{guile-config} to help you find the
-right values for these options. You would typically run
-@code{guile-config} during the configuration phase of your program and
+@code{<libguile.h>} is not in the default search path for headers,
+because Guile supports parallel installation of multiple versions of
+Guile, with each version's headers under their own directories. This is
+to allow development against, say, both Guile 2.0 and 2.2.
+
+To compile code that includes @code{<libguile.h>}, or links to
+@code{libguile}, you need to select the effective version you are
+interested in, and then ask @code{pkg-config} for the compilation flags
+or linking instructions. For effective version
+@value{EFFECTIVE-VERSION}, for example, you would invoke
+@code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}} to get
+the compilation and linking flags necessary to link to version
+@value{EFFECTIVE-VERSION} of Guile. You would typically run
+@code{pkg-config} during the configuration phase of your program and
use the obtained information in the Makefile.
+See the @code{pkg-config} man page, for more information.
+
@menu
* Guile Initialization Functions:: What to call first.
* A Sample Guile Main Program:: Sources and makefiles.
@@ -98,17 +106,17 @@ ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
process the command-line arguments in the usual way.
Here is a Makefile which you can use to compile the above program. It
-uses @code{guile-config} to learn about the necessary compiler and
+uses @code{pkg-config} to learn about the necessary compiler and
linker flags.
@example
# Use GCC, if you have it installed.
CC=gcc
# Tell the C compiler where to find <libguile.h>
-CFLAGS=`guile-config compile`
+CFLAGS=`pkg-config --cflags guile-@value{EFFECTIVE-VERSION}`
# Tell the linker what libraries to use and where to find them.
-LIBS=`guile-config link`
+LIBS=`pkg-config --libs guile-@value{EFFECTIVE-VERSION}`
simple-guile: simple-guile.o
$@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
@@ -120,13 +128,11 @@ simple-guile.o: simple-guile.c
If you are using the GNU Autoconf package to make your application more
portable, Autoconf will settle many of the details in the Makefile above
automatically, making it much simpler and more portable; we recommend
-using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
-macro for autoconf that performs all necessary checks. Here is a
-@file{configure.in} file for @code{simple-guile} that uses this macro.
-Autoconf can use this file as a template to generate a @code{configure}
-script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
-will need to run @code{aclocal} first (@pxref{Invoking aclocal,,,
-automake, GNU Automake}).
+using Autoconf with Guile. Here is a @file{configure.ac} file for
+@code{simple-guile} that uses the standard @code{PKG_CHECK_MODULES}
+macro to check for Guile. Autoconf will process this file into a
+@code{configure} script. We recommend invoking Autoconf via the
+@code{autoreconf} utility.
@example
AC_INIT(simple-guile.c)
@@ -135,19 +141,21 @@ AC_INIT(simple-guile.c)
AC_PROG_CC
# Check for Guile
-GUILE_FLAGS
+PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
# Generate a Makefile, based on the results.
AC_OUTPUT(Makefile)
@end example
+Run @code{autoreconf -vif} to generate @code{configure}.
+
Here is a @code{Makefile.in} template, from which the @code{configure}
script produces a Makefile customized for the host system:
@example
# The configure script fills in these values.
CC=@@CC@@
CFLAGS=@@GUILE_CFLAGS@@
-LIBS=@@GUILE_LDFLAGS@@
+LIBS=@@GUILE_LIBS@@
simple-guile: simple-guile.o
$@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
@@ -156,23 +164,28 @@ simple-guile.o: simple-guile.c
@end example
The developer should use Autoconf to generate the @file{configure}
-script from the @file{configure.in} template, and distribute
+script from the @file{configure.ac} template, and distribute
@file{configure} with the application. Here's how a user might go about
building the application:
@example
$ ls
-Makefile.in configure* configure.in simple-guile.c
+Makefile.in configure* configure.ac simple-guile.c
$ ./configure
-creating cache ./config.cache
-checking for gcc... (cached) gcc
-checking whether the C compiler (gcc ) works... yes
-checking whether the C compiler (gcc ) is a cross-compiler... no
-checking whether we are using GNU C... (cached) yes
-checking whether gcc accepts -g... (cached) yes
-checking for Guile... yes
-creating ./config.status
-creating Makefile
+checking for gcc... ccache gcc
+checking whether the C compiler works... yes
+checking for C compiler default output file name... a.out
+checking for suffix of executables...
+checking whether we are cross compiling... no
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether ccache gcc accepts -g... yes
+checking for ccache gcc option to accept ISO C89... none needed
+checking for pkg-config... /usr/bin/pkg-config
+checking pkg-config is at least version 0.9.0... yes
+checking for GUILE... yes
+configure: creating ./config.status
+config.status: creating Makefile
$ make
[...]
$ ./simple-guile
diff --git a/doc/ref/libguile-smobs.texi b/doc/ref/libguile-smobs.texi
index c6581a1ac..eb938f099 100644
--- a/doc/ref/libguile-smobs.texi
+++ b/doc/ref/libguile-smobs.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -686,9 +686,9 @@ Here is a sample build and interaction with the code from the
@example
zwingli:example-smob$ make CC=gcc
-gcc `guile-config compile` -c image-type.c -o image-type.o
-gcc `guile-config compile` -c myguile.c -o myguile.o
-gcc image-type.o myguile.o `guile-config link` -o myguile
+gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` -c image-type.c -o image-type.o
+gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` -c myguile.c -o myguile.o
+gcc image-type.o myguile.o `pkg-config --libs guile-@value{EFFECTIVE-VERSION}` -o myguile
zwingli:example-smob$ ./myguile
guile> make-image
#<primitive-procedure make-image>
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index 72a3f3486..bc569ed69 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -38,9 +38,11 @@ does not restore it. This is a bug.
@item
R6RS unicode escapes within strings are disabled by default, because
-they conflict with Guile's already-existing escapes. R6RS behavior can
-be turned on via a reader option. @xref{String Syntax}, for more
-information.
+they conflict with Guile's already-existing escapes. The same is the
+case for R6RS treatment of escaped newlines in strings.
+
+R6RS behavior can be turned on via a reader option. @xref{String
+Syntax}, for more information.
@item
A @code{set!} to a variable transformer may only expand to an
@@ -51,23 +53,8 @@ expression was in definition context.
Instead of using the algorithm detailed in chapter 10 of the R6RS,
expansion of toplevel forms happens sequentially.
-For example, while the expansion of the following set of recursive
-nested definitions does do the correct thing:
-
-@example
-(let ()
- (define even?
- (lambda (x)
- (or (= x 0) (odd? (- x 1)))))
- (define-syntax odd?
- (syntax-rules ()
- ((odd? x) (not (even? x)))))
- (even? 10))
-@result{} #t
-@end example
-
-@noindent
-The same definitions at the toplevel do not:
+For example, while the expansion of the following set of toplevel
+definitions does the correct thing:
@example
(begin
@@ -78,6 +65,20 @@ The same definitions at the toplevel do not:
(syntax-rules ()
((odd? x) (not (even? x)))))
(even? 10))
+@result{} #t
+@end example
+
+@noindent
+The same definitions outside of the @code{begin} wrapper do not:
+
+@example
+(define even?
+ (lambda (x)
+ (or (= x 0) (odd? (- x 1)))))
+(define-syntax odd?
+ (syntax-rules ()
+ ((odd? x) (not (even? x)))))
+(even? 10)
<unnamed port>:4:18: In procedure even?:
<unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
@end example
@@ -86,10 +87,10 @@ This is because when expanding the right-hand-side of @code{even?}, the
reference to @code{odd?} is not yet marked as a syntax transformer, so
it is assumed to be a function.
-While it is likely that we can fix the case of toplevel forms nested in
-a @code{begin} or a @code{library} form, a fix for toplevel programs
-seems trickier to implement in a backward-compatible way. Suggestions
-and/or patches would be appreciated.
+This bug will only affect top-level programs, not code in @code{library}
+forms. Fixing it for toplevel forms seems doable, but tricky to
+implement in a backward-compatible way. Suggestions and/or patches would
+be appreciated.
@item
The @code{(rnrs io ports)} module is mostly unimplemented. Work is
@@ -378,6 +379,7 @@ grouped below by the existing manual sections to which they correspond.
@deffnx {Scheme Procedure} even? n
@deffnx {Scheme Procedure} gcd x ...
@deffnx {Scheme Procedure} lcm x ...
+@deffnx {Scheme Procedure} exact-integer-sqrt k
@xref{Integer Operations}, for documentation.
@end deffn
@@ -524,11 +526,6 @@ This is a consequence of the requirement that
@end lisp
@end deffn
-@deffn {Scheme Procedure} exact-integer-sqrt k
-This procedure returns two nonnegative integer objects @code{s} and
-@code{r} such that k = s^2 + r and k < (s + 1)^2.
-@end deffn
-
@deffn {Scheme Procedure} real-valued? obj
@deffnx {Scheme Procedure} rational-valued? obj
@deffnx {Scheme Procedure} integer-valued? obj
diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi
index 5a6f494d1..0ad1becf3 100644
--- a/doc/ref/scheme-scripts.texi
+++ b/doc/ref/scheme-scripts.texi
@@ -196,6 +196,11 @@ interactive session. When executing a script with @code{-s} or
Do not use the debugging VM engine, even when entering an interactive
session.
+@item -q
+Do not the local initialization file, @code{.guile}. This option only
+has an effect when running interactively; running scripts does not load
+the @code{.guile} file. @xref{Init File}.
+
@item --listen[=@var{p}]
While this program runs, listen on a local port or a path for REPL
clients. If @var{p} starts with a number, it is assumed to be a local
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 126b84590..7995c8c04 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2006, 2010
+@c Copyright (C) 2006, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -35,6 +35,7 @@ current language is @code{scheme}, and the current module is
support for languages other than Scheme.
@menu
+* Init File::
* Readline::
* Value History::
* REPL Commands::
@@ -43,6 +44,22 @@ support for languages other than Scheme.
@end menu
+@node Init File
+@subsection The Init File, @file{~/.guile}
+
+@cindex .guile
+When run interactively, Guile will load a local initialization file from
+@file{~/.guile}. This file should contain Scheme expressions for
+evaluation.
+
+This facility lets the user customize their interactive Guile
+environment, pulling in extra modules or parameterizing the REPL
+implementation.
+
+To run Guile without loading the init file, use the @code{-q}
+command-line option.
+
+
@node Readline
@subsection Readline
@@ -58,10 +75,8 @@ scheme@@(guile-user)> (activate-readline)
@end lisp
It's a good idea to put these two lines (without the
-@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file. Guile
-reads this file when it starts up interactively, so anything in this
-file has the same effect as if you type it in by hand at the
-@code{scheme@@(guile-user)>} prompt.
+@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file.
+@xref{Init File}, for more on @file{.guile}.
@node Value History
@@ -337,6 +352,12 @@ Show the VM registers associated with the current frame.
@xref{Stack Layout}, for more information on VM stack frames.
@end deffn
+@deffn {REPL Command} width [cols]
+Sets the number of display columns in the output of @code{,backtrace}
+and @code{,locals} to @var{cols}. If @var{cols} is not given, the width
+of the terminal is used.
+@end deffn
+
The next 3 commands work at any REPL.
@deffn {REPL Command} break proc
@@ -404,6 +425,35 @@ List/show/set options.
Quit this session.
@end deffn
+Current REPL options include:
+
+@table @code
+@item compile-options
+The options used when compiling expressions entered at the REPL.
+@xref{Compilation}, for more on compilation options.
+@item interp
+Whether to interpret or compile expressions given at the REPL, if such a
+choice is available. Off by default (indicating compilation).
+@item prompt
+A customized REPL prompt. @code{#f} by default, indicating the default
+prompt.
+@item value-history
+Whether value history is on or not. @xref{Value History}.
+@item on-error
+What to do when an error happens. By default, @code{debug}, meaning to
+enter the debugger. Other values include @code{backtrace}, to show a
+backtrace without entering the debugger, or @code{report}, to simply
+show a short error printout.
+@end table
+
+Default values for REPL options may be set using
+@code{repl-default-option-set!} from @code{(system repl common)}:
+
+@deffn {Scheme Procedure} repl-set-default-option! key value
+Set the default value of a REPL option. This function is particularly
+useful in a user's init file. @xref{Init File}.
+@end deffn
+
@node Error Handling
@subsection Error Handling
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index bda7cbb37..a5b9740f3 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -35,6 +35,7 @@ get the relevant SRFI documents from the SRFI home page
* SRFI-17:: Generalized set!
* SRFI-18:: Multithreading support
* SRFI-19:: Time/Date library.
+* SRFI-23:: Error reporting
* SRFI-26:: Specializing parameters
* SRFI-27:: Sources of Random Bits
* SRFI-30:: Nested multi-line block comments
@@ -1927,6 +1928,13 @@ The functions created by @code{define-record-type} are ordinary
top-level @code{define}s. They can be redefined or @code{set!} as
desired, exported from a module, etc.
+@unnumberedsubsubsec Non-toplevel Record Definitions
+
+The SRFI-9 specification explicitly disallows record definitions in a
+non-toplevel context, such as inside @code{lambda} body or inside a
+@var{let} block. However, Guile's implementation does not enforce that
+restriction.
+
@unnumberedsubsubsec Custom Printers
You may use @code{set-record-type-printer!} to customize the default printing
@@ -3128,6 +3136,11 @@ Conversion is locale-dependent on systems that support it
locale.
@end defun
+@node SRFI-23
+@subsection SRFI-23 - Error Reporting
+@cindex SRFI-23
+
+The SRFI-23 @code{error} procedure is always available.
@node SRFI-26
@subsection SRFI-26 - specializing parameters
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
index 2f4f59ac9..7a98884d8 100644
--- a/doc/ref/tools.texi
+++ b/doc/ref/tools.texi
@@ -303,14 +303,11 @@ is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
@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.
+When Guile is installed, in addition to the @code{(ice-9 FOO)} modules, a set
+of @dfn{guile-tools modules} @code{(scripts BAR)} is also installed. Each is
+a regular Scheme module that has some additional packaging so that it can be
+used by guile-tools, from the shell. For this reason, we sometimes use the
+term @dfn{script} in this context to mean the same thing.
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
@@ -346,17 +343,11 @@ executable module. Feel free to skip to the next chapter.
See template file @code{PROGRAM} for a quick start.
-Programs must follow the @dfn{executable module} convention, documented here:
+Programs must follow the @dfn{guile-tools} 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:
@@ -377,20 +368,10 @@ There must be the alias:
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
+@code{(scripts PROGRAM)} in addition to being invoked by guile-tools. Please
also include a helpful Commentary section w/ some usage info.
@c tools.texi ends here
diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi
index 2215cf034..c6949eb34 100644
--- a/doc/ref/tour.texi
+++ b/doc/ref/tour.texi
@@ -1,6 +1,6 @@
@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 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -115,7 +115,7 @@ can be compiled and linked like this:
@example
$ gcc -o simple-guile simple-guile.c \
- `pkg-config --cflags --libs guile-2.0`
+ `pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}`
@end example
When it is run, it behaves just like the @code{guile} program except
@@ -163,7 +163,8 @@ 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
+gcc `pkg-config --cflags guile-@value{EFFECTIVE-VERSION}` \
+ -shared -o libguile-bessel.so -fPIC bessel.c
@end smallexample
For creating shared libraries portably, we recommend the use of GNU
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index fa73f9b2e..0a1425026 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2008, 2009, 2010, 2011
+@c Copyright (C) 2008,2009,2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -1063,7 +1063,7 @@ 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
-Latin-1-encoded.
+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
@@ -1071,7 +1071,7 @@ 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
-Latin-1-encoded. Symbols backed by wide strings may
+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
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index c7018e9c6..46d4cfbdd 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -59,8 +59,8 @@ valid dates. Error handling for a number of basic cases, like invalid
dates, occurs on the boundary in which we produce a SRFI 19 date record
from other types, like strings.
-With regards to the web, data types are help in the two broad phases of
-HTTP messages: parsing and generation.
+With regards to the web, data types are helpful in the two broad phases
+of HTTP messages: parsing and generation.
Consider a server, which has to parse a request, and produce a response.
Guile will parse the request into an HTTP request object
@@ -339,7 +339,7 @@ For example:
(string->header "FOO")
@result{} foo
-(header->string 'foo
+(header->string 'foo)
@result{} "Foo"
@end example
@@ -387,12 +387,6 @@ leaving it as a string. You could register this header with Guile's
HTTP stack like this:
@example
-(define (parse-ip str)
- (inet-aton str)
-(define (validate-ip ip)
-(define (write-ip ip port)
- (display (inet-ntoa ip) port))
-
(declare-header! "X-Client-Address"
(lambda (str)
(inet-aton str))
@@ -1331,13 +1325,20 @@ If the read failed, the @code{read} hook may return #f for the client
socket, request, and body.
@item
-A user-provided handler procedure is called, with the request
-and body as its arguments. The handler should return two
-values: the response, as a @code{<response>} record from @code{(web
-response)}, and the response body as a string, bytevector, or
-@code{#f} if not present. We also allow the response to be simply an
-alist of headers, in which case a default response object is
-constructed with those headers.
+A user-provided handler procedure is called, with the request and body
+as its arguments. The handler should return two values: the response,
+as a @code{<response>} record from @code{(web response)}, and the
+response body as bytevector, or @code{#f} if not present.
+
+The respose and response body are run through @code{sanitize-response},
+documented below. This allows the handler writer to take some
+convenient shortcuts: for example, instead of a @code{<response>}, the
+handler can simply return an alist of headers, in which case a default
+response object is constructed with those headers. Instead of a
+bytevector for the body, the handler can return a string, which will be
+serialized into an appropriate encoding; or it can return a procedure,
+which will be called on a port to write out the data. See the
+@code{sanitize-response} documentation, for more.
@item
The @code{write} hook is called with three arguments: the client
@@ -1581,7 +1582,7 @@ probably know, we'll want to return a 404 response.
(define (not-found request)
(values (build-response #:code 404)
(string-append "Resource not found: "
- (unparse-uri (request-uri request)))))
+ (uri->string (request-uri request)))))
;; Now paste this to let the web server keep going:
,continue