@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Programming Overview
@section An Overview of Guile Programming
@subsection How One Might Extend Dia Using Guile
Dia is a free software program for drawing schematic diagrams like flow
-charts and floor plans (REFFIXME). This section conducts the thought
+charts and floor plans (@uref{http://www.gnome.org/projects/dia/}).
+This section conducts the thought
experiment of adding Guile to Dia. In so doing, it aims to illustrate
several of the steps and considerations involved in adding Guile to
applications in general.
primitive:
@lisp
-#define FUNC_NAME "square?"
static SCM square_p (SCM shape)
@{
struct dia_guile_shape * guile_shape;
/* Check that arg is really a shape SMOB. */
- SCM_VALIDATE_SHAPE (SCM_ARG1, shape);
+ scm_assert_smob_type (shape_tag, shape);
/* Access Scheme-specific shape structure. */
guile_shape = SCM_SMOB_DATA (shape);
return scm_from_bool (guile_shape->c_shape &&
(guile_shape->c_shape->type == DIA_SQUARE));
@}
-#undef FUNC_NAME
@end lisp
Notice how easy it is to chain through from the @code{SCM shape}
Scheme-specific structure inside the SMOB, and thence to the underlying
C structure for the shape.
-In this code, @code{SCM_SMOB_DATA} and @code{scm_from_bool} are from
-the standard Guile API. @code{SCM_VALIDATE_SHAPE} is a macro that you
-should define as part of your SMOB definition: it checks that the
-passed parameter is of the expected type. This is needed to guard
+In this code, @code{scm_assert_smob_type}, @code{SCM_SMOB_DATA}, and
+@code{scm_from_bool} are from the standard Guile API. We assume that
+@code{shape_tag} was given to us when we made the shape SMOB type, using
+@code{scm_make_smob_type}. The call to @code{scm_assert_smob_type}
+ensures that @var{shape} is indeed a shape. This is needed to guard
against Scheme code using the @code{square?} procedure incorrectly, as
in @code{(square? "hello")}; Scheme's latent typing means that usage
errors like this must be caught at run time.
Having written the C code for your primitives, you need to make them
available as Scheme procedures by calling the @code{scm_c_define_gsubr}
-function. @code{scm_c_define_gsubr} (REFFIXME) takes arguments that
+function. @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) takes arguments that
specify the Scheme-level name for the primitive and how many required,
optional and rest arguments it can accept. The @code{square?} primitive
always requires exactly one argument, so the call to make it available
application needs is not already available in this form, and it is
impossible to write the new functionality in Scheme, you will need to
write some C code. If the required function is already available in C
-(e.g. in a library), all you need is a little glue to connect it to the
+(e.g.@: in a library), all you need is a little glue to connect it to the
world of Guile. If not, you need both to write the basic code and to
plumb it into Guile.
functionality provided by the original application. As such, all the
discussions of the preceding sections of this chapter are relevant to
how you can proceed with developing your extension.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: