dmbcs/guile
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'boehm-demers-weiser-gc' into bdw-gc-static-alloc

Browse source 
Conflicts:
	acinclude.m4
	libguile/strings.c
This commit is contained in:
Ludovic Courtès 2009-09-02 00:07:27 +02:00
commit 5f236208d0
932 changed files with 123625 additions and 18312 deletions
Download patch file Download diff file Expand all files Collapse all files

52
.gitignore vendored
View file

@ -12,7 +12,6 @@ config.guess
config.status
config.log
config.h
guile-readline-config.h
*.doc
*.x
*.lo
@ -37,7 +36,7 @@ autom4te.cache
benchmark-guile
check-guile
check-guile.log
compile
build-aux/compile
confdefs.h
config.build-subdirs
config.cache
@ -53,7 +52,6 @@ conftest.c
depcomp
elisp-comp
guile-*.tar.gz
guile-tools
install-sh
libtool
ltconfig
@ -66,12 +64,52 @@ pre-inst-guile-env
stamp-h1
guile-procedures.txt
guile-config/guile-config
guile-readline/guile-readline-config.h
guile-readline/guile-readline-config.h.in
*.go
TAGS
guile-1.8.pc
libguile/stack-limit-calibration.scm
/meta/guile-2.0.pc
/meta/guile-2.0-uninstalled.pc
gdb-pre-inst-guile
cscope.out
cscope.files
*.log
gds-test.debug
gds-test.transcript
INSTALL
*.aux
*.cp
*.cps
*.dvi
*.fn
*.fns
*.ky
*.pg
*.toc
*.tp
*.vr
*.tps
*.vrs
*.pgs
*.rn
*.rns
/meta/gdb-uninstalled-guile
/meta/guile
/meta/uninstalled-env
/examples/box-module/box
/examples/box/box
/lib/alloca.h
/lib/charset.alias
/lib/configmake.h
/lib/ref-add.sed
/lib/ref-del.sed
/lib/stdlib.h
/lib/string.h
/lib/strings.h
/lib/sys/file.h
/lib/time.h
/lib/unistd.h
/lib/unistr/.dirstamp
/GPATH
/GRTAGS
/GSYMS
/GTAGS
/meta/guile-tools

2
ANNOUNCE
View file

@ -30,7 +30,7 @@ The NEWS file is quite long. Here are the most interesting entries:
from threads that have not been created by Guile.
* Mutexes and condition variables are now always fair. A recursive
mutex must be requested explicitely.
mutex must be requested explicitly.
* The low-level thread API has been removed.

29
AUTHORS
View file

@ -206,8 +206,34 @@ In the subdirectory doc, changes to:
Many changes throughout.
Neil Jerram:
In the subdirectory emacs, wrote:
gds.el gds-scheme.el gds-server.el
gds-test.el gds-test.sh gds-test.stdin
gds-tutorial.txt gds-faq.txt
In the subdirectory ice-9, wrote:
buffered-input.scm
buffered-input.scm gds-client.scm gds-server.scm
In the subdirectory ice-9/debugging, wrote:
example-fns.scm ice-9-debugger-extensions.scm
steps.scm trace.scm traps.scm
trc.scm
In the subdirectory lang/elisp, wrote:
base.scm example.el interface.scm
transform.scm variables.scm
In the subdirectory lang/elisp/internals, wrote:
evaluation.scm format.scm fset.scm
lambda.scm load.scm null.scm
set.scm signal.scm time.scm
trace.scm
In the subdirectory lang/elisp/primitives, wrote:
buffers.scm char-table.scm features.scm
fns.scm format.scm guile.scm
keymaps.scm lists.scm load.scm
match.scm numbers.scm pure.scm
read.scm signal.scm strings.scm
symprop.scm syntax.scm system.scm
time.scm
In the subdirectory srfi, wrote:
srfi-34.scm
In the subdirectory doc, wrote:
deprecated.texi goops.texi scheme-ideas.texi
scheme-reading.texi
@ -227,6 +253,7 @@ In the subdirectory doc, changes to:
scm.texi scripts.texi script-getopt.texi
In the subdirectory doc/maint, wrote:
docstring.el
Many other changes throughout.
Thien-Thi Nguyen:
In the top-level directory, wrote:

674
COPYING Normal file
View file

@ -0,0 +1,674 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
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 3 of the License, 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 program. If not, see <http://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<http://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<http://www.gnu.org/philosophy/why-not-lgpl.html>.

617
COPYING.LESSER
View file

@ -1,504 +1,165 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
0. Additional Definitions.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
1. Exception to Section 3 of the GNU GPL.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
2. Conveying Modified Versions.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3. Object Code Incorporating Material from Library Header Files.
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
b) Accompany the object code with a copy of the GNU GPL and this license
document.
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
4. Combined Works.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library 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
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!

19
FAQ
View file

@ -1,19 +0,0 @@
Guile FAQ -*- outline -*-
* Build problems
** readline.c: error: `rl_pending_input' undeclared
This occurs if the Readline library detected by Guile's configure
script is actually the BSD Editline project's supposedly
Readline-compatible library. The immediate fix is to uninstall
Editline and install the real GNU Readline instead. When you do this,
please note that it probably won't work to keep Editline in /usr and
install GNU Readline in /usr/local (or some similar arrangement),
because the Editline library will then still be picked up at link and
run time; it's best (subject to other constraints) to remove Editline
completely.
For the longer term, please also report this problem to the Editline
project, to encourage them to fix it in the next release of their
Readline compatibility library.

2
GUILE-VERSION
View file

@ -2,7 +2,7 @@
GUILE_MAJOR_VERSION=1
GUILE_MINOR_VERSION=9
GUILE_MICRO_VERSION=0
GUILE_MICRO_VERSION=2
GUILE_EFFECTIVE_VERSION=${GUILE_MAJOR_VERSION}.${GUILE_MINOR_VERSION}
GUILE_VERSION=${GUILE_EFFECTIVE_VERSION}.${GUILE_MICRO_VERSION}-bdwgc

9
HACKING
View file

@ -59,8 +59,9 @@ Automake --- a system for automatically generating Makefiles that
libtool --- a system for managing the zillion hairy options needed
on various systems to produce shared libraries. Available in
"ftp://ftp.gnu.org/pub/gnu/libtool". Version 1.5.26 (or
later) is needed for correct AIX support.
"ftp://ftp.gnu.org/pub/gnu/libtool". Version 2.2 (or
later) is recommended (for correct AIX support, and correct
interaction with the Gnulib module for using libunistring).
gettext --- a system for rigging a program so that it can output its
messages in the local tongue. Guile presently only exports
@ -88,6 +89,10 @@ have been known to cause problems, and a short description of the problem.
- autoreconf from autoconf prior to 2.59 will run gettextize, which
will mess up the Guile tree.
- libtool 1.5.26 does not know that it should remove the -R options
that the Gnulib libunistring and havelib modules generate (because
gcc doesn't actually support -R).
- (add here.)

2
LICENSE
View file

@ -1,2 +1,2 @@
Guile is covered under the terms of the GNU Lesser General Public
License, version 2.1. See COPYING.LESSER.
License, version 3 or later. See COPYING.LESSER and COPYING.

43
Makefile.am
View file

@ -1,38 +1,37 @@
## Process this file with automake to produce Makefile.in.
##
## Copyright (C) 1998, 1999, 2000, 2001, 2002, 2006, 2007, 2008 Free Software Foundation, Inc.
## Copyright (C) 1998, 1999, 2000, 2001, 2002, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
# want automake 1.10 or higher so that AM_GNU_GETTEXT can tell automake that
# config.rpath is needed
#
AUTOMAKE_OPTIONS = 1.10
SUBDIRS = lib oop libguile ice-9 guile-config guile-readline emacs \
scripts srfi doc examples test-suite benchmark-suite lang am
bin_SCRIPTS = guile-tools
SUBDIRS = lib meta libguile guile-readline emacs \
srfi doc examples test-suite benchmark-suite lang am \
module testsuite
include_HEADERS = libguile.h
EXTRA_DIST = LICENSE HACKING GUILE-VERSION \
m4/ChangeLog-2008 FAQ guile-1.8.pc.in \
m4/ChangeLog-2008 \
m4/autobuild.m4 ChangeLog-2008
TESTS = check-guile
@ -41,7 +40,19 @@ ACLOCAL_AMFLAGS = -I m4
DISTCLEANFILES = check-guile.log
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = guile-1.8.pc
dist-hook: gen-ChangeLog
clean-local:
rm -rf cache/
gen_start_rev = 61db429e251bfd2f75cb4632972e0238056eb24b
.PHONY: gen-ChangeLog
gen-ChangeLog:
if test -d .git; then \
$(top_srcdir)/build-aux/gitlog-to-changelog \
$(gen_start_rev)..HEAD > $(distdir)/cl-t; \
rm -f $(distdir)/ChangeLog; \
mv $(distdir)/cl-t $(distdir)/ChangeLog; \
fi
# Makefile.am ends here

643
NEWS
View file

@ -5,29 +5,566 @@ See the end for copying conditions.
Please send Guile bug reports to bug-guile@gnu.org.
Changes in 1.9.0:
(During the 1.9 series, we will keep an incremental NEWS for the latest
prerelease, and a full NEWS corresponding to 1.8 -> 2.0.)
Changes in 1.9.3 (since the 1.9.2 prerelease):
** Removed deprecated uniform array procedures: scm_make_uve,
scm_array_prototype, scm_list_to_uniform_array,
scm_dimensions_to_uniform_array, scm_make_ra, scm_shap2ra, scm_cvref,
scm_ra_set_contp, scm_aind, scm_raprin1
These functions have been deprecated since early 2005.
** scm_array_p has one argument, not two
Use of the second argument produced a deprecation warning, so it is
unlikely that any code out there actually used this functionality.
** Removed deprecated uniform array procedures:
dimensions->uniform-array, list->uniform-array, array-prototype
Instead, use make-typed-array, list->typed-array, or array-type,
respectively.
** And of course, the usual collection of bugfixes
Interested users should see the ChangeLog for more information.
Changes in 1.9.x (since the 1.8.x series):
* New modules (see the manual for details)
** `(srfi srfi-18)', multithreading support
** The `(ice-9 i18n)' module provides internationalization support
* Changes to the distribution
** Guile now uses Gnulib as a portability aid
** `(srfi srfi-18)', more sophisticated multithreading support
** `(ice-9 i18n)', internationalization support
** `(rnrs bytevector)', the R6RS bytevector API
** `(rnrs io ports)', a subset of the R6RS I/O port API
** `(system xref)', a cross-referencing facility (FIXME undocumented)
* Changes to the stand-alone interpreter
** Guile now can compile Scheme to bytecode for a custom virtual machine.
Compiled code loads much faster than Scheme source code, and runs around
3 or 4 times as fast, generating much less garbage in the process.
** The stack limit is now initialized from the environment.
If getrlimit(2) is available and a stack limit is set, Guile will set
its stack limit to 80% of the rlimit. Otherwise the limit is 160000
words, a four-fold increase from the earlier default limit.
** New environment variables: GUILE_LOAD_COMPILED_PATH,
GUILE_SYSTEM_LOAD_COMPILED_PATH
GUILE_LOAD_COMPILED_PATH is for compiled files what GUILE_LOAD_PATH is
for source files. It is a different path, however, because compiled
files are architecture-specific. GUILE_SYSTEM_LOAD_COMPILED_PATH is like
GUILE_SYSTEM_PATH.
** New read-eval-print loop (REPL) implementation
Running Guile with no arguments drops the user into the new REPL. While
it is self-documenting to an extent, the new REPL has not yet been
documented in the manual. This will be fixed before 2.0.
** New `guile-tools' commands: `compile', `disassemble'
Pass the `--help' command-line option to these commands for more
information.
* Changes to Scheme functions and syntax
** A new 'memoize-symbol evaluator trap has been added. This trap can
be used for efficiently implementing a Scheme code coverage.
** Procedure removed: `the-environment'
This procedure was part of the interpreter's execution model, and does
not apply to the compiler.
** Files loaded with `primitive-load-path' will now be compiled
automatically.
If a compiled .go file corresponding to a .scm file is not found or is
not fresh, the .scm file will be compiled on the fly, and the resulting
.go file stored away. An advisory note will be printed on the console.
Note that this mechanism depends on preservation of the .scm and .go
modification times; if the .scm or .go files are moved after
installation, care should be taken to preserve their original
timestamps.
Autocompiled files will be stored in the $XDG_CACHE_HOME/guile/ccache
directory, where $XDG_CACHE_HOME defaults to ~/.cache. This directory
will be created if needed.
To inhibit autocompilation, set the GUILE_AUTO_COMPILE environment
variable to 0, or pass --no-autocompile on the Guile command line.
Note that there is currently a bug here: automatic compilation will
sometimes be attempted when it shouldn't.
For example, the old (lang elisp) modules are meant to be interpreted,
not compiled. This bug will be fixed before 2.0. FIXME 2.0: Should say
something here about module-transformer called for compile.
** New POSIX procedures: `getrlimit' and `setrlimit'
Note however that the interface of these functions is likely to change
in the next prerelease.
** New procedure in `(oops goops)': `method-formals'
** BUG: (procedure-property func 'arity) does not work on compiled
procedures
This will be fixed one way or another before 2.0.
** New procedures in (ice-9 session): `add-value-help-handler!',
`remove-value-help-handler!', `add-name-help-handler!'
`remove-name-help-handler!', `procedure-arguments',
The value and name help handlers provide some minimal extensibility to
the help interface. Guile-lib's `(texinfo reflection)' uses them, for
example, to make stexinfo help documentation available. See those
procedures' docstrings for more information.
`procedure-arguments' describes the arguments that a procedure can take,
combining arity and formals. For example:
(procedure-arguments resolve-interface)
=> ((required . (name)) (rest . args))
Additionally, `module-commentary' is now publically exported from
`(ice-9 session).
** Deprecated: `procedure->memoizing-macro', `procedure->syntax'
These procedures will not work with syncase expansion, and indeed are
not used in the normal course of Guile. They are still used by the old
Emacs Lisp support, however.
** New language: ECMAScript
Guile now ships with one other high-level language supported,
ECMAScript. The goal is to support all of version 3.1 of the standard,
but not all of the libraries are there yet. This support is not yet
documented; ask on the mailing list if you are interested.
** New language: Brainfuck
Brainfuck is a toy language that closely models Turing machines. Guile's
brainfuck compiler is meant to be an example of implementing other
languages. See the manual for details, or
http://en.wikipedia.org/wiki/Brainfuck for more information about the
Brainfuck language itself.
** Defmacros may now have docstrings.
Indeed, any macro may have a docstring. `object-documentation' from
`(ice-9 documentation)' may be used to retrieve the docstring, once you
have a macro value -- but see the above note about first-class macros.
Docstrings are associated with the syntax transformer procedures.
** The psyntax expander now knows how to interpret the @ and @@ special
forms.
** The psyntax expander is now hygienic with respect to modules.
Free variables in a macro are scoped in the module that the macro was
defined in, not in the module the macro is used in. For example, code
like this works now:
(define-module (foo) #:export (bar))
(define (helper x) ...)
(define-syntax bar
(syntax-rules () ((_ x) (helper x))))
(define-module (baz) #:use-module (foo))
(bar qux)
It used to be you had to export `helper' from `(foo)' as well.
Thankfully, this has been fixed.
** New function, `procedure-module'
While useful on its own, `procedure-module' is used by psyntax on syntax
transformers to determine the module in which to scope introduced
identifiers.
** `eval-case' has been deprecated, and replaced by `eval-when'.
The semantics of `eval-when' are easier to understand. It is still
missing documentation, however.
** Guile is now more strict about prohibiting definitions in expression
contexts.
Although previous versions of Guile accepted it, the following
expression is not valid, in R5RS or R6RS:
(if test (define foo 'bar) (define foo 'baz))
In this specific case, it would be better to do:
(define foo (if test 'bar 'baz))
It is certainly possible to circumvent this resriction with e.g.
`(module-define! (current-module) 'foo 'baz)'. We would appreciate
feedback about this change (a consequence of using psyntax as the
default expander), and may choose to revisit this situation before 2.0
in response to user feedback.
** Defmacros must now produce valid Scheme expressions.
It used to be that defmacros could unquote in Scheme values, as a way of
supporting partial evaluation, and avoiding some hygiene issues. For
example:
(define (helper x) ...)
(define-macro (foo bar)
`(,helper ,bar))
Assuming this macro is in the `(baz)' module, the direct translation of
this code would be:
(define (helper x) ...)
(define-macro (foo bar)
`((@@ (baz) helper) ,bar))
Of course, one could just use a hygienic macro instead:
(define-syntax foo
(syntax-rules ()
((_ bar) (helper bar))))
** Guile's psyntax now supports docstrings and internal definitions.
The following Scheme is not strictly legal:
(define (foo)
"bar"
(define (baz) ...)
(baz))
However its intent is fairly clear. Guile interprets "bar" to be the
docstring of `foo', and the definition of `baz' is still in definition
context.
** Macros need to be defined before their first use.
It used to be that with lazy memoization, this might work:
(define (foo x)
(ref x))
(define-macro (ref x) x)
(foo 1) => 1
But now, the body of `foo' is interpreted to mean a call to the toplevel
`ref' function, instead of a macro expansion. The solution is to define
macros before code that uses them.
** Functions needed by macros at expand-time need to be present at
expand-time.
For example, this code will work at the REPL:
(define (double-helper x) (* x x))
(define-macro (double-literal x) (double-helper x))
(double-literal 2) => 4
But it will not work when a file is compiled, because the definition of
`double-helper' is not present at expand-time. The solution is to wrap
the definition of `double-helper' in `eval-when':
(eval-when (load compile eval)
(define (double-helper x) (* x x)))
(define-macro (double-literal x) (double-helper x))
(double-literal 2) => 4
See the (currently missing) documentation for eval-when for more
information.
** New variable, %pre-modules-transformer
Need to document this one some more.
** Temporarily removed functions: `macroexpand', `macroexpand-1'
`macroexpand' will be added back before 2.0. It is unclear how to
implement `macroexpand-1' with syntax-case, though PLT Scheme does prove
that it is possible.
** New reader macros: #' #` #, #,@
These macros translate, respectively, to `syntax', `quasisyntax',
`unsyntax', and `unsyntax-splicing'. See the R6RS for more information.
These reader macros may be overridden by `read-hash-extend'.
** Incompatible change to #'
Guile did have a #' hash-extension, by default, which just returned the
subsequent datum: #'foo => foo. In the unlikely event that anyone
actually used this, this behavior may be reinstated via the
`read-hash-extend' mechanism.
** Scheme expresssions may be commented out with #;
#; comments out an entire expression. See SRFI-62 or the R6RS for more
information.
** `make-stack' with a tail-called procedural narrowing argument no longer
works (with compiled procedures)
It used to be the case that a captured stack could be narrowed to select
calls only up to or from a certain procedure, even if that procedure
already tail-called another procedure. This was because the debug
information from the original procedure was kept on the stack.
Now with the new compiler, the stack only contains active frames from
the current continuation. A narrow to a procedure that is not in the
stack will result in an empty stack. To fix this, narrow to a procedure
that is active in the current continuation, or narrow to a specific
number of stack frames.
** backtraces through compiled procedures only show procedures that are
active in the current continuation
Similarly to the previous issue, backtraces in compiled code may be
different from backtraces in interpreted code. There are no semantic
differences, however. Please mail bug-guile@gnu.org if you see any
deficiencies with Guile's backtraces.
** syntax-rules and syntax-case macros now propagate source information
through to the expanded code
This should result in better backtraces.
** The currying behavior of `define' has been removed.
Before, `(define ((f a) b) (* a b))' would translate to
(define f (lambda (a) (lambda (b) (* a b))))
Now a syntax error is signaled, as this syntax is not supported by
default. If there is sufficient demand, this syntax can be supported
again by default.
** All modules have names now
Before, you could have anonymous modules: modules without names. Now,
because of hygiene and macros, all modules have names. If a module was
created without a name, the first time `module-name' is called on it, a
fresh name will be lazily generated for it.
** Many syntax errors have different texts now
Syntax errors still throw to the `syntax-error' key, but the arguments
are often different now. Perhaps in the future, Guile will switch to
using standard SRFI-35 conditions.
** Returning multiple values to compiled code will silently truncate the
values to the expected number
For example, the interpreter would raise an error evaluating the form,
`(+ (values 1 2) (values 3 4))', because it would see the operands as
being two compound "values" objects, to which `+' does not apply.
The compiler, on the other hand, receives multiple values on the stack,
not as a compound object. Given that it must check the number of values
anyway, if too many values are provided for a continuation, it chooses
to truncate those values, effectively evaluating `(+ 1 3)' instead.
The idea is that the semantics that the compiler implements is more
intuitive, and the use of the interpreter will fade out with time.
This behavior is allowed both by the R5RS and the R6RS.
** Multiple values in compiled code are not represented by compound
objects
This change may manifest itself in the following situation:
(let ((val (foo))) (do-something) val)
In the interpreter, if `foo' returns multiple values, multiple values
are produced from the `let' expression. In the compiler, those values
are truncated to the first value, and that first value is returned. In
the compiler, if `foo' returns no values, an error will be raised, while
the interpreter would proceed.
Both of these behaviors are allowed by R5RS and R6RS. The compiler's
behavior is more correct, however. If you wish to preserve a potentially
multiply-valued return, you will need to set up a multiple-value
continuation, using `call-with-values'.
** Defmacros are now implemented in terms of syntax-case.
The practical ramification of this is that the `defmacro?' predicate has
been removed, along with `defmacro-transformer', `macro-table',
`xformer-table', `assert-defmacro?!', `set-defmacro-transformer!' and
`defmacro:transformer'. This is because defmacros are simply macros. If
any of these procedures provided useful facilities to you, we encourage
you to contact the Guile developers.
** psyntax is now the default expander
Scheme code is now expanded by default by the psyntax hygienic macro
expander. Expansion is performed completely before compilation or
interpretation.
Notably, syntax errors will be signalled before interpretation begins.
In the past, many syntax errors were only detected at runtime if the
code in question was memoized.
As part of its expansion, psyntax renames all lexically-bound
identifiers. Original identifier names are preserved and given to the
compiler, but the interpreter will see the renamed variables, e.g.,
`x432' instead of `x'.
Note that the psyntax that Guile uses is a fork, as Guile already had
modules before incompatible modules were added to psyntax -- about 10
years ago! Thus there are surely a number of bugs that have been fixed
in psyntax since then. If you find one, please notify bug-guile@gnu.org.
** syntax-rules and syntax-case are available by default.
There is no longer any need to import the `(ice-9 syncase)' module
(which is now deprecated). The expander may be invoked directly via
`sc-expand', though it is normally searched for via the current module
transformer.
Also, the helper routines for syntax-case are available in the default
environment as well: `syntax->datum', `datum->syntax',
`bound-identifier=?', `free-identifier=?', `generate-temporaries',
`identifier?', and `syntax-violation'. See the R6RS for documentation.
** Lexical bindings introduced by hygienic macros may not be referenced
by nonhygienic macros.
If a lexical binding is introduced by a hygienic macro, it may not be
referenced by a nonhygienic macro. For example, this works:
(let ()
(define-macro (bind-x val body)
`(let ((x ,val)) ,body))
(define-macro (ref x)
x)
(bind-x 10 (ref x)))
But this does not:
(let ()
(define-syntax bind-x
(syntax-rules ()
((_ val body) (let ((x val)) body))))
(define-macro (ref x)
x)
(bind-x 10 (ref x)))
It is not normal to run into this situation with existing code. However,
as code is ported over from defmacros to syntax-case, it is possible to
run into situations like this. In the future, Guile will probably port
its `while' macro to syntax-case, which makes this issue one to know
about.
** Macros may no longer be referenced as first-class values.
In the past, you could evaluate e.g. `if', and get its macro value. Now,
expanding this form raises a syntax error.
Macros still /exist/ as first-class values, but they must be
/referenced/ via the module system, e.g. `(module-ref (current-module)
'if)'.
This decision may be revisited before the 2.0 release. Feedback welcome
to guile-devel@gnu.org (subscription required) or bug-guile@gnu.org (no
subscription required).
** Unicode characters
Unicode characters may be entered in octal format via e.g. `#\454', or
created via (integer->char 300). A hex external representation will
probably be introduced at some point.
** Unicode strings
Internally, strings are now represented either in the `latin-1'
encoding, one byte per character, or in UTF-32, with four bytes per
character. Strings manage their own allocation, switching if needed.
Currently no locale conversion is performed. Extended characters may be
written in a string using the hexadecimal escapes `\xXX', `\uXXXX', or
`\UXXXXXX', for 8-bit, 16-bit, or 24-bit codepoints, respectively.
** Global variables `scm_charnames' and `scm_charnums' are removed
These variables contained the names of control characters and were
used when writing characters. While these were global, they were
never intended to be public API. They have been replaced with private
functions.
** EBCDIC support is removed
There was an EBCDIC compile flag that altered some of the character
processing. It appeared that full EBCDIC support was never completed
and was unmaintained.
** New macro type: syncase-macro
XXX Need to decide whether to document this for 2.0, probably should:
make-syncase-macro, make-extended-syncase-macro, macro-type,
syncase-macro-type, syncase-macro-binding
** A new `memoize-symbol' evaluator trap has been added.
This trap can be used for efficiently implementing a Scheme code
coverage.
** Duplicate bindings among used modules are resolved lazily.
This slightly improves program startup times.
** New thread cancellation and thread cleanup API
See `cancel-thread', `set-thread-cleanup!', and `thread-cleanup'.
** Fix bad interaction between `false-if-exception' and stack-call.
Exceptions thrown by `false-if-exception' were erronously causing the
stack to be saved, causing later errors to show the incorrectly-saved
backtrace. This has been fixed.
** New global variables: %load-compiled-path, %load-compiled-extensions
These are analogous to %load-path and %load-extensions.
** New procedure, `make-promise'
`(make-promise (lambda () foo))' is equivalent to `(delay foo)'.
** `defined?' may accept a module as its second argument
Previously it only accepted internal structures from the evaluator.
** New entry into %guile-build-info: `ccachedir'
** Fix bug in `module-bound?'.
`module-bound?' was returning true if a module did have a local
variable, but one that was unbound, but another imported module bound
the variable. This was an error, and was fixed.
** `(ice-9 syncase)' has been deprecated.
As syntax-case is available by default, importing `(ice-9 syncase)' has
no effect, and will trigger a deprecation warning.
** Removed deprecated uniform array procedures:
dimensions->uniform-array, list->uniform-array, array-prototype
Instead, use make-typed-array, list->typed-array, or array-type,
respectively.
* Changes to the C interface
** The GH interface (deprecated in version 1.6, 2001) was removed.
@ -40,18 +577,93 @@ application code.
** Functions for handling `scm_option' now no longer require an argument
indicating length of the `scm_t_option' array.
** Primitive procedures (aka. "subrs") are now stored in double cells
This removes the subr table and simplifies the code.
** scm_primitive_load_path has additional argument, exception_on_error
** New C function: scm_module_public_interface
This procedure corresponds to Scheme's `module-public-interface'.
** `scm_stat' has an additional argument, `exception_on_error'
** `scm_primitive_load_path' has an additional argument `exception_on_not_found'
** `scm_set_port_seek' and `scm_set_port_truncate' use the `scm_t_off' type
Previously they would use the `off_t' type, which is fragile since its
definition depends on the application's value for `_FILE_OFFSET_BITS'.
** The `long_long' C type, deprecated in 1.8, has been removed
** Removed deprecated uniform array procedures: scm_make_uve,
scm_array_prototype, scm_list_to_uniform_array,
scm_dimensions_to_uniform_array, scm_make_ra, scm_shap2ra, scm_cvref,
scm_ra_set_contp, scm_aind, scm_raprin1
These functions have been deprecated since early 2005.
** scm_array_p has one argument, not two
Use of the second argument produced a deprecation warning, so it is
unlikely that any code out there actually used this functionality.
* Changes to the distribution
** Guile's license is now LGPLv3+
In other words the GNU Lesser General Public License, version 3 or
later (at the discretion of each person that chooses to redistribute
part of Guile).
** `guile-config' will be deprecated in favor of `pkg-config'
`guile-config' has been rewritten to get its information from
`pkg-config', so this should be a transparent change. Note however that
guile.m4 has yet to be modified to call pkg-config instead of
guile-config.
** Guile now provides `guile-2.0.pc' instead of `guile-1.8.pc'
Programs that use `pkg-config' to find Guile or one of its Autoconf
macros should now require `guile-2.0' instead of `guile-1.8'.
** New installation directory: $(pkglibdir)/1.9/ccache
If $(libdir) is /usr/lib, for example, Guile will install its .go files
to /usr/lib/guile/1.9/ccache. These files are architecture-specific.
** New dependency: GNU libunistring.
See http://www.gnu.org/software/libunistring/, for more information. Our
unicode support uses routines from libunistring.
Changes in 1.8.8 (since 1.8.7)
* Bugs fixed
** Fix possible buffer overruns when parsing numbers
** Avoid clash with system setjmp/longjmp on IA64
Changes in 1.8.7 (since 1.8.6)
* New modules (see the manual for details)
** `(srfi srfi-98)', an interface to access environment variables
* Bugs fixed
** Fix compilation with `--disable-deprecated'
** Fix %fast-slot-ref/set!, to avoid possible segmentation fault
** Fix MinGW build problem caused by HAVE_STRUCT_TIMESPEC confusion
** Fix build problem when scm_t_timespec is different from struct timespec
** Fix build when compiled with -Wundef -Werror
** More build fixes for `alphaev56-dec-osf5.1b' (Tru64)
** Build fixes for `powerpc-ibm-aix5.3.0.0' (AIX 5.3)
** With GCC, always compile with `-mieee' on `alpha*' and `sh*'
** Better diagnose broken `(strftime "%z" ...)' in `time.test' (bug #24130)
** Fix parsing of SRFI-88/postfix keywords longer than 128 characters
** Fix reading of complex numbers where both parts are inexact decimals
** Allow @ macro to work with (ice-9 syncase)
@ -60,6 +672,8 @@ transformed by (ice-9 syncase) would cause an "Invalid syntax" error.
Now it works as you would expect (giving the value of the specified
module binding).
** Have `scm_take_locale_symbol ()' return an interned symbol (bug #25865)
Changes in 1.8.6 (since 1.8.5)
@ -178,13 +792,6 @@ lead to a stack overflow.
** Fixed shadowing of libc's <random.h> on Tru64, which broke compilation
** Make sure all tests honor `$TMPDIR'
* Changes to the distribution
** New FAQ
We've started collecting Frequently Asked Questions (FAQ), and will
distribute these (with answers!) in future Guile releases.
Changes in 1.8.4 (since 1.8.3)

57
NEWS.guile-vm Normal file
View file

@ -0,0 +1,57 @@
Guile-VM NEWS
Guile-VM is a bytecode compiler and virtual machine for Guile.
guile-vm 0.7 -- 2008-05-20
==========================
* Initial release with NEWS.
* Revived from Keisuke Nishida's Guile-VM project from 2000-2001, with
the help of Ludovic Courtès.
* Meta-level changes
** Updated to compile with Guile 1.8.
** Documentation updated, including documentation on the instructions.
** Added benchmarking and a test harness.
* Changes to the inventory
** Renamed the library from libguilevm to libguile-vm.
** Added new executable script, guile-disasm.
* New features
** Add support for compiling macros, both defmacros and syncase macros.
Primitive macros produced with the procedure->macro family of procedures
are not supported, however.
** Improvements to the REPL
Multiple values support, readline integration, ice-9 history integration
** Add support for eval-case
The compiler recognizes compile-toplevel in addition to load-toplevel
** Completely self-compiling
Almost, anyway: not (system repl describe), because it uses GOOPS
* Internal cleanups
** Internal objects are now based on Guile records.
** Guile-VM's code doesn't use the dot-syntax any more.
** Changed (ice-9 match) for Kiselyov's pmatch.scm
** New instructions: define, link-later, link-now, late-variable-{ref,set}
** Object code now represented as u8vectors instead of strings.
** Remove local import of an old version of slib
* Bugfixes
** The `optimize' procedure is coming out of bitrot
** The Scheme compiler is now more strict about placement of internal
defines
** set! is now compiled differently from define
** Module-level variables are now bound at first use instead of in the
program prolog
** Bugfix to load-program (stack misinterpretation)
Copyright (C) 2008 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice
and this notice are preserved.

82
README
View file

@ -14,7 +14,7 @@ Guile versions with an odd middle number, i.e. 1.9.* are unstable
development versions. Even middle numbers indicate stable versions.
This has been the case since the 1.3.* series.
The next stable release will likely be version 1.10.0.
The next stable release will likely be version 2.0.0.
Please send bug reports to bug-guile@gnu.org.
@ -27,24 +27,38 @@ Generic instructions for configuring and compiling Guile can be found
in the INSTALL file. Guile specific information and configure options
can be found below, including instructions for installing SLIB.
Guile requires a few external packages and can optionally use a number
of external packages such as `readline' when they are available.
Guile expects to be able to find these packages in the default
compiler setup, it does not try to make any special arrangements
itself. For example, for the `readline' package, Guile expects to be
able to find the include file <readline/readline.h>, without passing
any special `-I' options to the compiler.
Guile depends on the following external libraries.
- libgmp
- libiconv
- libintl
- libltdl
- libunistring
It will also use the libreadline library if it is available. For each
of these there is a corresponding --with-XXX-prefix option that you
can use when invoking ./configure, if you have these libraries
installed in a location other than the standard places (/usr and
/usr/local).
If you installed an external package, and you used the --prefix
installation option to install it somewhere else than /usr/local, you
must arrange for your compiler to find it by default. If that
compiler is gcc, one convenient way of making such arrangements is to
use the --with-local-prefix option during installation, naming the
same directory as you used in the --prefix option of the package. In
particular, it is not good enough to use the same --prefix option when
you install gcc and the package; you need to use the
--with-local-prefix option as well. See the gcc documentation for
more details.
These options are provided by the Gnulib `havelib' module, and details
of how they work are documented in `Searching for Libraries' in the
Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent
to which they work on a given OS depends on whether that OS supports
encoding full library path names in executables (aka `rpath'). Also
note that using these options, and hence hardcoding full library path
names (where that is supported), makes it impossible to later move the
built executables and libraries to an installation location other than
the one that was specified at build time.
Another possible approach is to set CPPFLAGS and LDFLAGS before
running configure, so that they include -I options for all the
non-standard places where you have installed header files and -L
options for all the non-standard places where you have installed
libraries. This will allow configure and make to find those headers
and libraries during the build. The locations found will not be
hardcoded into the build executables and libraries, so with this
approach you will probably also need to set LD_LIBRARY_PATH
correspondingly, to allow Guile to find the necessary libraries again
at runtime.
Required External Packages ================================================
@ -61,6 +75,12 @@ Guile requires the following external packages:
libltdl is used for loading extensions at run-time. It is
available from http://www.gnu.org/software/libtool/
- GNU libunistring
libunistring is used for Unicode string operations, such as the
`utf*->string' procedures. It is available from
http://www.gnu.org/software/libunistring/ .
Special Instructions For Some Systems =====================================
@ -223,9 +243,23 @@ GUILE_FOR_BUILD variable, it defaults to just "guile".
Using Guile Without Installing It =========================================
The top directory of the Guile sources contains a script called
"pre-inst-guile" that can be used to run the Guile that has just been
built.
The "meta/" subdirectory of the Guile sources contains a script called
"guile" that can be used to run the Guile that has just been built. Note
that this is not the same "guile" as the one that is installed; this
"guile" is a wrapper script that sets up the environment appropriately,
then invokes the Guile binary.
You may also build external packages against an uninstalled Guile build
tree. The "uninstalled-env" script in the "meta/" subdirectory will set
up an environment with a path including "meta/", a modified dynamic
linker path, a modified PKG_CONFIG_PATH, etc.
For example, you can enter this environment via invoking
meta/uninstalled-env bash
Within that shell, other packages should be able to build against
uninstalled Guile.
Installing SLIB ===========================================================
@ -265,9 +299,8 @@ Guile Documentation ==================================================
If you've never used Scheme before, then the Guile Tutorial
(guile-tut.info) is a good starting point. The Guile Reference Manual
(guile.info) is the primary documentation for Guile. The Goops object
system is documented separately (goops.info). A copy of the R5RS
Scheme specification is included too (r5rs.info).
(guile.info) is the primary documentation for Guile. A copy of the
R5RS Scheme specification is included too (r5rs.info).
Info format versions of this documentation are installed as part of
the normal build process. The texinfo sources are under the doc
@ -289,6 +322,7 @@ About This Distribution ==============================================
Interesting files include:
- LICENSE, which contains the exact terms of the Guile license.
- COPYING.LESSER, which contains the terms of the GNU Lesser General Public License.
- COPYING, which contains the terms of the GNU General Public License.
- INSTALL, which contains general instructions for building/installing Guile.
- NEWS, which describes user-visible changes since the last release of Guile.

117
README.guile-vm Normal file
View file

@ -0,0 +1,117 @@
This is an attempt to revive the Guile-VM project by Keisuke Nishida
written back in the years 2000 and 2001. Below are a few pointers to
relevant threads on Guile's development mailing list.
Enjoy!
Ludovic Courtès <ludovic.courtes@laas.fr>, Apr. 2005.
Pointers
--------
Status of the last release, 0.5
http://lists.gnu.org/archive/html/guile-devel/2001-04/msg00266.html
The very first release, 0.0
http://sources.redhat.com/ml/guile/2000-07/msg00418.html
Simple benchmark
http://sources.redhat.com/ml/guile/2000-07/msg00425.html
Performance, portability, GNU Lightning
http://lists.gnu.org/archive/html/guile-devel/2001-03/msg00132.html
Playing with GNU Lightning
http://lists.gnu.org/archive/html/guile-devel/2001-03/msg00185.html
On things left to be done
http://lists.gnu.org/archive/html/guile-devel/2001-03/msg00146.html
---8<--- Original README below. -----------------------------------------
Installation
------------
1. Install the latest Guile from CVS.
2. Install Guile VM:
% configure
% make install
% ln -s module/{guile,system,language} /usr/local/share/guile/
3. Add the following lines to your ~/.guile:
(use-modules (system vm core)
(cond ((string=? (car (command-line)) "guile-vm")
(use-modules (system repl repl))
(start-repl 'scheme)
(quit)))
Example Session
---------------
% guile-vm
Guile Scheme interpreter 0.5 on Guile 1.4.1
Copyright (C) 2001 Free Software Foundation, Inc.
Enter `,help' for help.
scheme@guile-user> (+ 1 2)
3
scheme@guile-user> ,c -c (+ 1 2) ;; Compile into GLIL
(@asm (0 1 0 0)
(module-ref #f +)
(const 1)
(const 2)
(tail-call 2))
scheme@guile-user> ,c (+ 1 2) ;; Compile into object code
Disassembly of #<objcode 403c5fb0>:
nlocs = 0 nexts = 0
0 link "+" ;; (+ . ???)
3 variable-ref
4 make-int8:1 ;; 1
5 make-int8 2 ;; 2
7 tail-call 2
scheme@guile-user> (define (add x y) (+ x y))
scheme@guile-user> (add 1 2)
3
scheme@guile-user> ,x add ;; Disassemble
Disassembly of #<program add>:
nargs = 2 nrest = 0 nlocs = 0 nexts = 0
Bytecode:
0 object-ref 0 ;; (+ . #<primitive-procedure +>)
2 variable-ref
3 local-ref 0
5 local-ref 1
7 tail-call 2
Objects:
0 (+ . #<primitive-procedure +>)
scheme@guile-user>
Compile Modules
---------------
Use `guilec' to compile your modules:
% cat fib.scm
(define-module (fib) :export (fib))
(define (fib n) (if (< n 2) 1 (+ (fib (- n 1)) (fib (- n 2)))))
% guilec fib.scm
Wrote fib.go
% guile
guile> (use-modules (fib))
guile> (fib 8)
34

13
THANKS
View file

@ -3,6 +3,7 @@ Contributors since the last release:
Rob Browning
Ludovic Courtès
Julian Graham
Mike Gran
Stefan Jahn
Neil Jerram
Gregory Marton
@ -13,6 +14,7 @@ Contributors since the last release:
Kevin Ryde
Bill Schottstaedt
Richard Todd
Andy Wingo
Sponsors since the last release:
@ -23,10 +25,12 @@ For fixes or providing information which led to a fix:
David Allouche
Martin Baulig
Fabrice Bauzac
Sylvain Beucler
Carlo Bramini
Rob Browning
Adrian Bunk
Michael Carmack
R Clayton
Stephen Compall
Brian Crowder
Christopher Cramer
@ -37,6 +41,7 @@ For fixes or providing information which led to a fix:
John W Eaton
Clinton Ebadi
David Fang
Barry Fishman
Charles Gagnon
Peter Gavin
Eric Gillespie, Jr
@ -48,6 +53,7 @@ For fixes or providing information which led to a fix:
Roland Haeder
Sven Hartrumpf
Eric Hanchrow
Judy Hawkins
Sam Hocevar
Patrick Horgan
Ales Hvezda
@ -61,10 +67,12 @@ For fixes or providing information which led to a fix:
René Köcher
Matthias Köppe
Matt Kraai
Daniel Kraft
Miroslav Lichvar
Jeff Long
Marco Maggi
Gregory Marton
Kjetil S. Matheussen
Antoine Mathys
Dan McMahill
Roger Mc Murtrie
@ -82,15 +90,18 @@ For fixes or providing information which led to a fix:
David Pirotte
Carlos Pita
Ken Raeburn
Juhani Rantanen
Andreas Rottmann
Hugh Sasse
Werner Scheinast
Bill Schottstaedt
Frank Schwidom
John Steele Scott
Thiemo Seufer
Scott Shedden
Alex Shinn
Daniel Skarda
Dale Smith
Cesar Strauss
Rainer Tammer
Richard Todd
@ -106,6 +117,8 @@ For fixes or providing information which led to a fix:
Andreas Vögele
Michael Talbot-Wilson
Michael Tuexen
Thomas Wawrzinek
Mark H. Weaver
Jon Wilson
Andy Wingo
Keith Wright

1
THANKS.guile-vm Normal file
View file

@ -0,0 +1 @@
Guile VM was inspired by QScheme, librep, and Objective Caml.

68
acinclude.m4
View file

@ -311,7 +311,6 @@ fi
AC_LANG_RESTORE
])dnl ACX_PTHREAD
dnl Check whether GNU ld's read-only relocations (the `PT_GNU_RELRO'
dnl ELF segment header) are supported. This allows things like
dnl statically allocated cells (1) to eventually be remapped read-only
@ -327,3 +326,70 @@ AC_DEFUN([GUILE_GNU_LD_RELRO], [
[AC_MSG_RESULT([no])
LDFLAGS="$save_LDFLAGS"])
])
dnl GUILE_READLINE
dnl
dnl Check all the things needed by `guile-readline', the Readline
dnl bindings.
AC_DEFUN([GUILE_READLINE], [
for termlib in ncurses curses termcap terminfo termlib ; do
AC_CHECK_LIB(${termlib}, [tgoto],
[READLINE_LIBS="-l${termlib} $READLINE_LIBS"; break])
done
AC_LIB_LINKFLAGS([readline])
if test "x$LTLIBREADLINE" = "x"; then
AC_MSG_WARN([GNU Readline was not found on your system.])
else
rl_save_LIBS="$LIBS"
LIBS="$LIBREADLINE $READLINE_LIBS $LIBS"
AC_CHECK_FUNCS([siginterrupt rl_clear_signals rl_cleanup_after_signal])
dnl Check for modern readline naming
AC_CHECK_FUNCS([rl_filename_completion_function])
dnl Check for rl_get_keymap. We only use this for deciding whether to
dnl install paren matching on the Guile command line (when using
dnl readline for input), so it's completely optional.
AC_CHECK_FUNCS([rl_get_keymap])
AC_CACHE_CHECK([for rl_getc_function pointer in readline],
ac_cv_var_rl_getc_function,
[AC_TRY_LINK([
#include <stdio.h>
#include <readline/readline.h>],
[printf ("%ld", (long) rl_getc_function)],
[ac_cv_var_rl_getc_function=yes],
[ac_cv_var_rl_getc_function=no])])
if test "${ac_cv_var_rl_getc_function}" = "yes"; then
AC_DEFINE([HAVE_RL_GETC_FUNCTION], 1,
[Define if your readline library has the rl_getc_function variable.])
fi
if test $ac_cv_var_rl_getc_function = no; then
AC_MSG_WARN([*** GNU Readline is too old on your system.])
AC_MSG_WARN([*** You need readline version 2.1 or later.])
LTLIBREADLINE=""
LIBREADLINE=""
fi
LIBS="$rl_save_LIBS"
READLINE_LIBS="$LTLIBREADLINE $READLINE_LIBS"
fi
AM_CONDITIONAL([HAVE_READLINE], [test "x$LTLIBREADLINE" != "x"])
AC_CHECK_FUNCS([strdup])
AC_SUBST([READLINE_LIBS])
. $srcdir/guile-readline/LIBGUILEREADLINE-VERSION
AC_SUBST(LIBGUILEREADLINE_MAJOR)
AC_SUBST(LIBGUILEREADLINE_INTERFACE_CURRENT)
AC_SUBST(LIBGUILEREADLINE_INTERFACE_REVISION)
AC_SUBST(LIBGUILEREADLINE_INTERFACE_AGE)
AC_SUBST(LIBGUILEREADLINE_INTERFACE)
])

18
am/Makefile.am
View file

@ -4,24 +4,24 @@
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu
am_frags = pre-inst-guile maintainer-dirs
am_frags = pre-inst-guile maintainer-dirs guilec
EXTRA_DIST = $(am_frags) ChangeLog-2008

33
am/guilec Normal file
View file

@ -0,0 +1,33 @@
# -*- makefile -*-
GOBJECTS = $(SOURCES:%.scm=%.go)
moddir = $(pkgdatadir)/$(GUILE_EFFECTIVE_VERSION)/$(modpath)
nobase_mod_DATA = $(SOURCES) $(NOCOMP_SOURCES)
ccachedir = $(pkglibdir)/$(GUILE_EFFECTIVE_VERSION)/ccache/$(modpath)
nobase_ccache_DATA = $(GOBJECTS)
EXTRA_DIST = $(SOURCES) $(NOCOMP_SOURCES)
CLEANFILES = $(GOBJECTS)
# Well, shit. We can't have install changing timestamps, can we? But
# install_sh doesn't know how to preserve timestamps. Soooo, fondle
# automake to make things happen.
install-data-hook:
@$(am__vpath_adj_setup) \
list='$(nobase_mod_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
$(am__vpath_adj) \
echo " touch -r '$$d$$p' '$(DESTDIR)$(moddir)/$$f'"; \
touch -r "$$d$$p" "$(DESTDIR)$(moddir)/$$f"; \
done
@$(am__vpath_adj_setup) \
list='$(nobase_ccache_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
$(am__vpath_adj) \
echo " touch -r '$$d$$p' '$(DESTDIR)$(ccachedir)/$$f'"; \
touch -r "$$d$$p" "$(DESTDIR)$(ccachedir)/$$f"; \
done
SUFFIXES = .scm .go
.scm.go:
GUILE_AUTO_COMPILE=0 $(top_builddir)/meta/uninstalled-env guile-tools compile -o "$@" "$<"

10
am/maintainer-dirs
View file

@ -5,17 +5,17 @@
## This file is part of GUILE.
##
## GUILE 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
## it under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA

12
am/pre-inst-guile
View file

@ -5,17 +5,17 @@
## This file is part of GUILE.
##
## GUILE 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
## it under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
@ -28,7 +28,7 @@
## Code:
preinstguile = $(top_builddir_absolute)/pre-inst-guile
preinstguile = $(top_builddir_absolute)/meta/guile
preinstguiletool = GUILE="$(preinstguile)" $(top_srcdir)/scripts
## am/pre-inst-guile ends here

4
benchmark-guile.in
View file

@ -1,6 +1,6 @@
#! /bin/sh
# Usage: benchmark-guile [-i GUILE-INTERPRETER] [GUILE-BENCHMARK-ARGS]
# If `-i GUILE-INTERPRETER' is omitted, use ${top_builddir}/pre-inst-guile.
# If `-i GUILE-INTERPRETER' is omitted, use ${top_builddir}/meta/guile.
# See ${top_srcdir}/benchmark-suite/guile-benchmark for documentation on GUILE-BENCHMARK-ARGS.
#
# Example invocations:
@ -21,7 +21,7 @@ if [ x"$1" = x-i ] ; then
shift
shift
else
guile=${top_builddir}/pre-inst-guile
guile=${top_builddir}/meta/guile
fi
GUILE_LOAD_PATH=$BENCHMARK_SUITE_DIR

1
benchmark-suite/Makefile.am
View file

@ -1,4 +1,5 @@
SCM_BENCHMARKS = benchmarks/0-reference.bm \
benchmarks/bytevectors.bm \
benchmarks/continuations.bm \
benchmarks/if.bm \
benchmarks/logand.bm \

100
benchmark-suite/benchmarks/bytevectors.bm Normal file
View file

@ -0,0 +1,100 @@
;;; -*- mode: scheme; coding: latin-1; -*-
;;; R6RS Byte Vectors.
;;;
;;; Copyright 2009 Ludovic Courtès <ludo@gnu.org>
;;;
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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 Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks bytevector)
:use-module (rnrs bytevector)
:use-module (srfi srfi-4)
:use-module (benchmark-suite lib))
(define bv (make-bytevector 16384))
(define %native-endianness
(native-endianness))
(define %foreign-endianness
(if (eq? (native-endianness) (endianness little))
(endianness big)
(endianness little)))
(define u8v (make-u8vector 16384))
(define u16v (make-u16vector 8192))
(define u32v (make-u32vector 4196))
(define u64v (make-u64vector 2048))
(with-benchmark-prefix "ref/set!"
(benchmark "bytevector-u8-ref" 1000000
(bytevector-u8-ref bv 0))
(benchmark "bytevector-u16-ref (foreign)" 1000000
(bytevector-u16-ref bv 0 %foreign-endianness))
(benchmark "bytevector-u16-ref (native)" 1000000
(bytevector-u16-ref bv 0 %native-endianness))
(benchmark "bytevector-u16-native-ref" 1000000
(bytevector-u16-native-ref bv 0))
(benchmark "bytevector-u32-ref (foreign)" 1000000
(bytevector-u32-ref bv 0 %foreign-endianness))
(benchmark "bytevector-u32-ref (native)" 1000000
(bytevector-u32-ref bv 0 %native-endianness))
(benchmark "bytevector-u32-native-ref" 1000000
(bytevector-u32-native-ref bv 0))
(benchmark "bytevector-u64-ref (foreign)" 1000000
(bytevector-u64-ref bv 0 %foreign-endianness))
(benchmark "bytevector-u64-ref (native)" 1000000
(bytevector-u64-ref bv 0 %native-endianness))
(benchmark "bytevector-u64-native-ref" 1000000
(bytevector-u16-native-ref bv 0)))
(with-benchmark-prefix "lists"
(benchmark "bytevector->u8-list" 2000
(bytevector->u8-list bv))
(benchmark "bytevector->uint-list 16-bit" 2000
(bytevector->uint-list bv (native-endianness) 2))
(benchmark "bytevector->uint-list 64-bit" 2000
(bytevector->uint-list bv (native-endianness) 8)))
(with-benchmark-prefix "SRFI-4" ;; for comparison
(benchmark "u8vector-ref" 1000000
(u8vector-ref u8v 0))
(benchmark "u16vector-ref" 1000000
(u16vector-ref u16v 0))
(benchmark "u32vector-ref" 1000000
(u32vector-ref u32v 0))
(benchmark "u64vector-ref" 1000000
(u64vector-ref u64v 0)))

57
benchmark-suite/benchmarks/chars.bm Normal file
View file

@ -0,0 +1,57 @@
;;; -*- mode: scheme; coding: latin-1; -*-
;;; chars.bm
;;;
;;; Copyright (C) 2009 Free Software Foundation, Inc.
;;;
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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 Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks chars)
:use-module (benchmark-suite lib))
(with-benchmark-prefix "chars"
(benchmark "char" 1000000
#\a)
(benchmark "octal" 1000000
#\123)
(benchmark "char? eq" 1000000
(char? #\a))
(benchmark "char=?" 1000000
(char=? #\a #\a))
(benchmark "char<?" 1000000
(char=? #\a #\a))
(benchmark "char-ci=?" 1000000
(char=? #\a #\a))
(benchmark "char-ci<? " 1000000
(char=? #\a #\a))
(benchmark "char->integer" 1000000
(char->integer #\a))
(benchmark "char-alphabetic?" 1000000
(char-upcase #\a))
(benchmark "char-numeric?" 1000000
(char-upcase #\a)))

18
benchmark-suite/benchmarks/read.bm
View file

@ -2,20 +2,20 @@
;;;
;;; Copyright (C) 2008 Free Software Foundation, Inc.
;;;
;;; 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 free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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.
;;; GNU Lesser 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., 51 Franklin Street, Fifth Floor,
;;; Boston, MA 02110-1301 USA
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks read)
:use-module (benchmark-suite lib))

310
benchmark-suite/benchmarks/srfi-13.bm Normal file
View file

@ -0,0 +1,310 @@
;;; -*- mode: scheme; coding: latin-1; -*-
;;; srfi-13.bm
;;;
;;; Copyright (C) 2009 Free Software Foundation, Inc.
;;;
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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 Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks strings)
:use-module (benchmark-suite lib))
(seed->random-state 1)
(define short-string "Hi")
(define medium-string
"ARMA virumque cano, Troiae qui primus ab oris
Italiam, fato profugus, Laviniaque venit")
(define long-string
(string-tabulate
(lambda (n) (integer->char (+ 32 (random 90))))
1000))
(define short-chlist (string->list short-string))
(define medium-chlist (string->list medium-string))
(define long-chlist (string->list long-string))
(define str1 (string-copy short-string))
(define str2 (string-copy medium-string))
(define str3 (string-copy long-string))
(with-benchmark-prefix "strings"
(with-benchmark-prefix "predicates"
(benchmark "string?" 1190000
(string? short-string)
(string? medium-string)
(string? long-string))
(benchmark "null?" 969000
(string-null? short-string)
(string-null? medium-string)
(string-null? long-string))
(benchmark "any" 94000
(string-any #\a short-string)
(string-any #\a medium-string)
(string-any #\a long-string))
(benchmark "every" 94000
(string-every #\a short-string)
(string-every #\a medium-string)
(string-every #\a long-string)))
(with-benchmark-prefix "constructors"
(benchmark "string" 5000
(apply string short-chlist)
(apply string medium-chlist)
(apply string long-chlist))
(benchmark "list->" 4500
(list->string short-chlist)
(list->string medium-chlist)
(list->string long-chlist))
(benchmark "reverse-list->" 5000
(reverse-list->string short-chlist)
(reverse-list->string medium-chlist)
(reverse-list->string long-chlist))
(benchmark "make" 22000
(make-string 250 #\x))
(benchmark "tabulate" 17000
(string-tabulate integer->char 250))
(benchmark "join" 5500
(string-join (list short-string medium-string long-string) "|" 'suffix)))
(with-benchmark-prefix "list/string"
(benchmark "->list" 7300
(string->list short-string)
(string->list medium-string)
(string->list long-string))
(benchmark "split" 60000
(string-split short-string #\a)
(string-split medium-string #\a)
(string-split long-string #\a)))
(with-benchmark-prefix "selection"
(benchmark "ref" 660
(let loop ((k 0))
(if (< k (string-length short-string))
(begin
(string-ref short-string k)
(loop (+ k 1)))))
(let loop ((k 0))
(if (< k (string-length medium-string))
(begin
(string-ref medium-string k)
(loop (+ k 1)))))
(let loop ((k 0))
(if (< k (string-length long-string))
(begin
(string-ref long-string k)
(loop (+ k 1))))))
(benchmark "copy" 1100
(string-copy short-string)
(string-copy medium-string)
(string-copy long-string)
(substring/copy short-string 0 1)
(substring/copy medium-string 10 20)
(substring/copy long-string 100 200))
(benchmark "pad" 6800
(string-pad short-string 100)
(string-pad medium-string 100)
(string-pad long-string 100))
(benchmark "trim trim-right trim-both" 60000
(string-trim short-string char-alphabetic?)
(string-trim medium-string char-alphabetic?)
(string-trim long-string char-alphabetic?)
(string-trim-right short-string char-alphabetic?)
(string-trim-right medium-string char-alphabetic?)
(string-trim-right long-string char-alphabetic?)
(string-trim-both short-string char-alphabetic?)
(string-trim-both medium-string char-alphabetic?)
(string-trim-both long-string char-alphabetic?)))
(with-benchmark-prefix "modification"
(set! str1 (string-copy short-string))
(set! str2 (string-copy medium-string))
(set! str3 (string-copy long-string))
(benchmark "set!" 3000
(let loop ((k 1))
(if (< k (string-length short-string))
(begin
(string-set! str1 k #\x)
(loop (+ k 1)))))
(let loop ((k 20))
(if (< k (string-length medium-string))
(begin
(string-set! str2 k #\x)
(loop (+ k 1)))))
(let loop ((k 900))
(if (< k (string-length long-string))
(begin
(string-set! str3 k #\x)
(loop (+ k 1))))))
(set! str1 (string-copy short-string))
(set! str2 (string-copy medium-string))
(set! str3 (string-copy long-string))
(benchmark "sub-move!" 230000
(substring-move! short-string 0 2 str2 10)
(substring-move! medium-string 10 20 str3 20))
(set! str1 (string-copy short-string))
(set! str2 (string-copy medium-string))
(set! str3 (string-copy long-string))
(benchmark "fill!" 230000
(string-fill! str1 #\y 0 1)
(string-fill! str2 #\y 10 20)
(string-fill! str3 #\y 20 30))
(with-benchmark-prefix "comparison"
(benchmark "compare compare-ci" 140000
(string-compare short-string medium-string string<? string=? string>?)
(string-compare long-string medium-string string<? string=? string>?)
(string-compare-ci short-string medium-string string<? string=? string>?)
(string-compare-ci long-string medium-string string<? string=? string>?))
(benchmark "hash hash-ci" 1000
(string-hash short-string)
(string-hash medium-string)
(string-hash long-string)
(string-hash-ci short-string)
(string-hash-ci medium-string)
(string-hash-ci long-string))))
(with-benchmark-prefix "searching" 20000
(benchmark "prefix-length suffix-length" 270
(string-prefix-length short-string
(string-append short-string medium-string))
(string-prefix-length long-string
(string-append long-string medium-string))
(string-suffix-length short-string
(string-append medium-string short-string))
(string-suffix-length long-string
(string-append medium-string long-string))
(string-prefix-length-ci short-string
(string-append short-string medium-string))
(string-prefix-length-ci long-string
(string-append long-string medium-string))
(string-suffix-length-ci short-string
(string-append medium-string short-string))
(string-suffix-length-ci long-string
(string-append medium-string long-string)))
(benchmark "prefix? suffix?" 270
(string-prefix? short-string
(string-append short-string medium-string))
(string-prefix? long-string
(string-append long-string medium-string))
(string-suffix? short-string
(string-append medium-string short-string))
(string-suffix? long-string
(string-append medium-string long-string))
(string-prefix-ci? short-string
(string-append short-string medium-string))
(string-prefix-ci? long-string
(string-append long-string medium-string))
(string-suffix-ci? short-string
(string-append medium-string short-string))
(string-suffix-ci? long-string
(string-append medium-string long-string)))
(benchmark "index index-right rindex" 100000
(string-index short-string #\T)
(string-index medium-string #\T)
(string-index long-string #\T)
(string-index-right short-string #\T)
(string-index-right medium-string #\T)
(string-index-right long-string #\T)
(string-rindex short-string #\T)
(string-rindex medium-string #\T)
(string-rindex long-string #\T))
(benchmark "skip skip-right?" 100000
(string-skip short-string char-alphabetic?)
(string-skip medium-string char-alphabetic?)
(string-skip long-string char-alphabetic?)
(string-skip-right short-string char-alphabetic?)
(string-skip-right medium-string char-alphabetic?)
(string-skip-right long-string char-alphabetic?))
(benchmark "count" 10000
(string-count short-string char-alphabetic?)
(string-count medium-string char-alphabetic?)
(string-count long-string char-alphabetic?))
(benchmark "contains contains-ci" 34000
(string-contains short-string short-string)
(string-contains medium-string (substring medium-string 10 15))
(string-contains long-string (substring long-string 100 130))
(string-contains-ci short-string short-string)
(string-contains-ci medium-string (substring medium-string 10 15))
(string-contains-ci long-string (substring long-string 100 130)))
(set! str1 (string-copy short-string))
(set! str2 (string-copy medium-string))
(set! str3 (string-copy long-string))
(benchmark "upcase downcase upcase! downcase!" 600
(string-upcase short-string)
(string-upcase medium-string)
(string-upcase long-string)
(string-downcase short-string)
(string-downcase medium-string)
(string-downcase long-string)
(string-upcase! str1 0 1)
(string-upcase! str2 10 20)
(string-upcase! str3 100 130)
(string-downcase! str1 0 1)
(string-downcase! str2 10 20)
(string-downcase! str3 100 130)))
(with-benchmark-prefix "readers"
(benchmark "read token, method 1" 1200
(let ((buf (make-string 512)))
(let loop ((i 0))
(if (< i 512)
(begin
(string-set! buf i #\x)
(loop (+ i 1)))
buf))))
(benchmark "read token, method 2" 1200
(let ((lst '()))
(let loop ((i 0))
(set! lst (append! lst (list #\x)))
(if (< i 512)
(loop (+ i 1))
(list->string lst)))))))

18
benchmark-suite/benchmarks/subr.bm
View file

@ -2,20 +2,20 @@
;;;
;;; Copyright (C) 2009 Free Software Foundation, Inc.
;;;
;;; 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 free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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.
;;; GNU Lesser 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., 51 Franklin Street, Fifth Floor,
;;; Boston, MA 02110-1301 USA
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks subrs)
:use-module (benchmark-suite lib))

18
benchmark-suite/benchmarks/uniform-vector-read.bm
View file

@ -2,20 +2,20 @@
;;;
;;; Copyright (C) 2008 Free Software Foundation, Inc.
;;;
;;; 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 free software; you can redistribute it and/or
;;; modify it under the terms of the GNU Lesser General Public License
;;; as published by the Free Software Foundation; either version 3, 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.
;;; GNU Lesser 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., 51 Franklin Street, Fifth Floor,
;;; Boston, MA 02110-1301 USA
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this software; see the file COPYING.LESSER. If
;;; not, write to the Free Software Foundation, Inc., 51 Franklin
;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmarks uniform-vector-read)
:use-module (benchmark-suite lib)

18
benchmark-suite/guile-benchmark
View file

@ -7,20 +7,20 @@
;;;;
;;;; Copyright (C) 2002, 2006 Free Software Foundation, Inc.
;;;;
;;;; 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 free software; you can redistribute it and/or
;;;; modify it under the terms of the GNU Lesser General Public
;;;; License as published by the Free Software Foundation; either
;;;; version 3, 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.
;;;; GNU Lesser 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., 51 Franklin Street, Fifth Floor,
;;;; Boston, MA 02110-1301 USA
;;;; You should have received a copy of the GNU Lesser General Public
;;;; License along with this software; see the file COPYING.LESSER.
;;;; If not, write to the Free Software Foundation, Inc., 51 Franklin
;;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
;;;; Usage: [guile -e main -s] guile-benchmark [OPTIONS] [BENCHMARK ...]

18
benchmark-suite/lib.scm
View file

@ -1,20 +1,20 @@
;;;; benchmark-suite/lib.scm --- generic support for benchmarking
;;;; Copyright (C) 2002, 2006 Free Software Foundation, Inc.
;;;;
;;;; 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 free software; you can redistribute it and/or
;;;; modify it under the terms of the GNU Lesser General Public
;;;; License as published by the Free Software Foundation; either
;;;; version 3, 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.
;;;; GNU Lesser 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., 51 Franklin Street, Fifth Floor,
;;;; Boston, MA 02110-1301 USA
;;;; You should have received a copy of the GNU Lesser General Public
;;;; License along with this software; see the file COPYING.LESSER.
;;;; If not, write to the Free Software Foundation, Inc., 51 Franklin
;;;; Street, Fifth Floor, Boston, MA 02110-1301 USA
(define-module (benchmark-suite lib)
:export (

111
benchmark/lib.scm Normal file
View file

@ -0,0 +1,111 @@
;; -*- Scheme -*-
;;
;; A library of dumb functions that may be used to benchmark Guile-VM.
;; The comments are from Ludovic, a while ago. The speedups now are much
;; more significant (all over 2x, sometimes 8x).
(define (fibo x)
(if (or (= x 1) (= x 2))
1
(+ (fibo (- x 1))
(fibo (- x 2)))))
(define (g-c-d x y)
(if (= x y)
x
(if (< x y)
(g-c-d x (- y x))
(g-c-d (- x y) y))))
(define (loop n)
;; This one shows that procedure calls are no faster than within the
;; interpreter: the VM yields no performance improvement.
(if (= 0 n)
0
(loop (1- n))))
;; Disassembly of `loop'
;;
;; Disassembly of #<objcode b79bdf28>:
;; nlocs = 0 nexts = 0
;; 0 (make-int8 64) ;; 64
;; 2 (load-symbol "guile-user") ;; guile-user
;; 14 (list 0 1) ;; 1 element
;; 17 (load-symbol "loop") ;; loop
;; 23 (link-later)
;; 24 (vector 0 1) ;; 1 element
;; 27 (make-int8 0) ;; 0
;; 29 (load-symbol "n") ;; n
;; 32 (make-false) ;; #f
;; 33 (make-int8 0) ;; 0
;; 35 (list 0 3) ;; 3 elements
;; 38 (list 0 2) ;; 2 elements
;; 41 (list 0 1) ;; 1 element
;; 44 (make-int8 5) ;; 5
;; 46 (make-false) ;; #f
;; 47 (cons)
;; 48 (make-int8 18) ;; 18
;; 50 (make-false) ;; #f
;; 51 (cons)
;; 52 (make-int8 20) ;; 20
;; 54 (make-false) ;; #f
;; 55 (cons)
;; 56 (list 0 4) ;; 4 elements
;; 59 (load-program ##{66}#)
;; 81 (define "loop")
;; 87 (variable-set)
;; 88 (void)
;; 89 (return)
;; Bytecode ##{66}#:
;; 0 (make-int8 0) ;; 0
;; 2 (local-ref 0)
;; 4 (ee?)
;; 5 (br-if-not 0 3) ;; -> 11
;; 8 (make-int8 0) ;; 0
;; 10 (return)
;; 11 (toplevel-ref 0)
;; 13 (local-ref 0)
;; 15 (make-int8 1) ;; 1
;; 17 (sub)
;; 18 (tail-call 1)
(define (loopi n)
;; Same as `loop'.
(let loopi ((n n))
(if (= 0 n)
0
(loopi (1- n)))))
(define (do-loop n)
;; Same as `loop' using `do'.
(do ((i n (1- i)))
((= 0 i))
;; do nothing
))
(define (do-cons x)
;; This one shows that the built-in `cons' instruction yields a significant
;; improvement (speedup: 1.5).
(let loop ((x x)
(result '()))
(if (<= x 0)
result
(loop (1- x) (cons x result)))))
(define big-list (iota 500000))
(define (copy-list lst)
;; Speedup: 5.9.
(let loop ((lst lst)
(result '()))
(if (null? lst)
result
(loop (cdr lst)
(cons (car lst) result)))))

64
benchmark/measure.scm Executable file
View file

@ -0,0 +1,64 @@
#!/bin/sh
# aside from this initial boilerplate, this is actually -*- scheme -*- code
main='(module-ref (resolve-module '\''(measure)) '\'main')'
exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
!#
;; A simple interpreter vs. VM performance comparison tool
;;
(define-module (measure)
:export (measure)
:use-module (system vm vm)
:use-module (system base compile)
:use-module (system base language))
(define (time-for-eval sexp eval)
(let ((before (tms:utime (times))))
(eval sexp)
(let ((elapsed (- (tms:utime (times)) before)))
(format #t "elapsed time: ~a~%" elapsed)
elapsed)))
(define *scheme* (lookup-language 'scheme))
(define (measure . args)
(if (< (length args) 2)
(begin
(format #t "Usage: measure SEXP FILE-TO-LOAD...~%")
(format #t "~%")
(format #t "Example: measure '(loop 23424)' lib.scm~%~%")
(exit 1)))
(for-each load (cdr args))
(let* ((sexp (with-input-from-string (car args)
(lambda ()
(read))))
(eval-here (lambda (sexp) (eval sexp (current-module))))
(proc-name (car sexp))
(proc-source (procedure-source (eval proc-name (current-module))))
(% (format #t "proc: ~a~%source: ~a~%" proc-name proc-source))
(time-interpreted (time-for-eval sexp eval-here))
(& (if (defined? proc-name)
(eval `(set! ,proc-name #f) (current-module))
(format #t "unbound~%")))
(the-program (compile proc-source))
(time-compiled (time-for-eval `(,proc-name ,@(cdr sexp))
(lambda (sexp)
(eval `(begin
(define ,proc-name
,the-program)
,sexp)
(current-module))))))
(format #t "proc: ~a => ~a~%"
proc-name (eval proc-name (current-module)))
(format #t "interpreted: ~a~%" time-interpreted)
(format #t "compiled: ~a~%" time-compiled)
(format #t "speedup: ~a~%"
(exact->inexact (/ time-interpreted time-compiled)))
0))
(define main measure)

24
build-aux/config.rpath
View file

@ -47,7 +47,7 @@ for cc_temp in $CC""; do
done
cc_basename=`echo "$cc_temp" | sed -e 's%^.*/%%'`
# Code taken from libtool.m4's AC_LIBTOOL_PROG_COMPILER_PIC.
# Code taken from libtool.m4's _LT_COMPILER_PIC.
wl=
if test "$GCC" = yes; then
@ -64,7 +64,7 @@ else
;;
esac
;;
mingw* | cygwin* | pw32* | os2*)
mingw* | cygwin* | pw32* | os2* | cegcc*)
;;
hpux9* | hpux10* | hpux11*)
wl='-Wl,'
@ -76,7 +76,13 @@ else
;;
linux* | k*bsd*-gnu)
case $cc_basename in
icc* | ecc*)
ecc*)
wl='-Wl,'
;;
icc* | ifort*)
wl='-Wl,'
;;
lf95*)
wl='-Wl,'
;;
pgcc | pgf77 | pgf90)
@ -124,7 +130,7 @@ else
esac
fi
# Code taken from libtool.m4's AC_LIBTOOL_PROG_LD_SHLIBS.
# Code taken from libtool.m4's _LT_LINKER_SHLIBS.
hardcode_libdir_flag_spec=
hardcode_libdir_separator=
@ -132,7 +138,7 @@ hardcode_direct=no
hardcode_minus_L=no
case "$host_os" in
cygwin* | mingw* | pw32*)
cygwin* | mingw* | pw32* | cegcc*)
# FIXME: the MSVC++ port hasn't been tested in a loooong time
# When not using gcc, we currently assume that we are using
# Microsoft Visual C++.
@ -182,7 +188,7 @@ if test "$with_gnu_ld" = yes; then
ld_shlibs=no
fi
;;
cygwin* | mingw* | pw32*)
cygwin* | mingw* | pw32* | cegcc*)
# hardcode_libdir_flag_spec is actually meaningless, as there is
# no search path for DLLs.
hardcode_libdir_flag_spec='-L$libdir'
@ -326,7 +332,7 @@ else
;;
bsdi[45]*)
;;
cygwin* | mingw* | pw32*)
cygwin* | mingw* | pw32* | cegcc*)
# When not using gcc, we currently assume that we are using
# Microsoft Visual C++.
# hardcode_libdir_flag_spec is actually meaningless, as there is
@ -494,7 +500,7 @@ else
fi
# Check dynamic linker characteristics
# Code taken from libtool.m4's AC_LIBTOOL_SYS_DYNAMIC_LINKER.
# Code taken from libtool.m4's _LT_SYS_DYNAMIC_LINKER.
# Unlike libtool.m4, here we don't care about _all_ names of the library, but
# only about the one the linker finds when passed -lNAME. This is the last
# element of library_names_spec in libtool.m4, or possibly two of them if the
@ -517,7 +523,7 @@ case "$host_os" in
bsdi[45]*)
library_names_spec='$libname$shrext'
;;
cygwin* | mingw* | pw32*)
cygwin* | mingw* | pw32* | cegcc*)
shrext=.dll
library_names_spec='$libname.dll.a $libname.lib'
;;

183
build-aux/gitlog-to-changelog Executable file
View file

@ -0,0 +1,183 @@
#!/usr/bin/perl
# Convert git log output to ChangeLog format.
my $VERSION = '2009-06-04 08:53'; # UTC
# The definition above must lie within the first 8 lines in order
# for the Emacs time-stamp write hook (at end) to update it.
# If you change this file with Emacs, please let the write hook
# do its job. Otherwise, update this string manually.
# Copyright (C) 2008, 2009 Free Software Foundation, Inc.
# 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 3 of the License, 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 program. If not, see <http://www.gnu.org/licenses/>.
# Written by Jim Meyering
use strict;
use warnings;
use Getopt::Long;
use POSIX qw(strftime);
(my $ME = $0) =~ s|.*/||;
# use File::Coda; # http://meyering.net/code/Coda/
END {
defined fileno STDOUT or return;
close STDOUT and return;
warn "$ME: failed to close standard output: $!\n";
$? ||= 1;
}
sub usage ($)
{
my ($exit_code) = @_;
my $STREAM = ($exit_code == 0 ? *STDOUT : *STDERR);
if ($exit_code != 0)
{
print $STREAM "Try `$ME --help' for more information.\n";
}
else
{
print $STREAM <<EOF;
Usage: $ME [OPTIONS] [ARGS]
Convert git log output to ChangeLog format. If present, any ARGS
are passed to "git log". To avoid ARGS being parsed as options to
$ME, they may be preceded by '--'.
OPTIONS:
--since=DATE convert only the logs since DATE;
the default is to convert all log entries.
--help display this help and exit
--version output version information and exit
EXAMPLE:
$ME --since=2008-01-01 > ChangeLog
$ME -- -n 5 foo > last-5-commits-to-branch-foo
EOF
}
exit $exit_code;
}
# If the string $S is a well-behaved file name, simply return it.
# If it contains white space, quotes, etc., quote it, and return the new string.
sub shell_quote($)
{
my ($s) = @_;
if ($s =~ m![^\w+/.,-]!)
{
# Convert each single quote to '\''
$s =~ s/\'/\'\\\'\'/g;
# Then single quote the string.
$s = "'$s'";
}
return $s;
}
sub quoted_cmd(@)
{
return join (' ', map {shell_quote $_} @_);
}
{
my $since_date = '1970-01-01 UTC';
GetOptions
(
help => sub { usage 0 },
version => sub { print "$ME version $VERSION\n"; exit },
'since=s' => \$since_date,
) or usage 1;
my @cmd = (qw (git log --log-size), "--since=$since_date",
'--pretty=format:%ct %an <%ae>%n%n%s%n%b%n', @ARGV);
open PIPE, '-|', @cmd
or die ("$ME: failed to run `". quoted_cmd (@cmd) ."': $!\n"
. "(Is your Git too old? Version 1.5.1 or later is required.)\n");
my $prev_date_line = '';
while (1)
{
defined (my $in = <PIPE>)
or last;
$in =~ /^log size (\d+)$/
or die "$ME:$.: Invalid line (expected log size):\n$in";
my $log_nbytes = $1;
my $log;
my $n_read = read PIPE, $log, $log_nbytes;
$n_read == $log_nbytes
or die "$ME:$.: unexpected EOF\n";
my @line = split "\n", $log;
my $author_line = shift @line;
defined $author_line
or die "$ME:$.: unexpected EOF\n";
$author_line =~ /^(\d+) (.*>)$/
or die "$ME:$.: Invalid line "
. "(expected date/author/email):\n$author_line\n";
my $date_line = sprintf "%s $2\n", strftime ("%F", localtime ($1));
# If this line would be the same as the previous date/name/email
# line, then arrange not to print it.
if ($date_line ne $prev_date_line)
{
$prev_date_line eq ''
or print "\n";
print $date_line;
}
$prev_date_line = $date_line;
# Omit "Signed-off-by..." lines.
@line = grep !/^Signed-off-by: .*>$/, @line;
# If there were any lines
if (@line == 0)
{
warn "$ME: warning: empty commit message:\n $date_line\n";
}
else
{
# Remove leading and trailing blank lines.
while ($line[0] =~ /^\s*$/) { shift @line; }
while ($line[$#line] =~ /^\s*$/) { pop @line; }
# Prefix each non-empty line with a TAB.
@line = map { length $_ ? "\t$_" : '' } @line;
print "\n", join ("\n", @line), "\n";
}
defined ($in = <PIPE>)
or last;
$in ne "\n"
and die "$ME:$.: unexpected line:\n$in";
}
close PIPE
or die "$ME: error closing pipe from " . quoted_cmd (@cmd) . "\n";
# FIXME-someday: include $PROCESS_STATUS in the diagnostic
}
# Local Variables:
# indent-tabs-mode: nil
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "my $VERSION = '"
# time-stamp-format: "%:y-%02m-%02d %02H:%02M"
# time-stamp-time-zone: "UTC"
# time-stamp-end: "'; # UTC"
# End:

7
check-guile.in
View file

@ -1,6 +1,6 @@
#! /bin/sh
# Usage: check-guile [-i GUILE-INTERPRETER] [GUILE-TEST-ARGS]
# If `-i GUILE-INTERPRETER' is omitted, use ${top_builddir}/pre-inst-guile.
# If `-i GUILE-INTERPRETER' is omitted, use ${top_builddir}/meta/guile.
# See ${top_srcdir}/test-suite/guile-test for documentation on GUILE-TEST-ARGS.
#
# Example invocations:
@ -21,7 +21,7 @@ if [ x"$1" = x-i ] ; then
shift
shift
else
guile=${top_builddir}/pre-inst-guile
guile=${top_builddir}/meta/guile
fi
GUILE_LOAD_PATH=$TEST_SUITE_DIR
@ -41,8 +41,7 @@ if [ ! -f guile-procedures.txt ] ; then
fi
exec $guile \
-l ${top_builddir}/libguile/stack-limit-calibration.scm \
-e main -s "$TEST_SUITE_DIR/guile-test" \
--no-autocompile -e main -s "$TEST_SUITE_DIR/guile-test" \
--test-suite "$TEST_SUITE_DIR/tests" \
--log-file check-guile.log "$@"

120
configure.in → configure.ac
View file

@ -8,20 +8,20 @@ Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
This file is part of GUILE
GUILE 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.
GUILE is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 3, or (at your option) any
later version.
GUILE 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.
GUILE 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 Lesser General Public
License for more details.
You should have received a copy of the GNU General Public License
along with GUILE; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
You should have received a copy of the GNU Lesser General Public
License along with GUILE; see the file COPYING.LESSER. If not, write
to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
Floor, Boston, MA 02110-1301, USA.
]])
@ -51,14 +51,6 @@ AC_CONFIG_SRCDIR([GUILE-VERSION])
AC_CONFIG_HEADERS([config.h])
AH_TOP(/*GUILE_CONFIGURE_COPYRIGHT*/)
#--------------------------------------------------------------------
#
# Independent Subdirectories
#
#--------------------------------------------------------------------
AC_CONFIG_SUBDIRS(guile-readline)
#--------------------------------------------------------------------
AC_LANG([C])
@ -159,6 +151,7 @@ AC_ARG_ENABLE([deprecated],
if test "$enable_deprecated" = no; then
SCM_I_GSC_ENABLE_DEPRECATED=0
warn_default=no
else
if test "$enable_deprecated" = yes || test "$enable_deprecated" = ""; then
warn_default=summary
@ -168,9 +161,9 @@ else
warn_default=$enable_deprecated
fi
SCM_I_GSC_ENABLE_DEPRECATED=1
AC_DEFINE_UNQUOTED(SCM_WARN_DEPRECATED_DEFAULT, "$warn_default",
[Define this to control the default warning level for deprecated features.])
fi
AC_DEFINE_UNQUOTED(SCM_WARN_DEPRECATED_DEFAULT, "$warn_default",
[Define this to control the default warning level for deprecated features.])
AC_ARG_ENABLE(elisp,
[ --disable-elisp omit Emacs Lisp support],,
@ -288,6 +281,8 @@ AC_CHECK_LIB(uca, __uc_get_ar_bsp)
AC_C_BIGENDIAN
AC_C_LABELS_AS_VALUES
AC_CHECK_SIZEOF(char)
AC_CHECK_SIZEOF(unsigned char)
AC_CHECK_SIZEOF(short)
@ -618,6 +613,8 @@ AC_SUBST([SCM_I_GSC_HAVE_STRUCT_DIRENT64])
# Reasons for testing:
# complex.h - new in C99
# fenv.h - available in C99, but not older systems
# machine/fpu.h - on Tru64 5.1b, the declaration of fesetround(3) is in
# this file instead of <fenv.h>
# process.h - mingw specific
# langinfo.h, nl_types.h - SuS v2
#
@ -625,7 +622,7 @@ AC_CHECK_HEADERS([complex.h fenv.h io.h libc.h limits.h malloc.h memory.h proces
regex.h rxposix.h rx/rxposix.h sys/dir.h sys/ioctl.h sys/select.h \
sys/time.h sys/timeb.h sys/times.h sys/stdtypes.h sys/types.h \
sys/utime.h time.h unistd.h utime.h pwd.h grp.h sys/utsname.h \
direct.h langinfo.h nl_types.h])
direct.h langinfo.h nl_types.h machine/fpu.h])
# "complex double" is new in C99, and "complex" is only a keyword if
# <complex.h> is included
@ -731,10 +728,14 @@ AC_CHECK_FUNCS([DINFINITY DQNAN cexp chsize clog clog10 ctermid fesetround ftime
# sethostname - the function itself check because it's not in mingw,
# the DECL is checked because Solaris 10 doens't have in any header
# xlocale.h - needed on Darwin for the `locale_t' API
# hstrerror - on Tru64 5.1b the symbol is available in libc but the
# declaration isn't anywhere.
# cuserid - on Tru64 5.1b the declaration is documented to be available
# only with `_XOPEN_SOURCE' or some such.
#
AC_CHECK_HEADERS(crypt.h netdb.h pthread.h sys/param.h sys/resource.h sys/file.h xlocale.h)
AC_CHECK_FUNCS(chroot flock getlogin cuserid getpriority setpriority getpass sethostname gethostname)
AC_CHECK_DECLS([sethostname])
AC_CHECK_DECLS([sethostname, hstrerror, cuserid])
# crypt() may or may not be available, for instance in some countries there
# are restrictions on cryptography.
@ -818,14 +819,13 @@ fi
dnl GMP tests
AC_CHECK_LIB([gmp], [__gmpz_init], ,
[AC_MSG_ERROR([GNU MP not found, see README])])
# mpz_import is a macro so we need to include <gmp.h>
AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <gmp.h>]],
[[mpz_import (0, 0, 0, 0, 0, 0, 0); ]])],
AC_LIB_HAVE_LINKFLAGS(gmp,
[],
[AC_MSG_ERROR([At least GNU MP 4.1 is required, see README])])
[#include <gmp.h>],
[mpz_import (0, 0, 0, 0, 0, 0, 0);],
AC_MSG_ERROR([GNU MP 4.1 or greater not found, see README]))
dnl GNU libunistring is checked for by Gnulib's `libunistring' module.
dnl i18n tests
#AC_CHECK_HEADERS([libintl.h])
@ -881,6 +881,8 @@ if test -n "$have_sys_un_h" ; then
[Define if the system supports Unix-domain (file-domain) sockets.])
fi
AC_CHECK_FUNCS(getrlimit setrlimit)
AC_CHECK_FUNCS(socketpair getgroups setgroups setpwent pause tzset)
AC_CHECK_FUNCS(sethostent gethostent endhostent dnl
@ -1035,18 +1037,6 @@ if test $guile_cv_localtime_cache = yes; then
AC_DEFINE(LOCALTIME_CACHE, 1, [Define if localtime caches the TZ setting.])
fi
dnl Test whether system calls are restartable by default on the
dnl current system. If they are not, we put a loop around every system
dnl call to check for EINTR (see SCM_SYSCALL) and do not attempt to
dnl change from the default behaviour. On the other hand, if signals
dnl are restartable then the loop is not installed and when libguile
dnl initialises it also resets the behaviour of each signal to cause a
dnl restart (in case a different runtime had a different default
dnl behaviour for some reason: e.g., different versions of linux seem
dnl to behave differently.)
AC_SYS_RESTARTABLE_SYSCALLS
if test "$enable_regex" = yes; then
if test "$ac_cv_header_regex_h" = yes ||
test "$ac_cv_header_rxposix_h" = yes ||
@ -1258,11 +1248,12 @@ case "$with_threads" in
build_pthread_support="yes"
ACX_PTHREAD(CC="$PTHREAD_CC"
LIBS="$PTHREAD_LIBS $LIBS"
SCM_I_GSC_USE_PTHREAD_THREADS=1
with_threads="pthreads",
with_threads="null")
ACX_PTHREAD([CC="$PTHREAD_CC"
LIBS="$PTHREAD_LIBS $LIBS"
SCM_I_GSC_USE_PTHREAD_THREADS=1
with_threads="pthreads"],
[with_threads="null"
build_pthread_support="no"])
old_CFLAGS="$CFLAGS"
CFLAGS="$PTHREAD_CFLAGS $CFLAGS"
@ -1461,6 +1452,9 @@ LIBLOBJS="`echo ${LIB@&t@OBJS} | sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`"
EXTRA_DOT_DOC_FILES="`echo ${LIB@&t@OBJS} | sed 's,\.[[^.]]* ,.doc ,g;s,\.[[^.]]*$,.doc,'`"
EXTRA_DOT_X_FILES="`echo ${LIB@&t@OBJS} | sed 's,\.[[^.]]* ,.x ,g;s,\.[[^.]]*$,.x,'`"
# GNU Readline bindings.
GUILE_READLINE
AC_SUBST(GUILE_MAJOR_VERSION)
AC_SUBST(GUILE_MINOR_VERSION)
AC_SUBST(GUILE_MICRO_VERSION)
@ -1547,39 +1541,30 @@ AC_CONFIG_FILES([
lib/Makefile
benchmark-suite/Makefile
doc/Makefile
doc/goops/Makefile
doc/r5rs/Makefile
doc/ref/Makefile
doc/tutorial/Makefile
emacs/Makefile
examples/Makefile
examples/box-dynamic-module/Makefile
examples/box-dynamic/Makefile
examples/box-module/Makefile
examples/box/Makefile
examples/modules/Makefile
examples/safe/Makefile
examples/scripts/Makefile
guile-config/Makefile
ice-9/Makefile
ice-9/debugger/Makefile
ice-9/debugging/Makefile
lang/Makefile
libguile/Makefile
oop/Makefile
oop/goops/Makefile
scripts/Makefile
srfi/Makefile
guile-readline/Makefile
test-suite/Makefile
test-suite/standalone/Makefile
meta/Makefile
module/Makefile
testsuite/Makefile
])
AC_CONFIG_FILES([guile-1.8.pc])
AC_CONFIG_FILES([meta/guile-2.0.pc])
AC_CONFIG_FILES([meta/guile-2.0-uninstalled.pc])
AC_CONFIG_FILES([check-guile], [chmod +x check-guile])
AC_CONFIG_FILES([benchmark-guile], [chmod +x benchmark-guile])
AC_CONFIG_FILES([guile-tools], [chmod +x guile-tools])
AC_CONFIG_FILES([pre-inst-guile], [chmod +x pre-inst-guile])
AC_CONFIG_FILES([pre-inst-guile-env], [chmod +x pre-inst-guile-env])
AC_CONFIG_FILES([meta/guile], [chmod +x meta/guile])
AC_CONFIG_FILES([meta/uninstalled-env], [chmod +x meta/uninstalled-env])
AC_CONFIG_FILES([meta/gdb-uninstalled-guile], [chmod +x meta/gdb-uninstalled-guile])
AC_CONFIG_FILES([meta/guile-tools], [chmod +x meta/guile-tools])
AC_CONFIG_FILES([libguile/guile-snarf],
[chmod +x libguile/guile-snarf])
AC_CONFIG_FILES([libguile/guile-doc-snarf],
@ -1592,6 +1577,7 @@ AC_CONFIG_FILES([test-suite/standalone/test-use-srfi],
[chmod +x test-suite/standalone/test-use-srfi])
AC_CONFIG_FILES([test-suite/standalone/test-fast-slot-ref],
[chmod +x test-suite/standalone/test-fast-slot-ref])
AC_CONFIG_FILES([doc/ref/effective-version.texi])
AC_OUTPUT

21
doc/Makefile.am
View file

@ -1,27 +1,27 @@
## Process this file with Automake to create Makefile.in
##
## Copyright (C) 1998, 2002, 2006, 2008 Free Software Foundation, Inc.
## Copyright (C) 1998, 2002, 2006, 2008, 2009 Free Software Foundation, Inc.
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu
SUBDIRS = ref tutorial goops r5rs
SUBDIRS = ref tutorial r5rs
dist_man1_MANS = guile.1
@ -43,4 +43,3 @@ include $(top_srcdir)/am/maintainer-dirs
guile-api.alist: guile-api.alist-FORCE
( cd $(top_builddir) ; $(mscripts)/update-guile-api.alist )
guile-api.alist-FORCE:

4
doc/README
View file

@ -8,10 +8,6 @@ The documentation consists of the following manuals.
- The Guile Reference Manual (guile.texi) contains (or is intended to
contain) reference documentation on all aspects of Guile.
- The GOOPS Manual (goops.texi) contains both tutorial-style and
reference documentation for using GOOPS, Guile's Object Oriented
Programming System.
- The Revised^5 Report on the Algorithmic Language Scheme (r5rs.texi).
Please be aware that this is all very much work in progress (apart

24
doc/example-smob/image-type.c
View file

@ -2,20 +2,20 @@
*
* Copyright (C) 1998, 2000, 2004, 2006 Free Software Foundation, Inc.
*
* 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 free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 3, 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.
* 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
* Lesser 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., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301 USA
* You should have received a copy of the GNU Lesser General Public
* License along with this software; see the file COPYING.LESSER. If
* not, write to the Free Software Foundation, Inc., 51 Franklin
* Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include <stdlib.h>

24
doc/example-smob/myguile.c
View file

@ -2,20 +2,20 @@
*
* Copyright (C) 1998, 2006 Free Software Foundation, Inc.
*
* 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 free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 3, 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.
* 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
* Lesser 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., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301 USA
* You should have received a copy of the GNU Lesser General Public
* License along with this software; see the file COPYING.LESSER. If
* not, write to the Free Software Foundation, Inc., 51 Franklin
* Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include <libguile.h>

78
doc/goops.mail Normal file
View file

@ -0,0 +1,78 @@
From: Mikael Djurfeldt <mdj@mdj.nada.kth.se>
Subject: Re: After GOOPS integration: Computation with native types!
To: Keisuke Nishida <kxn30@po.cwru.edu>
Cc: djurfeldt@nada.kth.se, guile@sourceware.cygnus.com
Cc: djurfeldt@nada.kth.se
Date: 17 Aug 2000 03:01:13 +0200
Keisuke Nishida <kxn30@po.cwru.edu> writes:
> Do I need to include some special feature in my VM? Hmm, but maybe
> I shouldn't do that now...
Probably not, so I probably shouldn't answer, but... :)
You'll need to include some extremely efficient mechanism to do
multi-method dispatch. The SCM_IM_DISPATCH form, with its
implementation at line 2250 in eval.c, is the current basis for
efficient dispatch in GOOPS.
I think we should develop a new instruction for the VM which
corresponds to the SCM_IM_DISPATCH form.
This form serves both the purpose to map argument types to the correct
code, and as a cache of compiled methods.
Notice that I talk about cmethods below, not methods. In GOOPS, the
GF has a set of methods, but each method has a "code-table" mapping
argument types to code compiled for those particular concrete types.
(So, in essence, GOOPS methods abstractly do a deeper level of type
dispatch.)
The SCM_IM_DISPATCH form has two shapes, depending on whether we use
sequential search (few cmethods) or hashed lookup (many cmethods).
Shape 1:
(#@dispatch args N-SPECIALIZED #((TYPE1 ... ENV FORMALS FORM1 ...) ...) GF)
Shape 2:
(#@dispatch args N-SPECIALIZED HASHSET MASK
#((TYPE1 ... ENV FORMALS FORM1 ...) ...)
GF)
`args' is (I hope!) a now historic obscure optimization.
N-SPECIALIZED is the maximum number of arguments t do type checking
on. This is used early termination of argument checking where the
already checked arguments are enough to pick out the cmethod.
The vector is the cache proper.
During sequential search the argument types are simply checked against
each entry.
The method for hashed dispatch is described in:
http://www.parc.xerox.com/csl/groups/sda/publications/papers/Kiczales-Andreas-PCL
In this method, each class has a hash code. Dispatch means summing
the hash codes for all arguments (up til N-SPECIALIZED) and using the
sum to pick a location in the cache. The cache is sequentially
searched for an argument type match from that point.
Kiczales introduced a clever method to maximize the probability of a
direct cache hit. We actually have 8 separate sets of hash codes for
all types. The hash set to use is selected specifically per GF and is
optimized to give fastest average hit.
What we could try to do as soon as the VM is complete enough is to
represent the cmethods as chunks of byte code. In the current GOOPS
code, the compilation step (which is currently empty) is situated in
`compile-cmethod' in guile-oops/compile.scm. [Apologies for the
terrible code. That particular part was written at Arlanda airport
after a sleepless night (packing luggage, not coding), on my way to
visit Marius (who, BTW, didn't take GOOPS seriously. ;-)]

29
doc/goops/Makefile.am
View file

@ -1,29 +0,0 @@
## Process this file with Automake to create Makefile.in
##
## Copyright (C) 1998, 2004, 2006, 2008 Free Software Foundation, Inc.
##
## This file is part of GUILE.
##
## GUILE 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.
##
## GUILE 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 GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu
info_TEXINFOS = goops.texi
goops_TEXINFOS = goops-tutorial.texi \
hierarchy.eps hierarchy.png hierarchy.txt hierarchy.pdf
EXTRA_DIST = ChangeLog-2008

18
doc/groupings.alist
View file

@ -3,19 +3,19 @@
;; Copyright (C) 2002, 2006 Free Software Foundation, Inc.
;;
;; 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
;; modify it under the terms of the GNU Lesser General Public License
;; as published by the Free Software Foundation; either version 3, 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
;; 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.
;; Lesser 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., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301 USA
;; You should have received a copy of the GNU Lesser General Public
;; License along with this software; see the file COPYING.LESSER. If
;; not, write to the Free Software Foundation, Inc., 51 Franklin
;; Street, Fifth Floor, Boston, MA 02110-1301 USA
;;; Commentary:

26
doc/maint/docstring.el
View file

@ -2,22 +2,22 @@
;;;
;;; Copyright (C) 2001, 2004 Neil Jerram
;;;
;;; This file is not part of GNU Emacs, but the same permissions apply.
;;; This file is not part of GUILE, but the same permissions apply.
;;;
;;; GNU Emacs 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.
;;; GUILE is free software; you can redistribute it and/or modify it
;;; under the terms of the GNU Lesser General Public License as
;;; published by the Free Software Foundation; either version 3, or
;;; (at your option) any later version.
;;;
;;; GNU Emacs 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.
;;; GUILE 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
;;; Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with GNU Emacs; see the file COPYING. If not, write to the
;;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;;; Boston, MA 02110-1301, USA.
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with GUILE; see the file COPYING.LESSER. If not,
;;; write to the Free Software Foundation, Inc., 51 Franklin Street,
;;; Fifth Floor, Boston, MA 02110-1301, USA.
;;; Commentary:

2
doc/maint/guile.texi
View file

@ -204,7 +204,7 @@ Execute all thunks from the asyncs of the list @var{list_of_a}.
@deffn {Scheme Procedure} system-async thunk
@deffnx {C Function} scm_system_async (thunk)
This function is deprecated. You can use @var{thunk} directly
instead of explicitely creating an async object.
instead of explicitly creating an async object.
@end deffn

17
doc/oldfmt.c
View file

@ -1,18 +1,19 @@
/* Copyright (C) 2000,2001, 2006, 2008 Free Software Foundation, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 3, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
* License along with this software; see the file COPYING.LESSER. If
* not, write to the Free Software Foundation, Inc., 51 Franklin
* Street, Fifth Floor, Boston, MA 02110-1301 USA
*/

16
doc/r5rs/Makefile.am
View file

@ -4,20 +4,20 @@
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu

1
doc/ref/.gitignore vendored
View file

@ -1,2 +1,3 @@
autoconf-macros.texi
lib-version.texi
effective-version.texi

0
doc/goops/ChangeLog-2008 → doc/ref/ChangeLog-goops-2008
View file

37
doc/ref/Makefile.am
View file

@ -4,20 +4,20 @@
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu
@ -68,6 +68,9 @@ guile_TEXINFOS = preface.texi \
autoconf.texi \
autoconf-macros.texi \
tools.texi \
history.texi \
vm.texi \
compiler.texi \
fdl.texi \
libguile-concepts.texi \
libguile-smobs.texi \
@ -75,19 +78,29 @@ guile_TEXINFOS = preface.texi \
libguile-linking.texi \
libguile-extensions.texi \
api-init.texi \
mod-getopt-long.texi
mod-getopt-long.texi \
goops.texi \
goops-tutorial.texi \
effective-version.texi
ETAGS_ARGS = $(info_TEXINFOS) $(guile_TEXINFOS)
EXTRA_DIST = ChangeLog-2008
PICTURES = hierarchy.eps \
hierarchy.pdf \
hierarchy.png \
hierarchy.txt \
mop.text
EXTRA_DIST = ChangeLog-2008 $(PICTURES)
include $(top_srcdir)/am/pre-inst-guile
# Automated snarfing
autoconf.texi: autoconf-macros.texi
autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4
$(preinstguiletool)/snarf-guile-m4-docs $(top_srcdir)/guile-config/guile.m4 \
autoconf-macros.texi: $(top_srcdir)/meta/guile.m4
GUILE_AUTO_COMPILE=0 $(top_builddir)/meta/uninstalled-env guile-tools \
snarf-guile-m4-docs $(top_srcdir)/meta/guile.m4 \
> $(srcdir)/$@
lib-version.texi: $(top_srcdir)/GUILE-VERSION

16
doc/ref/api-binding.texi
View file

@ -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
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -271,10 +271,16 @@ with duplicate bindings.
Guile provides a procedure for checking whether a symbol is bound in the
top level environment.
@c NJFIXME explain [env]
@deffn {Scheme Procedure} defined? sym [env]
@deffnx {C Function} scm_defined_p (sym, env)
Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
@deffn {Scheme Procedure} defined? sym [module]
@deffnx {C Function} scm_defined_p (sym, module)
Return @code{#t} if @var{sym} is defined in the module @var{module} or
the current module when @var{module} is not specified; otherwise return
@code{#f}.
Up to Guile 1.8, the second optional argument had to be @dfn{lexical
environment} as returned by @code{the-environment}, for example. The
behavior of this function remains unchanged when the second argument is
omitted.
@end deffn

99
doc/ref/api-compound.texi
View file

@ -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, 2005, 2006, 2007
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -1344,9 +1344,9 @@ otherwise.
@deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s168vector (const scm_t_int16 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s328vector (const scm_t_int32 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
@deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
@ -1405,6 +1405,12 @@ C}), but returns a pointer to the elements of a uniform numeric vector
of the indicated kind.
@end deftypefn
Uniform numeric vectors can be written to and read from input/output
ports using the procedures listed below. However, bytevectors may often
be more convenient for binary input/output since they provide more
flexibility in the interpretation of raw byte sequences
(@pxref{Bytevectors}).
@deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
@deffnx {C Function} scm_uniform_vector_read_x (uvec, port_or_fd, start, end)
Fill the elements of @var{uvec} by reading
@ -1643,18 +1649,18 @@ and writing.
@subsection Generalized Vectors
Guile has a number of data types that are generally vector-like:
strings, uniform numeric vectors, bitvectors, and of course ordinary
vectors of arbitrary Scheme values. These types are disjoint: a
Scheme value belongs to at most one of the four types listed above.
strings, uniform numeric vectors, bytevectors, bitvectors, and of course
ordinary vectors of arbitrary Scheme values. These types are disjoint:
a Scheme value belongs to at most one of the five types listed above.
If you want to gloss over this distinction and want to treat all four
types with common code, you can use the procedures in this section.
They work with the @emph{generalized vector} type, which is the union
of the four vector-like types.
of the five vector-like types.
@deffn {Scheme Procedure} generalized-vector? obj
@deffnx {C Function} scm_generalized_vector_p (obj)
Return @code{#t} if @var{obj} is a vector, string,
Return @code{#t} if @var{obj} is a vector, bytevector, string,
bitvector, or uniform numeric vector.
@end deffn
@ -1743,9 +1749,9 @@ matrix with zero columns and 3 rows is different from a matrix with 3
columns and zero rows, which again is different from a vector of
length zero.
Generalized vectors, such as strings, uniform numeric vectors, bit
vectors and ordinary vectors, are the special case of one dimensional
arrays.
Generalized vectors, such as strings, uniform numeric vectors,
bytevectors, bit vectors and ordinary vectors, are the special case of
one dimensional arrays.
@menu
* Array Syntax::
@ -1828,6 +1834,16 @@ is a rank-zero array with contents 12.
@end table
In addition, bytevectors are also arrays, but use a different syntax
(@pxref{Bytevectors}):
@table @code
@item #vu8(1 2 3)
is a 3-byte long bytevector, with contents 1, 2, 3.
@end table
@node Array Procedures
@subsubsection Array Procedures
@ -1985,13 +2001,24 @@ enclosed array is unspecified.
For example,
@lisp
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
(enclose-array '#3(((a b c)
(d e f))
((1 2 3)
(4 5 6)))
1)
@result{}
#<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
#<enclosed-array (#1(a d) #1(b e) #1(c f))
(#1(1 4) #1(2 5) #1(3 6))>
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
(enclose-array '#3(((a b c)
(d e f))
((1 2 3)
(4 5 6)))
1 0)
@result{}
#<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
#<enclosed-array #2((a 1) (d 4))
#2((b 2) (e 5))
#2((c 3) (f 6))>
@end lisp
@end deffn
@ -2342,21 +2369,13 @@ the danger of a deadlock. In a multi-threaded program, you will need
additional synchronization to avoid modifying reserved arrays.)
You must take care to always unreserve an array after reserving it,
also in the presence of non-local exits. To simplify this, reserving
and unreserving work like a dynwind context (@pxref{Dynamic Wind}): a
call to @code{scm_array_get_handle} can be thought of as beginning a
dynwind context and @code{scm_array_handle_release} as ending it.
When a non-local exit happens between these two calls, the array is
implicitely unreserved.
even in the presence of non-local exits. If a non-local exit can
happen between these two calls, you should install a dynwind context
that releases the array when it is left (@pxref{Dynamic Wind}).
That is, you need to properly pair reserving and unreserving in your
code, but you don't need to worry about non-local exits.
These calls and other pairs of calls that establish dynwind contexts
need to be properly nested. If you begin a context prior to reserving
an array, you need to unreserve the array before ending the context.
Likewise, when reserving two or more arrays in a certain order, you
need to unreserve them in the opposite order.
In addition, array reserving and unreserving must be properly
paired. For instance, when reserving two or more arrays in a certain
order, you need to unreserve them in the opposite order.
Once you have reserved an array and have retrieved the pointer to its
elements, you must figure out the layout of the elements in memory.
@ -2797,11 +2816,11 @@ structure.
@example
(make-vtable "prpw"
(lambda (struct port)
(display "#<")
(display (struct-ref 0))
(display " and ")
(display (struct-ref 1))
(display ">")))
(display "#<" port)
(display (struct-ref struct 0) port)
(display " and " port)
(display (struct-ref struct 1) port)
(display ">" port)))
@end example
@end deffn
@ -3075,8 +3094,10 @@ which can be changed.
(color ball)
(owner ball)))
ball-color))
(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
(define (owner ball) (struct-ref ball 0))
(define (color ball)
(struct-ref (struct-vtable ball) vtable-offset-user))
(define (owner ball)
(struct-ref ball 0))
(define red (make-ball-type 'red))
(define green (make-ball-type 'green))
@ -3452,7 +3473,8 @@ whole is not a proper list:
(assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
@result{}
ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 2) ("key" . "door") . "open sesame")
ERROR: Wrong type argument in position 2 (expecting
association list): ((1 . 2) ("key" . "door") . "open sesame")
(sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
@result{}
@ -3466,7 +3488,8 @@ Secondly, if one of the entries in the specified alist is not a pair:
(assoc 2 '((1 . 1) 2 (3 . 9)))
@result{}
ERROR: In procedure assoc in expression (assoc 2 (quote #)):
ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 1) 2 (3 . 9))
ERROR: Wrong type argument in position 2 (expecting
association list): ((1 . 1) 2 (3 . 9))
(sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
@result{}

28
doc/ref/api-control.texi
View file

@ -22,6 +22,7 @@ flow of Scheme affects C code.
* Error Reporting:: Procedures for signaling errors.
* Dynamic Wind:: Dealing with non-local entrance/exit.
* Handling Errors:: How to handle errors in C code.
* Continuation Barriers:: Protection from non-local control flow.
@end menu
@node begin
@ -1501,6 +1502,33 @@ which is the name of the procedure incorrectly invoked.
@end deftypefn
@node Continuation Barriers
@subsection Continuation Barriers
The non-local flow of control caused by continuations might sometimes
not be wanted. You can use @code{with-continuation-barrier} etc to
errect fences that continuations can not pass.
@deffn {Scheme Procedure} with-continuation-barrier proc
@deffnx {C Function} scm_with_continuation_barrier (proc)
Call @var{proc} and return its result. Do not allow the invocation of
continuations that would leave or enter the dynamic extent of the call
to @code{with-continuation-barrier}. Such an attempt causes an error
to be signaled.
Throws (such as errors) that are not caught from within @var{proc} are
caught by @code{with-continuation-barrier}. In that case, a short
message is printed to the current error port and @code{#f} is returned.
Thus, @code{with-continuation-barrier} returns exactly once.
@end deffn
@deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
Like @code{scm_with_continuation_barrier} but call @var{func} on
@var{data}. When an error is caught, @code{NULL} is returned.
@end deftypefn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

469
doc/ref/api-data.texi
View file

@ -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, 2006, 2007, 2008
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -45,6 +45,7 @@ For the documentation of such @dfn{compound} data types, see
* Characters:: Single characters.
* Character Sets:: Sets of characters.
* Strings:: Sequences of characters.
* Bytevectors:: Sequences of bytes.
* Regular Expressions:: Pattern matching and substitution.
* Symbols:: Symbols.
* Keywords:: Self-quoting, customizable display keywords.
@ -331,7 +332,7 @@ integers.
The motivation for this behavior is that the inexactness of a number
should not be lost silently. If you want to allow inexact integers,
you can explicitely insert a call to @code{inexact->exact} or to its C
you can explicitly insert a call to @code{inexact->exact} or to its C
equivalent @code{scm_inexact_to_exact}. (Only inexact integers will
be converted by this call into exact integers; inexact non-integers
will become exact fractions.)
@ -3476,9 +3477,9 @@ allocated string.
@deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end)
Without optional arguments, this procedure is equivalent to
@smalllisp
@lisp
(string-concatenate (reverse ls))
@end smalllisp
@end lisp
If the optional argument @var{final_string} is specified, it is
consed onto the beginning to @var{ls} before performing the
@ -3534,11 +3535,12 @@ For example, to change characters to alternately upper and lower case,
@example
(define str (string-copy "studly"))
(string-for-each-index (lambda (i)
(string-set! str i
((if (even? i) char-upcase char-downcase)
(string-ref str i))))
str)
(string-for-each-index
(lambda (i)
(string-set! str i
((if (even? i) char-upcase char-downcase)
(string-ref str i))))
str)
str @result{} "StUdLy"
@end example
@end deffn
@ -3746,6 +3748,445 @@ is larger than @var{max_len}, only @var{max_len} bytes have been
stored and you probably need to try again with a larger buffer.
@end deftypefn
@node Bytevectors
@subsection Bytevectors
@cindex bytevector
@cindex R6RS
A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevector)}
module provides the programming interface specified by the
@uref{http://www.r6rs.org/, Revised^6 Report on the Algorithmic Language
Scheme (R6RS)}. It contains procedures to manipulate bytevectors and
interpret their contents in a number of ways: bytevector contents can be
accessed as signed or unsigned integer of various sizes and endianness,
as IEEE-754 floating point numbers, or as strings. It is a useful tool
to encode and decode binary data.
The R6RS (Section 4.3.4) specifies an external representation for
bytevectors, whereby the octets (integers in the range 0--255) contained
in the bytevector are represented as a list prefixed by @code{#vu8}:
@lisp
#vu8(1 53 204)
@end lisp
denotes a 3-byte bytevector containing the octets 1, 53, and 204. Like
string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
they do not need to be quoted:
@lisp
#vu8(1 53 204)
@result{} #vu8(1 53 204)
@end lisp
Bytevectors can be used with the binary input/output primitives of the
R6RS (@pxref{R6RS I/O Ports}).
@menu
* Bytevector Endianness:: Dealing with byte order.
* Bytevector Manipulation:: Creating, copying, manipulating bytevectors.
* Bytevectors as Integers:: Interpreting bytes as integers.
* Bytevectors and Integer Lists:: Converting to/from an integer list.
* Bytevectors as Floats:: Interpreting bytes as real numbers.
* Bytevectors as Strings:: Interpreting bytes as Unicode strings.
* Bytevectors as Generalized Vectors:: Guile extension to the bytevector API.
@end menu
@node Bytevector Endianness
@subsubsection Endianness
@cindex endianness
@cindex byte order
@cindex word order
Some of the following procedures take an @var{endianness} parameter.
The @dfn{endianness} is defined as the order of bytes in multi-byte
numbers: numbers encoded in @dfn{big endian} have their most
significant bytes written first, whereas numbers encoded in
@dfn{little endian} have their least significant bytes
first@footnote{Big-endian and little-endian are the most common
``endiannesses'', but others do exist. For instance, the GNU MP
library allows @dfn{word order} to be specified independently of
@dfn{byte order} (@pxref{Integer Import and Export,,, gmp, The GNU
Multiple Precision Arithmetic Library Manual}).}.
Little-endian is the native endianness of the IA32 architecture and
its derivatives, while big-endian is native to SPARC and PowerPC,
among others. The @code{native-endianness} procedure returns the
native endianness of the machine it runs on.
@deffn {Scheme Procedure} native-endianness
@deffnx {C Function} scm_native_endianness ()
Return a value denoting the native endianness of the host machine.
@end deffn
@deffn {Scheme Macro} endianness symbol
Return an object denoting the endianness specified by @var{symbol}. If
@var{symbol} is neither @code{big} nor @code{little} then an error is
raised at expand-time.
@end deffn
@defvr {C Variable} scm_endianness_big
@defvrx {C Variable} scm_endianness_little
The objects denoting big- and little-endianness, respectively.
@end defvr
@node Bytevector Manipulation
@subsubsection Manipulating Bytevectors
Bytevectors can be created, copied, and analyzed with the following
procedures and C functions.
@deffn {Scheme Procedure} make-bytevector len [fill]
@deffnx {C Function} scm_make_bytevector (len, fill)
@deffnx {C Function} scm_c_make_bytevector (size_t len)
Return a new bytevector of @var{len} bytes. Optionally, if @var{fill}
is given, fill it with @var{fill}; @var{fill} must be in the range
[-128,255].
@end deffn
@deffn {Scheme Procedure} bytevector? obj
@deffnx {C Function} scm_bytevector_p (obj)
Return true if @var{obj} is a bytevector.
@end deffn
@deftypefn {C Function} int scm_is_bytevector (SCM obj)
Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
@end deftypefn
@deffn {Scheme Procedure} bytevector-length bv
@deffnx {C Function} scm_bytevector_length (bv)
Return the length in bytes of bytevector @var{bv}.
@end deffn
@deftypefn {C Function} size_t scm_c_bytevector_length (SCM bv)
Likewise, return the length in bytes of bytevector @var{bv}.
@end deftypefn
@deffn {Scheme Procedure} bytevector=? bv1 bv2
@deffnx {C Function} scm_bytevector_eq_p (bv1, bv2)
Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
length and contents.
@end deffn
@deffn {Scheme Procedure} bytevector-fill! bv fill
@deffnx {C Function} scm_bytevector_fill_x (bv, fill)
Fill bytevector @var{bv} with @var{fill}, a byte.
@end deffn
@deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
@deffnx {C Function} scm_bytevector_copy_x (source, source_start, target, target_start, len)
Copy @var{len} bytes from @var{source} into @var{target}, starting
reading from @var{source-start} (a positive index within @var{source})
and start writing at @var{target-start}.
@end deffn
@deffn {Scheme Procedure} bytevector-copy bv
@deffnx {C Function} scm_bytevector_copy (bv)
Return a newly allocated copy of @var{bv}.
@end deffn
@deftypefn {C Function} scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index)
Return the byte at @var{index} in bytevector @var{bv}.
@end deftypefn
@deftypefn {C Function} void scm_c_bytevector_set_x (SCM bv, size_t index, scm_t_uint8 value)
Set the byte at @var{index} in @var{bv} to @var{value}.
@end deftypefn
Low-level C macros are available. They do not perform any
type-checking; as such they should be used with care.
@deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
Return the length in bytes of bytevector @var{bv}.
@end deftypefn
@deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
Return a pointer to the contents of bytevector @var{bv}.
@end deftypefn
@node Bytevectors as Integers
@subsubsection Interpreting Bytevector Contents as Integers
The contents of a bytevector can be interpreted as a sequence of
integers of any given size, sign, and endianness.
@lisp
(let ((bv (make-bytevector 4)))
(bytevector-u8-set! bv 0 #x12)
(bytevector-u8-set! bv 1 #x34)
(bytevector-u8-set! bv 2 #x56)
(bytevector-u8-set! bv 3 #x78)
(map (lambda (number)
(number->string number 16))
(list (bytevector-u8-ref bv 0)
(bytevector-u16-ref bv 0 (endianness big))
(bytevector-u32-ref bv 0 (endianness little)))))
@result{} ("12" "1234" "78563412")
@end lisp
The most generic procedures to interpret bytevector contents as integers
are described below.
@deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
@deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
@deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
@deffnx {C Function} scm_bytevector_sint_ref (bv, index, endianness, size)
Return the @var{size}-byte long unsigned (resp. signed) integer at
index @var{index} in @var{bv}, decoded according to @var{endianness}.
@end deffn
@deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
@deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
@deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
@deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
Set the @var{size}-byte long unsigned (resp. signed) integer at
@var{index} to @var{value}, encoded according to @var{endianness}.
@end deffn
The following procedures are similar to the ones above, but specialized
to a given integer size:
@deffn {Scheme Procedure} bytevector-u8-ref bv index
@deffnx {Scheme Procedure} bytevector-s8-ref bv index
@deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
@deffnx {C Function} scm_bytevector_u8_ref (bv, index)
@deffnx {C Function} scm_bytevector_s8_ref (bv, index)
@deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_s64_ref (bv, index, endianness)
Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
16, 32 or 64) from @var{bv} at @var{index}, decoded according to
@var{endianness}.
@end deffn
@deffn {Scheme Procedure} bytevector-u8-set! bv index value
@deffnx {Scheme Procedure} bytevector-s8-set! bv index value
@deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
@deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_s64_set_x (bv, index, value, endianness)
Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
@var{endianness}.
@end deffn
Finally, a variant specialized for the host's endianness is available
for each of these functions (with the exception of the @code{u8}
accessors, for obvious reasons):
@deffn {Scheme Procedure} bytevector-u16-native-ref bv index
@deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
@deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
@deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
@deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
@deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
@deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_s64_native_ref (bv, index)
Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
host's native endianness.
@end deffn
@deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
@deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
host's native endianness.
@end deffn
@node Bytevectors and Integer Lists
@subsubsection Converting Bytevectors to/from Integer Lists
Bytevector contents can readily be converted to/from lists of signed or
unsigned integers:
@lisp
(bytevector->sint-list (u8-list->bytevector (make-list 4 255))
(endianness little) 2)
@result{} (-1 -1)
@end lisp
@deffn {Scheme Procedure} bytevector->u8-list bv
@deffnx {C Function} scm_bytevector_to_u8_list (bv)
Return a newly allocated list of unsigned 8-bit integers from the
contents of @var{bv}.
@end deffn
@deffn {Scheme Procedure} u8-list->bytevector lst
@deffnx {C Function} scm_u8_list_to_bytevector (lst)
Return a newly allocated bytevector consisting of the unsigned 8-bit
integers listed in @var{lst}.
@end deffn
@deffn {Scheme Procedure} bytevector->uint-list bv endianness size
@deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
@deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
@deffnx {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
Return a list of unsigned (resp. signed) integers of @var{size} bytes
representing the contents of @var{bv}, decoded according to
@var{endianness}.
@end deffn
@deffn {Scheme Procedure} uint-list->bytevector lst endianness size
@deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
@deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
@deffnx {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
Return a new bytevector containing the unsigned (resp. signed) integers
listed in @var{lst} and encoded on @var{size} bytes according to
@var{endianness}.
@end deffn
@node Bytevectors as Floats
@subsubsection Interpreting Bytevector Contents as Floating Point Numbers
@cindex IEEE-754 floating point numbers
Bytevector contents can also be accessed as IEEE-754 single- or
double-precision floating point numbers (respectively 32 and 64-bit
long) using the procedures described here.
@deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
@deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
@deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
@deffnx {C Function} scm_bytevector_ieee_double_ref (bv, index, endianness)
Return the IEEE-754 single-precision floating point number from @var{bv}
at @var{index} according to @var{endianness}.
@end deffn
@deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
@deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
@deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
@deffnx {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, endianness)
Store real number @var{value} in @var{bv} at @var{index} according to
@var{endianness}.
@end deffn
Specialized procedures are also available:
@deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
@deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
@deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
@deffnx {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
Return the IEEE-754 single-precision floating point number from @var{bv}
at @var{index} according to the host's native endianness.
@end deffn
@deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
@deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
@deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
@deffnx {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, value)
Store real number @var{value} in @var{bv} at @var{index} according to
the host's native endianness.
@end deffn
@node Bytevectors as Strings
@subsubsection Interpreting Bytevector Contents as Unicode Strings
@cindex Unicode string encoding
Bytevector contents can also be interpreted as Unicode strings encoded
in one of the most commonly available encoding formats@footnote{Guile
1.8 does @emph{not} support Unicode strings. Therefore, the procedures
described here assume that Guile strings are internally encoded
according to the current locale. For instance, if @code{$LC_CTYPE} is
@code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
assume that Guile strings are Latin-1-encoded.}.
@lisp
(utf8->string (u8-list->bytevector '(99 97 102 101)))
@result{} "cafe"
(string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
@result{} #vu8(99 97 102 195 169)
@end lisp
@deffn {Scheme Procedure} string->utf8 str
@deffnx {Scheme Procedure} string->utf16 str
@deffnx {Scheme Procedure} string->utf32 str
@deffnx {C Function} scm_string_to_utf8 (str)
@deffnx {C Function} scm_string_to_utf16 (str)
@deffnx {C Function} scm_string_to_utf32 (str)
Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
UTF-32 (aka. UCS-4) encoding of @var{str}.
@end deffn
@deffn {Scheme Procedure} utf8->string utf
@deffnx {Scheme Procedure} utf16->string utf
@deffnx {Scheme Procedure} utf32->string utf
@deffnx {C Function} scm_utf8_to_string (utf)
@deffnx {C Function} scm_utf16_to_string (utf)
@deffnx {C Function} scm_utf32_to_string (utf)
Return a newly allocated string that contains from the UTF-8-, UTF-16-,
or UTF-32-decoded contents of bytevector @var{utf}.
@end deffn
@node Bytevectors as Generalized Vectors
@subsubsection Accessing Bytevectors with the Generalized Vector API
As an extension to the R6RS, Guile allows bytevectors to be manipulated
with the @dfn{generalized vector} procedures (@pxref{Generalized
Vectors}). This also allows bytevectors to be accessed using the
generic @dfn{array} procedures (@pxref{Array Procedures}). When using
these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
@example
(define bv #vu8(0 1 2 3))
(generalized-vector? bv)
@result{} #t
(generalized-vector-ref bv 2)
@result{} 2
(generalized-vector-set! bv 2 77)
(array-ref bv 2)
@result{} 77
(array-type bv)
@result{} vu8
@end example
@node Regular Expressions
@subsection Regular Expressions
@tpindex Regular expressions
@ -4007,7 +4448,8 @@ Or matching a @sc{yyyymmdd} format date such as @samp{20020828} and
re-ordering and hyphenating the fields.
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define date-regex
"([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
(regexp-substitute #f (string-match date-regex s)
'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
@ -4067,7 +4509,8 @@ example the following is the date example from
@code{string-match} call.
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define date-regex
"([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
(regexp-substitute/global #f date-regex s
'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
@ -5062,7 +5505,7 @@ the @code{read-set!} procedure documented in @ref{User level options
interfaces} and @ref{Reader options}. Note that the @code{prefix} and
@code{postfix} syntax are mutually exclusive.
@smalllisp
@lisp
(read-set! keywords 'prefix)
#:type
@ -5094,7 +5537,7 @@ type:
ERROR: In expression :type:
ERROR: Unbound variable: :type
ABORT: (unbound-variable)
@end smalllisp
@end lisp
@node Keyword Procedures
@subsubsection Keyword Procedures

68
doc/ref/api-debug.texi
View file

@ -283,9 +283,9 @@ runs a script non-interactively.
The following procedures can be used to access and set the source
properties of read expressions.
@deffn {Scheme Procedure} set-source-properties! obj plist
@deffnx {C Function} scm_set_source_properties_x (obj, plist)
Install the association list @var{plist} as the source property
@deffn {Scheme Procedure} set-source-properties! obj alist
@deffnx {C Function} scm_set_source_properties_x (obj, alist)
Install the association list @var{alist} as the source property
list for @var{obj}.
@end deffn
@ -302,12 +302,12 @@ Return the source property association list of @var{obj}.
@deffn {Scheme Procedure} source-property obj key
@deffnx {C Function} scm_source_property (obj, key)
Return the source property specified by @var{key} from
@var{obj}'s source property list.
Return the property specified by @var{key} from @var{obj}'s source
properties.
@end deffn
In practice there are only two ways that you should use the ability to
set an expression's source breakpoints.
set an expression's source properties.
@itemize
@item
@ -330,9 +330,9 @@ involved in a backtrace or error report.
If you are looking for a way to attach arbitrary information to an
expression other than these properties, you should use
@code{make-object-property} instead (@pxref{Object Properties}), because
that will avoid bloating the source property hash table, which is really
only intended for the specific purposes described in this section.
@code{make-object-property} instead (@pxref{Object Properties}). That
will avoid bloating the source property hash table, which is really
only intended for the debugging purposes just described.
@node Decoding Memoized Source Expressions
@ -1708,7 +1708,7 @@ facilities just described.
A good way to explore in detail what a Scheme procedure does is to set
a trap on it and then single step through what it does. To do this,
make and install a @code{<procedure-trap>} with the @code{debug-trap}
behaviour from @code{(ice-9 debugging ice-9-debugger-extensions)}.
behaviour from @code{(ice-9 debugger)}.
The following sample session illustrates this. It assumes that the
file @file{matrix.scm} defines a procedure @code{mkmatrix}, which is
@ -1718,7 +1718,6 @@ calls @code{mkmatrix}.
@lisp
$ /usr/bin/guile -q
guile> (use-modules (ice-9 debugger)
(ice-9 debugging ice-9-debugger-extensions)
(ice-9 debugging traps))
guile> (load "matrix.scm")
guile> (install-trap (make <procedure-trap>
@ -1732,16 +1731,16 @@ Frame 2 at matrix.scm:8:3
[mkmatrix]
debug> next
Frame 3 at matrix.scm:4:3
(let ((x 1)) (quote this-is-a-matric))
(let ((x 1)) (quote hi!))
debug> info frame
Stack frame: 3
This frame is an evaluation.
The expression being evaluated is:
matrix.scm:4:3:
(let ((x 1)) (quote this-is-a-matric))
(let ((x 1)) (quote hi!))
debug> next
Frame 3 at matrix.scm:5:21
(quote this-is-a-matric)
(quote hi!)
debug> bt
In unknown file:
?: 0* [primitive-eval (do-main 4)]
@ -1750,18 +1749,17 @@ In standard input:
In matrix.scm:
8: 2 [mkmatrix]
...
5: 3 (quote this-is-a-matric)
5: 3 (quote hi!)
debug> quit
this-is-a-matric
hi!
guile>
@end lisp
Or you can use Guile's Emacs interface (GDS), by using the module
@code{(ice-9 gds-client)} instead of @code{(ice-9 debugger)} and
@code{(ice-9 debugging ice-9-debugger-extensions)}, and changing
@code{debug-trap} to @code{gds-debug-trap}. Then the stack and
corresponding source locations are displayed in Emacs instead of on
the Guile command line.
changing @code{debug-trap} to @code{gds-debug-trap}. Then the stack and
corresponding source locations are displayed in Emacs instead of on the
Guile command line.
@node Profiling or Tracing a Procedure's Code
@ -1813,7 +1811,7 @@ guile> (do-main 4)
| 5: (memq sym bindings)
| 5: [memq let (debug)]
| 5: =>#f
| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric)))
| 2: (letrec ((yy 23)) (let ((x 1)) (quote hi!)))
| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f]
| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f]
| 4: (and (memq sym bindings) (let ...))
@ -1832,7 +1830,7 @@ guile> (do-main 4)
| 5: (memq sym bindings)
| 5: [memq let (debug)]
| 5: =>#f
| 2: (let ((x 1)) (quote this-is-a-matric))
| 2: (let ((x 1)) (quote hi!))
| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f]
| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f]
| 4: (and (memq sym bindings) (let ...))
@ -1841,15 +1839,15 @@ guile> (do-main 4)
| 5: =>#f
| 2: [let (let # #) (# # #)]
| 2: [let (let # #) (# # #)]
| 2: =>(#@@let* (x 1) #@@let (quote this-is-a-matric))
this-is-a-matric
| 2: =>(#@@let* (x 1) #@@let (quote hi!))
hi!
guile> (do-main 4)
| 2: [mkmatrix]
| 2: (letrec ((yy 23)) (let* ((x 1)) (quote this-is-a-matric)))
| 2: (let* ((x 1)) (quote this-is-a-matric))
| 2: (quote this-is-a-matric)
| 2: =>this-is-a-matric
this-is-a-matric
| 2: (letrec ((yy 23)) (let* ((x 1)) (quote hi!)))
| 2: (let* ((x 1)) (quote hi!))
| 2: (quote hi!)
| 2: =>hi!
hi!
guile>
@end lisp
@ -1881,14 +1879,16 @@ each trace line instead of the stack depth.
guile> (set-trace-layout "|~16@@a: ~a\n" trace/source trace/info)
guile> (do-main 4)
| matrix.scm:7:2: [mkmatrix]
| : (letrec ((yy 23)) (let* ((x 1)) (quote this-is-a-matric)))
| matrix.scm:3:2: (let* ((x 1)) (quote this-is-a-matric))
| matrix.scm:4:4: (quote this-is-a-matric)
| matrix.scm:4:4: =>this-is-a-matric
this-is-a-matric
| : (letrec ((yy 23)) (let* ((x 1)) (quote hi!)))
| matrix.scm:3:2: (let* ((x 1)) (quote hi!))
| matrix.scm:4:4: (quote hi!)
| matrix.scm:4:4: =>hi!
hi!
guile>
@end lisp
@anchor{Memoization}
@cindex Memoization
(For anyone wondering why the first @code{(do-main 4)} call above
generates lots more trace lines than the subsequent calls: these
examples also demonstrate how the Guile evaluator ``memoizes'' code.

108
doc/ref/api-evaluation.texi
View file

@ -5,20 +5,22 @@
@c See the file guile.texi for copying conditions.
@page
@node Read/Load/Eval
@node Read/Load/Eval/Compile
@section Reading and Evaluating Scheme Code
This chapter describes Guile functions that are concerned with reading,
loading and evaluating Scheme code at run time.
loading, evaluating, and compiling Scheme code at run time.
@menu
* Scheme Syntax:: Standard and extended Scheme syntax.
* Scheme Read:: Reading Scheme code.
* Fly Evaluation:: Procedures for on the fly evaluation.
* Compilation:: How to compile Scheme files and procedures.
* Loading:: Loading 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
@ -411,6 +413,69 @@ the current module.
@end deffn
@node Compilation
@subsection Compiling Scheme Code
The @code{eval} procedure directly interprets the S-expression
representation of Scheme. An alternate strategy for evaluation is to
determine ahead of time what computations will be necessary to
evaluate the expression, and then use that recipe to produce the
desired results. This is known as @dfn{compilation}.
While it is possible to compile simple Scheme expressions such as
@code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
interesting in the context of procedures. Compiling a lambda expression
produces a compiled procedure, which is just like a normal procedure
except typically much faster, because it can bypass the generic
interpreter.
Functions from system modules in a Guile installation are normally
compiled already, so they load and run quickly.
Note that well-written Scheme programs will not typically call the
procedures in this section, for the same reason that it is often bad
taste to use @code{eval}. The normal interface to the compiler is the
command-line file compiler, which can be invoked from the shell as
@code{guile-tools compile @var{foo.scm}}. This interface needs more
documentation.
(Why are calls to @code{eval} and @code{compile} usually in bad taste?
Because they are limited, in that they can only really make sense for
top-level expressions. Also, most needs for ``compile-time''
computation are fulfilled by macros and closures. Of course one good
counterexample is the REPL itself, or any code that reads expressions
from a port.)
For more information on the compiler itself, see @ref{Compiling to the
Virtual Machine}. For information on the virtual machine, see @ref{A
Virtual Machine for Guile}.
@deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
Compile the expression @var{exp} in the environment @var{env}. If
@var{exp} is a procedure, the result will be a compiled procedure;
otherwise @code{compile} is mostly equivalent to @code{eval}.
For a discussion of languages and compiler options, @xref{Compiling to
the Virtual Machine}.
@end deffn
@deffn {Scheme Procedure} compile-file file [to=objcode] [opts='()]
Compile the file named @var{file}.
Output will be written to a file in the current directory whose name
is computed as @code{(compiled-file-name @var{file})}.
@end deffn
@deffn {Scheme Procedure} compiled-file-name file
Compute an appropriate name for a compiled version of a Scheme file
named @var{file}.
Usually, the result will be the original file name with the
@code{.scm} suffix replaced with @code{.go}, but the exact behavior
depends on the contents of the @code{%load-extensions} and
@code{%load-compiled-extensions} lists.
@end deffn
@node Loading
@subsection Loading Scheme Code from File
@ -435,9 +500,19 @@ procedure that will be called before any code is loaded. See
documentation for @code{%load-hook} later in this section.
@end deffn
@deffn {Scheme Procedure} load-compiled filename
Load the compiled file named @var{filename}. The load paths are not
searched.
Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
calling @code{load-compiled} on the resulting file is equivalent to
calling @code{load} on the source file.
@end deffn
@deffn {Scheme Procedure} load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
paths.
paths. Preferentially loads a compiled version of the file, if it is
available and up-to-date.
@end deffn
@deffn {Scheme Procedure} primitive-load filename
@ -461,7 +536,8 @@ documentation for @code{%load-hook} later in this section.
Search @code{%load-path} for the file named @var{filename} and
load it into the top-level environment. If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled.
an error is signalled. Preferentially loads a compiled version of the
file, if it is available and up-to-date.
@end deffn
@deffn {Scheme Procedure} %search-load-path filename
@ -639,6 +715,30 @@ trap handlers.
Option interface for the evaluator trap options.
@end deffn
@node VM Behaviour
@subsection VM Behaviour
Like the procedures from the previous section that operate on the
evaluator, there are also procedures to modify the behavior of a
virtual machine.
The most useful thing that a user can do is to add to one of the
virtual machine's predefined hooks:
@deffn {Scheme Procedure} vm-next-hook vm
@deffnx {Scheme Procedure} vm-apply-hook vm
@deffnx {Scheme Procedure} vm-boot-hook vm
@deffnx {Scheme Procedure} vm-return-hook vm
@deffnx {Scheme Procedure} vm-break-hook vm
@deffnx {Scheme Procedure} vm-exit-hook vm
@deffnx {Scheme Procedure} vm-halt-hook vm
@deffnx {Scheme Procedure} vm-enter-hook vm
Accessors to a virtual machine's hooks. Usually you pass
@code{(the-vm)} as the @var{vm}.
@end deffn
@xref{A Virtual Machine for Guile}, for more information on Guile's
virtual machine.
@c Local Variables:
@c TeX-master: "guile.texi"

2
doc/ref/api-init.texi
View file

@ -61,7 +61,7 @@ Arrange things so that all of the code in the current thread executes as
if from within a call to @code{scm_with_guile}. That is, all functions
called by the current thread can assume that @code{SCM} values on their
stack frames are protected from the garbage collector (except when the
thread has explicitely left guile mode, of course).
thread has explicitly left guile mode, of course).
When @code{scm_init_guile} is called from a thread that already has been
in guile mode once, nothing happens. This behavior matters when you

286
doc/ref/api-io.texi
View file

@ -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, 2007
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -18,6 +18,7 @@
* Block Reading and Writing:: Reading and writing blocks of text.
* Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them.
* R6RS I/O Ports:: The R6RS port API.
* I/O Extensions:: Using and extending ports in C.
@end menu
@ -423,9 +424,9 @@ the current size, but this is not mandatory in the POSIX standard.
The delimited-I/O module can be accessed with:
@smalllisp
@lisp
(use-modules (ice-9 rdelim))
@end smalllisp
@end lisp
It can be used to read or write lines of text, or read text delimited by
a specified set of characters. It's similar to the @code{(scsh rdelim)}
@ -535,9 +536,9 @@ delimiter may be either a newline or the @var{eof-object}; if
The Block-string-I/O module can be accessed with:
@smalllisp
@lisp
(use-modules (ice-9 rw))
@end smalllisp
@end lisp
It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh.
@ -794,17 +795,17 @@ current interfaces.
@rnindex open-input-file
@deffn {Scheme Procedure} open-input-file filename
Open @var{filename} for input. Equivalent to
@smalllisp
@lisp
(open-file @var{filename} "r")
@end smalllisp
@end lisp
@end deffn
@rnindex open-output-file
@deffn {Scheme Procedure} open-output-file filename
Open @var{filename} for output. Equivalent to
@smalllisp
@lisp
(open-file @var{filename} "w")
@end smalllisp
@end lisp
@end deffn
@deffn {Scheme Procedure} call-with-input-file filename proc
@ -1023,6 +1024,269 @@ documentation for @code{open-file} in @ref{File Ports}.
@end deffn
@node R6RS I/O Ports
@subsection R6RS I/O Ports
@cindex R6RS
@cindex R6RS ports
The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
io ports)} module. It provides features, such as binary I/O and Unicode
string I/O, that complement or refine Guile's historical port API
presented above (@pxref{Input and Output}).
@c FIXME: Update description when implemented.
@emph{Note}: The implementation of this R6RS API is currently far from
complete, notably due to the lack of support for Unicode I/O and strings.
@menu
* R6RS End-of-File:: The end-of-file object.
* R6RS Port Manipulation:: Manipulating R6RS ports.
* R6RS Binary Input:: Binary input.
* R6RS Binary Output:: Binary output.
@end menu
@node R6RS End-of-File
@subsubsection The End-of-File Object
@cindex EOF
@cindex end-of-file
R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
ports)} module:
@deffn {Scheme Procedure} eof-object? obj
@deffnx {C Function} scm_eof_object_p (obj)
Return true if @var{obj} is the end-of-file (EOF) object.
@end deffn
In addition, the following procedure is provided:
@deffn {Scheme Procedure} eof-object
@deffnx {C Function} scm_eof_object ()
Return the end-of-file (EOF) object.
@lisp
(eof-object? (eof-object))
@result{} #t
@end lisp
@end deffn
@node R6RS Port Manipulation
@subsubsection Port Manipulation
The procedures listed below operate on any kind of R6RS I/O port.
@deffn {Scheme Procedure} port-position port
If @var{port} supports it (see below), return the offset (an integer)
indicating where the next octet will be read from/written to in
@var{port}. If @var{port} does not support this operation, an error
condition is raised.
This is similar to Guile's @code{seek} procedure with the
@code{SEEK_CUR} argument (@pxref{Random Access}).
@end deffn
@deffn {Scheme Procedure} port-has-port-position? port
Return @code{#t} is @var{port} supports @code{port-position}.
@end deffn
@deffn {Scheme Procedure} set-port-position! port offset
If @var{port} supports it (see below), set the position where the next
octet will be read from/written to @var{port} to @var{offset} (an
integer). If @var{port} does not support this operation, an error
condition is raised.
This is similar to Guile's @code{seek} procedure with the
@code{SEEK_SET} argument (@pxref{Random Access}).
@end deffn
@deffn {Scheme Procedure} port-has-set-port-position!? port
Return @code{#t} is @var{port} supports @code{set-port-position!}.
@end deffn
@deffn {Scheme Procedure} call-with-port port proc
Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
of @var{proc}. Return the return values of @var{proc}.
@end deffn
@node R6RS Binary Input
@subsubsection Binary Input
@cindex binary input
R6RS binary input ports can be created with the procedures described
below.
@deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
@deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
Return an input port whose contents are drawn from bytevector @var{bv}
(@pxref{Bytevectors}).
@c FIXME: Update description when implemented.
The @var{transcoder} argument is currently not supported.
@end deffn
@cindex custom binary input ports
@deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
@deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
Return a new custom binary input port@footnote{This is similar in spirit
to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
string) whose input is drained by invoking @var{read!} and passing it a
bytevector, an index where bytes should be written, and the number of
bytes to read. The @code{read!} procedure must return an integer
indicating the number of bytes read, or @code{0} to indicate the
end-of-file.
Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
that will be called when @var{port-position} is invoked on the custom
binary port and should return an integer indicating the position within
the underlying data stream; if @var{get-position} was not supplied, the
returned port does not support @var{port-position}.
Likewise, if @var{set-position!} is not @code{#f}, it should be a
one-argument procedure. When @var{set-port-position!} is invoked on the
custom binary input port, @var{set-position!} is passed an integer
indicating the position of the next byte is to read.
Finally, if @var{close} is not @code{#f}, it must be a thunk. It is
invoked when the custom binary input port is closed.
Using a custom binary input port, the @code{open-bytevector-input-port}
procedure could be implemented as follows:
@lisp
(define (open-bytevector-input-port source)
(define position 0)
(define length (bytevector-length source))
(define (read! bv start count)
(let ((count (min count (- length position))))
(bytevector-copy! source position
bv start count)
(set! position (+ position count))
count))
(define (get-position) position)
(define (set-position! new-position)
(set! position new-position))
(make-custom-binary-input-port "the port" read!
get-position
set-position!))
(read (open-bytevector-input-port (string->utf8 "hello")))
@result{} hello
@end lisp
@end deffn
@cindex binary input
Binary input is achieved using the procedures below:
@deffn {Scheme Procedure} get-u8 port
@deffnx {C Function} scm_get_u8 (port)
Return an octet read from @var{port}, a binary input port, blocking as
necessary, or the end-of-file object.
@end deffn
@deffn {Scheme Procedure} lookahead-u8 port
@deffnx {C Function} scm_lookahead_u8 (port)
Like @code{get-u8} but does not update @var{port}'s position to point
past the octet.
@end deffn
@deffn {Scheme Procedure} get-bytevector-n port count
@deffnx {C Function} scm_get_bytevector_n (port, count)
Read @var{count} octets from @var{port}, blocking as necessary and
return a bytevector containing the octets read. If fewer bytes are
available, a bytevector smaller than @var{count} is returned.
@end deffn
@deffn {Scheme Procedure} get-bytevector-n! port bv start count
@deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count)
Read @var{count} bytes from @var{port} and store them in @var{bv}
starting at index @var{start}. Return either the number of bytes
actually read or the end-of-file object.
@end deffn
@deffn {Scheme Procedure} get-bytevector-some port
@deffnx {C Function} scm_get_bytevector_some (port)
Read from @var{port}, blocking as necessary, until data are available or
and end-of-file is reached. Return either a new bytevector containing
the data read or the end-of-file object.
@end deffn
@deffn {Scheme Procedure} get-bytevector-all port
@deffnx {C Function} scm_get_bytevector_all (port)
Read from @var{port}, blocking as necessary, until the end-of-file is
reached. Return either a new bytevector containing the data read or the
end-of-file object (if no data were available).
@end deffn
@node R6RS Binary Output
@subsubsection Binary Output
Binary output ports can be created with the procedures below.
@deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
@deffnx {C Function} scm_open_bytevector_output_port (transcoder)
Return two values: a binary output port and a procedure. The latter
should be called with zero arguments to obtain a bytevector containing
the data accumulated by the port, as illustrated below.
@lisp
(call-with-values
(lambda ()
(open-bytevector-output-port))
(lambda (port get-bytevector)
(display "hello" port)
(get-bytevector)))
@result{} #vu8(104 101 108 108 111)
@end lisp
@c FIXME: Update description when implemented.
The @var{transcoder} argument is currently not supported.
@end deffn
@cindex custom binary output ports
@deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
@deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close)
Return a new custom binary output port named @var{id} (a string) whose
output is sunk by invoking @var{write!} and passing it a bytevector, an
index where bytes should be read from this bytevector, and the number of
bytes to be ``written''. The @code{write!} procedure must return an
integer indicating the number of bytes actually written; when it is
passed @code{0} as the number of bytes to write, it should behave as
though an end-of-file was sent to the byte sink.
The other arguments are as for @code{make-custom-binary-input-port}
(@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
@end deffn
@cindex binary output
Writing to a binary output port can be done using the following
procedures:
@deffn {Scheme Procedure} put-u8 port octet
@deffnx {C Function} scm_put_u8 (port, octet)
Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
binary output port.
@end deffn
@deffn {Scheme Procedure} put-bytevector port bv [start [count]]
@deffnx {C Function} scm_put_bytevector (port, bv, start, count)
Write the contents of @var{bv} to @var{port}, optionally starting at
index @var{start} and limiting to @var{count} octets.
@end deffn
@node I/O Extensions
@subsection Using and Extending Ports in C
@ -1267,7 +1531,7 @@ implementations take care to avoid this problem.
The procedure is set using
@deftypefun void scm_set_port_seek (scm_t_bits tc, off_t (*seek) (SCM port, off_t offset, int whence))
@deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
@end deftypefun
@item truncate
@ -1275,7 +1539,7 @@ Truncate the port data to be specified length. It can be assumed that the
current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
Set using
@deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, off_t length))
@deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length))
@end deftypefun
@end table

4
doc/ref/api-memory.texi
View file

@ -10,7 +10,7 @@
Guile uses a @emph{garbage collector} to manage most of its objects.
While the garbage collector is designed to be mostly invisible, you
sometimes need to interact with it explicitely.
sometimes need to interact with it explicitly.
See @ref{Garbage Collection} for a general discussion of how garbage
collection relates to using Guile from C.
@ -201,7 +201,7 @@ below for a motivation.
@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
Note that you need to explicitely pass the @var{size} parameter. This
Note that you need to explicitly pass the @var{size} parameter. This
is done since it should normally be easy to provide this parameter
(for memory that is associated with GC controlled objects) and this
frees us from tracking this value in the GC itself, which will keep

46
doc/ref/api-modules.texi
View file

@ -60,15 +60,15 @@ Library files in SLIB @emph{provide} a feature, and when user programs
For example, the file @file{random.scm} in the SLIB package contains the
line
@smalllisp
@lisp
(provide 'random)
@end smalllisp
@end lisp
so to use its procedures, a user would type
@smalllisp
@lisp
(require 'random)
@end smalllisp
@end lisp
and they would magically become available, @emph{but still have the same
names!} So this method is nice, but not as good as a full-featured
@ -99,9 +99,9 @@ i.e., passed as the second argument to @code{eval}.
Note: the following two procedures are available only when the
@code{(ice-9 r5rs)} module is loaded:
@smalllisp
@lisp
(use-modules (ice-9 r5rs))
@end smalllisp
@end lisp
@deffn {Scheme Procedure} scheme-report-environment version
@deffnx {Scheme Procedure} null-environment version
@ -224,9 +224,9 @@ An @dfn{interface specification} has one of two forms. The first
variation is simply to name the module, in which case its public
interface is the one accessed. For example:
@smalllisp
@lisp
(use-modules (ice-9 popen))
@end smalllisp
@end lisp
Here, the interface specification is @code{(ice-9 popen)}, and the
result is that the current module now has access to @code{open-pipe},
@ -241,11 +241,11 @@ module to be accessed, but also selects bindings from it and renames
them to suit the current module's needs. For example:
@cindex binding renamer
@smalllisp
@lisp
(use-modules ((ice-9 popen)
:select ((open-pipe . pipe-open) close-pipe)
:renamer (symbol-prefix-proc 'unixy:)))
@end smalllisp
#:select ((open-pipe . pipe-open) close-pipe)
#:renamer (symbol-prefix-proc 'unixy:)))
@end lisp
Here, the interface specification is more complex than before, and the
result is that a custom interface with only two bindings is created and
@ -270,10 +270,10 @@ You can also directly refer to bindings in a module by using the
open-pipe)}. Thus an alternative to the complete @code{use-modules}
statement would be
@smalllisp
@lisp
(define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
(define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
@end smalllisp
@end lisp
There is also @code{@@@@}, which can be used like @code{@@}, but does
not check whether the variable that is being accessed is actually
@ -307,9 +307,9 @@ whose public interface is found and used.
@var{spec} can also be of the form:
@cindex binding renamer
@smalllisp
@lisp
(MODULE-NAME [:select SELECTION] [:renamer RENAMER])
@end smalllisp
@end lisp
in which case a custom interface is newly created and used.
@var{module-name} is a list of symbols, as above; @var{selection} is a
@ -373,9 +373,9 @@ by using @code{define-public} or @code{export} (both documented below).
@var{module-name} is of the form @code{(hierarchy file)}. One
example of this is
@smalllisp
@lisp
(define-module (ice-9 popen))
@end smalllisp
@end lisp
@code{define-module} makes this module available to Guile programs under
the given @var{module-name}.
@ -541,9 +541,9 @@ duplication to the next handler in @var{list}.
The default duplicate binding resolution policy is given by the
@code{default-duplicate-binding-handler} procedure, and is
@smalllisp
@lisp
(replace warn-override-core warn last)
@end smalllisp
@end lisp
@item #:no-backtrace
@cindex no backtrace
@ -758,7 +758,7 @@ Record definition with @code{define-record-type} (@pxref{SRFI-9}).
Read hash extension @code{#,()} (@pxref{SRFI-10}).
@item (srfi srfi-11)
Multiple-value handling with @code{let-values} and @code{let-values*}
Multiple-value handling with @code{let-values} and @code{let*-values}
(@pxref{SRFI-11}).
@item (srfi srfi-13)
@ -1138,12 +1138,12 @@ gcc -shared -o libbessel.so -fPIC bessel.c
Now fire up Guile:
@smalllisp
@lisp
(define bessel-lib (dynamic-link "./libbessel.so"))
(dynamic-call "init_math_bessel" bessel-lib)
(j0 2)
@result{} 0.223890779141236
@end smalllisp
@end lisp
The filename @file{./libbessel.so} should be pointing to the shared
library produced with the @code{gcc} command above, of course. The

15
doc/ref/api-options.texi
View file

@ -82,10 +82,11 @@ general are stored. On Unix-like systems, this is usually
@deffnx {C Function} scm_sys_library_dir ()
Return the name of the directory where the Guile Scheme files that
belong to the core Guile installation (as opposed to files from a 3rd
party package) are installed. On Unix-like systems, this is usually
party package) are installed. On Unix-like systems this is usually
@file{/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or
@file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>}, for example:
@file{/usr/local/share/guile/1.6}.
@file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
@noindent for example @file{/usr/local/share/guile/1.6}.
@end deffn
@deffn {Scheme Procedure} %site-dir
@ -503,9 +504,9 @@ Guile is case-sensitive by default.
To make Guile case insensitive, you can type
@smalllisp
@lisp
(read-enable 'case-insensitive)
@end smalllisp
@end lisp
@node Printing options
@subsubsection Printing options
@ -680,7 +681,8 @@ the maximum stack size, use @code{debug-set!}, for example:
@lisp
(debug-set! stack 200000)
@result{}
(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
(show-file-name #t stack 200000 debug backtrace depth 20
maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
(non-tail-recursive-factorial 500)
@result{}
@ -717,7 +719,6 @@ backtrace. Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate
@smalllisp
guile> (define abc "hello")
guile> abc

151
doc/ref/api-procedures.texi
View file

@ -11,6 +11,7 @@
@menu
* Lambda:: Basic procedure creation using lambda.
* Primitive Procedures:: Procedures defined in C.
* Compiled Procedures:: Scheme procedures can be compiled.
* Optional Arguments:: Handling keyword, optional and rest arguments.
* Procedure Properties:: Procedure properties and meta-information.
* Procedures with Setters:: Procedures with setters.
@ -131,6 +132,156 @@ 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
Procedures that were created when loading a compiled file are
themselves compiled. (In contrast, procedures that are defined by
loading a Scheme source file are interpreted, and often not as fast as
compiled procedures.)
Loading compiled files is the normal way that compiled procedures come
to being, though procedures can be compiled at runtime as well.
@xref{Read/Load/Eval/Compile}, for more information on runtime
compilation.
Compiled procedures, also known as @dfn{programs}, respond all
procedures that operate on procedures. In addition, there are a few
more accessors for low-level details on programs.
Most people won't need to use the routines described in this section,
but it's good to have them documented. You'll have to include the
appropriate module first, though:
@example
(use-modules (system vm program))
@end example
@deffn {Scheme Procedure} program? obj
@deffnx {C Function} scm_program_p (obj)
Returns @code{#t} iff @var{obj} is a compiled procedure.
@end deffn
@deffn {Scheme Procedure} program-objcode program
@deffnx {C Function} scm_program_objcode (program)
Returns the object code associated with this program. @xref{Bytecode
and Objcode}, for more information.
@end deffn
@deffn {Scheme Procedure} program-objects program
@deffnx {C Function} scm_program_objects (program)
Returns the ``object table'' associated with this program, as a
vector. @xref{VM Programs}, for more information.
@end deffn
@deffn {Scheme Procedure} program-module program
@deffnx {C Function} scm_program_module (program)
Returns the module that was current when this program was created. Can
return @code{#f} if the compiler could determine that this information
was unnecessary.
@end deffn
@deffn {Scheme Procedure} program-external program
@deffnx {C Function} scm_program_external (program)
Returns the set of heap-allocated variables that this program captures
in its closure, as a list. If a closure is code with data, you can get
the code from @code{program-bytecode}, and the data via
@code{program-external}.
Users must not modify the returned value unless they think they're
really clever.
@end deffn
@deffn {Scheme Procedure} program-external-set! program external
@deffnx {C Function} scm_program_external_set_x (program, external)
Set @var{external} as the set of closure variables on @var{program}.
The Guile maintainers will not be held responsible for side effects of
calling this function, including but not limited to replacement of
shampoo with hair dye, and a slight salty taste in tomorrow's dinner.
@end deffn
@deffn {Scheme Procedure} program-arity program
@deffnx {C Function} scm_program_arity (program)
@deffnx {Scheme Procedure} arity:nargs arity
@deffnx {Scheme Procedure} arity:nrest arity
@deffnx {Scheme Procedure} arity:nlocs arity
@deffnx {Scheme Procedure} arity:nexts arity
Accessors for a representation of the ``arity'' of a program.
@code{nargs} is the number of arguments to the procedure, and
@code{nrest} will be non-zero if the last argument is a rest argument.
The other two accessors determine the number of local and external
(heap-allocated) variables that this procedure will need to have
allocated.
@end deffn
@deffn {Scheme Procedure} program-meta program
@deffnx scm_program_meta (program)
Return the metadata thunk of @var{program}, or @code{#f} if it has no
metadata.
When called, a metadata thunk returns a list of the following form:
@code{(@var{bindings} @var{sources} . @var{properties})}. The format
of each of these elements is discussed below.
@end deffn
@deffn {Scheme Procedure} program-bindings program
@deffnx {Scheme Procedure} make-binding name extp index start end
@deffnx {Scheme Procedure} binding:name binding
@deffnx {Scheme Procedure} binding:extp binding
@deffnx {Scheme Procedure} binding:index binding
@deffnx {Scheme Procedure} binding:start binding
@deffnx {Scheme Procedure} binding:end binding
Bindings annotations for programs, along with their accessors.
Bindings declare names and liveness extents for block-local variables.
The best way to see what these are is to play around with them at a
REPL. The only tricky bit is that @var{extp} is a boolean, declaring
whether the binding is heap-allocated or not. @xref{VM Concepts}, for
more information.
Note that bindings information is stored in a program as part of its
metadata thunk, so including it in the generated object code does not
impose a runtime performance penalty.
@end deffn
@deffn {Scheme Procedure} program-sources program
@deffnx {Scheme Procedure} source:addr source
@deffnx {Scheme Procedure} source:line source
@deffnx {Scheme Procedure} source:column source
@deffnx {Scheme Procedure} source:file source
Source location annotations for programs, along with their accessors.
Source location information propagates through the compiler and ends
up being serialized to the program's metadata. This information is
keyed by the offset of the instruction pointer within the object code
of the program. Specifically, it is keyed on the @code{ip} @emph{just
following} an instruction, so that backtraces can find the source
location of a call that is in progress.
@end deffn
@deffn {Scheme Procedure} program-properties program
Return the properties of a @code{program} as an association list,
keyed by property name (a symbol).
Some interesting properties include:
@itemize
@item @code{name}, the name of the procedure
@item @code{documentation}, the procedure's docstring
@end itemize
@end deffn
@deffn {Scheme Procedure} program-property program name
Access a program's property by name, returning @code{#f} if not found.
@end deffn
@deffn {Scheme Procedure} program-documentation program
@deffnx {Scheme Procedure} program-name program
Accessors for specific properties.
@end deffn
@node Optional Arguments
@subsection Optional Arguments

63
doc/ref/api-scheduling.texi
View file

@ -8,14 +8,9 @@
@node Scheduling
@section Threads, Mutexes, Asyncs and Dynamic Roots
[FIXME: This is pasted in from Tom Lord's original guile.texi chapter
plus the Cygnus programmer's manual; it should be *very* carefully
reviewed and largely reorganized.]
@menu
* Arbiters:: Synchronization primitives.
* Asyncs:: Asynchronous procedure invocation.
* Continuation Barriers:: Protection from non-local control flow.
* Threads:: Multiple threads of execution.
* Mutexes and Condition Variables:: Synchronization primitives.
* Blocking:: How to block properly in guile mode.
@ -47,7 +42,6 @@ process synchronization.
@deffn {Scheme Procedure} try-arbiter arb
@deffnx {C Function} scm_try_arbiter (arb)
@deffnx {C Function} scm_try_arbiter (arb)
If @var{arb} is unlocked, then lock it and return @code{#t}.
If @var{arb} is already locked, then do nothing and return
@code{#f}.
@ -70,7 +64,7 @@ release it, but that's not required, any thread can release it.
@cindex user asyncs
@cindex system asyncs
Asyncs are a means of deferring the excution of Scheme code until it is
Asyncs are a means of deferring the execution of Scheme code until it is
safe to do so.
Guile provides two kinds of asyncs that share the basic concept but are
@ -132,43 +126,42 @@ This procedure is not safe to be called from signal handlers. Use
signal handlers.
@end deffn
@c FIXME: The use of @deffnx for scm_c_call_with_blocked_asyncs and
@c scm_c_call_with_unblocked_asyncs puts "void" into the function
@c index. Would prefer to use @deftypefnx if makeinfo allowed that,
@c or a @deftypefn with an empty return type argument if it didn't
@c introduce an extra space.
@deffn {Scheme Procedure} call-with-blocked-asyncs proc
@deffnx {C Function} scm_call_with_blocked_asyncs (proc)
@deffnx {C Function} {void *} scm_c_call_with_blocked_asyncs (void * (*proc) (void *data), void *data)
@findex scm_c_call_with_blocked_asyncs
Call @var{proc} and block the execution of system asyncs by one level
for the current thread while it is running. Return the value returned
by @var{proc}. For the first two variants, call @var{proc} with no
arguments; for the third, call it with @var{data}.
@end deffn
@deftypefn {C Function} {void *} scm_c_call_with_blocked_asyncs (void * (*proc) (void *data), void *data)
The same but with a C function @var{proc} instead of a Scheme thunk.
@end deftypefn
@deffn {Scheme Procedure} call-with-unblocked-asyncs proc
@deffnx {C Function} scm_call_with_unblocked_asyncs (proc)
@deffnx {C Function} {void *} scm_c_call_with_unblocked_asyncs (void *(*p) (void *d), void *d)
@findex scm_c_call_with_unblocked_asyncs
Call @var{proc} and unblock the execution of system asyncs by one
level for the current thread while it is running. Return the value
returned by @var{proc}. For the first two variants, call @var{proc}
with no arguments; for the third, call it with @var{data}.
@end deffn
@deftypefn {C Function} {void *} scm_c_call_with_unblocked_asyncs (void *(*proc) (void *data), void *data)
The same but with a C function @var{proc} instead of a Scheme thunk.
@end deftypefn
@deftypefn {C Function} void scm_dynwind_block_asyncs ()
This function must be used inside a pair of calls to
During the current dynwind context, increase the blocking of asyncs by
one level. This function must be used inside a pair of calls to
@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
Wind}). During the dynwind context, asyncs are blocked by one level.
Wind}).
@end deftypefn
@deftypefn {C Function} void scm_dynwind_unblock_asyncs ()
This function must be used inside a pair of calls to
During the current dynwind context, decrease the blocking of asyncs by
one level. This function must be used inside a pair of calls to
@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
Wind}). During the dynwind context, asyncs are unblocked by one
level.
Wind}).
@end deftypefn
@node User asyncs
@ -197,32 +190,6 @@ Mark the user async @var{a} for future execution.
Execute all thunks from the marked asyncs of the list @var{list_of_a}.
@end deffn
@node Continuation Barriers
@subsection Continuation Barriers
The non-local flow of control caused by continuations might sometimes
not be wanted. You can use @code{with-continuation-barrier} etc to
errect fences that continuations can not pass.
@deffn {Scheme Procedure} with-continuation-barrier proc
@deffnx {C Function} scm_with_continuation_barrier (proc)
Call @var{proc} and return its result. Do not allow the invocation of
continuations that would leave or enter the dynamic extent of the call
to @code{with-continuation-barrier}. Such an attempt causes an error
to be signaled.
Throws (such as errors) that are not caught from within @var{proc} are
caught by @code{with-continuation-barrier}. In that case, a short
message is printed to the current error port and @code{#f} is returned.
Thus, @code{with-continuation-barrier} returns exactly once.
@end deffn
@deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
Like @code{scm_with_continuation_barrier} but call @var{func} on
@var{data}. When an error is caught, @code{NULL} is returned.
@end deftypefn
@node Threads
@subsection Threads
@cindex threads

2
doc/ref/api-undocumented.texi
View file

@ -257,7 +257,7 @@ otherwise return the first argument.
@deffn {Scheme Procedure} system-async thunk
@deffnx {C Function} scm_system_async (thunk)
This function is deprecated. You can use @var{thunk} directly
instead of explicitely creating an async object.
instead of explicitly creating an async object.
@end deffn

19
doc/ref/autoconf.texi
View file

@ -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
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -48,19 +48,18 @@ checks.
@cindex pkg-config
@cindex autoconf
GNU Guile provides a @dfn{pkg-config} description file, installed as
@file{@var{prefix}/lib/pkgconfig/guile-1.8.pc}, which contains all the
information necessary to compile and link C applications that use Guile.
The @code{pkg-config} program is able to read this file and provide this
information to application programmers; it can be obtained at
@url{http://pkg-config.freedesktop.org/}.
GNU Guile provides a @dfn{pkg-config} description file, which contains
all the information necessary to compile and link C applications that
use Guile. The @code{pkg-config} program is able to read this file
and provide this information to application programmers; it can be
obtained at @url{http://pkg-config.freedesktop.org/}.
The following command lines give respectively the C compilation and link
flags needed to build Guile-using programs:
@example
pkg-config guile-1.8 --cflags
pkg-config guile-1.8 --libs
pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
pkg-config guile-@value{EFFECTIVE-VERSION} --libs
@end example
To ease use of pkg-config with Autoconf, pkg-config comes with a
@ -71,7 +70,7 @@ accordingly, or prints an error and exits if Guile was not found:
@findex PKG_CHECK_MODULES
@example
PKG_CHECK_MODULES([GUILE], [guile-1.8])
PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
@end example
Guile comes with additional Autoconf macros providing more information,

785
doc/ref/compiler.texi Normal file
View file

@ -0,0 +1,785 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 2008, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Compiling to the Virtual Machine
@section Compiling to the Virtual Machine
Compilers have a mystique about them that is attractive and
off-putting at the same time. They are attractive because they are
magical -- they transform inert text into live results, like throwing
the switch on Frankenstein's monster. However, this magic is perceived
by many to be impenetrable.
This section aims to pay attention to the small man behind the
curtain.
@xref{Read/Load/Eval/Compile}, if you're lost and you just wanted to
know how to compile your @code{.scm} file.
@menu
* Compiler Tower::
* The Scheme Compiler::
* Tree-IL::
* GLIL::
* Assembly::
* Bytecode and Objcode::
* Writing New High-Level Languages::
* Extending the Compiler::
@end menu
@node Compiler Tower
@subsection Compiler Tower
Guile's compiler is quite simple, actually -- its @emph{compilers}, to
put it more accurately. Guile defines a tower of languages, starting
at Scheme and progressively simplifying down to languages that
resemble the VM instruction set (@pxref{Instruction Set}).
Each language knows how to compile to the next, so each step is simple
and understandable. Furthermore, this set of languages is not
hardcoded into Guile, so it is possible for the user to add new
high-level languages, new passes, or even different compilation
targets.
Languages are registered in the module, @code{(system base language)}:
@example
(use-modules (system base language))
@end example
They are registered with the @code{define-language} form.
@deffn {Scheme Syntax} define-language @
name title version reader printer @
[parser=#f] [compilers='()] [decompilers='()] [evaluator=#f]
Define a language.
This syntax defines a @code{#<language>} object, bound to @var{name}
in the current environment. In addition, the language will be added to
the global language set. For example, this is the language definition
for Scheme:
@example
(define-language scheme
#:title "Guile Scheme"
#:version "0.5"
#:reader read
#:compilers `((tree-il . ,compile-tree-il))
#:decompilers `((tree-il . ,decompile-tree-il))
#:evaluator (lambda (x module) (primitive-eval x))
#:printer write)
@end example
@end deffn
The interesting thing about having languages defined this way is that
they present a uniform interface to the read-eval-print loop. This
allows the user to change the current language of the REPL:
@example
$ guile
Guile Scheme interpreter 0.5 on Guile 1.9.0
Copyright (C) 2001-2008 Free Software Foundation, Inc.
Enter `,help' for help.
scheme@@(guile-user)> ,language tree-il
Tree Intermediate Language interpreter 1.0 on Guile 1.9.0
Copyright (C) 2001-2008 Free Software Foundation, Inc.
Enter `,help' for help.
tree-il@@(guile-user)>
@end example
Languages can be looked up by name, as they were above.
@deffn {Scheme Procedure} lookup-language name
Looks up a language named @var{name}, autoloading it if necessary.
Languages are autoloaded by looking for a variable named @var{name} in
a module named @code{(language @var{name} spec)}.
The language object will be returned, or @code{#f} if there does not
exist a language with that name.
@end deffn
Defining languages this way allows us to programmatically determine
the necessary steps for compiling code from one language to another.
@deffn {Scheme Procedure} lookup-compilation-order from to
Recursively traverses the set of languages to which @var{from} can
compile, depth-first, and return the first path that can transform
@var{from} to @var{to}. Returns @code{#f} if no path is found.
This function memoizes its results in a cache that is invalidated by
subsequent calls to @code{define-language}, so it should be quite
fast.
@end deffn
There is a notion of a ``current language'', which is maintained in
the @code{*current-language*} fluid. This language is normally Scheme,
and may be rebound by the user. The run-time compilation interfaces
(@pxref{Read/Load/Eval/Compile}) also allow you to choose other source
and target languages.
The normal tower of languages when compiling Scheme goes like this:
@itemize
@item Scheme, which we know and love
@item Tree Intermediate Language (Tree-IL)
@item Guile Low Intermediate Language (GLIL)
@item Assembly
@item Bytecode
@item Objcode
@end itemize
Object code may be serialized to disk directly, though it has a cookie
and version prepended to the front. But when compiling Scheme at run
time, you want a Scheme value: for example, a compiled procedure. For
this reason, so as not to break the abstraction, Guile defines a fake
language at the bottom of the tower:
@itemize
@item Value
@end itemize
Compiling to @code{value} loads the object code into a procedure, and
wakes the sleeping giant.
Perhaps this strangeness can be explained by example:
@code{compile-file} defaults to compiling to object code, because it
produces object code that has to live in the barren world outside the
Guile runtime; but @code{compile} defaults to compiling to
@code{value}, as its product re-enters the Guile world.
Indeed, the process of compilation can circulate through these
different worlds indefinitely, as shown by the following quine:
@example
((lambda (x) ((compile x) x)) '(lambda (x) ((compile x) x)))
@end example
@node The Scheme Compiler
@subsection The Scheme Compiler
The job of the Scheme compiler is to expand all macros and all of
Scheme to its most primitive expressions. The definition of
``primitive'' is given by the inventory of constructs provided by
Tree-IL, the target language of the Scheme compiler: procedure
applications, conditionals, lexical references, etc. This is described
more fully in the next section.
The tricky and amusing thing about the Scheme-to-Tree-IL compiler is
that it is completely implemented by the macro expander. Since the
macro expander has to run over all of the source code already in order
to expand macros, it might as well do the analysis at the same time,
producing Tree-IL expressions directly.
Because this compiler is actually the macro expander, it is
extensible. Any macro which the user writes becomes part of the
compiler.
The Scheme-to-Tree-IL expander may be invoked using the generic
@code{compile} procedure:
@lisp
(compile '(+ 1 2) #:from 'scheme #:to 'tree-il)
@result{}
#<<application> src: #f
proc: #<<toplevel-ref> src: #f name: +>
args: (#<<const> src: #f exp: 1>
#<<const> src: #f exp: 2>)>
@end lisp
Or, since Tree-IL is so close to Scheme, it is often useful to expand
Scheme to Tree-IL, then translate back to Scheme. For that reason the
expander provides two interfaces. The former is equivalent to calling
@code{(sc-expand '(+ 1 2) 'c)}, where the @code{'c} is for
``compile''. With @code{'e} (the default), the result is translated
back to Scheme:
@lisp
(sc-expand '(+ 1 2))
@result{} (+ 1 2)
(sc-expand '(let ((x 10)) (* x x)))
@result{} (let ((x84 10)) (* x84 x84))
@end lisp
The second example shows that as part of its job, the macro expander
renames lexically-bound variables. The original names are preserved
when compiling to Tree-IL, but can't be represented in Scheme: a
lexical binding only has one name. It is for this reason that the
@emph{native} output of the expander is @emph{not} Scheme. There's too
much information we would lose if we translated to Scheme directly:
lexical variable names, source locations, and module hygiene.
Note however that @code{sc-expand} does not have the same signature as
@code{compile-tree-il}. @code{compile-tree-il} is a small wrapper
around @code{sc-expand}, to make it conform to the general form of
compiler procedures in Guile's language tower.
Compiler procedures take three arguments: an expression, an
environment, and a keyword list of options. They return three values:
the compiled expression, the corresponding environment for the target
language, and a ``continuation environment''. The compiled expression
and environment will serve as input to the next language's compiler.
The ``continuation environment'' can be used to compile another
expression from the same source language within the same module.
For example, you might compile the expression, @code{(define-module
(foo))}. This will result in a Tree-IL expression and environment. But
if you compiled a second expression, you would want to take into
account the compile-time effect of compiling the previous expression,
which puts the user in the @code{(foo)} module. That is purpose of the
``continuation environment''; you would pass it as the environment
when compiling the subsequent expression.
For Scheme, an environment may be one of two things:
@itemize
@item @code{#f}, in which case compilation is performed in the context
of the current module; or
@item a module, which specifies the context of the compilation.
@end itemize
@node Tree-IL
@subsection Tree-IL
Tree Intermediate Language (Tree-IL) is a structured intermediate
language that is close in expressive power to Scheme. It is an
expanded, pre-analyzed Scheme.
Tree-IL is ``structured'' in the sense that its representation is
based on records, not S-expressions. This gives a rigidity to the
language that ensures that compiling to a lower-level language only
requires a limited set of transformations. Practically speaking,
consider the Tree-IL type, @code{<const>}, which has two fields,
@code{src} and @code{exp}. Instances of this type are records created
via @code{make-const}, and whose fields are accessed as
@code{const-src}, and @code{const-exp}. There is also a predicate,
@code{const?}. @xref{Records}, for more information on records.
@c alpha renaming
All Tree-IL types have a @code{src} slot, which holds source location
information for the expression. This information, if present, will be
residualized into the compiled object code, allowing backtraces to
show source information. The format of @code{src} is the same as that
returned by Guile's @code{source-properties} function. @xref{Source
Properties}, for more information.
Although Tree-IL objects are represented internally using records,
there is also an equivalent S-expression external representation for
each kind of Tree-IL. For example, an the S-expression representation
of @code{#<const src: #f exp: 3>} expression would be:
@example
(const 3)
@end example
Users may program with this format directly at the REPL:
@example
scheme@@(guile-user)> ,language tree-il
Tree Intermediate Language interpreter 1.0 on Guile 1.9.0
Copyright (C) 2001-2008 Free Software Foundation, Inc.
Enter `,help' for help.
tree-il@@(guile-user)> (apply (primitive +) (const 32) (const 10))
@result{} 42
@end example
The @code{src} fields are left out of the external representation.
One may create Tree-IL objects from their external representations via
calling @code{parse-tree-il}, the reader for Tree-IL. If any source
information is attached to the input S-expression, it will be
propagated to the resulting Tree-IL expressions. This is probably the
easiest way to compile to Tree-IL: just make the appropriate external
representations in S-expression format, and let @code{parse-tree-il}
take care of the rest.
@deftp {Scheme Variable} <void> src
@deftpx {External Representation} (void)
An empty expression. In practice, equivalent to Scheme's @code{(if #f
#f)}.
@end deftp
@deftp {Scheme Variable} <const> src exp
@deftpx {External Representation} (const @var{exp})
A constant.
@end deftp
@deftp {Scheme Variable} <primitive-ref> src name
@deftpx {External Representation} (primitive @var{name})
A reference to a ``primitive''. A primitive is a procedure that, when
compiled, may be open-coded. For example, @code{cons} is usually
recognized as a primitive, so that it compiles down to a single
instruction.
Compilation of Tree-IL usually begins with a pass that resolves some
@code{<module-ref>} and @code{<toplevel-ref>} expressions to
@code{<primitive-ref>} expressions. The actual compilation pass
has special cases for applications of certain primitives, like
@code{apply} or @code{cons}.
@end deftp
@deftp {Scheme Variable} <lexical-ref> src name gensym
@deftpx {External Representation} (lexical @var{name} @var{gensym})
A reference to a lexically-bound variable. The @var{name} is the
original name of the variable in the source program. @var{gensym} is a
unique identifier for this variable.
@end deftp
@deftp {Scheme Variable} <lexical-set> src name gensym exp
@deftpx {External Representation} (set! (lexical @var{name} @var{gensym}) @var{exp})
Sets a lexically-bound variable.
@end deftp
@deftp {Scheme Variable} <module-ref> src mod name public?
@deftpx {External Representation} (@@ @var{mod} @var{name})
@deftpx {External Representation} (@@@@ @var{mod} @var{name})
A reference to a variable in a specific module. @var{mod} should be
the name of the module, e.g. @code{(guile-user)}.
If @var{public?} is true, the variable named @var{name} will be looked
up in @var{mod}'s public interface, and serialized with @code{@@};
otherwise it will be looked up among the module's private bindings,
and is serialized with @code{@@@@}.
@end deftp
@deftp {Scheme Variable} <module-set> src mod name public? exp
@deftpx {External Representation} (set! (@@ @var{mod} @var{name}) @var{exp})
@deftpx {External Representation} (set! (@@@@ @var{mod} @var{name}) @var{exp})
Sets a variable in a specific module.
@end deftp
@deftp {Scheme Variable} <toplevel-ref> src name
@deftpx {External Representation} (toplevel @var{name})
References a variable from the current procedure's module.
@end deftp
@deftp {Scheme Variable} <toplevel-set> src name exp
@deftpx {External Representation} (set! (toplevel @var{name}) @var{exp})
Sets a variable in the current procedure's module.
@end deftp
@deftp {Scheme Variable} <toplevel-define> src name exp
@deftpx {External Representation} (define (toplevel @var{name}) @var{exp})
Defines a new top-level variable in the current procedure's module.
@end deftp
@deftp {Scheme Variable} <conditional> src test then else
@deftpx {External Representation} (if @var{test} @var{then} @var{else})
A conditional. Note that @var{else} is not optional.
@end deftp
@deftp {Scheme Variable} <application> src proc args
@deftpx {External Representation} (apply @var{proc} . @var{args})
A procedure call.
@end deftp
@deftp {Scheme Variable} <sequence> src exps
@deftpx {External Representation} (begin . @var{exps})
Like Scheme's @code{begin}.
@end deftp
@deftp {Scheme Variable} <lambda> src names vars meta body
@deftpx {External Representation} (lambda @var{names} @var{vars} @var{meta} @var{body})
A closure. @var{names} is original binding form, as given in the
source code, which may be an improper list. @var{vars} are gensyms
corresponding to the @var{names}. @var{meta} is an association list of
properties. The actual @var{body} is a single Tree-IL expression.
@end deftp
@deftp {Scheme Variable} <let> src names vars vals exp
@deftpx {External Representation} (let @var{names} @var{vars} @var{vals} @var{exp})
Lexical binding, like Scheme's @code{let}. @var{names} are the
original binding names, @var{vars} are gensyms corresponding to the
@var{names}, and @var{vals} are Tree-IL expressions for the values.
@var{exp} is a single Tree-IL expression.
@end deftp
@deftp {Scheme Variable} <letrec> src names vars vals exp
@deftpx {External Representation} (letrec @var{names} @var{vars} @var{vals} @var{exp})
A version of @code{<let>} that creates recursive bindings, like
Scheme's @code{letrec}.
@end deftp
There are two Tree-IL constructs that are not normally produced by
higher-level compilers, but instead are generated during the
source-to-source optimization and analysis passes that the Tree-IL
compiler does. Users should not generate these expressions directly,
unless they feel very clever, as the default analysis pass will
generate them as necessary.
@deftp {Scheme Variable} <let-values> src names vars exp body
@deftpx {External Representation} (let-values @var{names} @var{vars} @var{exp} @var{body})
Like Scheme's @code{receive} -- binds the values returned by
evaluating @code{exp} to the @code{lambda}-like bindings described by
@var{vars}. That is to say, @var{vars} may be an improper list.
@code{<let-values>} is an optimization of @code{<application>} of the
primitive, @code{call-with-values}.
@end deftp
@deftp {Scheme Variable} <fix> src names vars vals body
@deftpx {External Representation} (fix @var{names} @var{vars} @var{vals} @var{body})
Like @code{<letrec>}, but only for @var{vals} that are unset
@code{lambda} expressions.
@code{fix} is an optimization of @code{letrec} (and @code{let}).
@end deftp
Tree-IL implements a compiler to GLIL that recursively traverses
Tree-IL expressions, writing out GLIL expressions into a linear list.
The compiler also keeps some state as to whether the current
expression is in tail context, and whether its value will be used in
future computations. This state allows the compiler not to emit code
for constant expressions that will not be used (e.g. docstrings), and
to perform tail calls when in tail position.
Most optimization, such as it currently is, is performed on Tree-IL
expressions as source-to-source transformations. There will be more
optimizations added in the future.
Interested readers are encouraged to read the implementation in
@code{(language tree-il compile-glil)} for more details.
@node GLIL
@subsection GLIL
Guile Low Intermediate Language (GLIL) is a structured intermediate
language whose expressions more closely approximate Guile's VM
instruction set. Its expression types are defined in @code{(language
glil)}.
@deftp {Scheme Variable} <glil-program> nargs nrest nlocs meta . body
A unit of code that at run-time will correspond to a compiled
procedure. @var{nargs} @var{nrest} and @var{nlocs} collectively define
the program's arity; see @ref{Compiled Procedures}, for more
information. @var{meta} should be an alist of properties, as in
Tree-IL's @code{<lambda>}. @var{body} is an ordered list of GLIL
expressions.
@end deftp
@deftp {Scheme Variable} <glil-bind> . vars
An advisory expression that notes a liveness extent for a set of
variables. @var{vars} is a list of @code{(@var{name} @var{type}
@var{index})}, where @var{type} should be either @code{argument},
@code{local}, or @code{external}.
@code{<glil-bind>} expressions end up being serialized as part of a
program's metadata and do not form part of a program's code path.
@end deftp
@deftp {Scheme Variable} <glil-mv-bind> vars rest
A multiple-value binding of the values on the stack to @var{vars}. Iff
@var{rest} is true, the last element of @var{vars} will be treated as
a rest argument.
In addition to pushing a binding annotation on the stack, like
@code{<glil-bind>}, an expression is emitted at compilation time to
make sure that there are enough values available to bind. See the
notes on @code{truncate-values} in @ref{Procedural Instructions}, for
more information.
@end deftp
@deftp {Scheme Variable} <glil-unbind>
Closes the liveness extent of the most recently encountered
@code{<glil-bind>} or @code{<glil-mv-bind>} expression. As GLIL
expressions are compiled, a parallel stack of live bindings is
maintained; this expression pops off the top element from that stack.
Bindings are written into the program's metadata so that debuggers and
other tools can determine the set of live local variables at a given
offset within a VM program.
@end deftp
@deftp {Scheme Variable} <glil-source> loc
Records source information for the preceding expression. @var{loc}
should be an association list of containing @code{line} @code{column},
and @code{filename} keys, e.g. as returned by
@code{source-properties}.
@end deftp
@deftp {Scheme Variable} <glil-void>
Pushes ``the unspecified value'' on the stack.
@end deftp
@deftp {Scheme Variable} <glil-const> obj
Pushes a constant value onto the stack. @var{obj} must be a number,
string, symbol, keyword, boolean, character, uniform array, the empty
list, or a pair or vector of constants.
@end deftp
@deftp {Scheme Variable} <glil-lexical> local? boxed? op index
Accesses a lexically bound variable. If the variable is not
@var{local?} it is free. All variables may have @code{ref} and
@code{set} as their @var{op}. Boxed variables may also have the
@var{op}s @code{box}, @code{empty-box}, and @code{fix}, which
correspond in semantics to the VM instructions @code{box},
@code{empty-box}, and @code{fix-closure}. @xref{Stack Layout}, for
more information.
@end deftp
@deftp {Scheme Variable} <glil-toplevel> op name
Accesses a toplevel variable. @var{op} may be @code{ref}, @code{set},
or @code{define}.
@end deftp
@deftp {Scheme Variable} <glil-module> op mod name public?
Accesses a variable within a specific module. See Tree-IL's
@code{<module-ref>}, for more information.
@end deftp
@deftp {Scheme Variable} <glil-label> label
Creates a new label. @var{label} can be any Scheme value, and should
be unique.
@end deftp
@deftp {Scheme Variable} <glil-branch> inst label
Branch to a label. @var{label} should be a @code{<ghil-label>}.
@code{inst} is a branching instruction: @code{br-if}, @code{br}, etc.
@end deftp
@deftp {Scheme Variable} <glil-call> inst nargs
This expression is probably misnamed, as it does not correspond to
function calls. @code{<glil-call>} invokes the VM instruction named
@var{inst}, noting that it is called with @var{nargs} stack arguments.
The arguments should be pushed on the stack already. What happens to
the stack afterwards depends on the instruction.
@end deftp
@deftp {Scheme Variable} <glil-mv-call> nargs ra
Performs a multiple-value call. @var{ra} is a @code{<glil-label>}
corresponding to the multiple-value return address for the call. See
the notes on @code{mv-call} in @ref{Procedural Instructions}, for more
information.
@end deftp
Users may enter in GLIL at the REPL as well, though there is a bit
more bookkeeping to do. Since GLIL needs the set of variables to be
declared explicitly in a @code{<glil-program>}, GLIL expressions must
be wrapped in a thunk that declares the arity of the expression:
@example
scheme@@(guile-user)> ,language glil
Guile Lowlevel Intermediate Language (GLIL) interpreter 0.3 on
Guile 1.9.0
Copyright (C) 2001-2008 Free Software Foundation, Inc.
Enter `,help' for help.
glil@@(guile-user)> (program 0 0 0 () (const 3) (call return 1))
@result{} 3
@end example
Just as in all of Guile's compilers, an environment is passed to the
GLIL-to-object code compiler, and one is returned as well, along with
the object code.
@node Assembly
@subsection Assembly
Assembly is an S-expression-based, human-readable representation of
the actual bytecodes that will be emitted for the VM. As such, it is a
useful intermediate language both for compilation and for
decompilation.
Besides the fact that it is not a record-based language, assembly
differs from GLIL in four main ways:
@itemize
@item Labels have been resolved to byte offsets in the program.
@item Constants inside procedures have either been expressed as inline
instructions or cached in object arrays.
@item Procedures with metadata (source location information, liveness
extents, procedure names, generic properties, etc) have had their
metadata serialized out to thunks.
@item All expressions correspond directly to VM instructions -- i.e.,
there is no @code{<glil-lexical>} which can be a ref or a set.
@end itemize
Assembly is isomorphic to the bytecode that it compiles to. You can
compile to bytecode, then decompile back to assembly, and you have the
same assembly code.
The general form of assembly instructions is the following:
@lisp
(@var{inst} @var{arg} ...)
@end lisp
The @var{inst} names a VM instruction, and its @var{arg}s will be
embedded in the instruction stream. The easiest way to see assembly is
to play around with it at the REPL, as can be seen in this annotated
example:
@example
scheme@@(guile-user)> (compile '(lambda (x) (+ x x)) #:to 'assembly)
(load-program 0 0 0
() ; Labels
70 ; Length
#f ; Metadata
(make-false)
(make-false) ; object table for the returned lambda
(nop)
(nop) ; Alignment. Since assembly has already resolved its labels
(nop) ; to offsets, and programs must be 8-byte aligned since their
(nop) ; object code is mmap'd directly to structures, assembly
(nop) ; has to have the alignment embedded in it.
(nop)
(load-program
1
0
()
8
(load-program 0 0 0 () 21 #f
(load-symbol "x") ; Name and liveness extent for @code{x}.
(make-false)
(make-int8:0) ; Some instruction+arg combinations
(make-int8:0) ; have abbreviations.
(make-int8 6)
(list 0 5)
(list 0 1)
(make-eol)
(list 0 2)
(return))
; And here, the actual code.
(local-ref 0)
(local-ref 0)
(add)
(return)
(nop)
(nop))
; Return our new procedure.
(return))
@end example
Of course you can switch the REPL to assembly and enter in assembly
S-expressions directly, like with other languages, though it is more
difficult, given that the length fields have to be correct.
@node Bytecode and Objcode
@subsection Bytecode and Objcode
Finally, the raw bytes. There are actually two different ``languages''
here, corresponding to two different ways to represent the bytes.
``Bytecode'' represents code as uniform byte vectors, useful for
structuring and destructuring code on the Scheme level. Bytecode is
the next step down from assembly:
@example
scheme@@(guile-user)> (compile '(+ 32 10) #:to 'assembly)
@result{} (load-program 0 0 0 () 6 #f
(make-int8 32) (make-int8 10) (add) (return))
scheme@@(guile-user)> (compile '(+ 32 10) #:to 'bytecode)
@result{} #u8(0 0 0 0 6 0 0 0 0 0 0 0 0 0 0 0 10 32 10 10 120 52)
@end example
``Objcode'' is bytecode, but mapped directly to a C structure,
@code{struct scm_objcode}:
@example
struct scm_objcode @{
scm_t_uint8 nargs;
scm_t_uint8 nrest;
scm_t_uint16 nlocs;
scm_t_uint32 len;
scm_t_uint32 metalen;
scm_t_uint8 base[0];
@};
@end example
As one might imagine, objcode imposes a minimum length on the
bytecode. Also, the multibyte fields are in native endianness, which
makes objcode (and bytecode) system-dependent. Indeed, in the short
example above, all but the last 6 bytes were the program's header.
Objcode also has a couple of important efficiency hacks. First,
objcode may be mapped directly from disk, allowing compiled code to be
loaded quickly, often from the system's disk cache, and shared among
multiple processes. Secondly, objcode may be embedded in other
objcode, allowing procedures to have the text of other procedures
inlined into their bodies, without the need for separate allocation of
the code. Of course, the objcode object itself does need to be
allocated.
Procedures related to objcode are defined in the @code{(system vm
objcode)} module.
@deffn {Scheme Procedure} objcode? obj
@deffnx {C Function} scm_objcode_p (obj)
Returns @code{#f} iff @var{obj} is object code, @code{#f} otherwise.
@end deffn
@deffn {Scheme Procedure} bytecode->objcode bytecode
@deffnx {C Function} scm_bytecode_to_objcode (bytecode,)
Makes a bytecode object from @var{bytecode}, which should be a
@code{u8vector}.
@end deffn
@deffn {Scheme Variable} load-objcode file
@deffnx {C Function} scm_load_objcode (file)
Load object code from a file named @var{file}. The file will be mapped
into memory via @code{mmap}, so this is a very fast operation.
On disk, object code has an sixteen-byte cookie prepended to it, to
prevent accidental loading of arbitrary garbage.
@end deffn
@deffn {Scheme Variable} write-objcode objcode file
@deffnx {C Function} scm_write_objcode (objcode)
Write object code out to a file, prepending the eight-byte cookie.
@end deffn
@deffn {Scheme Variable} objcode->u8vector objcode
@deffnx {C Function} scm_objcode_to_u8vector (objcode)
Copy object code out to a @code{u8vector} for analysis by Scheme.
@end deffn
The following procedure is actually in @code{(system vm program)}, but
we'll mention it here:
@deffn {Scheme Variable} make-program objcode objtable [free-vars=#f]
@deffnx {C Function} scm_make_program (objcode, objtable, free_vars)
Load up object code into a Scheme program. The resulting program will
have @var{objtable} as its object table, which should be a vector or
@code{#f}, and will capture the free variables from @var{free-vars}.
@end deffn
Object code from a file may be disassembled at the REPL via the
meta-command @code{,disassemble-file}, abbreviated as @code{,xx}.
Programs may be disassembled via @code{,disassemble}, abbreviated as
@code{,x}.
Compiling object code to the fake language, @code{value}, is performed
via loading objcode into a program, then executing that thunk with
respect to the compilation environment. Normally the environment
propagates through the compiler transparently, but users may specify
the compilation environment manually as well:
@deffn {Scheme Procedure} make-objcode-env module free-vars
Make an object code environment. @var{module} should be a Scheme
module, and @var{free-vars} should be a vector of free variables.
@code{#f} is also a valid object code environment.
@end deffn
@node Writing New High-Level Languages
@subsection Writing New High-Level Languages
In order to integrate a new language @var{lang} into Guile's compiler
system, one has to create the module @code{(language @var{lang} spec)}
containing the language definition and referencing the parser,
compiler and other routines processing it. The module hierarchy in
@code{(language brainfuck)} defines a very basic Brainfuck
implementation meant to serve as easy-to-understand example on how to
do this. See for instance @url{http://en.wikipedia.org/wiki/Brainfuck}
for more information about the Brainfuck language itself.
@node Extending the Compiler
@subsection Extending the Compiler
At this point, we break with the impersonal tone of the rest of the
manual, and make an intervention. Admit it: if you've read this far
into the compiler internals manual, you are a junkie. Perhaps a course
at your university left you unsated, or perhaps you've always harbored
a sublimated desire to hack the holy of computer science holies: a
compiler. Well you're in good company, and in a good position. Guile's
compiler needs your help.
There are many possible avenues for improving Guile's compiler.
Probably the most important improvement, speed-wise, will be some form
of native compilation, both just-in-time and ahead-of-time. This could
be done in many ways. Probably the easiest strategy would be to extend
the compiled procedure structure to include a pointer to a native code
vector, and compile from bytecode to native code at run-time after a
procedure is called a certain number of times.
The name of the game is a profiling-based harvest of the low-hanging
fruit, running programs of interest under a system-level profiler and
determining which improvements would give the most bang for the buck.
It's really getting to the point though that native compilation is the
next step.
The compiler also needs help at the top end, enhancing the Scheme that
it knows to also understand R6RS, and adding new high-level compilers.
We have JavaScript and Emacs Lisp mostly complete, but they could use
some love; Lua would be nice as well, butq whatever language it is
that strikes your fancy would be welcome too.
Compilers are for hacking, not for admiring or for complaining about.
Get to it!

154
doc/ref/data-rep.texi
View file

@ -4,135 +4,6 @@
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@c essay \input texinfo
@c essay @c -*-texinfo-*-
@c essay @c %**start of header
@c essay @setfilename data-rep.info
@c essay @settitle Data Representation in Guile
@c essay @c %**end of header
@c essay @include version.texi
@c essay @dircategory The Algorithmic Language Scheme
@c essay @direntry
@c essay * data-rep: (data-rep). Data Representation in Guile --- how to use
@c essay Guile objects in your C code.
@c essay @end direntry
@c essay @setchapternewpage off
@c essay @ifinfo
@c essay Data Representation in Guile
@c essay Copyright (C) 1998, 1999, 2000, 2003, 2006 Free Software Foundation
@c essay Permission is granted to make and distribute verbatim copies of
@c essay this manual provided the copyright notice and this permission notice
@c essay are preserved on all copies.
@c essay @ignore
@c essay Permission is granted to process this file through TeX and print the
@c essay results, provided the printed document carries copying permission
@c essay notice identical to this one except for the removal of this paragraph
@c essay (this paragraph not being relevant to the printed manual).
@c essay @end ignore
@c essay Permission is granted to copy and distribute modified versions of this
@c essay manual under the conditions for verbatim copying, provided that the entire
@c essay resulting derived work is distributed under the terms of a permission
@c essay notice identical to this one.
@c essay Permission is granted to copy and distribute translations of this manual
@c essay into another language, under the above conditions for modified versions,
@c essay except that this permission notice may be stated in a translation approved
@c essay by the Free Software Foundation.
@c essay @end ifinfo
@c essay @titlepage
@c essay @sp 10
@c essay @comment The title is printed in a large font.
@c essay @title Data Representation in Guile
@c essay @subtitle $Id: data-rep.texi,v 1.20 2006-04-16 23:11:15 kryde Exp $
@c essay @subtitle For use with Guile @value{VERSION}
@c essay @author Jim Blandy
@c essay @author Free Software Foundation
@c essay @author @email{jimb@@red-bean.com}
@c essay @c The following two commands start the copyright page.
@c essay @page
@c essay @vskip 0pt plus 1filll
@c essay @vskip 0pt plus 1filll
@c essay Copyright @copyright{} 1998, 2006 Free Software Foundation
@c essay Permission is granted to make and distribute verbatim copies of
@c essay this manual provided the copyright notice and this permission notice
@c essay are preserved on all copies.
@c essay Permission is granted to copy and distribute modified versions of this
@c essay manual under the conditions for verbatim copying, provided that the entire
@c essay resulting derived work is distributed under the terms of a permission
@c essay notice identical to this one.
@c essay Permission is granted to copy and distribute translations of this manual
@c essay into another language, under the above conditions for modified versions,
@c essay except that this permission notice may be stated in a translation approved
@c essay by Free Software Foundation.
@c essay @end titlepage
@c essay @c @smallbook
@c essay @c @finalout
@c essay @headings double
@c essay @node Top, Data Representation in Scheme, (dir), (dir)
@c essay @top Data Representation in Guile
@c essay @ifinfo
@c essay This essay is meant to provide the background necessary to read and
@c essay write C code that manipulates Scheme values in a way that conforms to
@c essay libguile's interface. If you would like to write or maintain a
@c essay Guile-based application in C or C++, this is the first information you
@c essay need.
@c essay In order to make sense of Guile's @code{SCM_} functions, or read
@c essay libguile's source code, it's essential to have a good grasp of how Guile
@c essay actually represents Scheme values. Otherwise, a lot of the code, and
@c essay the conventions it follows, won't make very much sense.
@c essay We assume you know both C and Scheme, but we do not assume you are
@c essay familiar with Guile's C interface.
@c essay @end ifinfo
@node Data Representation
@appendix Data Representation in Guile
@strong{by Jim Blandy}
[Due to the rather non-orthogonal and performance-oriented nature of the
SCM interface, you need to understand SCM internals *before* you can use
the SCM API. That's why this chapter comes first.]
[NOTE: this is Jim Blandy's essay almost entirely unmodified. It has to
be adapted to fit this manual smoothly.]
In order to make sense of Guile's SCM_ functions, or read libguile's
source code, it's essential to have a good grasp of how Guile actually
represents Scheme values. Otherwise, a lot of the code, and the
conventions it follows, won't make very much sense. This essay is meant
to provide the background necessary to read and write C code that
manipulates Scheme values in a way that is compatible with libguile.
We assume you know both C and Scheme, but we do not assume you are
familiar with Guile's implementation.
@menu
* Data Representation in Scheme:: Why things aren't just totally
straightforward, in general terms.
* How Guile does it:: How to write C code that manipulates
Guile values, with an explanation
of Guile's garbage collector.
@end menu
@node Data Representation in Scheme
@section Data Representation in Scheme
@ -159,8 +30,8 @@ The following sections will present a simple typing system, and then
make some refinements to correct its major weaknesses. However, this is
not a description of the system Guile actually uses. It is only an
illustration of the issues Guile's system must address. We provide all
the information one needs to work with Guile's data in @ref{How Guile
does it}.
the information one needs to work with Guile's data in @ref{The
Libguile Runtime Environment}.
@menu
@ -423,22 +294,21 @@ significant loss of efficiency, but the simplified system would still be
more complex than what we've presented above.
@node How Guile does it
@section How Guile does it
@node The Libguile Runtime Environment
@section The Libguile Runtime Environment
Here we present the specifics of how Guile represents its data. We
don't go into complete detail; an exhaustive description of Guile's
system would be boring, and we do not wish to encourage people to write
code which depends on its details anyway. We do, however, present
everything one need know to use Guile's data.
everything one need know to use Guile's data. It is assumed that the
reader understands the concepts laid out in @ref{Data Representation
in Scheme}.
This section is in limbo. It used to document the 'low-level' C API
of Guile that was used both by clients of libguile and by libguile
itself.
In the future, clients should only need to look into the sections
@ref{Programming in C} and @ref{API Reference}. This section will in
the end only contain stuff about the internals of Guile.
FIXME: much of this is outdated as of 1.8, we don't provide many of
these macros any more. Also here we're missing sections about the
evaluator implementation, which is interesting, and notes about tail
recursion between scheme and c.
@menu
* General Rules::
@ -1127,7 +997,7 @@ This reference can be decoded to a C pointer to a heap cell using the
@code{SCM} value is done using the @code{PTR2SCM} macro.
@c (FIXME:: this name should be changed)
@deftypefn Macro (scm_t_cell *) SCM2PTR (SCM @var{x})
@deftypefn Macro {scm_t_cell *} SCM2PTR (SCM @var{x})
Extract and return the heap cell pointer from a non-immediate @code{SCM}
object @var{x}.
@end deftypefn

1
doc/ref/effective-version.texi.in Normal file
View file

@ -0,0 +1 @@
@set EFFECTIVE-VERSION @GUILE_EFFECTIVE_VERSION@

16
doc/ref/expect.texi
View file

@ -10,9 +10,9 @@
The macros in this section are made available with:
@smalllisp
@lisp
(use-modules (ice-9 expect))
@end smalllisp
@end lisp
@code{expect} is a macro for selecting actions based on the output from
a port. The name comes from a tool of similar functionality by Don Libes.
@ -30,14 +30,14 @@ which is matched against each of the patterns. When a
pattern matches, the remaining expression(s) in
the clause are evaluated and the value of the last is returned. For example:
@smalllisp
@lisp
(with-input-from-file "/etc/passwd"
(lambda ()
(expect-strings
("^nobody" (display "Got a nobody user.\n")
(display "That's no problem.\n"))
("^daemon" (display "Got a daemon user.\n")))))
@end smalllisp
@end lisp
The regular expression is compiled with the @code{REG_NEWLINE} flag, so
that the ^ and $ anchors will match at any newline, not just at the start
@ -54,13 +54,13 @@ The symbol @code{=>} can be used to indicate that the expression is a
procedure which will accept the result of a successful regular expression
match. E.g.,
@smalllisp
@lisp
("^daemon" => write)
("^d(aemon)" => (lambda args (for-each write args)))
("^da(em)on" => (lambda (all sub)
(write all) (newline)
(write sub) (newline)))
@end smalllisp
@end lisp
The order of the substrings corresponds to the order in which the
opening brackets occur.
@ -135,12 +135,12 @@ expression.
In the following example, a string will only be matched at the beginning
of the file:
@smalllisp
@lisp
(let ((expect-port (open-input-file "/etc/passwd")))
(expect
((lambda (s eof?) (string=? s "fnord!"))
(display "Got a nobody user!\n"))))
@end smalllisp
@end lisp
The control variables described for @code{expect-strings} also
influence the behaviour of @code{expect}, with the exception of

396
doc/goops/goops-tutorial.texi → doc/ref/goops-tutorial.texi
View file

@ -1,3 +1,9 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 2008, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@c Original attribution:
@c
@ -24,19 +30,33 @@
@c Guile
@c @end macro
This is chapter was originally written by Erick Gallesio as an appendix
for the STk reference manual, and subsequently adapted to @goops{}.
This section introduces the @goops{} package in more detail. It was
originally written by Erick Gallesio as an appendix for the STk
reference manual, and subsequently adapted to @goops{}.
The procedures and syntax described in this tutorial are provided by
Guile modules that may need to be imported before being available.
The main @goops{} module is imported by evaluating:
@lisp
(use-modules (oop goops))
@end lisp
@findex (oop goops)
@cindex main module
@cindex loading
@cindex preparing
@menu
* Copyright::
* Intro::
* Class definition and instantiation::
* Class definition::
* Instance creation and slot access::
* Slot description::
* Inheritance::
* Generic functions::
@end menu
@node Copyright, Intro, Tutorial, Tutorial
@section Copyright
@node Copyright
@subsection Copyright
Original attribution:
@ -52,52 +72,13 @@ required for any of the authorized uses.
This software is provided ``AS IS'' without express or implied
warranty.
Adapted for use in Guile with the authors permission
Adapted for use in Guile with the author's permission
@node Intro, Class definition and instantiation, Copyright, Tutorial
@section Introduction
@goops{} is the object oriented extension to @guile{}. Its
implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
version 1.3 of the Gregor Kiczales @cite{Tiny-Clos}. It is very close
to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is adapted for
the Scheme language.
Briefly stated, the @goops{} extension gives the user a full object
oriented system with multiple inheritance and generic functions with
multi-method dispatch. Furthermore, the implementation relies on a true
meta object protocol, in the spirit of the one defined for CLOS
(@cite{Gregor Kiczales: A Metaobject Protocol}).
The purpose of this tutorial is to introduce briefly the @goops{}
package and in no case will it replace the @goops{} reference manual
(which needs to be urgently written now@ @dots{}).
Note that the operations described in this tutorial resides in modules
that may need to be imported before being available. The main module is
imported by evaluating:
@lisp
(use-modules (oop goops))
@end lisp
@findex (oop goops)
@cindex main module
@cindex loading
@cindex preparing
@node Class definition and instantiation, Inheritance, Intro, Tutorial
@section Class definition and instantiation
@menu
* Class definition::
@end menu
@node Class definition, , Class definition and instantiation, Class definition and instantiation
@node Class definition
@subsection Class definition
A new class is defined with the @code{define-class}@footnote{Don't
forget to import the @code{(oop goops)} module} macro. The syntax of
@code{define-class} is close to CLOS @code{defclass}:
A new class is defined with the @code{define-class} macro. The syntax
of @code{define-class} is close to CLOS @code{defclass}:
@findex define-class
@cindex class
@ -107,105 +88,36 @@ forget to import the @code{(oop goops)} module} macro. The syntax of
@var{class-option} @dots{})
@end lisp
Class options will not be discussed in this tutorial. The list of
@var{superclass}es specifies which classes to inherit properties from
@var{class} (see @ref{Inheritance} for more details). A
@var{slot-description} gives the name of a slot and, eventually, some
``properties'' of this slot (such as its initial value, the function
which permit to access its value, @dots{}). Slot descriptions will be
discussed in @ref{Slot description}.
@var{class} is the class being defined. The list of
@var{superclass}es specifies which existing classes, if any, to
inherit slots and properties from. Each @var{slot-description} gives
the name of a slot and optionally some ``properties'' of this slot;
for example its initial value, the name of a function which will
access its value, and so on. Slot descriptions and inheritance are
discussed more below. For class options, see @ref{Class Options}.
@cindex slot
As an example, let us define a type for representation of complex
numbers in terms of real numbers. This can be done with the following
class definition:
As an example, let us define a type for representing a complex number
in terms of two real numbers.@footnote{Of course Guile already
provides complex numbers, and @code{<complex>} is in fact a predefined
class in GOOPS; but the definition here is still useful as an
example.} This can be done with the following class definition:
@lisp
(define-class <complex> (<number>)
(define-class <my-complex> (<number>)
r i)
@end lisp
This binds the variable @code{<complex>}@footnote{@code{<complex>} is in
fact a builtin class in GOOPS. Because of this, GOOPS will create a new
class. The old class will still serve as the type for Guile's native
complex numbers.} to a new class whose instances contain two
slots. These slots are called @code{r} an @code{i} and we suppose here
that they contain respectively the real part and the imaginary part of a
complex number. Note that this class inherits from @code{<number>} which
is a pre-defined class. (@code{<number>} is the direct super class of
the pre-defined class @code{<complex>} which, in turn, is the super
class of @code{<real>} which is the super of
@code{<integer>}.)@footnote{With the new definition of @code{<complex>},
a @code{<real>} is not a @code{<complex>} since @code{<real>} inherits
from @code{ <number>} rather than @code{<complex>}. In practice,
inheritance could be modified @emph{a posteriori}, if needed. However,
this necessitates some knowledge of the meta object protocol and it will
not be shown in this document}.
This binds the variable @code{<my-complex>} to a new class whose
instances will contain two slots. These slots are called @code{r} and
@code{i} and will hold the real and imaginary parts of a complex
number. Note that this class inherits from @code{<number>}, which is a
predefined class.@footnote{@code{<number>} is the direct superclass of
the predefined class @code{<complex>}; @code{<complex>} is the
superclass of @code{<real>}, and @code{<real>} is the superclass of
@code{<integer>}.}
@node Inheritance, Generic functions, Class definition and instantiation, Tutorial
@section Inheritance
@c \label{inheritance}
@menu
* Class hierarchy and inheritance of slots::
* Instance creation and slot access::
* Slot description::
* Class precedence list::
@end menu
@node Class hierarchy and inheritance of slots, Instance creation and slot access, Inheritance, Inheritance
@subsection Class hierarchy and inheritance of slots
Inheritance is specified upon class definition. As said in the
introduction, @goops{} supports multiple inheritance. Here are some
class definitions:
@lisp
(define-class A () a)
(define-class B () b)
(define-class C () c)
(define-class D (A B) d a)
(define-class E (A C) e c)
(define-class F (D E) f)
@end lisp
@code{A}, @code{B}, @code{C} have a null list of super classes. In this
case, the system will replace it by the list which only contains
@code{<object>}, the root of all the classes defined by
@code{define-class}. @code{D}, @code{E}, @code{F} use multiple
inheritance: each class inherits from two previously defined classes.
Those class definitions define a hierarchy which is shown in Figure@ 1.
In this figure, the class @code{<top>} is also shown; this class is the
super class of all Scheme objects. In particular, @code{<top>} is the
super class of all standard Scheme types.
@example
@group
@image{hierarchy}
@center @emph{Fig 1: A class hierarchy}
@iftex
@emph{(@code{<complex>} which is the direct subclass of @code{<number>}
and the direct superclass of @code{<real>} has been omitted in this
figure.)}
@end iftex
@end group
@end example
The set of slots of a given class is calculated by taking the union of the
slots of all its super class. For instance, each instance of the class
D, defined before will have three slots (@code{a}, @code{b} and
@code{d}). The slots of a class can be obtained by the @code{class-slots}
primitive. For instance,
@lisp
(class-slots A) @result{} ((a))
(class-slots E) @result{} ((a) (e) (c))
(class-slots F) @result{} ((e) (c) (b) (d) (a) (f))
@c used to be ((d) (a) (b) (c) (f))
@end lisp
@emph{Note: } The order of slots is not significant.
@node Instance creation and slot access, Slot description, Class hierarchy and inheritance of slots, Inheritance
@node Instance creation and slot access
@subsection Instance creation and slot access
Creation of an instance of a previously defined
@ -218,16 +130,16 @@ slots of the newly created instance. For instance, the following form
@findex make
@cindex instance
@lisp
(define c (make <complex>))
(define c (make <my-complex>))
@end lisp
will create a new @code{<complex>} object and will bind it to the @code{c}
@noindent
will create a new @code{<my-complex>} object and will bind it to the @code{c}
Scheme variable.
Accessing the slots of the new complex number can be done with the
@code{slot-ref} and the @code{slot-set!} primitives. @code{Slot-set!}
primitive permits to set the value of an object slot and @code{slot-ref}
permits to get its value.
@code{slot-ref} and the @code{slot-set!} primitives. @code{slot-set!}
sets the value of an object slot and @code{slot-ref} retrieves it.
@findex slot-set!
@findex slot-ref
@ -250,52 +162,60 @@ First load the module @code{(oop goops describe)}:
@code{(use-modules (oop goops describe))}
@end example
The expression
@smalllisp
(describe c)
@end smalllisp
will now print the following information on the standard output:
@noindent
Then the expression
@lisp
#<<complex> 401d8638> is an instance of class <complex>
(describe c)
@end lisp
@noindent
will print the following information on the standard output:
@smalllisp
#<<my-complex> 401d8638> is an instance of class <my-complex>
Slots are:
r = 10
i = 3
@end lisp
@end smalllisp
@node Slot description, Class precedence list, Instance creation and slot access, Inheritance
@node Slot description
@subsection Slot description
@c \label{slot-description}
When specifying a slot, a set of options can be given to the
system. Each option is specified with a keyword. The list of authorized
keywords is given below:
When specifying a slot (in a @code{(define-class @dots{})} form),
various options can be specified in addition to the slot's name. Each
option is specified by a keyword. The list of authorized keywords is
given below:
@cindex keyword
@itemize @bullet
@item
@code{#:init-value} permits to supply a default value for the slot. This
default value is obtained by evaluating the form given after the
@code{#:init-form} in the global environment, at class definition time.
@code{#:init-value} permits to supply a constant default value for the
slot. The value is obtained by evaluating the form given after the
@code{#:init-value} at class definition time.
@cindex default slot value
@findex #:init-value
@cindex top level environment
@item
@code{#:init-form} specifies a form that, when evaluated, will return
an initial value for the slot. The form is evaluated each time that
an instance of the class is created, in the lexical environment of the
containing @code{define-class} expression.
@cindex default slot value
@findex #:init-form
@item
@code{#:init-thunk} permits to supply a thunk that will provide a
default value for the slot. The value is obtained by evaluating the
thunk a instance creation time.
@c CHECKME: in the global environment?
default value for the slot. The value is obtained by invoking the
thunk at instance creation time.
@findex default slot value
@findex #:init-thunk
@cindex top level environment
@item
@code{#:init-keyword} permits to specify the keyword for initializing a
slot. The init-keyword may be provided during instance creation (i.e. in
the @code{make} optional parameter list). Specifying such a keyword
@code{#:init-keyword} permits to specify a keyword for initializing the
slot. The init-keyword may be provided during instance creation (i.e. in
the @code{make} optional parameter list). Specifying such a keyword
during instance initialization will supersede the default slot
initialization possibly given with @code{#:init-form}.
@findex #:init-keyword
@ -361,11 +281,11 @@ and @code{#:slot-set!} options. See the example below.
@end itemize
@end itemize
To illustrate slot description, we shall redefine the @code{<complex>} class
To illustrate slot description, we shall redefine the @code{<my-complex>} class
seen before. A definition could be:
@lisp
(define-class <complex> (<number>)
(define-class <my-complex> (<number>)
(r #:init-value 0 #:getter get-r #:setter set-r! #:init-keyword #:r)
(i #:init-value 0 #:getter get-i #:setter set-i! #:init-keyword #:i))
@end lisp
@ -378,11 +298,11 @@ functions @code{get-r} and @code{set-r!} (resp. @code{get-i} and
the @code{r} (resp. @code{i}) slot.
@lisp
(define c1 (make <complex> #:r 1 #:i 2))
(define c1 (make <my-complex> #:r 1 #:i 2))
(get-r c1) @result{} 1
(set-r! c1 12)
(get-r c1) @result{} 12
(define c2 (make <complex> #:r 2))
(define c2 (make <my-complex> #:r 2))
(get-r c2) @result{} 2
(get-i c2) @result{} 0
@end lisp
@ -390,12 +310,12 @@ the @code{r} (resp. @code{i}) slot.
Accessors provide an uniform access for reading and writing an object
slot. Writing a slot is done with an extended form of @code{set!}
which is close to the Common Lisp @code{setf} macro. So, another
definition of the previous @code{<complex>} class, using the
definition of the previous @code{<my-complex>} class, using the
@code{#:accessor} option, could be:
@findex set!
@lisp
(define-class <complex> (<number>)
(define-class <my-complex> (<number>)
(r #:init-value 0 #:accessor real-part #:init-keyword #:r)
(i #:init-value 0 #:accessor imag-part #:init-keyword #:i))
@end lisp
@ -416,13 +336,13 @@ coordinates as well as with polar coordinates. One solution could be to
have a definition of complex numbers which uses one particular
representation and some conversion functions to pass from one
representation to the other. A better solution uses virtual slots. A
complete definition of the @code{<complex>} class using virtual slots is
complete definition of the @code{<my-complex>} class using virtual slots is
given in Figure@ 2.
@example
@group
@lisp
(define-class <complex> (<number>)
(define-class <my-complex> (<number>)
;; True slots use rectangular coordinates
(r #:init-value 0 #:accessor real-part #:init-keyword #:r)
(i #:init-value 0 #:accessor imag-part #:init-keyword #:i)
@ -446,7 +366,7 @@ given in Figure@ 2.
(slot-set! o 'i (* m (sin a)))))))
@end lisp
@center @emph{Fig 2: A @code{<complex>} number class definition using virtual slots}
@center @emph{Fig 2: A @code{<my-complex>} number class definition using virtual slots}
@end group
@end example
@ -480,20 +400,21 @@ A more complete example is given below:
@example
@group
@lisp
(define c (make <complex> #:r 12 #:i 20))
@smalllisp
(define c (make <my-complex> #:r 12 #:i 20))
(real-part c) @result{} 12
(angle c) @result{} 1.03037682652431
(slot-set! c 'i 10)
(set! (real-part c) 1)
(describe c) @result{}
#<<complex> 401e9b58> is an instance of class <complex>
Slots are:
r = 1
i = 10
m = 10.0498756211209
a = 1.47112767430373
@end lisp
(describe c)
@print{}
#<<my-complex> 401e9b58> is an instance of class <my-complex>
Slots are:
r = 1
i = 10
m = 10.0498756211209
a = 1.47112767430373
@end smalllisp
@end group
@end example
@ -503,14 +424,75 @@ Scheme primitives.
@lisp
(define make-rectangular
(lambda (x y) (make <complex> #:r x #:i y)))
(lambda (x y) (make <my-complex> #:r x #:i y)))
(define make-polar
(lambda (x y) (make <complex> #:magn x #:angle y)))
(lambda (x y) (make <my-complex> #:magn x #:angle y)))
@end lisp
@node Class precedence list, , Slot description, Inheritance
@subsection Class precedence list
@node Inheritance
@subsection Inheritance
@c \label{inheritance}
@menu
* Class hierarchy and inheritance of slots::
* Class precedence list::
@end menu
@node Class hierarchy and inheritance of slots
@subsubsection Class hierarchy and inheritance of slots
Inheritance is specified upon class definition. As said in the
introduction, @goops{} supports multiple inheritance. Here are some
class definitions:
@lisp
(define-class A () a)
(define-class B () b)
(define-class C () c)
(define-class D (A B) d a)
(define-class E (A C) e c)
(define-class F (D E) f)
@end lisp
@code{A}, @code{B}, @code{C} have a null list of super classes. In this
case, the system will replace it by the list which only contains
@code{<object>}, the root of all the classes defined by
@code{define-class}. @code{D}, @code{E}, @code{F} use multiple
inheritance: each class inherits from two previously defined classes.
Those class definitions define a hierarchy which is shown in Figure@ 1.
In this figure, the class @code{<top>} is also shown; this class is the
super class of all Scheme objects. In particular, @code{<top>} is the
super class of all standard Scheme types.
@example
@group
@image{hierarchy}
@center @emph{Fig 1: A class hierarchy}
@iftex
@emph{(@code{<complex>} which is the direct subclass of @code{<number>}
and the direct superclass of @code{<real>} has been omitted in this
figure.)}
@end iftex
@end group
@end example
The set of slots of a given class is calculated by taking the union of the
slots of all its super class. For instance, each instance of the class
D, defined before will have three slots (@code{a}, @code{b} and
@code{d}). The slots of a class can be obtained by the @code{class-slots}
primitive. For instance,
@lisp
(class-slots A) @result{} ((a))
(class-slots E) @result{} ((a) (e) (c))
(class-slots F) @result{} ((e) (c) (b) (d) (a) (f))
@c used to be ((d) (a) (b) (c) (f))
@end lisp
@emph{Note: } The order of slots is not significant.
@node Class precedence list
@subsubsection Class precedence list
A class may have more than one superclass. @footnote{This section is an
adaptation of Jeff Dalton's (J.Dalton@@ed.ac.uk) @cite{Brief
@ -587,8 +569,8 @@ However, this result is not too much readable; using the function
(map class-name (class-precedence-list B)) @result{} (B <object> <top>)
@end lisp
@node Generic functions, , Inheritance, Tutorial
@section Generic functions
@node Generic functions
@subsection Generic functions
@menu
* Generic functions and methods::
@ -596,8 +578,8 @@ However, this result is not too much readable; using the function
* Example::
@end menu
@node Generic functions and methods, Next-method, Generic functions, Generic functions
@subsection Generic functions and methods
@node Generic functions and methods
@subsubsection Generic functions and methods
@c \label{gf-n-methods}
Neither @goops{} nor CLOS use the message mechanism for methods as most
@ -687,8 +669,8 @@ In this case,
(G 'a 1) @result{} top-number
@end lisp
@node Next-method, Example, Generic functions and methods, Generic functions
@subsection Next-method
@node Next-method
@subsubsection Next-method
When you call a generic function, with a particular set of arguments,
GOOPS builds a list of all the methods that are applicable to those
@ -737,16 +719,16 @@ Number is in range
lead to an infinite recursion, but this consideration is just the same
as in Scheme code in general.)
@node Example, , Next-method, Generic functions
@subsection Example
@node Example
@subsubsection Example
In this section we shall continue to define operations on the @code{<complex>}
In this section we shall continue to define operations on the @code{<my-complex>}
class defined in Figure@ 2. Suppose that we want to use it to implement
complex numbers completely. For instance a definition for the addition of
two complexes could be
@lisp
(define-method (new-+ (a <complex>) (b <complex>))
(define-method (new-+ (a <my-complex>) (b <my-complex>))
(make-rectangular (+ (real-part a) (real-part b))
(+ (imag-part a) (imag-part b))))
@end lisp
@ -758,7 +740,7 @@ addition we can do:
(define-generic new-+)
(let ((+ +))
(define-method (new-+ (a <complex>) (b <complex>))
(define-method (new-+ (a <my-complex>) (b <my-complex>))
(make-rectangular (+ (real-part a) (real-part b))
(+ (imag-part a) (imag-part b)))))
@end lisp
@ -778,13 +760,13 @@ Figure@ 3.
(define-method (new-+ (a <real>) (b <real>)) (+ a b))
(define-method (new-+ (a <real>) (b <complex>))
(define-method (new-+ (a <real>) (b <my-complex>))
(make-rectangular (+ a (real-part b)) (imag-part b)))
(define-method (new-+ (a <complex>) (b <real>))
(define-method (new-+ (a <my-complex>) (b <real>))
(make-rectangular (+ (real-part a) b) (imag-part a)))
(define-method (new-+ (a <complex>) (b <complex>))
(define-method (new-+ (a <my-complex>) (b <my-complex>))
(make-rectangular (+ (real-part a) (real-part b))
(+ (imag-part a) (imag-part b))))
@ -823,7 +805,7 @@ To terminate our implementation (integration?) of complex numbers, we can
redefine standard Scheme predicates in the following manner:
@lisp
(define-method (complex? c <complex>) #t)
(define-method (complex? c <my-complex>) #t)
(define-method (complex? c) #f)
(define-method (number? n <number>) #t)

391
doc/goops/goops.texi → doc/ref/goops.texi
View file

@ -1,19 +1,8 @@
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename goops.info
@settitle Goops Manual
@set goops
@setchapternewpage odd
@paragraphindent 0
@c %**end of header
@set VERSION 0.3
@dircategory The Algorithmic Language Scheme
@direntry
* GOOPS: (goops). The GOOPS reference manual.
@end direntry
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 2008, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@macro goops
GOOPS
@ -23,77 +12,8 @@ GOOPS
Guile
@end macro
@ifinfo
This file documents GOOPS, an object oriented extension for Guile.
Copyright (C) 1999, 2000, 2001, 2003, 2006 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo
@c This title page illustrates only one of the
@c two methods of forming a title page.
@titlepage
@title Goops Manual
@subtitle For use with GOOPS @value{VERSION}
@c AUTHORS
@c The GOOPS tutorial was written by Christian Lynbech and Mikael
@c Djurfeldt, who also wrote GOOPS itself. The GOOPS reference manual
@c and MOP documentation were written by Neil Jerram and reviewed by
@c Mikael Djurfeldt.
@author Christian Lynbech
@author @email{chl@@tbit.dk}
@author
@author Mikael Djurfeldt
@author @email{djurfeldt@@nada.kth.se}
@author
@author Neil Jerram
@author @email{neil@@ossau.uklinux.net}
@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999, 2006 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage
@node Top, Introduction, (dir), (dir)
@menu
* Introduction::
* Getting Started::
* Reference Manual::
* MOP Specification::
* Tutorial::
* Concept Index::
* Function and Variable Index::
@end menu
@iftex
@chapter Preliminaries
@end iftex
@node Introduction, Getting Started, Top, Top
@iftex
@section Introduction
@end iftex
@ifnottex
@chapter Introduction
@end ifnottex
@node GOOPS
@chapter GOOPS
@goops{} is the object oriented extension to @guile{}. Its
implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
@ -109,71 +29,58 @@ multi-method dispatch. Furthermore, the implementation relies on a true
meta object protocol, in the spirit of the one defined for CLOS
(@cite{Gregor Kiczales: A Metaobject Protocol}).
@node Getting Started, Reference Manual, Introduction, Top
@iftex
@section Getting Started
@end iftex
@ifnottex
@chapter Getting Started
@end ifnottex
@menu
* Running GOOPS::
Examples of some basic GOOPS functionality.
* Methods::
* User-defined types::
* Asking for the type of an object::
See further in the GOOPS tutorial available in this distribution in
info (goops.info) and texinfo format.
* Quick Start::
* Tutorial::
* Reference Manual::
* MOP Specification::
@end menu
@node Running GOOPS, Methods, Getting Started, Getting Started
@subsection Running GOOPS
@node Quick Start
@section Quick Start
@enumerate
@item
Type
To give an immediate flavour of what GOOPS can do, here is a very
brief introduction to its main operations.
@smalllisp
guile-oops
@end smalllisp
To start using GOOPS, load the @code{(oop goops)} module:
You should now be at the Guile prompt ("guile> ").
@item
Type
@smalllisp
@lisp
(use-modules (oop goops))
@end smalllisp
to load GOOPS. (If your system supports dynamic loading, you
should be able to do this not only from `guile-oops' but from an
arbitrary Guile interpreter.)
@end enumerate
@end lisp
We're now ready to try some basic GOOPS functionality.
@node Methods, User-defined types, Running GOOPS, Getting Started
@menu
* Methods::
* User-defined types::
* Asking for the type of an object::
@end menu
@node Methods
@subsection Methods
@smalllisp
@group
A GOOPS method is like a Scheme procedure except that it is
specialized for a particular set of argument types.
@lisp
(define-method (+ (x <string>) (y <string>))
(string-append x y))
(+ 1 2) --> 3
(+ "abc" "de") --> "abcde"
@end group
@end smalllisp
(+ "abc" "de") @result{} "abcde"
@end lisp
@node User-defined types, Asking for the type of an object, Methods, Getting Started
If @code{+} is used with arguments that do not match the method's
types, Guile falls back to using the normal Scheme @code{+} procedure.
@lisp
(+ 1 2) @result{} 3
@end lisp
@node User-defined types
@subsection User-defined types
@smalllisp
@lisp
(define-class <2D-vector> ()
(x #:init-value 0 #:accessor x-component #:init-keyword #:x)
(y #:init-value 0 #:accessor y-component #:init-keyword #:y))
@ -182,12 +89,11 @@ We're now ready to try some basic GOOPS functionality.
(use-modules (ice-9 format))
(define-method (write (obj <2D-vector>) port)
(display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
port))
(format port "<~S, ~S>" (x-component obj) (y-component obj)))
(define v (make <2D-vector> #:x 3 #:y 4))
v --> <3, 4>
v @result{} <3, 4>
@end group
@group
@ -196,24 +102,28 @@ v --> <3, 4>
#:x (+ (x-component x) (x-component y))
#:y (+ (y-component x) (y-component y))))
(+ v v) --> <6, 8>
(+ v v) @result{} <6, 8>
@end group
@end smalllisp
@end lisp
@node Asking for the type of an object, , User-defined types, Getting Started
@node Asking for the type of an object
@subsection Types
@example
(class-of v) --> #<<class> <2D-vector> 40241ac0>
<2D-vector> --> #<<class> <2D-vector> 40241ac0>
(class-of 1) --> #<<class> <integer> 401b2a98>
<integer> --> #<<class> <integer> 401b2a98>
(class-of v) @result{} #<<class> <2D-vector> 40241ac0>
<2D-vector> @result{} #<<class> <2D-vector> 40241ac0>
(class-of 1) @result{} #<<class> <integer> 401b2a98>
<integer> @result{} #<<class> <integer> 401b2a98>
(is-a? v <2D-vector>) --> #t
(is-a? v <2D-vector>) @result{} #t
@end example
@node Reference Manual, MOP Specification, Getting Started, Top
@chapter Reference Manual
@node Tutorial
@section Tutorial
@include goops-tutorial.texi
@node Reference Manual
@section Reference Manual
This chapter is the GOOPS reference manual. It aims to describe all the
syntax, procedures, options and associated concepts that a typical
@ -241,7 +151,7 @@ For a detailed specification of the GOOPS metaobject protocol, see
@end menu
@node Introductory Remarks
@section Introductory Remarks
@subsection Introductory Remarks
GOOPS is an object-oriented programming system based on a ``metaobject
protocol'' derived from the ones used in CLOS (the Common Lisp Object
@ -261,19 +171,19 @@ GOOPS' power, by customizing the behaviour of GOOPS itself.
Each of the following sections of the reference manual is arranged
such that the most basic usage is introduced first, and then subsequent
subsections discuss the related internal functions and metaobject
subsubsections discuss the related internal functions and metaobject
protocols, finishing with a description of how to customize that area of
functionality.
These introductory remarks continue with a few words about metaobjects
and the MOP. Readers who do not want to be bothered yet with the MOP
and customization could safely skip this subsection on a first reading,
and should correspondingly skip subsequent subsections that are
and customization could safely skip this subsubsection on a first reading,
and should correspondingly skip subsequent subsubsections that are
concerned with internals and customization.
In general, this reference manual assumes familiarity with standard
object oriented concepts and terminology. However, some of the terms
used in GOOPS are less well known, so the Terminology subsection
used in GOOPS are less well known, so the Terminology subsubsection
provides definitions for these terms.
@menu
@ -282,7 +192,7 @@ provides definitions for these terms.
@end menu
@node Metaobjects and the Metaobject Protocol
@subsection Metaobjects and the Metaobject Protocol
@subsubsection Metaobjects and the Metaobject Protocol
The conceptual building blocks of GOOPS are classes, slot definitions,
instances, generic functions and methods. A class is a grouping of
@ -377,7 +287,7 @@ Each subsequent section of the reference manual covers a particular area
of GOOPS functionality, and describes the generic functions that are
relevant for customization of that area.
We conclude this subsection by emphasizing a point that may seem
We conclude this subsubsection by emphasizing a point that may seem
obvious, but contrasts with the corresponding situation in some other
MOP implementations, such as CLOS. The point is simply that an
identifier which represents a GOOPS class or generic function is a
@ -392,7 +302,7 @@ class names), but it is worth noting that GOOPS conforms fully to this
Schemely principle.
@node Terminology
@subsection Terminology
@subsubsection Terminology
It is assumed that the reader is already familiar with standard object
orientation concepts such as classes, objects/instances,
@ -403,14 +313,7 @@ This section explains some of the less well known concepts and
terminology that GOOPS uses, which are assumed by the following sections
of the reference manual.
@menu
* Metaclass::
* Class Precedence List::
* Accessor::
@end menu
@node Metaclass
@subsubsection Metaclass
@subsubheading Metaclass
A @dfn{metaclass} is the class of an object which represents a GOOPS
class. Put more succinctly, a metaclass is a class's class.
@ -517,8 +420,7 @@ The metaclass of @code{<my-metaclass>} is @code{<class>}.
@code{<class>}.
@end itemize
@node Class Precedence List
@subsubsection Class Precedence List
@subsubheading Class Precedence List
The @dfn{class precedence list} of a class is the list of all direct and
indirect superclasses of that class, including the class itself.
@ -548,8 +450,7 @@ precedence list}.
``Class precedence list'' is often abbreviated, in documentation and
Scheme variable names, to @dfn{cpl}.
@node Accessor
@subsubsection Accessor
@subsubheading Accessor
An @dfn{accessor} is a generic function with both reference and setter
methods.
@ -583,7 +484,7 @@ be invoked using the generalized @code{set!} syntax, as in:
@end example
@node Defining New Classes
@section Defining New Classes
@subsection Defining New Classes
[ *fixme* Somewhere in this manual there needs to be an introductory
discussion about GOOPS classes, generic functions and methods, covering
@ -622,7 +523,7 @@ the discussion there. ]
@end menu
@node Basic Class Definition
@subsection Basic Class Definition
@subsubsection Basic Class Definition
New classes are defined using the @code{define-class} syntax, with
arguments that specify the classes that the new class should inherit
@ -651,7 +552,7 @@ keywords and corresponding values.
@end deffn
The standard GOOPS class and slot options are described in the following
subsections: see @ref{Class Options} and @ref{Slot Options}.
subsubsections: see @ref{Class Options} and @ref{Slot Options}.
Example 1. Define a class that combines two pre-existing classes by
inheritance but adds no new slots.
@ -681,13 +582,13 @@ customized via an application-defined metaclass.
@end example
@node Class Options
@subsection Class Options
@subsubsection Class Options
@deffn {class option} #:metaclass metaclass
The @code{#:metaclass} class option specifies the metaclass of the class
being defined. @var{metaclass} must be a class that inherits from
@code{<class>}. For an introduction to the use of metaclasses, see
@ref{Metaobjects and the Metaobject Protocol} and @ref{Metaclass}.
@ref{Metaobjects and the Metaobject Protocol} and @ref{Terminology}.
If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
metaclass for the new class by calling @code{ensure-metaclass}
@ -714,7 +615,7 @@ environment defaults to the top-level environment in which the
@end deffn
@node Slot Options
@subsection Slot Options
@subsubsection Slot Options
@deffn {slot option} #:allocation allocation
The @code{#:allocation} option tells GOOPS how to allocate storage for
@ -917,7 +818,7 @@ classes.
@end deffn
@node Class Definition Internals
@subsection Class Definition Internals
@subsubsection Class Definition Internals
Implementation notes: @code{define-class} expands to an expression which
@ -1030,7 +931,7 @@ class object, are described in @ref{Customizing Instance Creation},
which covers the creation and initialization of instances in general.
@node Customizing Class Definition
@subsection Customizing Class Definition
@subsubsection Customizing Class Definition
During the initialization of a new class, GOOPS calls a number of generic
functions with the newly allocated class instance as the first
@ -1124,7 +1025,8 @@ allocation to do this.
(let ((batch-allocation-count 0)
(batch-get-n-set #f))
(define-method (compute-get-n-set (class <batched-allocation-metaclass>) s)
(define-method (compute-get-n-set
(class <batched-allocation-metaclass>) s)
(case (slot-definition-allocation s)
((#:batched)
;; If we've already used the same slot storage for 10 instances,
@ -1165,7 +1067,7 @@ typically it would perform additional class initialization steps before
and/or after calling @code{(next-method)} for the standard behaviour.
@node STKlos Compatibility
@subsection STKlos Compatibility
@subsubsection STKlos Compatibility
If the STKlos compatibility module is loaded, @code{define-class} is
overwritten by a STKlos-specific definition; the standard GOOPS
@ -1178,7 +1080,7 @@ definition of @code{define-class} remains available in
@end deffn
@node Creating Instances
@section Creating Instances
@subsection Creating Instances
@menu
* Basic Instance Creation::
@ -1186,7 +1088,7 @@ definition of @code{define-class} remains available in
@end menu
@node Basic Instance Creation
@subsection Basic Instance Creation
@subsubsection Basic Instance Creation
To create a new instance of any GOOPS class, use the generic function
@code{make} or @code{make-instance}, passing the required class and any
@ -1223,7 +1125,7 @@ instance's class. Any unprocessed keyword value pairs are ignored.
@end deffn
@node Customizing Instance Creation
@subsection Customizing Instance Creation
@subsubsection Customizing Instance Creation
@code{make} itself is a generic function. Hence the @code{make}
invocation itself can be customized in the case where the new instance's
@ -1290,7 +1192,7 @@ and closures in the slot definitions, it is neater to write an
and initializes all the dependent slot values according to the results.
@node Accessing Slots
@section Accessing Slots
@subsection Accessing Slots
The definition of a slot contains at the very least a slot name, and may
also contain various slot options, including getter, setter and/or
@ -1298,7 +1200,7 @@ accessor functions for the slot.
It is always possible to access slots by name, using the various
``slot-ref'' and ``slot-set!'' procedures described in the following
subsections. For example,
subsubsections. For example,
@example
(define-class <my-class> () ;; Define a class with slots
@ -1354,7 +1256,7 @@ closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
@end menu
@node Instance Slots
@subsection Instance Slots
@subsubsection Instance Slots
Any slot, regardless of its allocation, can be queried, referenced and
set using the following four primitive procedures.
@ -1451,7 +1353,7 @@ slot-missing}).
@end deffn
@node Class Slots
@subsection Class Slots
@subsubsection Class Slots
Slots whose allocation is per-class rather than per-instance can be
referenced and set without needing to specify any particular instance.
@ -1479,7 +1381,7 @@ function with arguments @var{class} and @var{slot-name}.
@end deffn
@node Handling Slot Access Errors
@subsection Handling Slot Access Errors
@subsubsection Handling Slot Access Errors
GOOPS calls one of the following generic functions when a ``slot-ref''
or ``slot-set!'' call specifies a non-existent slot name, or tries to
@ -1510,7 +1412,7 @@ message.
@end deffn
@node Creating Generic Functions
@section Creating Generic Functions
@subsection Creating Generic Functions
A generic function is a collection of methods, with rules for
determining which of the methods should be applied for any given
@ -1526,7 +1428,7 @@ GOOPS represents generic functions as metaobjects of the class
@end menu
@node Basic Generic Function Creation
@subsection Basic Generic Function Creation
@subsubsection Basic Generic Function Creation
The following forms may be used to bind a variable to a generic
function. Depending on that variable's pre-existing value, the generic
@ -1586,20 +1488,20 @@ This can be resolved automagically with the duplicates handler
@code{merge-generics} which gives the module system license to merge
all generic functions sharing a common name:
@smalllisp
@lisp
(define-module (math 2D-vectors)
:use-module (oop goops)
:export (x y ...))
#:use-module (oop goops)
#:export (x y ...))
(define-module (math 3D-vectors)
:use-module (oop goops)
:export (x y z ...))
#:use-module (oop goops)
#:export (x y z ...))
(define-module (my-module)
:use-module (math 2D-vectors)
:use-module (math 3D-vectors)
:duplicates merge-generics)
@end smalllisp
#:use-module (math 2D-vectors)
#:use-module (math 3D-vectors)
#:duplicates merge-generics)
@end lisp
The generic function @code{x} in @code{(my-module)} will now share
methods with @code{x} in both imported modules.
@ -1629,14 +1531,14 @@ Sharing is dynamic, so that adding new methods to a descendant implies
adding it to the ancestor.
If duplicates checking is desired in the above example, the following
form of the @code{:duplicates} option can be used instead:
form of the @code{#:duplicates} option can be used instead:
@smalllisp
:duplicates (merge-generics check)
@end smalllisp
@lisp
#:duplicates (merge-generics check)
@end lisp
@node Generic Function Internals
@subsection Generic Function Internals
@subsubsection Generic Function Internals
@code{define-generic} calls @code{ensure-generic} to upgrade a
pre-existing procedure value, or @code{make} with metaclass
@ -1705,7 +1607,7 @@ accessor, passing the setter generic function as the value of the
@code{#:setter} keyword.
@node Extending Guiles Primitives
@subsection Extending Guile's Primitives
@subsubsection Extending Guile's Primitives
When GOOPS is loaded, many of Guile's primitive procedures can be
extended by giving them a generic function definition that operates
@ -1752,7 +1654,7 @@ integrated into the core of Guile. Consequently, the
procedures described in this section may disappear as well.
@node Adding Methods to Generic Functions
@section Adding Methods to Generic Functions
@subsection Adding Methods to Generic Functions
@menu
* Basic Method Definition::
@ -1760,7 +1662,7 @@ procedures described in this section may disappear as well.
@end menu
@node Basic Method Definition
@subsection Basic Method Definition
@subsubsection Basic Method Definition
To add a method to a generic function, use the @code{define-method} form.
@ -1819,7 +1721,7 @@ invocation error handling, and generic function invocation in general,
see @ref{Invoking Generic Functions}.
@node Method Definition Internals
@subsection Method Definition Internals
@subsubsection Method Definition Internals
@code{define-method}
@ -1906,7 +1808,7 @@ function.
@end deffn
@node Invoking Generic Functions
@section Invoking Generic Functions
@subsection Invoking Generic Functions
When a variable with a generic function definition appears as the first
element of a list that is being evaluated, the Guile evaluator tries
@ -1928,7 +1830,7 @@ may be applied subsequently if a method that is being applied calls
@end menu
@node Determining Which Methods to Apply
@subsection Determining Which Methods to Apply
@subsubsection Determining Which Methods to Apply
[ *fixme* Sorry - this is the area of GOOPS that I understand least of
all, so I'm afraid I have to pass on this section. Would some other
@ -1959,7 +1861,7 @@ kind person consider filling it in? ]
@end deffn
@node Handling Invocation Errors
@subsection Handling Invocation Errors
@subsubsection Handling Invocation Errors
@deffn generic no-method
@deffnx method no-method (gf <generic>) args
@ -1987,7 +1889,7 @@ default method calls @code{goops-error} with an appropriate message.
@end deffn
@node Redefining a Class
@section Redefining a Class
@subsection Redefining a Class
Suppose that a class @code{<my-class>} is defined using @code{define-class}
(@pxref{Basic Class Definition,, define-class}), with slots that have
@ -2002,7 +1904,7 @@ make}). What then happens if @code{<my-class>} is redefined by calling
@end menu
@node Default Class Redefinition Behaviour
@subsection Default Class Redefinition Behaviour
@subsubsection Default Class Redefinition Behaviour
GOOPS' default answer to this question is as follows.
@ -2055,7 +1957,7 @@ Also bear in mind that, like most of GOOPS' default behaviour, it can
be customized@dots{}
@node Customizing Class Redefinition
@subsection Customizing Class Redefinition
@subsubsection Customizing Class Redefinition
When @code{define-class} notices that a class is being redefined,
it constructs the new class metaobject as usual, and then invokes the
@ -2092,7 +1994,8 @@ is specialized for this metaclass:
@example
(define-class <can-be-nameless> (<class>))
(define-method (class-redefinition (old <can-be-nameless>) (new <class>))
(define-method (class-redefinition (old <can-be-nameless>)
(new <class>))
new)
@end example
@ -2119,7 +2022,7 @@ generic functions, and so on@dots{} The detailed protocol for all of these
is described in @ref{MOP Specification}.
@node Changing the Class of an Instance
@section Changing the Class of an Instance
@subsection Changing the Class of an Instance
You can change the class of an existing instance by invoking the
generic function @code{change-class} with two arguments: the instance
@ -2158,7 +2061,7 @@ invokes the @code{change-class} generic function for each existing
instance of the redefined class.
@node Introspection
@section Introspection
@subsection Introspection
@dfn{Introspection}, also known as @dfn{reflection}, is the name given
to the ability to obtain information dynamically about GOOPS metaobjects.
@ -2197,7 +2100,7 @@ GOOPS equivalents --- to be obtained dynamically, at run time.
@end menu
@node Classes
@subsection Classes
@subsubsection Classes
@deffn {primitive procedure} class-name class
Return the name of class @var{class}.
@ -2257,7 +2160,7 @@ Return a list of all methods that use @var{class} or a subclass of
@end deffn
@node Slots
@subsection Slots
@subsubsection Slots
@deffn procedure class-slot-definition class slot-name
Return the slot definition for the slot named @var{slot-name} in class
@ -2338,7 +2241,7 @@ see @ref{Slot Options,, init-value}.
@end deffn
@node Instances
@subsection Instances
@subsubsection Instances
@deffn {primitive procedure} class-of value
Return the GOOPS class of any Scheme @var{value}.
@ -2359,7 +2262,7 @@ Implementation notes: @code{is-a?} uses @code{class-of} and
@var{object}.
@node Generic Functions
@subsection Generic Functions
@subsubsection Generic Functions
@deffn {primitive procedure} generic-function-name gf
Return the name of generic function @var{gf}.
@ -2371,7 +2274,7 @@ This is the value of the @var{gf} metaobject's @code{methods} slot.
@end deffn
@node Generic Function Methods
@subsection Generic Function Methods
@subsubsection Generic Function Methods
@deffn {primitive procedure} method-generic-function method
Return the generic function that @var{method} belongs to.
@ -2409,18 +2312,18 @@ Return an expression that prints to show the definition of method
@end deffn
@node Miscellaneous Functions
@section Miscellaneous Functions
@subsection Miscellaneous Functions
@menu
* Administrative Functions::
* Error Handling::
* GOOPS Error Handling::
* Object Comparisons::
* Cloning Objects::
* Write and Display::
@end menu
@node Administrative Functions
@subsection Administration Functions
@subsubsection Administration Functions
This section describes administrative, non-technical GOOPS functions.
@ -2428,8 +2331,8 @@ This section describes administrative, non-technical GOOPS functions.
Return the current GOOPS version as a string, for example ``0.2''.
@end deffn
@node Error Handling
@subsection Error Handling
@node GOOPS Error Handling
@subsubsection Error Handling
The procedure @code{goops-error} is called to raise an appropriate error
by the default methods of the following generic functions:
@ -2464,7 +2367,7 @@ as done by @code{scm-error}.
@end deffn
@node Object Comparisons
@subsection Object Comparisons
@subsubsection Object Comparisons
@deffn generic eqv?
@deffnx method eqv? ((x <top>) (y <top>))
@ -2493,7 +2396,7 @@ and the Guile reference manual.
@end deffn
@node Cloning Objects
@subsection Cloning Objects
@subsubsection Cloning Objects
@deffn generic shallow-clone
@deffnx method shallow-clone (self <object>)
@ -2514,7 +2417,7 @@ or by reference.
@end deffn
@node Write and Display
@subsection Write and Display
@subsubsection Write and Display
@deffn {primitive generic} write object port
@deffnx {primitive generic} display object port
@ -2542,8 +2445,8 @@ methods - instances of the class @code{<method>}.
as the Guile primitive @code{write} and @code{display} functions.
@end deffn
@node MOP Specification, Tutorial, Reference Manual, Top
@chapter MOP Specification
@node MOP Specification
@section MOP Specification
For an introduction to metaobjects and the metaobject protocol,
see @ref{Metaobjects and the Metaobject Protocol}.
@ -2598,7 +2501,7 @@ what the caller expects to get as the applied method's return value.
@end menu
@node Class Definition
@section Class Definition
@subsection Class Definition
@code{define-class} (syntax)
@ -2731,7 +2634,7 @@ or @code{#:accessor} option.
@end itemize
@node Instance Creation
@section Instance Creation
@subsection Instance Creation
@code{make <class> . @var{initargs}} (method)
@ -2752,13 +2655,13 @@ return value is ignored.
@end itemize
@node Class Redefinition
@section Class Redefinition
@subsection Class Redefinition
The default @code{class-redefinition} method, specialized for classes
with the default metaclass @code{<class>}, has the following internal
protocol.
@code{class-redefinition @var{(old <class>)} @var{(new <class>)}}
@code{class-redefinition (@var{old <class>}) (@var{new <class>})}
(method)
@itemize @bullet
@ -2797,7 +2700,7 @@ to the modified instance, and initializes new slots, as described in
generic function invocation that can be used to customize the instance
update algorithm.
@code{change-class @var{(old-instance <object>)} @var{(new <class>)}} (method)
@code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
@itemize @bullet
@item
@ -2814,7 +2717,7 @@ nothing.
@end itemize
@node Method Definition
@section Method Definition
@subsection Method Definition
@code{define-method} (syntax)
@ -2842,7 +2745,7 @@ theoretically handle adding methods to further types of target.
@end itemize
@node Generic Function Invocation
@section Generic Function Invocation
@subsection Generic Function Invocation
[ *fixme* Description required here. ]
@ -2885,21 +2788,3 @@ theoretically handle adding methods to further types of target.
@item
@code{no-next-method}
@end itemize
@node Tutorial, Concept Index, MOP Specification, Top
@chapter Tutorial
@include goops-tutorial.texi
@node Concept Index, Function and Variable Index, Tutorial, Top
@unnumberedsec Concept Index
@printindex cp
@node Function and Variable Index, , Concept Index, Top
@unnumberedsec Function and Variable Index
@printindex fn
@summarycontents
@contents
@bye

64
doc/ref/guile.texi
View file

@ -4,22 +4,21 @@
@setfilename guile.info
@settitle Guile Reference Manual
@set guile
@set MANUAL-EDITION 1.1
@set MANUAL-REVISION 1
@c %**end of header
@include version.texi
@include lib-version.texi
@include effective-version.texi
@copying
This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions. This is edition @value{MANUAL-EDITION}
corresponding to Guile @value{VERSION}.
This manual documents Guile version @value{VERSION}.
Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005 Free
Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009 Free
Software Foundation.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
any later version published by the Free Software Foundation; with
no Invariant Sections, with the Front-Cover Texts being ``A GNU
Manual,'' and with the Back-Cover Text ``You are free to copy and
modify this GNU Manual.''. A copy of the license is included in the
@ -137,7 +136,7 @@ x
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION}
@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $
@c See preface.texi for the list of authors
@ -177,11 +176,14 @@ x
* Guile Modules::
* GOOPS::
* Guile Implementation::
* Autoconf Support::
Appendices
* Data Representation:: All the details.
* GNU Free Documentation License:: The license of this manual.
Indices
@ -252,7 +254,9 @@ different ways to design a program around Guile, or how to embed Guile
into existing programs.
There is also a pedagogical yet detailed explanation of how the data
representation of Guile is implemented, @xref{Data Representation}.
representation of Guile is implemented, see @ref{Data Representation in
Scheme} and @ref{The Libguile Runtime Environment}.
You don't need to know the details given there to use Guile from C,
but they are useful when you want to modify Guile itself or when you
are just curious about how it is all done.
@ -298,7 +302,7 @@ available through both Scheme and C interfaces.
* Binding Constructs:: Definitions and variable bindings.
* Control Mechanisms:: Controlling the flow of program execution.
* Input and Output:: Ports, reading and writing.
* Read/Load/Eval:: Reading and evaluating Scheme code.
* 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.
@ -362,9 +366,47 @@ available through both Scheme and C interfaces.
@include scsh.texi
@include scheme-debugging.texi
@include goops.texi
@node Guile Implementation
@chapter Guile Implementation
At some point, after one has been programming in Scheme for some time,
another level of Scheme comes into view: its implementation. Knowledge
of how Scheme can be implemented turns out to be necessary to become
an expert hacker. As Peter Norvig notes in his retrospective on
PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
Artificial Intelligence Programming}, an old but still useful text on
Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
programmer eventually develops a good `efficiency model'.''
By this Norvig means that over time, the Lisp hacker eventually
develops an understanding of how much her code ``costs'' in terms of
space and time.
This chapter describes Guile as an implementation of Scheme: its
history, how it represents and evaluates its data, and its compiler.
This knowledge can help you to make that step from being one who is
merely familiar with Scheme to being a real hacker.
@menu
* History:: A brief history of Guile.
* Data Representation in Scheme:: Why things aren't just totally
straightforward, in general terms.
* The Libguile Runtime Environment:: Low-level details on Guile's C
runtime library.
* A Virtual Machine for Guile:: How compiled procedures work.
* Compiling to the Virtual Machine:: Not as hard as you might think.
@end menu
@include history.texi
@include data-rep.texi
@include vm.texi
@include compiler.texi
@include autoconf.texi
@include data-rep.texi
@include fdl.texi
@iftex

0
doc/goops/hierarchy.eps → doc/ref/hierarchy.eps
View file

0
doc/goops/hierarchy.pdf → doc/ref/hierarchy.pdf
View file

0
doc/goops/hierarchy.png → doc/ref/hierarchy.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.1 KiB

After

Width:  |  Height:  |  Size: 6.1 KiB

Before After
Before After

0
doc/goops/hierarchy.txt → doc/ref/hierarchy.txt
View file

285
doc/ref/history.texi Normal file
View file

@ -0,0 +1,285 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 2008
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node History
@section A Brief History of Guile
Guile is an artifact of historical processes, both as code and as a
community of hackers. It is sometimes useful to know this history when
hacking the source code, to know about past decisions and future
directions.
Of course, the real history of Guile is written by the hackers hacking
and not the writers writing, so we round up the section with a note on
current status and future directions.
@menu
* The Emacs Thesis::
* Early Days::
* A Scheme of Many Maintainers::
* A Timeline of Selected Guile Releases::
* Status::
@end menu
@node The Emacs Thesis
@subsection The Emacs Thesis
The story of Guile is the story of bringing the development experience
of Emacs to the mass of programs on a GNU system.
Emacs, when it was first created in its GNU form in 1984, was a new
take on the problem of ``how to make a program''. The Emacs thesis is
that it is delightful to create composite programs based on an
orthogonal kernel written in a low-level language together with a
powerful, high-level extension language.
Extension languages foster extensible programs, programs which adapt
readily to different users and to changing times. Proof of this can be
seen in Emacs' current and continued existence, spanning more than a
quarter-century.
Besides providing for modification of a program by others, extension
languages are good for @emph{intension} as well. Programs built in
``the Emacs way'' are pleasurable and easy for their authors to flesh
out with the features that they need.
After the Emacs experience was appreciated more widely, a number of
hackers started to consider how to spread this experience to the rest
of the GNU system. It was clear that the easiest way to Emacsify a
program would be to embed a shared language implementation into it.
@node Early Days
@subsection Early Days
Tom Lord was the first to fully concentrate his efforts on an
embeddable language runtime, which he named ``GEL'', the GNU Extension
Language.
GEL was the product of converting SCM, Aubrey Jaffer's implementation
of Scheme, into something more appropriate to embedding as a library.
(SCM was itself based on an implementation by George Carrette, SIOD.)
Lord managed to convince Richard Stallman to dub GEL the official
extension language for the GNU project. It was a natural fit, given
that Scheme was a cleaner, more modern Lisp than Emacs Lisp. Part of
the argument was that eventually when GEL became more capable, it
could gain the ability to execute other languages, especially Emacs
Lisp.
Due to a naming conflict with another programming language, Jim Blandy
suggested a new name for GEL: ``Guile''. Besides being a recursive
acroymn, ``Guile'' craftily follows the naming of its ancestors,
``Planner'', ``Conniver'', and ``Schemer''. (The latter was truncated
to ``Scheme'' due to a 6-character file name limit on an old operating
system.) Finally, ``Guile'' suggests ``guy-ell'', or ``Guy L.
Steele'', who, together with Gerald Sussman, originally discovered
Scheme.
Around the same time that Guile (then GEL) was readying itself for
public release, another extension language was gaining in popularity,
Tcl. Many developers found advantages in Tcl because of its shell-like
syntax and its well-developed graphical widgets library, Tk. Also, at
the time there was a large marketing push promoting Tcl as a
``universal extension language''.
Richard Stallman, as the primary author of GNU Emacs, had a particular
vision of what extension languages should be, and Tcl did not seem to
him to be as capable as Emacs Lisp. He posted a criticism to the
comp.lang.tcl newsgroup, sparking one of the internet's legendary
flamewars. As part of these discussions, retrospectively dubbed the
``Tcl Wars'', he announced the Free Software Foundation's intent to
promote Guile as the extension language for the GNU project.
It is a common misconception that Guile was created as a reaction to
Tcl. While it is true that the public announcement of Guile happened
at the same time as the ``Tcl wars'', Guile was created out of a
condition that existed outside the polemic. Indeed, the need for a
powerful language to bridge the gap between extension of existing
applications and a more fully dynamic programming environment is still
with us today.
@node A Scheme of Many Maintainers
@subsection A Scheme of Many Mantainers
Surveying the field, it seems that Scheme implementations correspond
with their maintainers on an N-to-1 relationship. That is to say, that
those people that implement Schemes might do so on a number of
occasions, but that the lifetime of a given Scheme is tied to the
maintainership of one individual.
Guile is atypical in this regard.
Tom Lord maintaned Guile for its first year and a half or so,
corresponding to the end of 1994 through the middle of 1996. The
releases made in this time constitute an arc from SCM as a standalone
program to Guile as a reusable, embeddable library, but passing
through a explosion of features: embedded Tcl and Tk, a toolchain for
compiling and disassembling Java, addition of a C-like syntax,
creation of a module system, and a start at a rich POSIX interface.
Only some of those features remain in Guile. There were ongoing
tensions between providing a small, embeddable language, and one which
had all of the features (e.g. a graphical toolkit) that a modern Emacs
might need. In the end, as Guile gained in uptake, the development
team decided to focus on depth, documentation and orthogonality rather
than on breadth. This has been the focus of Guile ever since, although
there is a wide range of third-party libraries for Guile.
Jim Blandy presided over that period of stabilization, in the three
years until the end of 1999, when he too moved on to other projects.
Since then, Guile has had a group maintainership. The first group was
Maciej Stachowiak, Mikael Djurfeldt, and Marius Vollmer, with Vollmer
staying on the longest. By late 2007, Vollmer had mostly moved on to
other things, so Neil Jerram and Ludovic Courtès stepped up to take on
the primary maintenance responsibility.
Of course, a large part of the actual work on Guile has come from
other contributors too numerous to mention, but without whom the world
would be a poorer place.
@node A Timeline of Selected Guile Releases
@subsection A Timeline of Selected Guile Releases
@table @asis
@item guile-i --- 4 February 1995
SCM, turned into a library.
@item guile-ii --- 6 April 1995
A low-level module system was added. Tcl/Tk support was added,
allowing extension of Scheme by Tcl or vice versa. POSIX support was
improved, and there was an experimental stab at Java integration.
@item guile-iii --- 18 August 1995
The C-like syntax, ctax, was improved, but mostly this release
featured a start at the task of breaking Guile into pieces.
@item 1.0 --- 5 January 1997
@code{#f} was distinguished from @code{'()}. User-level, cooperative
multi-threading was added. Source-level debugging became more useful,
and programmer's and user's manuals were begun. The module system
gained a high-level interface, which is still used today in more or
less the same form.
@item 1.1 --- 16 May 1997
@itemx 1.2 --- 24 June 1997
Support for Tcl/Tk and ctax were split off as separate packages, and
have remained there since. Guile became more compatible with SCSH, and
more useful as a UNIX scripting language. Libguile can now be built as
a shared library, and third-party extensions written in C became
loadable via dynamic linking.
@item 1.3.0 --- 19 October 1998
Command-line editing became much more pleasant through the use of the
readline library. The initial support for internationalization via
multi-byte strings was removed, and has yet to be added back, though
UTF-8 hacks are common. Modules gained the ability to have custom
expanders, which is still used for syntax-case macros. Initial Emacs
Lisp support landed, ports gained better support for file descriptors,
and fluids were added.
@item 1.3.2 --- 20 August 1999
@itemx 1.3.4 --- 25 September 1999
@itemx 1.4 --- 21 June 2000
A long list of lispy features were added: hooks, Common Lisp's
@code{format}, optional and keyword procedure arguments,
@code{getopt-long}, sorting, random numbers, and many other fixes and
enhancements. Guile now has an interactive debugger, interactive help,
and gives better backtraces.
@item 1.6 --- 6 September 2002
Guile gained support for the R5RS standard, and added a number of SRFI
modules. The module system was expanded with programmatic support for
identifier selection and renaming. The GOOPS object system was merged
into Guile core.
@item 1.8 --- 20 February 2006
Guile's arbitrary-precision arithmetic switched to use the GMP
library, and added support for exact rationals. Guile's embedded
user-space threading was removed in favor of POSIX pre-emptive
threads, providing true multiprocessing. Gettext support was added,
and Guile's C API was cleaned up and orthogonalized in a massive way.
@item 2.0 --- thus far, only unstable snapshots available
A virtual machine was added to Guile, along with the associated
compiler and toolchain. Support for internationalization was added.
Running Guile instances became controllable and debuggable from within
Emacs, via GDS, which was also backported to 1.8.5. An SRFI-18
interface to multithreading was added, including thread cancellation.
@end table
@node Status
@subsection Status, or: Your Help Needed
Guile has achieved much of what it set out to achieve, but there is
much remaining to do.
There is still the old problem of bringing existing applications into
a more Emacs-like experience. Guile has had some successes in this
respect, but still most applications in the GNU system are without
Guile integration.
Getting Guile to those applications takes an investment, the
``hacktivation energy'' needed to wire Guile into a program that only
pays off once it is good enough to enable new kinds of behavior. This
would be a great way for new hackers to contribute: take an
application that you use and that you know well, think of something
that it can't yet do, and figure out a way to integrate Guile and
implement that task in Guile.
With time, perhaps this exposure can reverse itself, whereby programs
can run under Guile instead of vice versa, eventually resulting in the
Emacsification of the entire GNU system. Indeed, this is the reason
for the naming of the many Guile modules that live in the @code{ice-9}
namespace, a nod to the fictional substance in Kurt Vonnegut's
novel, Cat's Cradle, capable of acting as a seed crystal to
crystallize the mass of software.
Implicit to this whole discussion is the idea that dynamic languages
are somehow better than languages like C. While languages like C have
their place, Guile's take on this question is that yes, Scheme is more
expressive than C, and more fun to write. This realization carries an
imperative with it to write as much code in Scheme as possible rather
than in other languages.
These days it is possible to write extensible applications almost
entirely from high-level languages, through byte-code and native
compilation, speed gains in the underlying hardware, and foreign call
interfaces in the high-level language. Smalltalk systems are like
this, as are Common Lisp-based systems. While there already are a
number of pure-Guile applications out there, users still need to drop
down to C for some tasks: interfacing to system libraries that don't
have prebuilt Guile interfaces, and for some tasks requiring high
performance.
The addition of the virtual machine in Guile 2.0, together with the
compiler infrastructure, should go a long way to addressing the speed
issues. But there is much optimization to be done. Interested
contributors will find lots of delightful low-hanging fruit, from
simple profile-driven optimization to hacking a just-in-time compiler
from VM bytecode to native code.
Still, even with an all-Guile application, sometimes you want to
provide an opportunity for users to extend your program from a
language with a syntax that is closer to C, or to Python. Another
interesting idea to consider is compiling e.g. Python to Guile. It's
not that far-fetched of an idea: see for example IronPython or JRuby.
And then there's Emacs itself. Though there is a somewhat-working
Emacs Lisp translator for Guile, it cannot yet execute all of Emacs
Lisp. A serious integration of Guile with Emacs would replace the
Elisp virtual machine with Guile, and provide the necessary C shims so
that Guile could emulate Emacs' C API. This would give lots of
exciting things to Emacs: native threads, a real object system, more
sophisticated types, cleaner syntax, and access to all of the Guile
extensions.
Finally, there is another axis of crystallization, the axis between
different Scheme implementations. Guile does not yet support the
latest Scheme standard, R6RS, and should do so. Like all standards,
R6RS is imperfect, but supporting it will allow more code to run on
Guile without modification, and will allow Guile hackers to produce
code compatible with other schemes. Help in this regard would be much
appreciated.

24
doc/ref/intro.texi
View file

@ -80,6 +80,7 @@ To unbundle Guile use the instruction
zcat guile-@value{VERSION}.tar.gz | tar xvf -
@end example
@noindent
which will create a directory called @file{guile-@value{VERSION}} with
all the sources. You can look at the file @file{INSTALL} for detailed
instructions on how to build and install Guile, but you should be able
@ -93,7 +94,7 @@ make install
@end example
This will install the Guile executable @file{guile}, the Guile library
@file{-lguile} and various associated header files and support
@file{libguile} and various associated header files and support
libraries. It will also install the Guile tutorial and reference
manual.
@ -101,14 +102,14 @@ manual.
Since this manual frequently refers to the Scheme ``standard'', also
known as R5RS, or the
@iftex
@tex
``Revised$^5$ Report on the Algorithmic Language Scheme'',
@end iftex
@end tex
@ifnottex
``Revised^5 Report on the Algorithmic Language Scheme'',
@end ifnottex
we have included the report in the Guile distribution;
@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
we have included the report in the Guile distribution; see
@ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
Language Scheme}.
This will also be installed in your info directory.
@ -470,12 +471,13 @@ You can get the version number by invoking the command
@example
$ guile --version
Guile 1.4.1
Copyright (c) 1995, 1996, 1997, 2000, 2006 Free Software Foundation
Guile may be distributed under the terms of the GNU General Public License;
certain other uses are permitted as well. For details, see the file
`COPYING', which is included in the Guile distribution.
There is no warranty, to the extent permitted by law.
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.
@end example
@item

10
doc/ref/libguile-concepts.texi
View file

@ -153,8 +153,8 @@ that have been added to Guile by third-party libraries.
Also, computing with @code{SCM} is not necessarily inefficient. Small
integers will be encoded directly in the @code{SCM} value, for example,
and do not need any additional memory on the heap. See @ref{Data
Representation} to find out the details.
and do not need any additional memory on the heap. See @ref{The
Libguile Runtime Environment} to find out the details.
Some special @code{SCM} values are available to C code without needing
to convert them from C values:
@ -170,8 +170,8 @@ In addition to @code{SCM}, Guile also defines the related type
@code{scm_t_bits}. This is an unsigned integral type of sufficient
size to hold all information that is directly contained in a
@code{SCM} value. The @code{scm_t_bits} type is used internally by
Guile to do all the bit twiddling explained in @ref{Data
Representation}, but you will encounter it occasionally in low-level
Guile to do all the bit twiddling explained in @ref{The Libguile
Runtime Environment}, but you will encounter it occasionally in low-level
user code as well.
@ -182,7 +182,7 @@ As explained above, the @code{SCM} type can represent all Scheme values.
Some values fit entirely into a @code{SCM} value (such as small
integers), but other values require additional storage in the heap (such
as strings and vectors). This additional storage is managed
automatically by Guile. You don't need to explicitely deallocate it
automatically by Guile. You don't need to explicitly deallocate it
when a @code{SCM} value is no longer used.
Two things must be guaranteed so that Guile is able to manage the

4
doc/ref/libguile-extensions.texi
View file

@ -94,11 +94,11 @@ we are going to call the function @code{init_bessel} which will make
@file{.so} when invoking @code{load-extension}. The right extension for
the host platform will be provided automatically.
@smalllisp
@lisp
(load-extension "libguile-bessel" "init_bessel")
(j0 2)
@result{} 0.223890779141236
@end smalllisp
@end lisp
For this to work, @code{load-extension} must be able to find
@file{libguile-bessel}, of course. It will look in the places that

3
doc/ref/libguile-linking.texi
View file

@ -173,7 +173,8 @@ creating ./config.status
creating Makefile
$ make
gcc -c -I/usr/local/include simple-guile.c
gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm
-o simple-guile
$ ./simple-guile
guile> (+ 1 2 3)
6

34
doc/ref/libguile-smobs.texi
View file

@ -28,7 +28,7 @@ datatypes described here.)
@menu
* Describing a New Type::
* Creating Instances::
* Creating Smob Instances::
* Type checking::
* Garbage Collecting Smobs::
* Garbage Collecting Simple Smobs::
@ -132,8 +132,8 @@ init_image_type (void)
@end example
@node Creating Instances
@subsection Creating Instances
@node Creating Smob Instances
@subsection Creating Smob Instances
Normally, smobs can have one @emph{immediate} word of data. This word
stores either a pointer to an additional memory block that holds the
@ -211,7 +211,8 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 1: Allocate the memory block.
*/
image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
image = (struct image *)
scm_gc_malloc (sizeof (struct image), "image");
/* Step 2: Initialize it with straight code.
*/
@ -228,7 +229,8 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 4: Finish the initialization.
*/
image->name = name;
image->pixels = scm_gc_malloc (width * height, "image pixels");
image->pixels =
scm_gc_malloc (width * height, "image pixels");
return smob;
@}
@ -404,7 +406,9 @@ free_image (SCM image_smob)
@{
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
scm_gc_free (image->pixels, image->width * image->height, "image pixels");
scm_gc_free (image->pixels,
image->width * image->height,
"image pixels");
scm_gc_free (image, sizeof (struct image), "image");
return 0;
@ -517,10 +521,10 @@ Smobs are called smob because they are small: they normally have only
room for one @code{void*} or @code{SCM} value plus 16 bits. The
reason for this is that smobs are directly implemented by using the
low-level, two-word cells of Guile that are also used to implement
pairs, for example. (@pxref{Data Representation} for the details.)
One word of the two-word cells is used for @code{SCM_SMOB_DATA} (or
@code{SCM_SMOB_OBJECT}), the other contains the 16-bit type tag and
the 16 extra bits.
pairs, for example. (@pxref{The Libguile Runtime Environment} for the
details.) One word of the two-word cells is used for
@code{SCM_SMOB_DATA} (or @code{SCM_SMOB_OBJECT}), the other contains
the 16-bit type tag and the 16 extra bits.
In addition to the fundamental two-word cells, Guile also has
four-word cells, which are appropriately called @dfn{double cells}.
@ -583,7 +587,8 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 1: Allocate the memory block.
*/
image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
image = (struct image *)
scm_gc_malloc (sizeof (struct image), "image");
/* Step 2: Initialize it with straight code.
*/
@ -600,7 +605,8 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 4: Finish the initialization.
*/
image->name = name;
image->pixels = scm_gc_malloc (width * height, "image pixels");
image->pixels =
scm_gc_malloc (width * height, "image pixels");
return smob;
@}
@ -642,7 +648,9 @@ free_image (SCM image_smob)
@{
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
scm_gc_free (image->pixels, image->width * image->height, "image pixels");
scm_gc_free (image->pixels,
image->width * image->height,
"image pixels");
scm_gc_free (image, sizeof (struct image), "image");
return 0;

0
doc/goops/mop.text → doc/ref/mop.text
View file

8
doc/ref/posix.texi
View file

@ -1909,10 +1909,6 @@ for termination, not stopping.
If a signal occurs while in a system call, deliver the signal then
restart the system call (as opposed to returning an @code{EINTR} error
from that call).
Guile always enables this flag where available, no matter what
@var{flags} are specified. This avoids spurious error returns in low
level operations.
@end defvar
The return value is a pair with information about the old handler as
@ -2076,9 +2072,9 @@ The following procedures are similar to the @code{popen} and
@code{pclose} system routines. The code is in a separate ``popen''
module:
@smalllisp
@lisp
(use-modules (ice-9 popen))
@end smalllisp
@end lisp
@findex popen
@deffn {Scheme Procedure} open-pipe command mode

30
doc/ref/preface.texi
View file

@ -7,12 +7,9 @@
@node Preface
@chapter 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 @value{MANUAL-EDITION} of the reference manual, and
corresponds to Guile version @value{VERSION}.
This manual documents version @value{VERSION} of Guile, GNU's
Ubiquitous Intelligent Language for Extensions. It describes how to
use Guile in many useful and interesting ways.
@menu
* Manual Layout::
@ -25,7 +22,7 @@ corresponds to Guile version @value{VERSION}.
@node Manual Layout
@section Layout of this Manual
The manual is divided into five chapters.
The manual is divided into the following chapters.
@table @strong
@item Chapter 1: Introduction to Guile
@ -38,7 +35,7 @@ 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.
@item Chapter 2: Programming in Scheme
This part provides an overview over programming in Scheme with Guile.
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
@ -61,6 +58,10 @@ Describes some important modules, distributed as part of the Guile
distribution, that extend the functionality provided by the Guile
Scheme core.
@item Chapter 6: GOOPS
Describes GOOPS, an object oriented extension to Guile that provides
classes, multiple inheritance and generic functions.
@end table
@ -72,7 +73,7 @@ We use some conventions in this manual.
@itemize @bullet
@item
For some procedures, notably type predicates, we use @dfn{iff} to mean
For some procedures, notably type predicates, we use ``iff'' to mean
``if and only if''. The construct is usually something like: `Return
@var{val} iff @var{condition}', where @var{val} is usually
``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that
@ -144,6 +145,9 @@ filling out a lot of the documentation of Scheme data types, control
mechanisms and procedures. In addition, he wrote the documentation
for Guile's SRFI modules and modules associated with the Guile REPL.
The chapter on GOOPS was written by Christian Lynbech, Mikael
Djurfeldt and Neil Jerram.
@node Guile License
@section The Guile License
@cindex copying
@ -159,12 +163,12 @@ person would want to do.
@itemize @bullet
@item
The Guile library (libguile) and supporting files are published under
the terms of the GNU Lesser General Public License version 2.1. See
the file @file{COPYING.LIB}.
the terms of the GNU Lesser General Public License version 3 or later.
See the files @file{COPYING.LESSER} and @file{COPYING}.
@item
The Guile readline module is published under the terms of the GNU
General Public License version 2. See the file @file{COPYING}.
General Public License version 3 or later. See the file @file{COPYING}.
@item
The manual you're now reading is published under the terms of the GNU
@ -179,7 +183,7 @@ C code linking to the Guile readline module is subject to the terms of
that module. Basically such code must be published on Free terms.
Scheme level code written to be run by Guile (but not derived from
Guile itself) is not resticted in any way, and may be published on any
Guile itself) is not restricted in any way, and may be published on any
terms. We encourage authors to publish on Free terms.
You must be aware there is no warranty whatsoever for Guile. This is

12
doc/ref/scheme-debugging.texi
View file

@ -14,9 +14,9 @@ call to that procedure is reported to the user during a program run.
The idea is that you can mark a collection of procedures for tracing,
and Guile will subsequently print out a line of the form
@smalllisp
@lisp
| | [@var{procedure} @var{args} @dots{}]
@end smalllisp
@end lisp
whenever a marked procedure is about to be applied to its arguments.
This can help a programmer determine whether a function is being called
@ -27,7 +27,7 @@ how the traced applications are or are not tail recursive with respect
to each other. Thus, a trace of a non-tail recursive factorial
implementation looks like this:
@smalllisp
@lisp
[fact1 4]
| [fact1 3]
| | [fact1 2]
@ -38,11 +38,11 @@ implementation looks like this:
| | 2
| 6
24
@end smalllisp
@end lisp
While a typical tail recursive implementation would look more like this:
@smalllisp
@lisp
[fact2 4]
[facti 1 4]
[facti 4 3]
@ -50,7 +50,7 @@ While a typical tail recursive implementation would look more like this:
[facti 24 1]
[facti 24 0]
24
@end smalllisp
@end lisp
@deffn {Scheme Procedure} trace procedure
Enable tracing for @code{procedure}. While a program is being run,

6
doc/ref/scheme-ideas.texi
View file

@ -390,7 +390,11 @@ this:
@noindent
This is a valid procedure invocation expression, and its result is the
string @code{"Name=FSF:Address=Cambridge"}.
string:
@lisp
"Name=FSF:Address=Cambridge"
@end lisp
It is more common, though, to store the procedure value in a variable ---

4
doc/ref/scsh.texi
View file

@ -19,8 +19,8 @@ For information about scsh see
The closest emulation of scsh can be obtained by running:
@smalllisp
@lisp
(load-from-path "scsh/init")
@end smalllisp
@end lisp
See the USAGE file supplied with guile-scsh for more details.

13
doc/ref/slib.texi
View file

@ -4,7 +4,6 @@
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@page
@node SLIB
@section SLIB
@cindex SLIB
@ -12,9 +11,9 @@
Before the SLIB facilities can be used, the following Scheme expression
must be executed:
@smalllisp
@lisp
(use-modules (ice-9 slib))
@end smalllisp
@end lisp
@findex require
@code{require} can then be used in the usual way (@pxref{Require,,,
@ -64,7 +63,7 @@ Alternatively, you can create a symlink in the Guile directory to SLIB,
e.g.:
@example
ln -s /usr/local/lib/slib /usr/local/share/guile/1.8/slib
ln -s /usr/local/lib/slib /usr/local/share/guile/@value{EFFECTIVE-VERSION}/slib
@end example
@item
@ -78,7 +77,7 @@ guile> (quit)
@end example
The catalog data should now be in
@file{/usr/local/share/guile/1.8/slibcat}.
@file{/usr/local/share/guile/@value{EFFECTIVE-VERSION}/slibcat}.
If instead you get an error such as:
@ -104,11 +103,11 @@ It is usually installed as an extra package in SLIB.
You can use Guile's interface to SLIB to invoke Jacal:
@smalllisp
@lisp
(use-modules (ice-9 slib))
(slib:load "math")
(math)
@end smalllisp
@end lisp
@noindent
For complete documentation on Jacal, please read the Jacal manual. If

20
doc/ref/srfi-modules.texi
View file

@ -47,6 +47,7 @@ get the relevant SRFI documents from the SRFI home page
* SRFI-61:: A more general `cond' clause
* SRFI-69:: Basic hash tables.
* SRFI-88:: Keyword objects.
* SRFI-98:: Accessing environment variables.
@end menu
@ -3608,6 +3609,25 @@ Return the keyword object whose name is @var{str}.
@end example
@end deffn
@node SRFI-98
@subsection SRFI-98 Accessing environment variables.
@cindex SRFI-98
@cindex environment variables
This is a portable wrapper around Guile's built-in support for
interacting with the current environment, @xref{Runtime Environment}.
@deffn {Scheme Procedure} get-environment-variable name
Returns a string containing the value of the environment variable
given by the string @code{name}, or @code{#f} if the named
environment variable is not found. This is equivalent to
@code{(getenv name)}.
@end deffn
@deffn {Scheme Procedure} get-environment-variables
Returns the names and values of all the environment variables as an
association list in which both the keys and the values are strings.
@end deffn
@c srfi-modules.texi ends here

6
doc/ref/tools.texi
View file

@ -232,8 +232,8 @@ is a expression suitable for initializing a new variable.
For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
want to be bothered with docstrings. Use @code{SCM_GPROC} for generic
functions (@pxref{Creating Generic Functions,,, goops, GOOPS}). All
procedures are declared with return type @code{SCM}.
functions (@pxref{Creating Generic Functions}). All procedures are
declared with return type @code{SCM}.
For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
symbols, and so on). Without "_GLOBAL_", the declarations are
@ -364,7 +364,7 @@ of the form:
@example
(define-module (scripts PROGRAM)
:export (PROGRAM))
#:export (PROGRAM))
@end example
Feel free to export other definitions useful in the module context.

1019
doc/ref/vm.texi Normal file
View file

File diff suppressed because it is too large Load diff

8962
doc/texinfo.tex Normal file
View file

File diff suppressed because it is too large Load diff

16
doc/tutorial/Makefile.am
View file

@ -4,20 +4,20 @@
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu

16
emacs/Makefile.am
View file

@ -4,20 +4,20 @@
##
## This file is part of GUILE.
##
## GUILE 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
## GUILE is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 3, or
## (at your option) any later version.
##
## GUILE 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.
## GNU Lesser General Public License for more details.
##
## You should have received a copy of the GNU General Public
## License along with GUILE; see the file COPYING. If not, write
## to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
## Floor, Boston, MA 02110-1301 USA
## You should have received a copy of the GNU Lesser General Public
## License along with GUILE; see the file COPYING.LESSER. If not,
## write to the Free Software Foundation, Inc., 51 Franklin Street,
## Fifth Floor, Boston, MA 02110-1301 USA
AUTOMAKE_OPTIONS = gnu

225
emacs/gds-faq.txt Executable file
View file

@ -0,0 +1,225 @@
* Installation
** How do I install guile-debugging?
After unpacking the .tar.gz file, run the usual sequence of commands:
$ ./configure
$ make
$ sudo make install
Then you need to make sure that the directory where guile-debugging's
Scheme files were installed is included in your Guile's load path.
(The sequence above will usually install guile-debugging under
/usr/local, and /usr/local is not in Guile's load path by default,
unless Guile itself was installed under /usr/local.) You can discover
your Guile's default load path by typing
$ guile -q -c '(begin (write %load-path) (newline))'
There are two ways to add guile-debugging's installation directory to
Guile's load path, if it isn't already there.
1. Edit or create the `init.scm' file, which Guile reads on startup,
so that it includes a line like this:
(set! %load-path (cons "/usr/local/share/guile" %load-path))
but with "/usr/local" replaced by the prefix that you installed
guile-debugging under, if not /usr/local.
The init.scm file must be installed (if it does not already exist
there) in one of the directories in Guile's default load-path.
2. Add this line to your .emacs file:
(setq gds-scheme-directory "/usr/local/share/guile")
before the `require' or `load' line that loads GDS, but with
"/usr/local" replaced by the prefix that you installed
guile-debugging under, if not /usr/local.
Finally, if you want guile-debugging's GDS interface to be loaded
automatically whenever you run Emacs, add this line to your .emacs:
(require 'gds)
* Troubleshooting
** "error in process filter" when starting Emacs (or loading GDS)
This is caused by an internal error in GDS's Scheme code, for which a
backtrace will have appeared in the gds-debug buffer, so please switch
to the gds-debug buffer and see what it says there.
The most common cause is a load path problem: Guile cannot find GDS's
Scheme code because it is not in the known load path. In this case
you should see the error message "no code for module" somewhere in the
backtrace. If you see this, please try the remedies described in `How
do I install guile-debugging?' above, then restart Emacs and see if
the problem has been cured.
If you don't see "no code for module", or if the described remedies
don't fix the problem, please send the contents of the gds-debug
buffer to me at <neil@ossau.uklinux.net>, so I can debug the problem.
If you don't see a backtrace at all in the gds-debug buffer, try the
next item ...
** "error in process filter" at some other time
This is caused by an internal error somewhere in GDS's Emacs Lisp
code. If possible, please
- switch on the `debug-on-error' option (M-x set-variable RET
debug-on-error RET t RET)
- do whatever you were doing so that the same error happens again
- send the Emacs Lisp stack trace which pops up to me at
<neil@ossau.uklinux.net>.
If that doesn't work, please just mail me with as much detail as
possible of what you were doing when the error occurred.
* GDS Features
** How do I inspect variable values?
Type `e' followed by the name of the variable, then <RET>. This
works whenever GDS is displaying a stack for an error at at a
breakpoint. (You can actually `e' to evaluate any expression in the
local environment of the selected stack frame; inspecting variables is
the special case of this where the expression is only a variable name.)
If GDS is displaying the associated source code in the window above or
below the stack, you can see the values of any variables in the
highlighted code just by hovering your mouse over them.
** How do I change a variable's value?
Type `e' and then `(set! VARNAME NEWVAL)', where VARNAME is the name
of the variable you want to set and NEWVAL is an expression which
Guile can evaluate to get the new value. This works whenever GDS is
displaying a stack for an error at at a breakpoint. The setting will
take effect in the local environment of the selected stack frame.
** How do I change the expression that Guile is about to evaluate?
Type `t' followed by the expression that you want Guile to evaluate
instead, then <RET>.
Then type one of the commands that tells Guile to continue execution.
(Tweaking expressions, as described here, is only supported by the
latest CVS version of Guile. The GDS stack display tells you when
tweaking is possible by adding "(tweakable)" to the first line of the
stack window.)
** How do I return a value from the current stack frame different to what the evaluator has calculated?
You have to be at the normal exit of the relevant frame first, so if
GDS is not already showing you the normally calculated return value,
type `o' to finish the evaluation of the selected frame.
Then type `t' followed by the value you want to return, and <RET>.
The value that you type can be any expression, but note that it will
not be evaluated before being returned; for example if you type `(+ 2
3)', the return value will be a three-element list, not 5.
Finally type one of the commands that tells Guile to continue
execution.
(Tweaking return values, as described here, is only supported by the
latest CVS version of Guile. The GDS stack display tells you when
tweaking is possible by adding "(tweakable)" to the first line of the
stack window.)
** How do I step over a line of code?
Scheme isn't organized by lines, so it doesn't really make sense to
think of stepping over lines. Instead please see the next entry on
stepping over expressions.
** How do I step over an expression?
It depends what you mean by "step over". If you mean that you want
Guile to evaluate that expression normally, but then show you its
return value, type `o', which does exactly that.
If you mean that you want to skip the evaluation of that expression
(for example because it has side effects that you don't want to
happen), use `t' to change the expression to something else which
Guile will evaluate instead.
There has to be a substitute expression so Guile can calculate a value
to return to the calling frame. If you know at a particular point
that the return value is not important, you can type `t #f <RET>' or
`t 0 <RET>'.
See `How do I change the expression that Guile is about to evaluate?'
above for more on using `t'.
** How do I move up and down the call stack?
Type `u' to move up and `d' to move down. "Up" in GDS means to a more
"inner" frame, and "down" means to a more "outer" frame.
** How do I run until the next breakpoint?
Type `g' (for "go").
** How do I run until the end of the selected stack frame?
Type `o'.
** How do I set a breakpoint?
First identify the code that you want to set the breakpoint in, and
what kind of breakpoint you want. To set a breakpoint on entry to a
top level procedure, move the cursor to anywhere in the procedure
definition, and make sure that the region/mark is inactive. To set a
breakpoint on a particular expression (or sequence of expressions) set
point and mark so that the region covers the opening parentheses of
all the target expressions.
Then type ...
`C-c C-b d' for a `debug' breakpoint, which means that GDS will
display the stack when the breakpoint is hit
`C-c C-b t' for a `trace' breakpoint, which means that the start and
end of the relevant procedure or expression(s) will be traced to the
*GDS Trace* buffer
`C-c C-b T' for a `trace-subtree' breakpoint, which means that every
evaluation step involved in the evaluation of the relevant procedure
or expression(s) will be traced to the *GDS Trace* buffer.
You can also type `C-x <SPC>', which does the same as one of the
above, depending on the value of `gds-default-breakpoint-type'.
** How do I clear a breakpoint?
Select a region containing the breakpoints that you want to clear, and
type `C-c C-b <DEL>'.
** How do I trace calls to a particular procedure or evaluations of a particular expression?
In GDS this means setting a breakpoint whose type is `trace' or
`trace-subtree'. See `How do I set a breakpoint?' above.
* Development
** How can I follow or contribute to guile-debugging's development?
guile-debugging is hosted at http://gna.org, so please see the project
page there. Feel free to raise bugs, tasks containing patches or
feature requests, and so on. You can also write directly to me by
email: <neil@ossau.uklinux.net>.
Local Variables:
mode: outline
End:

20
emacs/gds-scheme.el
View file

@ -5,8 +5,7 @@
;;;; This library is free software; you can redistribute it and/or
;;;; modify it under the terms of the GNU Lesser General Public
;;;; License as published by the Free Software Foundation; either
;;;; version 2.1 of the License, or (at your option) any later
;;;; version.
;;;; version 3 of the License, or (at your option) any later version.
;;;;
;;;; This library is distributed in the hope that it will be useful,
;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
@ -207,23 +206,28 @@ Emacs to display an error or trap so that the user can debug it."
"-q"
"--debug"
"-c"
code))
(client nil))
code)))
;; Note that this process can be killed automatically on Emacs
;; exit.
(process-kill-without-query proc)
;; Set up a process filter to catch the new client's number.
(set-process-filter proc
(lambda (proc string)
(setq client (string-to-number string))
(if (process-buffer proc)
(with-current-buffer (process-buffer proc)
(insert string)))))
(insert string)
(or gds-client
(save-excursion
(goto-char (point-min))
(setq gds-client
(condition-case nil
(read (current-buffer))
(error nil)))))))))
;; Accept output from the new process until we have its number.
(while (not client)
(while (not (with-current-buffer (process-buffer proc) gds-client))
(accept-process-output proc))
;; Return the new process's client number.
client))
(with-current-buffer (process-buffer proc) gds-client)))
;;;; Evaluating code.

22
emacs/gds-server.el
View file

@ -5,8 +5,7 @@
;;;; This library is free software; you can redistribute it and/or
;;;; modify it under the terms of the GNU Lesser General Public
;;;; License as published by the Free Software Foundation; either
;;;; version 2.1 of the License, or (at your option) any later
;;;; version.
;;;; version 3 of the License, or (at your option) any later version.
;;;;
;;;; This library is distributed in the hope that it will be useful,
;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
@ -44,25 +43,24 @@
:group 'gds
:type '(choice (const :tag "nil" nil) directory))
(defun gds-start-server (procname port-or-path protocol-handler &optional bufname)
"Start a GDS server process called PROCNAME, listening on TCP port
or Unix domain socket PORT-OR-PATH. PROTOCOL-HANDLER should be a
function that accepts and processes one protocol form. Optional arg
BUFNAME specifies the name of the buffer that is used for process
output; if not specified the buffer name is the same as the process
name."
(with-current-buffer (get-buffer-create (or bufname procname))
(defun gds-start-server (procname unix-socket-name tcp-port protocol-handler)
"Start a GDS server process called PROCNAME, listening on Unix
domain socket UNIX-SOCKET-NAME and TCP port number TCP-PORT.
PROTOCOL-HANDLER should be a function that accepts and processes
one protocol form."
(with-current-buffer (get-buffer-create procname)
(erase-buffer)
(let* ((code (format "(begin
%s
(use-modules (ice-9 gds-server))
(run-server %S))"
(run-server %S %S))"
(if gds-scheme-directory
(concat "(set! %load-path (cons "
(format "%S" gds-scheme-directory)
" %load-path))")
"")
port-or-path))
unix-socket-name
tcp-port))
(process-connection-type nil) ; use a pipe
(proc (start-process procname
(current-buffer)

166
emacs/gds-test.el Normal file
View file

@ -0,0 +1,166 @@
;; Test utility code.
(defun gds-test-execute-keys (keys &optional keys2)
(execute-kbd-macro (apply 'vector (listify-key-sequence keys))))
(defvar gds-test-expecting nil)
(defun gds-test-protocol-hook (form)
(message "[protocol: %s]" (car form))
(if (eq (car form) gds-test-expecting)
(setq gds-test-expecting nil)))
(defun gds-test-expect-protocol (proc &optional timeout)
(message "[expect: %s]" proc)
(setq gds-test-expecting proc)
(while gds-test-expecting
(or (accept-process-output gds-debug-server (or timeout 5))
(error "Timed out after %ds waiting for %s" (or timeout 5) proc))))
(defun gds-test-check-buffer (name &rest strings)
(let ((buf (or (get-buffer name) (error "No %s buffer" name))))
(save-excursion
(set-buffer buf)
(goto-char (point-min))
(while strings
(search-forward (car strings))
(setq strings (cdr strings))))))
(defun TEST (desc)
(message "TEST: %s" desc))
;; Make sure we take GDS elisp code from this code tree.
(setq load-path (cons (concat default-directory "emacs/") load-path))
;; Protect the tests so we can do some cleanups in case of error.
(unwind-protect
(progn
;; Visit the tutorial.
(find-file "gds-tutorial.txt")
(TEST "Load up GDS.")
(search-forward "(require 'gds)")
(setq load-path (cons (concat default-directory "emacs/") load-path))
(gds-test-execute-keys "\C-x\C-e")
;; Install our testing hook.
(add-hook 'gds-protocol-hook 'gds-test-protocol-hook)
(TEST "Help.")
(search-forward "(list-ref")
(backward-char 2)
(gds-test-execute-keys "\C-hg\C-m")
(gds-test-expect-protocol 'eval-results 10)
(gds-test-check-buffer "*Guile Help*"
"help list-ref"
"is a primitive procedure in the (guile) module")
(TEST "Completion.")
(re-search-forward "^with-output-to-s")
(gds-test-execute-keys "\e\C-i")
(beginning-of-line)
(or (looking-at "with-output-to-string")
(error "Expected completion `with-output-to-string' failed"))
(TEST "Eval defun.")
(search-forward "(display z)")
(gds-test-execute-keys "\e\C-x")
(gds-test-expect-protocol 'eval-results)
(gds-test-check-buffer "*Guile Evaluation*"
"(let ((x 1) (y 2))"
"Arctangent is: 0.46"
"=> 0.46")
(TEST "Multiple values.")
(search-forward "(values 'a ")
(gds-test-execute-keys "\e\C-x")
(gds-test-expect-protocol 'eval-results)
(gds-test-check-buffer "*Guile Evaluation*"
"(values 'a"
"hello world"
"=> a"
"=> b"
"=> c")
(TEST "Eval region with multiple expressions.")
(search-forward "(display \"Arctangent is: \")")
(beginning-of-line)
(push-mark nil nil t)
(forward-line 3)
(gds-test-execute-keys "\C-c\C-r")
(gds-test-expect-protocol 'eval-results)
(gds-test-check-buffer "*Guile Evaluation*"
"(display \"Arctangent is"
"Arctangent is:"
"=> no (or unspecified) value"
"ERROR: Unbound variable: z"
"=> error-in-evaluation"
"Evaluating expression 3"
"=> no (or unspecified) value")
(TEST "Eval syntactically unbalanced region.")
(search-forward "(let ((z (atan x y)))")
(beginning-of-line)
(push-mark nil nil t)
(forward-line 4)
(gds-test-execute-keys "\C-c\C-r")
(gds-test-expect-protocol 'eval-results)
(gds-test-check-buffer "*Guile Evaluation*"
"(let ((z (atan"
"Reading expressions to evaluate"
"ERROR"
"end of file"
"=> error-in-read")
(TEST "Stepping through an evaluation.")
(search-forward "(for-each (lambda (x)")
(forward-line 1)
(push-mark nil nil t)
(forward-line 1)
(gds-test-execute-keys "\C-u\e\C-x")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys " ")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "o")
(gds-test-expect-protocol 'stack)
(gds-test-execute-keys "g")
(gds-test-expect-protocol 'eval-results)
(gds-test-check-buffer "*Guile Evaluation*"
"(for-each (lambda"
"Evaluating in current module"
"3 cubed is 27"
"=> no (or unspecified) value")
;; Done.
(message "====================================")
(message "gds-test.el completed without errors")
(message "====================================")
)
(switch-to-buffer "gds-debug")
(write-region (point-min) (point-max) "gds-test.debug")
(switch-to-buffer "*GDS Transcript*")
(write-region (point-min) (point-max) "gds-test.transcript")
)

Some files were not shown because too many files have changed in this diff Show more