mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 03:30:27 +02:00
Code Activity

* preface.texi (Manual Conventions): Added description of

Browse source 
@result{} and @print{}.

	* scheme-data.texi (Hash Table Examples): New subsubsection.
This commit is contained in:
Martin Grabmüller 2001-06-30 13:45:22 +00:00
parent 4dadf664c6
commit e9566a8e4c
3 changed files with 100 additions and 159 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/ChangeLog
View file

@ -1,3 +1,10 @@
2001-06-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* preface.texi (Manual Conventions): Added description of
@result{} and @print{}.
* scheme-data.texi (Hash Table Examples): New subsubsection.
2001-06-30 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-data.texi (Hash Tables): Added docs for

158
doc/preface.texi
View file

@ -1,158 +0,0 @@
@iftex
@page
@unnumbered Preface
This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions. It describes how to use Guile in many useful
and interesting ways.
This is edition 1.0 of the reference manual, and corresponds to Guile
version @value{VERSION}.
@end iftex
@iftex
@section The Guile License
@end iftex
@ifnottex
@node Guile License
@chapter The Guile License
@end ifnottex
The license of Guile consists of the GNU GPL plus a special statement
giving blanket permission to link with non-free software. This is the
license statement as found in any individual file that it applies to:
@quotation
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this software; see the file COPYING. If not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA
As a special exception, the Free Software Foundation gives permission
for additional uses of the text contained in its release of GUILE.
The exception is that, if you link the GUILE library with other files to
produce an executable, this does not by itself cause the resulting
executable to be covered by the GNU General Public License. Your use of
that executable is in no way restricted on account of linking the GUILE
library code into it.
This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License.
This exception applies only to the code released by the Free Software
Foundation under the name GUILE. If you copy code from other Free
Software Foundation releases into a copy of GUILE, as the General Public
License permits, the exception does not apply to the code that you add
in this way. To avoid misleading anyone as to the status of such
modified files, you must delete this exception notice from them.
If you write modifications of your own for GUILE, it is your choice
whether to permit this exception to apply to your modifications. If you
do not wish that, delete this exception notice.
@end quotation
@iftex
@section Layout of this Manual
@end iftex
@ifnottex
@node Manual Layout
@chapter Layout of this Manual
@end ifnottex
This manual is divided into five parts.
@strong{Part I: Introduction to Guile} 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. All of the ideas introduced here are
documented in full by the later parts of the manual.
@strong{Part II: Guile Scheme} documents the core Scheme language and
features that Guile implements. Although the basis for this is the
Scheme language described in R5RS, this part of the manual does not
assume any prior familiarity with R5RS in particular, or with Scheme in
general. Basic Scheme concepts, standard aspects of the Scheme language
and Guile extensions on top of R5RS are all documented from scratch, and
organized by functionality rather than by the defining standards.
@strong{Part III: Guile Modules} describes some important modules,
distributed as part of the Guile distribution, that extend the
functionality provided by the Guile Scheme core, most notably:
@itemize @bullet
@item
the POSIX module, which provides Scheme level procedures for system and
network programming, conforming to the POSIX standard
@item
the SLIB module, which makes Aubrey Jaffer's portable Scheme library
available for use in Guile.
@end itemize
@strong{Part IV: Guile Scripting} documents the use of Guile as a script
interpreter, and illustrates this with a series of examples.
@strong{Part V: Extending Applications Using Guile} explains the options
available for using Guile as a application extension language. At the
simpler end of the scale, an application might use Guile to define some
application-specific primitives in C and then load an application Scheme
file. In this case most of the application code is written on the
Scheme level, and uses the application-specific primitives as an
extension to standard Scheme. At the other end of the scale, an
application might be predominantly written in C --- with its main
control loop implemented in C --- but make occasional forays into Scheme
to, say, read configuration data or run user-defined customization code.
This part of the manual covers the complete range of application
extension options.
Finally, the appendices explain how to obtain the latest version of
Guile, how to install it, where to find modules to work with Guile, and
how to use the Guile debugger.
@iftex
@section Manual Conventions
@end iftex
@ifnottex
@node Manual Conventions
@chapter Conventions used in this Manual
@end ifnottex
We use some conventions in this manual.
@itemize @bullet
@item
For some procedures, notably type predicates, we use @dfn{iff} to
mean `if and only if'. The construct is usually something like:
`Return @var{val} iff @var{condition}', where @var{val} is usually
`@code{#t}' or `non-@code{#f}'. This typically means that @var{val}
is returned if @var{condition} holds, and that @samp{#f} is returned
otherwise.
@cindex iff
@c Add other conventions here.
@end itemize
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

94
doc/scheme-data.texi
View file

@ -4784,6 +4784,98 @@ capitals
@subsection Hash Tables
@tpindex Hash Tables
@c FIXME::martin: Review me!
Hash tables are dictionaries which offer similar functionality as
association lists: They provide a mapping from keys to values. The
difference is that association lists need time linear in the size of
elements when searching for entries, whereas hash tables can normally
search in constant time. The drawback is that hash tables require a
little bit more memory, and that you can not use the normal list
procedures (@pxref{Lists}) for working with them.
@menu
* Hash Table Examples:: Demonstration of hash table usage.
* Hash Table Reference:: Hash table procedure descriptions.
@end menu
@node Hash Table Examples
@subsubsection Hash Table Examples
@c FIXME::martin: Review me!
For demonstration purposes, this section gives a few usage examples of
some hash table procedures, together with some explanation what they do.
First we start by creating a new hash table with 31 slots, and
populate it with two key/value pairs.
@lisp
(define h (make-hash-table 31))
(hashq-create-handle! h 'foo "bar")
@result{}
(foo . "bar")
(hashq-create-handle! h 'braz "zonk")
@result{}
(braz . "zonk")
(hashq-create-handle! h 'frob #f)
@result{}
(frob . #f)
@end lisp
You can get the value for a given key with the procedure
@code{hashq-ref}, but the problem with this procedure is that you
cannot reliably determine whether a key does exists in the table. The
reason is that the procedure returns @code{#f} if the key is not in
the table, but it will return the same value if the key is in the
table and just happens to have the value @code{#f}, as you can see in
the following examples.
@lisp
(hashq-ref h 'foo)
@result{}
"bar"
(hashq-ref h 'frob)
@result{}
#f
(hashq-ref h 'not-there)
@result{}
#f
@end lisp
Better is to use the procedure @code{hashq-get-handle}, which makes a
distinction between the two cases. Just like @code{assq}, this
procedure returns a key/value-pair on success, and @code{#f} if the
key is not found.
@lisp
(hashq-get-handle h 'foo)
@result{}
(foo . "bar")
(hashq-get-handle h 'not-there)
@result{}
#f
@end lisp
There is no procedure for calculating the number of key/value-pairs in
a hash table, but @code{hash-fold} can be used for doing exactly that.
@lisp
(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
@result{}
3
@end lisp
@node Hash Table Reference
@subsubsection Hash Table Reference
Like the association list functions, the hash table functions come
in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
The @code{hashq} functions use @code{eq?} to determine whether two
@ -4991,7 +5083,7 @@ The arguments to PROC are "(key value prior-result)" where key
and value are successive pairs from the hash table TABLE, and
prior-result is either INIT (for the first application of PROC)
or the return value of the previous application of PROC.
For example, @code{(hash-fold acons () tab)} will convert a hash
For example, @code{(hash-fold acons '() tab)} will convert a hash
table into an a-list of key-value pairs.
@end deffn