mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-02 04:40:29 +02:00
* More GH to scm transition documentation.
* Revise info about GH deprecation following Marius' suggestions.
This commit is contained in:
Neil Jerram
parent
f2ae455539
commit
fbcd68abe9
3 changed files with 139 additions and 55 deletions
|
|
@ -1,3 +1,10 @@
|
|||
2001-06-25 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* gh.texi (GH deprecation): Remove paragraph about portability.
|
||||
|
||||
* extend.texi (Libguile Intro): Updated following Marius'
|
||||
suggestions.
|
||||
|
||||
2001-06-25 Marius Vollmer <mvo@zagadka.ping.de>
|
||||
|
||||
* Makefile.am (version.texi, version-tutorial.texi): Removed
|
||||
|
|
@ -8,6 +15,12 @@
|
|||
* gh.texi (scm transition summary): New node for summary of how to
|
||||
transition from GH to scm interface.
|
||||
(GH): Link to new node.
|
||||
(Calling Scheme procedures from C): Remove doc for gh_set_car and
|
||||
gh_set_cdr, which don't actually exist.
|
||||
(Data types and constants defined by gh): Correct
|
||||
SCM_UNSPECIFIED/SCM_UNDEFINED confusion.
|
||||
(Calling Scheme procedures from C): Correct SCM_EOL/SCM_UNDEFINED
|
||||
confusion.
|
||||
|
||||
2001-06-20 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,26 +0,0 @@
|
|||
@page
|
||||
@node Libguile Intro
|
||||
@chapter Using Guile as an Extension Language
|
||||
|
||||
The chapters in this part of the manual explain how to use Guile as a
|
||||
powerful application extension language.
|
||||
|
||||
An important change for the 1.6.x series of Guile releases is that the
|
||||
GH interface is now deprecated. For the reasoning behind this decision,
|
||||
see @xref{GH deprecation}. The GH interface will continue to be
|
||||
supported for the 1.6.x and 1.8.x release series, but will be dropped
|
||||
thereafter, so developers are encouraged to switch progressively to the
|
||||
scm interface. The last chapter in this part of the manual (@pxref{GH})
|
||||
documents both how to use GH and how to switch from GH to scm.
|
||||
|
||||
The documentation of the scm interface is currently a bit confused, but
|
||||
the situation should improve rapidly once the 1.6.0 release is out. The
|
||||
plan is to refocus the bulk of Part II, currently ``Guile Scheme'', as
|
||||
the ``Guile API Reference'' so that it covers both Scheme and C
|
||||
interfaces. (This makes sense because almost all of Guile's primitive
|
||||
procedures on the Scheme level --- e.g. @code{memq} --- are also
|
||||
available as C level primitives in the scm interface ---
|
||||
e.g. @code{scm_memq}.) There will then remain a certain amount of
|
||||
Scheme-specific (such as the ``Basic Ideas'' chapter) and C-specific
|
||||
documentation (such as SMOB usage and interaction with the garbage
|
||||
collector) to collect into corresponding chapters.
|
||||
155
doc/gh.texi
155
doc/gh.texi
|
|
@ -62,25 +62,17 @@ Finally, the idea of multiple implementations of the GH interface did
|
|||
not really crystallize (apart, I believe, from a short lived
|
||||
implementation by the MzScheme project).
|
||||
|
||||
Where portability is concerned, the @code{scm_} interface is now already
|
||||
portable in the sense that other projects could provide an alternative
|
||||
implementation of the @code{scm_} header file. For the majority of
|
||||
@code{scm_} functions, all that is needed is a definition of the
|
||||
@code{SCM} type, and then those functions are automatically portable by
|
||||
virtue of the fact that their signatures refer only to this @code{SCM}
|
||||
type.
|
||||
|
||||
For all these reasons, the Guile developers have decided to deprecate
|
||||
the GH interface --- which means that support for GH will be completely
|
||||
removed after the next few releases --- and to focus only on the
|
||||
@code{scm_} interface, with additions to ensure that it is as easy to
|
||||
use in all respects as GH was.
|
||||
|
||||
It remains an open question whether deeper kinds of interface
|
||||
portability would be useful for extension language-based applications,
|
||||
and it may still be an interesting project to attempt to define a
|
||||
corresponding GH-like interface, but the Guile developers no longer plan
|
||||
to try to do this as part of the core Guile project.
|
||||
It remains an open question whether a deep kind of interface portability
|
||||
would be useful for extension language-based applications, and it may
|
||||
still be an interesting project to attempt to define a corresponding
|
||||
GH-like interface, but the Guile developers no longer plan to try to do
|
||||
this as part of the core Guile project.
|
||||
|
||||
|
||||
@node gh preliminaries
|
||||
|
|
@ -127,9 +119,16 @@ tend to just type @code{if (boolean_function()) @{ ... @}}
|
|||
@end defvr
|
||||
|
||||
@defvr Constant SCM_UNSPECIFIED
|
||||
This is an SCM object which does not correspond to any legal Scheme
|
||||
value. It can be used in C to terminate functions with variable numbers
|
||||
of arguments, such as @code{gh_list()}.
|
||||
This is a SCM value that is not the same as any legal Scheme value. It
|
||||
is the value that a Scheme function returns when its specification says
|
||||
that its return value is unspecified.
|
||||
@end defvr
|
||||
|
||||
@defvr Constant SCM_UNDEFINED
|
||||
This is another SCM value that is not the same as any legal Scheme
|
||||
value. It is the value used to mark variables that do not yet have a
|
||||
value, and it is also used in C to terminate functions with variable
|
||||
numbers of arguments, such as @code{gh_list()}.
|
||||
@end defvr
|
||||
|
||||
|
||||
|
|
@ -600,7 +599,7 @@ I will list these routines here without much explanation, since what
|
|||
they do is the same as documented in @ref{Standard procedures, R5RS, ,
|
||||
r5rs, R5RS}. But I will point out that when a procedure takes a
|
||||
variable number of arguments (such as @code{gh_list}), you should pass
|
||||
the constant @var{SCM_EOL} from C to signify the end of the list.
|
||||
the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
|
||||
|
||||
@deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
|
||||
Corresponds to the Scheme @code{(define name val)}: it binds a value to
|
||||
|
|
@ -616,13 +615,6 @@ These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
|
|||
@code{scm_listify()}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun SCM gh_set_car (SCM @var{obj}, SCM @var{val})
|
||||
@deftypefunx SCM gh_set_cdr (SCM @var{obj}, SCM @var{val})
|
||||
These correspond to the Scheme @code{(set-car! ...)} and @code{(set-cdr!
|
||||
...)} procedures.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@deftypefun SCM gh_car (SCM @var{obj})
|
||||
@deftypefunx SCM gh_cdr (SCM @var{obj})
|
||||
@dots{}
|
||||
|
|
@ -858,7 +850,7 @@ arbitrary Scheme value.
|
|||
@item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
|
||||
No change.
|
||||
|
||||
@item @code{SCM_UNSPECIFIED}
|
||||
@item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
|
||||
No change.
|
||||
|
||||
@item @code{gh_enter}
|
||||
|
|
@ -939,16 +931,32 @@ No direct scm equivalent. [FIXME]
|
|||
Use @code{SCM_NFALSEP} instead.
|
||||
|
||||
@item @code{gh_scm2int}
|
||||
Use @code{scm_num2int} instead.
|
||||
Replace @code{gh_scm2int (@var{obj})} by
|
||||
@example
|
||||
scm_num2int (@var{obj}, SCM_ARG1, @var{str})
|
||||
@end example
|
||||
where @var{str} is a C string that describes the context of the call.
|
||||
|
||||
@item @code{gh_scm2ulong}
|
||||
Use @code{scm_num2ulong} instead.
|
||||
Replace @code{gh_scm2ulong (@var{obj})} by
|
||||
@example
|
||||
scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
|
||||
@end example
|
||||
where @var{str} is a C string that describes the context of the call.
|
||||
|
||||
@item @code{gh_scm2long}
|
||||
Use @code{scm_num2long} instead.
|
||||
Replace @code{gh_scm2long (@var{obj})} by
|
||||
@example
|
||||
scm_num2long (@var{obj}, SCM_ARG1, @var{str})
|
||||
@end example
|
||||
where @var{str} is a C string that describes the context of the call.
|
||||
|
||||
@item @code{gh_scm2double}
|
||||
Use @code{scm_num2dbl} instead.
|
||||
Replace @code{gh_scm2double (@var{obj})} by
|
||||
@example
|
||||
scm_num2dbl (@var{obj}, @var{str})
|
||||
@end example
|
||||
where @var{str} is a C string that describes the context of the call.
|
||||
|
||||
@item @code{gh_scm2char}
|
||||
Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
|
||||
|
|
@ -1048,7 +1056,96 @@ Replace @code{gh_exact_p (@var{obj})} by
|
|||
SCM_NFALSEP (scm_exact_p (@var{obj}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_eq_p}
|
||||
Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
|
||||
(@var{x}, @var{y})} by
|
||||
@example
|
||||
SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_eqv_p}
|
||||
Replace @code{gh_eqv_p (@var{x}, @var{y})} by
|
||||
@example
|
||||
SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_equal_p}
|
||||
Replace @code{gh_equal_p (@var{x}, @var{y})} by
|
||||
@example
|
||||
SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_string_equal_p}
|
||||
Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
|
||||
@example
|
||||
SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_null_p}
|
||||
Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
|
||||
(@var{obj})} by
|
||||
@example
|
||||
SCM_NFALSEP (scm_null_p (@var{obj}))
|
||||
@end example
|
||||
|
||||
@item @code{gh_cons}
|
||||
Use @code{scm_cons} instead.
|
||||
|
||||
@item @code{gh_car} and @code{gh_cdr}
|
||||
Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
|
||||
|
||||
@item @code{gh_cxxr} and @code{gh_cxxxr}
|
||||
(Where each x is either @samp{a} or @samp{d}.) Use the corresponding
|
||||
@code{SCM_CXXR} or @code{SCM_CXXXR} macro instead.
|
||||
|
||||
@item @code{gh_set_car_x} and @code{gh_set_cdr_x}
|
||||
Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
|
||||
|
||||
@item @code{gh_list}
|
||||
Use @code{scm_listify} instead.
|
||||
|
||||
@item @code{gh_length}
|
||||
Replace @code{gh_length (@var{lst})} by
|
||||
@example
|
||||
scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
|
||||
@end example
|
||||
where @var{str} is a C string that describes the context of the call.
|
||||
|
||||
@item @code{gh_append}
|
||||
Use @code{scm_append} instead.
|
||||
|
||||
@item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
|
||||
Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
|
||||
@example
|
||||
scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
|
||||
@end example
|
||||
|
||||
@item @code{gh_reverse}
|
||||
Use @code{scm_reverse} instead.
|
||||
|
||||
@item @code{gh_list_tail} and @code{gh_list_ref}
|
||||
Use @code{scm_list_tail} and @code{scm_list_ref} instead.
|
||||
|
||||
@item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
|
||||
Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
|
||||
|
||||
@item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
|
||||
Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
|
||||
|
||||
@item @code{gh_make_vector}
|
||||
Use @code{scm_make_vector} instead.
|
||||
|
||||
@item @code{gh_vector} or @code{gh_list_to_vector}
|
||||
Use @code{scm_vector} instead.
|
||||
|
||||
@item @code{gh_vector_ref} and @code{gh_vector_set_x}
|
||||
Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
|
||||
|
||||
@item @code{gh_vector_length}
|
||||
Use the @code{SCM_VECTOR_LENGTH} macro instead.
|
||||
|
||||
@item @code{gh_apply}
|
||||
Use @code{scm_apply} instead, but note that @code{scm_apply} takes an
|
||||
additional third argument that you should set to @code{SCM_EOL}.
|
||||
|
||||
@end table
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue