From 7545ddd42a065da0d50b2d84e7889aeb5d71326b Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Thu, 12 Aug 2010 13:04:08 +0200 Subject: [PATCH] a number of doc fixes * doc/ref/api-control.texi (Handling Errors): Update docs for display-error. * libguile/backtrace.h (scm_i_display_error): Change prototype to s/stack/frame/. * libguile/throw.c (handler_message): Change invocation of scm_i_display_error to pass a frame. * doc/ref/api-deprecated.texi (Deprecation): Update wording. * doc/ref/api-evaluation.texi (Local Evaluation): Remove section on local-eval. * doc/ref/api-macros.texi: Fix a couple typos. * doc/ref/api-memory.texi (Objects): Remove terrible section. * doc/ref/api-procedures.texi (Procedure Properties): Remove docs for closure?. (Compiled Procedures): Update wording. * doc/ref/guile.texi (API Reference): Remove reference to "Objects". --- doc/ref/api-control.texi | 6 +++--- doc/ref/api-deprecated.texi | 22 ++++++++++------------ doc/ref/api-evaluation.texi | 15 --------------- doc/ref/api-macros.texi | 7 ++++--- doc/ref/api-memory.texi | 34 +--------------------------------- doc/ref/api-procedures.texi | 27 +++++++-------------------- doc/ref/guile.texi | 1 - libguile/backtrace.h | 2 +- libguile/throw.c | 4 +++- 9 files changed, 29 insertions(+), 89 deletions(-) diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 0b4b587ae..d0a8c0cb9 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -1402,10 +1402,10 @@ be @code{#f} if no additional objects are required. In addition to @code{catch} and @code{throw}, the following Scheme facilities are available: -@deffn {Scheme Procedure} display-error stack port subr message args rest -@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest) +@deffn {Scheme Procedure} display-error frame port subr message args rest +@deffnx {C Function} scm_display_error (frame, port, subr, message, args, rest) Display an error message to the output port @var{port}. -@var{stack} is the saved stack for the error, @var{subr} is +@var{frame} is the frame in which the error occurred, @var{subr} is the name of the procedure in which the error occurred and @var{message} is the actual error message, which may contain formatting instructions. These will format the arguments in diff --git a/doc/ref/api-deprecated.texi b/doc/ref/api-deprecated.texi index ea18e4a6e..76f099727 100644 --- a/doc/ref/api-deprecated.texi +++ b/doc/ref/api-deprecated.texi @@ -11,21 +11,19 @@ From time to time functions and other features of Guile become obsolete. Guile's @dfn{deprecation} is a mechanism that can help you cope with this. -When you use a feature that is deprecated, you will likely get a -warning message at run-time. Also, deprecated features are not ready -for production use: they might be very slow. +When you use a feature that is deprecated, you will likely get a warning +message at run-time. Also, if you have a new enough toolchain, using a +deprecated function from @code{libguile} will cause a link-time warning. -Additionally, if you have a new enough toolchain, using a deprecated -function from @code{libguile} will cause a link-time warning. - -The primary source for information about just what things are deprecated -in a given release is the file @file{NEWS}. That file also documents -what you should use instead of the obsoleted things. +The primary source for information about just what interfaces are +deprecated in a given release is the file @file{NEWS}. That file also +documents what you should use instead of the obsoleted things. The file @file{README} contains instructions on how to control the inclusion or removal of the deprecated features from the public API of Guile, and how to control the deprecation warning messages. -The idea behind those mechanisms is that normally all deprecated are -available, but you get feedback when compiling and running code that -uses them, so that you can migrate to the newer APIs at your leisure. +The idea behind this mechanism is that normally all deprecated +interfaces are available, but you get feedback when compiling and +running code that uses them, so that you can migrate to the newer APIs +at your leisure. diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 21eee689b..211649b38 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -18,7 +18,6 @@ loading, evaluating, and compiling Scheme code at run time. * Loading:: Loading Scheme code from file. * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. * Delayed Evaluation:: Postponing evaluation until it is needed. -* Local Evaluation:: Evaluation in a local environment. * Evaluator Behaviour:: Modifying Guile's evaluator. * VM Behaviour:: Modifying Guile's virtual machine. @end menu @@ -790,20 +789,6 @@ value. @end deffn -@node Local Evaluation -@subsection Local Evaluation - -[the-environment] - -@deffn {Scheme Procedure} local-eval exp [env] -@deffnx {C Function} scm_local_eval (exp, env) -Evaluate @var{exp} in its environment. If @var{env} is supplied, -it is the environment in which to evaluate @var{exp}. Otherwise, -@var{exp} must be a memoized code object (in which case, its environment -is implicit). -@end deffn - - @node Evaluator Behaviour @subsection Evaluator Behaviour diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi index fba14f3c8..325d0b28a 100644 --- a/doc/ref/api-macros.texi +++ b/doc/ref/api-macros.texi @@ -447,12 +447,12 @@ output from a @code{syntax-case} expression. It is not strictly necessary for a @code{syntax-case} expression to return a syntax object, because @code{syntax-case} expressions can be used in helper functions, or otherwise used outside of syntax expansion itself. However a -syntax transformer procedure must return a syntax object, so most uses of +syntax transformer procedure must return a syntax object, so most uses of @code{syntax-case} do end up returning syntax objects. Here in this case, the form that built the return value was @code{(syntax (+ exp 1))}. The interesting thing about this is that within a @code{syntax} -expression, any appearance of a pattern variable is substitued into the +expression, any appearance of a pattern variable is substituted into the resulting syntax object, carrying with it all relevant metadata from the source expression, such as lexical identity and source location. @@ -498,6 +498,7 @@ Returns @code{#t} iff @var{syntax-object} is an identifier. @end deffn @example +;; relying on previous add1 definition (define-syntax add1! (lambda (x) (syntax-case x () @@ -785,7 +786,7 @@ left-hand side of a @code{set!} expression, as in the following: As the example notes, the transformer procedure must be explicitly marked as being a ``variable transformer'', as most macros aren't -written to discriminate on the form in the operand position. +written to discriminate on the form in the operator position. @deffn {Scheme Procedure} make-variable-transformer transformer Mark the @var{transformer} procedure as being a ``variable diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index ec58470a5..375686d98 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.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, 2010 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -478,38 +478,6 @@ to the value, it is eligible to be returned from a guardian. @end deffn -@node Objects -@section Objects - -@deffn {Scheme Procedure} entity? obj -@deffnx {C Function} scm_entity_p (obj) -Return @code{#t} if @var{obj} is an entity. -@end deffn - -@deffn {Scheme Procedure} operator? obj -@deffnx {C Function} scm_operator_p (obj) -Return @code{#t} if @var{obj} is an operator. -@end deffn - -@deffn {Scheme Procedure} set-object-procedure! obj proc -@deffnx {C Function} scm_set_object_procedure_x (obj, proc) -Set the object procedure of @var{obj} to @var{proc}. -@var{obj} must be either an entity or an operator. -@end deffn - -@deffn {Scheme Procedure} make-class-object metaclass layout -@deffnx {C Function} scm_make_class_object (metaclass, layout) -Create a new class object of class @var{metaclass}, with the -slot layout specified by @var{layout}. -@end deffn - -@deffn {Scheme Procedure} make-subclass-object class layout -@deffnx {C Function} scm_make_subclass_object (class, layout) -Create a subclass object of @var{class}, with the slot layout -specified by @var{layout}. -@end deffn - - @c Local Variables: @c TeX-master: "guile.texi" @c End: diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index 0b0acf7f7..8fc7f33f5 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -121,22 +121,18 @@ same way as @code{scm_c_make_gsubr}, which is usually not further required. @end deftypefun -@code{scm_c_make_gsubr} and @code{scm_c_define_gsubr} automatically -use @code{scm_c_make_subr} and also @code{scm_makcclo} if necessary. -It is advisable to use the gsubr variants since they provide a -slightly higher-level abstraction of the Guile implementation. - @node Compiled Procedures @subsection Compiled Procedures -In Guile, procedures can be executed by directly interpreting their -source code. Scheme source code is a set of nested lists, after all, -with each list representing a procedure call. +The evaluation strategy given in @ref{Lambda} describes how procedures +are @dfn{interpreted}. Interpretation operates directly on expanded +Scheme source code, recursively calling the evaluator to obtain the +value of nested expressions. Most procedures are compiled, however. This means that Guile has done -some pre-computation on the procedure, to determine what it will need -to do each time the procedure runs. Compiled procedures run faster -than interpreted procedures. +some pre-computation on the procedure, to determine what it will need to +do each time the procedure runs. Compiled procedures run faster than +interpreted procedures. Loading files is the normal way that compiled procedures come to being. If Guile sees that a file is uncompiled, or that its compiled @@ -599,15 +595,6 @@ returns @code{#t} for procedures which do not accept any arguments. Return @code{#t} if @var{obj} is a procedure. @end deffn -@deffn {Scheme Procedure} closure? obj -@deffnx {C Function} scm_closure_p (obj) -Return @code{#t} if @var{obj} is a closure. This category somewhat -misnamed, actually, as it applies only to interpreted procedures, not -compiled procedures. But since it has historically been used more to -select on implementation details than on essence (closure or not), we -keep it here for compatibility. Don't use it in new code, though. -@end deffn - @deffn {Scheme Procedure} thunk? obj @deffnx {C Function} scm_thunk_p (obj) Return @code{#t} if @var{obj} is a thunk. diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index c47dfc5c2..18069ae6f 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -304,7 +304,6 @@ available through both Scheme and C interfaces. * LALR(1) Parsing:: Generating LALR(1) parsers. * Read/Load/Eval/Compile:: Reading and evaluating Scheme code. * Memory Management:: Memory management and garbage collection. -* Objects:: Low level object orientation support. * Modules:: Designing reusable code libraries. * Foreign Function Interface:: Interacting with C procedures and data. * Scheduling:: Threads, mutexes, asyncs and dynamic roots. diff --git a/libguile/backtrace.h b/libguile/backtrace.h index a8c6cc5d6..bc593bcc7 100644 --- a/libguile/backtrace.h +++ b/libguile/backtrace.h @@ -26,7 +26,7 @@ #include "libguile/__scm.h" SCM_API void scm_display_error_message (SCM message, SCM args, SCM port); -SCM_INTERNAL void scm_i_display_error (SCM stack, SCM port, SCM subr, +SCM_INTERNAL void scm_i_display_error (SCM frame, SCM port, SCM subr, SCM message, SCM args, SCM rest); SCM_API SCM scm_display_error (SCM frame, SCM port, SCM subr, SCM message, SCM args, SCM rest); SCM_API SCM scm_display_application (SCM frame, SCM port, SCM indent); diff --git a/libguile/throw.c b/libguile/throw.c index a6f04e116..238c52c5e 100644 --- a/libguile/throw.c +++ b/libguile/throw.c @@ -365,7 +365,9 @@ handler_message (void *handler_data, SCM tag, SCM args) highlights); scm_newline (p); } - scm_i_display_error (stack, p, subr, message, parts, rest); + scm_i_display_error (scm_is_true (stack) + ? scm_stack_ref (stack, SCM_INUM0) : SCM_BOOL_F, + p, subr, message, parts, rest); } else { -- 2.20.1