[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] GNU Guile branch, master, updated. release_1-9-10-51-g79
|
From: |
Neil Jerram |
|
Subject: |
[Guile-commits] GNU Guile branch, master, updated. release_1-9-10-51-g79bd99b |
|
Date: |
Sun, 25 Apr 2010 18:59:08 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".
http://git.savannah.gnu.org/cgit/guile.git/commit/?id=79bd99b3e407d89bc91fea59b119a2680b72b543
The branch, master has been updated
via 79bd99b3e407d89bc91fea59b119a2680b72b543 (commit)
via de3ba527c4cfbd6e168191a4fd305aedccac6e0c (commit)
via 42a438e89332072c71a682544d1e465a3543ec89 (commit)
via 46733b4284ea6958bdaf357b213537dbf6190c60 (commit)
via 45a272c5be582860f0c4ca52367c7aecdf9b0fd6 (commit)
via d665f75f5bf89ab1110cef9b983498932c6ab60a (commit)
from cb67c838f5658a74793f593c342873d32e4a145c (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 79bd99b3e407d89bc91fea59b119a2680b72b543
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 18:53:40 2010 +0100
Move description of manual organisation from Preface to Introduction
This material isn't "meta-" enough to be in the Preface, and it
supports (by its structure) some of the points that the Introduction
makes about Guile, so I think it belongs here.
* doc/ref/intro.texi (Introduction): Add `Organisation of this Manual'
menu item and material to here...
* doc/ref/preface.texi (Preface): ...from here.
commit de3ba527c4cfbd6e168191a4fd305aedccac6e0c
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 18:28:19 2010 +0100
Remove weird instruction
* doc/ref/intro.texi: Remove `Do not confuse the two.' (Or else
what?)
commit 42a438e89332072c71a682544d1e465a3543ec89
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 18:12:01 2010 +0100
Fix typo
* doc/ref/compiler.texi (Bytecode and Objcode): Remove extraneous
comma.
commit 46733b4284ea6958bdaf357b213537dbf6190c60
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 17:56:56 2010 +0100
Move `Reporting Bugs' section out of Introduction
I think it's too detailed, when compared with the other Introduction
sections. It probably also refers to concepts that haven't been
mentioned yet, but are mentioned in the following quick tour chapter;
so let's move it there.
* doc/ref/guile.texi: Move @raisesections and @lowersections for
tour.texi material from here to inside tour.texi.
* doc/ref/intro.texi (Introduction): Don't mention reporting problems
in first para. Move menu item and material for `Reporting Bugs'
from here...
* doc/ref/tour.texi (Hello Guile!): ...to here. Also mention
reporting problems in the introductory para.
commit 45a272c5be582860f0c4ca52367c7aecdf9b0fd6
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 17:01:01 2010 +0100
Move whirlwind tour material to its own chapter
* doc/ref/guile.texi (Top): New top level `Hello Guile!' menu item;
include new file tour.texi.
* doc/ref/intro.texi (Introduction): Remove whirlwind tour menu item
and material from here...
* doc/ref/tour.texi: ...to new file here.
commit d665f75f5bf89ab1110cef9b983498932c6ab60a
Author: Neil Jerram <address@hidden>
Date: Sun Apr 25 13:20:17 2010 +0100
Move Scheme introduction (Guile-independent) to its own chapter
This magically fixes all the internal wordings that say "chapter"
rather than "section", and separates Guile-independent and skippable
material from material that is Guile-specific and
probably-not-skippable - which I think is helpful.
* doc/ref/guile.texi (Top): New `Hello Scheme!' menu item, and removed
`Basic Ideas' item. Move include of scheme-ideas.texi before
`Programming in Scheme' chapter, using @raisesections and
@lowersections. Also move scheme-reading.texi to same place.
* doc/ref/scheme-ideas.texi: Change name from `Basic Ideas' (which is
a bit boring) to `Hello Scheme!'. Move `Further Reading' menu item
here.
-----------------------------------------------------------------------
Summary of changes:
doc/ref/compiler.texi | 2 +-
doc/ref/guile.texi | 14 +-
doc/ref/intro.texi | 496 +++++----------------------------------------
doc/ref/preface.texi | 42 +----
doc/ref/scheme-ideas.texi | 5 +-
doc/ref/tour.texi | 455 +++++++++++++++++++++++++++++++++++++++++
6 files changed, 519 insertions(+), 495 deletions(-)
create mode 100644 doc/ref/tour.texi
diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi
index 67a8ab4..05c4957 100644
--- a/doc/ref/compiler.texi
+++ b/doc/ref/compiler.texi
@@ -723,7 +723,7 @@ Returns @code{#f} iff @var{obj} is object code, @code{#f}
otherwise.
@end deffn
@deffn {Scheme Procedure} bytecode->objcode bytecode
address@hidden {C Function} scm_bytecode_to_objcode (bytecode,)
address@hidden {C Function} scm_bytecode_to_objcode (bytecode)
Makes a bytecode object from @var{bytecode}, which should be a
@code{u8vector}.
@end deffn
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 8a94efe..278aca9 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -169,6 +169,9 @@ x
* Preface::
* Introduction::
+* Hello Guile!::
+* Hello Scheme!::
+
* Programming in Scheme::
* Programming in C::
@@ -203,6 +206,13 @@ Indices
@include intro.texi
address@hidden tour.texi
+
address@hidden
address@hidden scheme-ideas.texi
address@hidden
address@hidden scheme-reading.texi
+
@node Programming in Scheme
@chapter Programming in Scheme
@@ -222,19 +232,15 @@ etc. that make up Guile's application programming
interface (API),
@xref{API Reference}.
@menu
-* Basic Ideas:: Basic ideas in Scheme.
* Guile Scheme:: Guile's implementation of Scheme.
* Guile Scripting:: How to write Guile scripts.
* Using Guile Interactively:: Guile's REPL features.
* Using Guile in Emacs:: Guile and Emacs.
-* Further Reading:: Where to find out more about Scheme.
@end menu
address@hidden scheme-ideas.texi
@include scheme-intro.texi
@include scheme-scripts.texi
@include scheme-using.texi
address@hidden scheme-reading.texi
@node Programming in C
@chapter Programming in C
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 86e52a5..7eb2ad3 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -37,11 +37,9 @@ it actually supports several languages, not just Scheme.
@end itemize
@noindent
-The next few sections explain what we mean by these points. The
-sections after that cover how you can obtain and install Guile, a tour
-of the ways that you can use it, how to report any problems that you
-encounter, and the typographical conventions that we use in this
-manual.
+The next few sections explain what we mean by these points. The sections after
+that cover how you can obtain and install Guile, and the typographical
+conventions that we use in this manual.
@menu
* Guile and Scheme::
@@ -50,8 +48,7 @@ manual.
* Interactive Programming::
* Supporting Multiple Languages::
* Obtaining and Installing Guile::
-* Whirlwind Tour::
-* Reporting Bugs::
+* Organisation of this Manual::
* Typographical Conventions::
@end menu
@@ -230,445 +227,50 @@ we have included the report in the Guile distribution;
see
Language Scheme}.
This will also be installed in your info directory.
address@hidden Whirlwind Tour
address@hidden A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used. There are additional examples in the @file{examples/}
-directory in the Guile source distribution.
-
-The following examples assume that Guile has been installed in
address@hidden/usr/local/}.
-
address@hidden
-* Running Guile Interactively::
-* Running Guile Scripts::
-* Linking Guile into Programs::
-* Writing Guile Extensions::
-* Using the Guile Module System::
address@hidden menu
-
-
address@hidden Running Guile Interactively
address@hidden Running Guile Interactively
-
-In its simplest form, Guile acts as an interactive interpreter for the
-Scheme programming language, reading and evaluating Scheme expressions
-the user enters from the terminal. Here is a sample interaction between
-Guile and a user; the user's input appears after the @code{$} and
address@hidden>} prompts:
-
address@hidden
-$ guile
-guile> (+ 1 2 3) ; add some numbers
-6
-guile> (define (factorial n) ; define a function
- (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb") ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
address@hidden example
-
-
address@hidden Running Guile Scripts
address@hidden Running Guile Scripts
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-Here is a trivial Guile script, for more details @xref{Guile Scripting}.
-
address@hidden
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
address@hidden example
-
-
address@hidden Linking Guile into Programs
address@hidden Linking Guile into Programs
-
-The Guile interpreter is available as an object library, to be linked
-into applications using Scheme as a configuration or extension
-language.
-
-Here is @file{simple-guile.c}, source code for a program that will
-produce a complete Guile interpreter. In addition to all usual
-functions provided by Guile, it will also offer the function
address@hidden
-
address@hidden
-#include <stdlib.h>
-#include <libguile.h>
-
-static SCM
-my_hostname (void)
address@hidden
- char *s = getenv ("HOSTNAME");
- if (s == NULL)
- return SCM_BOOL_F;
- else
- return scm_from_locale_string (s);
address@hidden
-
-static void
-inner_main (void *data, int argc, char **argv)
address@hidden
- scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
- scm_shell (argc, argv);
address@hidden
-
-int
-main (int argc, char **argv)
address@hidden
- scm_boot_guile (argc, argv, inner_main, 0);
- return 0; /* never reached */
address@hidden
address@hidden example
-
-When Guile is correctly installed on your system, the above program
-can be compiled and linked like this:
-
address@hidden
-$ gcc -o simple-guile simple-guile.c \
- `pkg-config --cflags --libs guile-2.0`
address@hidden example
-
-When it is run, it behaves just like the @code{guile} program except
-that you can also call the new @code{my-hostname} function.
-
address@hidden
-$ ./simple-guile
-guile> (+ 1 2 3)
-6
-guile> (my-hostname)
-"burns"
address@hidden example
-
address@hidden Writing Guile Extensions
address@hidden Writing Guile Extensions
-
-You can link Guile into your program and make Scheme available to the
-users of your program. You can also link your library into Guile and
-make its functionality available to all users of Guile.
-
-A library that is linked into Guile is called an @dfn{extensions}, but
-it really just is an ordinary object library.
-
-The following example shows how to write a simple extension for Guile
-that makes the @code{j0} function available to Scheme code.
-
address@hidden
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
address@hidden
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
address@hidden
-
-void
-init_bessel ()
address@hidden
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
address@hidden
address@hidden smallexample
-
-This C source file needs to be compiled into a shared library. Here is
-how to do it on GNU/Linux:
-
address@hidden
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
address@hidden smallexample
-
-For creating shared libraries portably, we recommend the use of GNU
-Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
-
-A shared library can be loaded into a running Guile process with the
-function @code{load-extension}. The @code{j0} is then immediately
-available:
-
address@hidden
-$ guile
-guile> (load-extension "./libguile-bessel" "init_bessel")
-guile> (j0 2)
-0.223890779141236
address@hidden smallexample
-
-
address@hidden Using the Guile Module System
address@hidden Using the Guile Module System
-
-Guile has support for dividing a program into @dfn{modules}. By using
-modules, you can group related code together and manage the
-composition of complete programs from largely independent parts.
-
-(Although the module system implementation is in flux, feel free to use it
-anyway. Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
address@hidden
-
address@hidden
-* Using Modules::
-* Writing new Modules::
-* Putting Extensions into Modules::
address@hidden menu
-
-
address@hidden Using Modules
address@hidden Using Modules
-
-Guile comes with a lot of useful modules, for example for string
-processing or command line parsing. Additionally, there exist many
-Guile modules written by other Guile hackers, but which have to be
-installed manually.
-
-Here is a sample interactive session that shows how to use the
address@hidden(ice-9 popen)} module which provides the means for communicating
-with other processes over pipes together with the @code{(ice-9
-rdelim)} module that provides the function @code{read-line}.
-
address@hidden
-$ guile
-guile> (use-modules (ice-9 popen))
-guile> (use-modules (ice-9 rdelim))
-guile> (define p (open-input-pipe "ls -l"))
-guile> (read-line p)
-"total 30"
-guile> (read-line p)
-"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
address@hidden smallexample
-
address@hidden Writing new Modules
address@hidden Writing new Modules
-
-You can create new modules using the syntactic form
address@hidden All definitions following this form until the
-next @code{define-module} are placed into the new module.
-
-One module is usually placed into one file, and that file is installed
-in a location where Guile can automatically find it. The following
-session shows a simple example.
-
address@hidden
-$ cat /usr/local/share/guile/foo/bar.scm
-
-(define-module (foo bar))
-(export frob)
-
-(define (frob x) (* 2 x))
-
-$ guile
-guile> (use-modules (foo bar))
-guile> (frob 12)
-24
address@hidden smallexample
-
address@hidden Putting Extensions into Modules
address@hidden Putting Extensions into Modules
-
-In addition to Scheme code you can also put things that are defined in
-C into a module.
-
-You do this by writing a small Scheme file that defines the module and
-call @code{load-extension} directly in the body of the module.
-
address@hidden
-$ cat /usr/local/share/guile/math/bessel.scm
-
-(define-module (math bessel))
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-
-$ file /usr/local/lib/libguile-bessel.so
address@hidden ELF 32-bit LSB shared object @dots{}
-$ guile
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
address@hidden smallexample
-
-There is also a way to manipulate the module system from C but only
-Scheme files can be autoloaded. Thus, we recommend that you define
-your modules in Scheme.
-
address@hidden Reporting Bugs
address@hidden Reporting Bugs
-
-Any problems with the installation should be reported to
address@hidden@@gnu.org}.
-
-Whenever you have found a bug in Guile you are encouraged to report it
-to the Guile developers, so they can fix it. They may also be able to
-suggest workarounds when it is not possible for you to apply the bug-fix
-or install a new version of Guile yourself.
-
-Before sending in bug reports, please check with the following list that
-you really have found a bug.
-
address@hidden @bullet
address@hidden
-Whenever documentation and actual behavior differ, you have certainly
-found a bug, either in the documentation or in the program.
-
address@hidden
-When Guile crashes, it is a bug.
-
address@hidden
-When Guile hangs or takes forever to complete a task, it is a bug.
-
address@hidden
-When calculations produce wrong results, it is a bug.
-
address@hidden
-When Guile signals an error for valid Scheme programs, it is a bug.
-
address@hidden
-When Guile does not signal an error for invalid Scheme programs, it may
-be a bug, unless this is explicitly documented.
-
address@hidden
-When some part of the documentation is not clear and does not make sense
-to you even after re-reading the section, it is a bug.
address@hidden itemize
-
-When you write a bug report, please make sure to include as much of the
-information described below in the report. If you can't figure out some
-of the items, it is not a problem, but the more information we get, the
-more likely we can diagnose and fix the bug.
-
address@hidden @bullet
address@hidden
-The version number of Guile. Without this, we won't know whether there
-is any point in looking for the bug in the current version of Guile.
-
-You can get the version number by invoking the command
-
address@hidden
-$ guile --version
-Guile 1.9.0
-Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
-2005, 2006, 2007, 2008, 2009 Free Software Foundation
-Guile may be distributed under the terms of the GNU Lesser General
-Public Licence. For details, see the files `COPYING.LESSER' and
-`COPYING', which are included in the Guile distribution. There is
-no warranty, to the extent permitted by law.
address@hidden example
-
address@hidden
-The type of machine you are using, and the operating system name and
-version number. On GNU systems, you can get it with @file{uname}.
-
address@hidden
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
address@hidden example
-
address@hidden
-The operands given to the @file{configure} command when Guile was
-installed. It's often useful to augment this with the output of the
-command @code{guile-config info}.
-
address@hidden
-A complete list of any modifications you have made to the Guile source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Guile. But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes. A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
address@hidden
-Details of any other deviations from the standard procedure for
-installing Guile.
-
address@hidden
-The complete text of any source files needed to reproduce the bug.
-
-If you can tell us a way to cause the problem without loading any source
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-
address@hidden
-The precise Guile invocation command line we need to type to reproduce
-the bug.
-
address@hidden
-A description of what behavior you observe that you believe is
-incorrect. For example, "The Guile process gets a fatal signal," or,
-"The resulting output is as follows, which I think is wrong."
-
-Of course, if the bug is that Guile gets a fatal signal, then one can't
-miss it. But if the bug is incorrect results, the maintainer might fail
-to notice what is wrong. Why leave it to chance?
-
-If the manifestation of the bug is a Guile error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Scheme program arrived at the error.
-
-This can be done using the procedure @code{backtrace} in the REPL.
-
address@hidden
-Check whether any programs you have loaded into Guile, including your
address@hidden file, set any variables that may affect the functioning of
-Guile. Also, see whether the problem happens in a freshly started Guile
-without loading your @file{.guile} file (start Guile with the @code{-q}
-switch to prevent loading the init file). If the problem does
address@hidden occur then, you must report the precise contents of any
-programs that you must load into Guile in order to cause the problem to
-occur.
-
address@hidden
-If the problem does depend on an init file or other Scheme programs that
-are not part of the standard Guile distribution, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Guile in a way
-that is supposed to work, they should report the bug.
-
address@hidden
-If you wish to mention something in the Guile source, show the line of
-code with a few lines of context. Don't just give a line number.
-
-The line numbers in the development sources might not match those in your
-sources. It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
address@hidden
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy. You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Guile distribution. To run Guile under GDB, you should
-switch to the @file{libguile} subdirectory in which Guile was compiled, then
-do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-For example, many people send just a backtrace, but that is not very
-useful by itself. A simple backtrace with arguments often conveys
-little about what is happening inside Guile, because most of the
-arguments listed in the backtrace are pointers to Scheme objects. The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
address@hidden itemize
-
address@hidden Organisation of this Manual
address@hidden Organisation of this Manual
+
+The rest of this manual is organised into the following chapters.
+
address@hidden @strong
address@hidden Chapter 1: Introduction
+This part provides an overview of what Guile is and how you can use
+it. A whirlwind tour shows how Guile can be used interactively and as
+a script interpreter, how to link Guile into your own applications,
+and how to write modules of interpreted and compiled code for use with
+Guile. Everything introduced here is documented again and in full by
+the later parts of the manual. This part also explains how to obtain
+and install new versions of Guile, and how to report bugs effectively.
+
address@hidden Chapter 2: Programming in Scheme
+This part provides an overview of programming in Scheme with Guile.
+It covers how to invoke the @code{guile} program from the command-line
+and how to write scripts in Scheme. It also gives an introduction
+into the basic ideas of Scheme itself and to the various extensions
+that Guile offers beyond standard Scheme.
+
address@hidden Chapter 3: Programming in C
+This part provides an overview of how to use Guile in a C program. It
+discusses the fundamental concepts that you need to understand to
+access the features of Guile, such as dynamic types and the garbage
+collector. It explains in a tutorial like manner how to define new
+data types and functions for the use by Scheme programs.
+
address@hidden Chapter 4: Guile API Reference
+This part of the manual documents the Guile @acronym{API} in
+functionality-based groups with the Scheme and C interfaces presented
+side by side.
+
address@hidden Chapter 5: Guile Modules
+Describes some important modules, distributed as part of the Guile
+distribution, that extend the functionality provided by the Guile
+Scheme core.
+
address@hidden Chapter 6: GOOPS
+Describes GOOPS, an object oriented extension to Guile that provides
+classes, multiple inheritance and generic functions.
+
address@hidden table
@node Typographical Conventions
@section Typographical Conventions
@@ -711,7 +313,7 @@ is denoted by the symbol @address@hidden
As you can see, this code prints @samp{1} (denoted by
@address@hidden), and returns @code{hooray} (denoted by
address@hidden@result{}}). Do not confuse the two.
address@hidden@result{}}).
@c Add other conventions here.
diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi
index f2d59cc..d0adf36 100644
--- a/doc/ref/preface.texi
+++ b/doc/ref/preface.texi
@@ -9,47 +9,7 @@
This manual describes how to use Guile, GNU's Ubiquitous Intelligent
Language for Extensions. It relates particularly to Guile version
address@hidden The manual is divided into the following chapters.
-
address@hidden @strong
address@hidden Chapter 1: Introduction
-This part provides an overview of what Guile is and how you can use
-it. A whirlwind tour shows how Guile can be used interactively and as
-a script interpreter, how to link Guile into your own applications,
-and how to write modules of interpreted and compiled code for use with
-Guile. Everything introduced here is documented again and in full by
-the later parts of the manual. This part also explains how to obtain
-and install new versions of Guile, and how to report bugs effectively.
-
address@hidden Chapter 2: Programming in Scheme
-This part provides an overview of programming in Scheme with Guile.
-It covers how to invoke the @code{guile} program from the command-line
-and how to write scripts in Scheme. It also gives an introduction
-into the basic ideas of Scheme itself and to the various extensions
-that Guile offers beyond standard Scheme.
-
address@hidden Chapter 3: Programming in C
-This part provides an overview of how to use Guile in a C program. It
-discusses the fundamental concepts that you need to understand to
-access the features of Guile, such as dynamic types and the garbage
-collector. It explains in a tutorial like manner how to define new
-data types and functions for the use by Scheme programs.
-
address@hidden Chapter 4: Guile API Reference
-This part of the manual documents the Guile @acronym{API} in
-functionality-based groups with the Scheme and C interfaces presented
-side by side.
-
address@hidden Chapter 5: Guile Modules
-Describes some important modules, distributed as part of the Guile
-distribution, that extend the functionality provided by the Guile
-Scheme core.
-
address@hidden Chapter 6: GOOPS
-Describes GOOPS, an object oriented extension to Guile that provides
-classes, multiple inheritance and generic functions.
-
address@hidden table
address@hidden
@menu
* Contributors::
diff --git a/doc/ref/scheme-ideas.texi b/doc/ref/scheme-ideas.texi
index e9b7765..d2dfbe7 100644
--- a/doc/ref/scheme-ideas.texi
+++ b/doc/ref/scheme-ideas.texi
@@ -4,8 +4,8 @@
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
address@hidden Basic Ideas
address@hidden Basic Ideas in Scheme
address@hidden Hello Scheme!
address@hidden Hello Scheme!
In this chapter, we introduce the basic concepts that underpin the
elegance and power of the Scheme language.
@@ -25,6 +25,7 @@ tutorial.
* About Procedures:: The representation and use of procedures.
* About Expressions:: All kinds of expressions and their meaning.
* About Closure:: Closure, scoping and environments.
+* Further Reading:: Where to find out more about Scheme.
@end menu
diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi
new file mode 100644
index 0000000..4a1a483
--- /dev/null
+++ b/doc/ref/tour.texi
@@ -0,0 +1,455 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006,
2010
address@hidden Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
+
address@hidden
+
address@hidden Hello Guile!
address@hidden Hello Guile!
+
+This chapter presents a quick tour of all the ways that Guile can be
+used. There are additional examples in the @file{examples/}
+directory in the Guile source distribution. It also explains how best to
report
+any problems that you find.
+
+The following examples assume that Guile has been installed in
address@hidden/usr/local/}.
+
address@hidden
+* Running Guile Interactively::
+* Running Guile Scripts::
+* Linking Guile into Programs::
+* Writing Guile Extensions::
+* Using the Guile Module System::
+* Reporting Bugs::
address@hidden menu
+
+
address@hidden Running Guile Interactively
address@hidden Running Guile Interactively
+
+In its simplest form, Guile acts as an interactive interpreter for the
+Scheme programming language, reading and evaluating Scheme expressions
+the user enters from the terminal. Here is a sample interaction between
+Guile and a user; the user's input appears after the @code{$} and
address@hidden>} prompts:
+
address@hidden
+$ guile
+guile> (+ 1 2 3) ; add some numbers
+6
+guile> (define (factorial n) ; define a function
+ (if (zero? n) 1 (* n (factorial (- n 1)))))
+guile> (factorial 20)
+2432902008176640000
+guile> (getpwnam "jimb") ; find my entry in /etc/passwd
+#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
+ "/usr/local/bin/bash")
+guile> @kbd{C-d}
+$
address@hidden example
+
+
address@hidden Running Guile Scripts
address@hidden Running Guile Scripts
+
+Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
+script is simply a file of Scheme code with some extra information at
+the beginning which tells the operating system how to invoke Guile, and
+then tells Guile how to handle the Scheme code.
+
+Here is a trivial Guile script, for more details @xref{Guile Scripting}.
+
address@hidden
+#!/usr/local/bin/guile -s
+!#
+(display "Hello, world!")
+(newline)
address@hidden example
+
+
address@hidden Linking Guile into Programs
address@hidden Linking Guile into Programs
+
+The Guile interpreter is available as an object library, to be linked
+into applications using Scheme as a configuration or extension
+language.
+
+Here is @file{simple-guile.c}, source code for a program that will
+produce a complete Guile interpreter. In addition to all usual
+functions provided by Guile, it will also offer the function
address@hidden
+
address@hidden
+#include <stdlib.h>
+#include <libguile.h>
+
+static SCM
+my_hostname (void)
address@hidden
+ char *s = getenv ("HOSTNAME");
+ if (s == NULL)
+ return SCM_BOOL_F;
+ else
+ return scm_from_locale_string (s);
address@hidden
+
+static void
+inner_main (void *data, int argc, char **argv)
address@hidden
+ scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
+ scm_shell (argc, argv);
address@hidden
+
+int
+main (int argc, char **argv)
address@hidden
+ scm_boot_guile (argc, argv, inner_main, 0);
+ return 0; /* never reached */
address@hidden
address@hidden example
+
+When Guile is correctly installed on your system, the above program
+can be compiled and linked like this:
+
address@hidden
+$ gcc -o simple-guile simple-guile.c \
+ `pkg-config --cflags --libs guile-2.0`
address@hidden example
+
+When it is run, it behaves just like the @code{guile} program except
+that you can also call the new @code{my-hostname} function.
+
address@hidden
+$ ./simple-guile
+guile> (+ 1 2 3)
+6
+guile> (my-hostname)
+"burns"
address@hidden example
+
address@hidden Writing Guile Extensions
address@hidden Writing Guile Extensions
+
+You can link Guile into your program and make Scheme available to the
+users of your program. You can also link your library into Guile and
+make its functionality available to all users of Guile.
+
+A library that is linked into Guile is called an @dfn{extensions}, but
+it really just is an ordinary object library.
+
+The following example shows how to write a simple extension for Guile
+that makes the @code{j0} function available to Scheme code.
+
address@hidden
+#include <math.h>
+#include <libguile.h>
+
+SCM
+j0_wrapper (SCM x)
address@hidden
+ return scm_make_real (j0 (scm_num2dbl (x, "j0")));
address@hidden
+
+void
+init_bessel ()
address@hidden
+ scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
address@hidden
address@hidden smallexample
+
+This C source file needs to be compiled into a shared library. Here is
+how to do it on GNU/Linux:
+
address@hidden
+gcc -shared -o libguile-bessel.so -fPIC bessel.c
address@hidden smallexample
+
+For creating shared libraries portably, we recommend the use of GNU
+Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
+
+A shared library can be loaded into a running Guile process with the
+function @code{load-extension}. The @code{j0} is then immediately
+available:
+
address@hidden
+$ guile
+guile> (load-extension "./libguile-bessel" "init_bessel")
+guile> (j0 2)
+0.223890779141236
address@hidden smallexample
+
+
address@hidden Using the Guile Module System
address@hidden Using the Guile Module System
+
+Guile has support for dividing a program into @dfn{modules}. By using
+modules, you can group related code together and manage the
+composition of complete programs from largely independent parts.
+
+(Although the module system implementation is in flux, feel free to use it
+anyway. Guile will provide reasonable backwards compatibility.)
+
+Details on the module system beyond this introductory material can be found in
address@hidden
+
address@hidden
+* Using Modules::
+* Writing new Modules::
+* Putting Extensions into Modules::
address@hidden menu
+
+
address@hidden Using Modules
address@hidden Using Modules
+
+Guile comes with a lot of useful modules, for example for string
+processing or command line parsing. Additionally, there exist many
+Guile modules written by other Guile hackers, but which have to be
+installed manually.
+
+Here is a sample interactive session that shows how to use the
address@hidden(ice-9 popen)} module which provides the means for communicating
+with other processes over pipes together with the @code{(ice-9
+rdelim)} module that provides the function @code{read-line}.
+
address@hidden
+$ guile
+guile> (use-modules (ice-9 popen))
+guile> (use-modules (ice-9 rdelim))
+guile> (define p (open-input-pipe "ls -l"))
+guile> (read-line p)
+"total 30"
+guile> (read-line p)
+"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
address@hidden smallexample
+
address@hidden Writing new Modules
address@hidden Writing new Modules
+
+You can create new modules using the syntactic form
address@hidden All definitions following this form until the
+next @code{define-module} are placed into the new module.
+
+One module is usually placed into one file, and that file is installed
+in a location where Guile can automatically find it. The following
+session shows a simple example.
+
address@hidden
+$ cat /usr/local/share/guile/foo/bar.scm
+
+(define-module (foo bar))
+(export frob)
+
+(define (frob x) (* 2 x))
+
+$ guile
+guile> (use-modules (foo bar))
+guile> (frob 12)
+24
address@hidden smallexample
+
address@hidden Putting Extensions into Modules
address@hidden Putting Extensions into Modules
+
+In addition to Scheme code you can also put things that are defined in
+C into a module.
+
+You do this by writing a small Scheme file that defines the module and
+call @code{load-extension} directly in the body of the module.
+
address@hidden
+$ cat /usr/local/share/guile/math/bessel.scm
+
+(define-module (math bessel))
+(export j0)
+
+(load-extension "libguile-bessel" "init_bessel")
+
+$ file /usr/local/lib/libguile-bessel.so
address@hidden ELF 32-bit LSB shared object @dots{}
+$ guile
+guile> (use-modules (math bessel))
+guile> (j0 2)
+0.223890779141236
address@hidden smallexample
+
+There is also a way to manipulate the module system from C but only
+Scheme files can be autoloaded. Thus, we recommend that you define
+your modules in Scheme.
+
address@hidden
+
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
+Any problems with the installation should be reported to
address@hidden@@gnu.org}.
+
+Whenever you have found a bug in Guile you are encouraged to report it
+to the Guile developers, so they can fix it. They may also be able to
+suggest workarounds when it is not possible for you to apply the bug-fix
+or install a new version of Guile yourself.
+
+Before sending in bug reports, please check with the following list that
+you really have found a bug.
+
address@hidden @bullet
address@hidden
+Whenever documentation and actual behavior differ, you have certainly
+found a bug, either in the documentation or in the program.
+
address@hidden
+When Guile crashes, it is a bug.
+
address@hidden
+When Guile hangs or takes forever to complete a task, it is a bug.
+
address@hidden
+When calculations produce wrong results, it is a bug.
+
address@hidden
+When Guile signals an error for valid Scheme programs, it is a bug.
+
address@hidden
+When Guile does not signal an error for invalid Scheme programs, it may
+be a bug, unless this is explicitly documented.
+
address@hidden
+When some part of the documentation is not clear and does not make sense
+to you even after re-reading the section, it is a bug.
address@hidden itemize
+
+When you write a bug report, please make sure to include as much of the
+information described below in the report. If you can't figure out some
+of the items, it is not a problem, but the more information we get, the
+more likely we can diagnose and fix the bug.
+
address@hidden @bullet
address@hidden
+The version number of Guile. Without this, we won't know whether there
+is any point in looking for the bug in the current version of Guile.
+
+You can get the version number by invoking the command
+
address@hidden
+$ guile --version
+Guile 1.9.0
+Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007, 2008, 2009 Free Software Foundation
+Guile may be distributed under the terms of the GNU Lesser General
+Public Licence. For details, see the files `COPYING.LESSER' and
+`COPYING', which are included in the Guile distribution. There is
+no warranty, to the extent permitted by law.
address@hidden example
+
address@hidden
+The type of machine you are using, and the operating system name and
+version number. On GNU systems, you can get it with @file{uname}.
+
address@hidden
+$ uname -a
+Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
address@hidden example
+
address@hidden
+The operands given to the @file{configure} command when Guile was
+installed. It's often useful to augment this with the output of the
+command @code{guile-config info}.
+
address@hidden
+A complete list of any modifications you have made to the Guile source.
+(We may not have time to investigate the bug unless it happens in an
+unmodified Guile. But if you've made modifications and you don't tell
+us, you are sending us on a wild goose chase.)
+
+Be precise about these changes. A description in English is not
+enough---send a context diff for them.
+
+Adding files of your own, or porting to another machine, is a
+modification of the source.
+
address@hidden
+Details of any other deviations from the standard procedure for
+installing Guile.
+
address@hidden
+The complete text of any source files needed to reproduce the bug.
+
+If you can tell us a way to cause the problem without loading any source
+files, please do so. This makes it much easier to debug. If you do
+need files, make sure you arrange for us to see their exact contents.
+
address@hidden
+The precise Guile invocation command line we need to type to reproduce
+the bug.
+
address@hidden
+A description of what behavior you observe that you believe is
+incorrect. For example, "The Guile process gets a fatal signal," or,
+"The resulting output is as follows, which I think is wrong."
+
+Of course, if the bug is that Guile gets a fatal signal, then one can't
+miss it. But if the bug is incorrect results, the maintainer might fail
+to notice what is wrong. Why leave it to chance?
+
+If the manifestation of the bug is a Guile error message, it is
+important to report the precise text of the error message, and a
+backtrace showing how the Scheme program arrived at the error.
+
+This can be done using the procedure @code{backtrace} in the REPL.
+
address@hidden
+Check whether any programs you have loaded into Guile, including your
address@hidden file, set any variables that may affect the functioning of
+Guile. Also, see whether the problem happens in a freshly started Guile
+without loading your @file{.guile} file (start Guile with the @code{-q}
+switch to prevent loading the init file). If the problem does
address@hidden occur then, you must report the precise contents of any
+programs that you must load into Guile in order to cause the problem to
+occur.
+
address@hidden
+If the problem does depend on an init file or other Scheme programs that
+are not part of the standard Guile distribution, then you should make
+sure it is not a bug in those programs by complaining to their
+maintainers first. After they verify that they are using Guile in a way
+that is supposed to work, they should report the bug.
+
address@hidden
+If you wish to mention something in the Guile source, show the line of
+code with a few lines of context. Don't just give a line number.
+
+The line numbers in the development sources might not match those in your
+sources. It would take extra work for the maintainers to determine what
+code is in your version at a given line number, and we could not be
+certain.
+
address@hidden
+Additional information from a C debugger such as GDB might enable
+someone to find a problem on a machine which he does not have available.
+If you don't know how to use GDB, please read the GDB manual---it is not
+very long, and using GDB is easy. You can find the GDB distribution,
+including the GDB manual in online form, in most of the same places you
+can find the Guile distribution. To run Guile under GDB, you should
+switch to the @file{libguile} subdirectory in which Guile was compiled, then
+do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
+
+However, you need to think when you collect the additional information
+if you want it to show what causes the bug.
+
+For example, many people send just a backtrace, but that is not very
+useful by itself. A simple backtrace with arguments often conveys
+little about what is happening inside Guile, because most of the
+arguments listed in the backtrace are pointers to Scheme objects. The
+numeric values of these pointers have no significance whatever; all that
+matters is the contents of the objects they point to (and most of the
+contents are themselves pointers).
address@hidden itemize
+
+
address@hidden Local Variables:
address@hidden TeX-master: "guile.texi"
address@hidden End:
hooks/post-receive
--
GNU Guile
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Guile-commits] GNU Guile branch, master, updated. release_1-9-10-51-g79bd99b,
Neil Jerram <=