mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-06-05 11:40:20 +02:00
bye bye
This commit is contained in:
Thien-Thi Nguyen
parent
a7dc0db49a
commit
8660251f7d
29 changed files with 0 additions and 1467 deletions
|
|
@ -1,295 +0,0 @@
|
||||||
@c devel/modules/desgin-notes.texi
|
|
||||||
|
|
||||||
@c TODO
|
|
||||||
@c - distill wishlist, index
|
|
||||||
@c - in Findings, characterize current module system wrt wishlist
|
|
||||||
|
|
||||||
@node Module System Design Notes
|
|
||||||
@chapter Module System Design Notes
|
|
||||||
|
|
||||||
This chapter documents module system design history. At the moment
|
|
||||||
(guile-1.5.4, 2002-02-08), the module system is supposedly undergoing
|
|
||||||
redesign; the provisional implementation works but has problems, notably
|
|
||||||
making compilation difficult.
|
|
||||||
|
|
||||||
Because module systems design is (was?) an area of active research and
|
|
||||||
development in the Scheme community, many different features are possible.
|
|
||||||
This section is a historical record of the selection process used by the Guile
|
|
||||||
hackers (if one can be discerned).
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Wishlist::
|
|
||||||
* Findings::
|
|
||||||
* Selection Criteria::
|
|
||||||
* Rationale Statements::
|
|
||||||
* Specification::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Wishlist
|
|
||||||
@subsection Wishlist
|
|
||||||
|
|
||||||
In the guile-related mailing lists of yore, discussion resulted in the
|
|
||||||
following desirable traits. Note that some of these contradict each other.
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
|
|
||||||
@item
|
|
||||||
support separate compilation
|
|
||||||
|
|
||||||
@item
|
|
||||||
hierarchical module names
|
|
||||||
|
|
||||||
@item
|
|
||||||
support relative references within the module name space (so that a
|
|
||||||
module within a package can use a sibling module without knowing the
|
|
||||||
prefix of the module name)
|
|
||||||
|
|
||||||
@item
|
|
||||||
support re-use of code (the same implementation can be presented to
|
|
||||||
the world through several interfaces)
|
|
||||||
|
|
||||||
@item
|
|
||||||
support individual and group renaming of bindings when using other
|
|
||||||
modules
|
|
||||||
|
|
||||||
@item
|
|
||||||
easy to import and re-export entire interfaces (so that a main
|
|
||||||
interface in a package can function as a "relay" and publish
|
|
||||||
bindings from many modules in the package)
|
|
||||||
|
|
||||||
@item
|
|
||||||
support both variable and syntactic bindings (these should be
|
|
||||||
clearly separated, though) and mesh well with hygienic macro
|
|
||||||
systems
|
|
||||||
|
|
||||||
@item
|
|
||||||
hygienic implies that we shouldn't need to care to export bindings
|
|
||||||
which an exported macro introduces at the point of its use
|
|
||||||
|
|
||||||
@item
|
|
||||||
autoloading
|
|
||||||
|
|
||||||
@item
|
|
||||||
unmemoization protocol
|
|
||||||
|
|
||||||
@item
|
|
||||||
cleanliness
|
|
||||||
|
|
||||||
A module should be able to be totally clean. There should be no
|
|
||||||
need to have *any* extra bindings in a module (a la
|
|
||||||
%module-interface or `define-module').
|
|
||||||
|
|
||||||
Therefore, we should have at least one dedicated "command" or
|
|
||||||
"config" or "repl" module.
|
|
||||||
|
|
||||||
It would probably be a good idea to follow other good Scheme
|
|
||||||
interpreters' lead and introduce the ,<command> syntax for walking
|
|
||||||
around modules, inspecting things, entering the debugger, etc.
|
|
||||||
Such commands can be looked up in this repl module.
|
|
||||||
|
|
||||||
If we insist on not using ,<command> syntax, we are forced to let
|
|
||||||
the module use list consist of a "sticky" part and the rest, where
|
|
||||||
the "sticky" part is only available at the repl prompt and not to
|
|
||||||
the code within the module, and which follows us when we walk around
|
|
||||||
in the system.
|
|
||||||
|
|
||||||
@item
|
|
||||||
well integrated with the translator framework
|
|
||||||
|
|
||||||
We should be able to say that a module uses a different syntax or
|
|
||||||
language.
|
|
||||||
|
|
||||||
Note here the nice config language of the Scheme48 module system
|
|
||||||
where it is possible to separate code from module specification: the
|
|
||||||
module specification can use scheme syntax and rest in one file,
|
|
||||||
while the module itself can use the syntax of another language.
|
|
||||||
|
|
||||||
This config language also supports re-use of code in a neat way.
|
|
||||||
|
|
||||||
@item
|
|
||||||
examine connection with object system: how easy is it to support
|
|
||||||
Java and other class-centered object systems?
|
|
||||||
|
|
||||||
@item
|
|
||||||
easy to export the same module under several different names
|
|
||||||
|
|
||||||
@item
|
|
||||||
easily supports both compiled and interpreted modules
|
|
||||||
|
|
||||||
@item
|
|
||||||
compiled modules can by dynamically loaded or statically linked in
|
|
||||||
(libltdl might provide this automatically)
|
|
||||||
|
|
||||||
@item
|
|
||||||
convenient syntax for referencing bindings in modules that are
|
|
||||||
loaded but not used
|
|
||||||
|
|
||||||
(Assuming this distinction exists.) But maybe group renaming is a better
|
|
||||||
solution to a similar class of problems.
|
|
||||||
|
|
||||||
@item
|
|
||||||
ability to unuse a module (and have it get collected when there are
|
|
||||||
no more references)
|
|
||||||
|
|
||||||
@item
|
|
||||||
orthoganality between source files, directories and modules. i.e. ability to
|
|
||||||
have multiple modules in one source file and/or multiple source files in one
|
|
||||||
module
|
|
||||||
|
|
||||||
@item
|
|
||||||
backward compatibility
|
|
||||||
|
|
||||||
@item
|
|
||||||
whenever possible the module's meta-information should be stored
|
|
||||||
within the module itself (only possible for scheme files)
|
|
||||||
|
|
||||||
@item
|
|
||||||
the compiler stores the meta-information into a single file and updates it
|
|
||||||
accordingly
|
|
||||||
|
|
||||||
(FIXME: per module, per package, directory?, per project?) This
|
|
||||||
meta-information should still be human readable (Sun's EJB use XML for their
|
|
||||||
deployment descriptors).
|
|
||||||
|
|
||||||
@item
|
|
||||||
use the file system as module repository
|
|
||||||
|
|
||||||
Since guile is a GNU project we can expect a GNU (or Unix) environment. That
|
|
||||||
means that we should use the file system as the module repository. (This
|
|
||||||
would help us avoid modules pointing to files which are pointing to other
|
|
||||||
files telling the user "hey, that's me (the module) over there".)
|
|
||||||
|
|
||||||
@item
|
|
||||||
every module has exactly @emph{one} owner who is responsible for the
|
|
||||||
module @emph{and} its interface (this contradicts with the "more than one
|
|
||||||
interface" concept)
|
|
||||||
|
|
||||||
@item
|
|
||||||
support module collections
|
|
||||||
|
|
||||||
Provide "packages" with a package scope for people working together on a
|
|
||||||
project. In some sense a module is a view on the underlying package.
|
|
||||||
|
|
||||||
@item
|
|
||||||
ability to request (i.e. import or access) complete packages
|
|
||||||
|
|
||||||
@item
|
|
||||||
support module "generations" (or "versions")
|
|
||||||
|
|
||||||
Whenever a new module fails to handle a request (due to an error) it will be
|
|
||||||
replaced by the old version.
|
|
||||||
|
|
||||||
@item
|
|
||||||
help the user to handle exceptions (note: exceptions
|
|
||||||
are not errors, see above)
|
|
||||||
|
|
||||||
@item
|
|
||||||
no special configuration language (like @code{,in} etc.)
|
|
||||||
|
|
||||||
You can always press Control-D to terminate the module's repl and return to
|
|
||||||
the config module.
|
|
||||||
|
|
||||||
@item
|
|
||||||
both C and Scheme level interfaces
|
|
||||||
|
|
||||||
@item
|
|
||||||
programming interface to module system primitives
|
|
||||||
|
|
||||||
One should be able to make customized module systems from the low-level
|
|
||||||
interface, as an alternative to using the default module system. The
|
|
||||||
default module system should use the same low-level procedures.
|
|
||||||
|
|
||||||
@item
|
|
||||||
Here are some features Keisuke Nishida desires to support his VM/compiler
|
|
||||||
[snarfed directly from post <m37l33z0cl.wl@kei.cwru.edu> dated 2001-02-06,
|
|
||||||
and requires formatting]:
|
|
||||||
|
|
||||||
* There is no "current module".
|
|
||||||
|
|
||||||
* Module variables are globally identified by an identifier
|
|
||||||
like "system::core::car".
|
|
||||||
|
|
||||||
* Bindings are solved syntactically, either by a translator
|
|
||||||
or a compiler. If you write just "car", it is expanded to
|
|
||||||
"system::core::car" by a translator or compiler, depending
|
|
||||||
on what modules you use.
|
|
||||||
|
|
||||||
* An interpreter (repl) may memorize the "current working module".
|
|
||||||
It tells the translator or the compiler what modules should be
|
|
||||||
used to identify a variable. So, during interactive sessions,
|
|
||||||
a user may feel as if there *is* the current module.
|
|
||||||
|
|
||||||
* But the fact is, all variables are globally identified at
|
|
||||||
syntax level. Therefore, the compiler can identify all
|
|
||||||
variables at compile time. This means the following code
|
|
||||||
is not allowed:
|
|
||||||
|
|
||||||
;; I want to access `foo' in the module named some-module-name
|
|
||||||
(let ((module (lookup-module some-module-name)))
|
|
||||||
(set! (current-module) module)
|
|
||||||
(foo x))
|
|
||||||
-> ERROR: Unbound variable: current-module
|
|
||||||
|
|
||||||
(let ((module (lookup-module some-module-name)))
|
|
||||||
(module::foo x))
|
|
||||||
-> ERROR: There is no variable named "module::foo"
|
|
||||||
|
|
||||||
Instead, you should write as follows if you need a dynamic access:
|
|
||||||
|
|
||||||
(let ((module (lookup-module some-module-name)))
|
|
||||||
((module-ref module 'foo) x))
|
|
||||||
|
|
||||||
(let ((module (lookup-module some-module-name)))
|
|
||||||
((module 'foo) x)) ;; if module is an applicable smob
|
|
||||||
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@c $Date: 2002-02-08 10:50:36 $
|
|
||||||
@node Findings
|
|
||||||
@subsection Findings
|
|
||||||
|
|
||||||
This section briefly describes module system truths that are one step more
|
|
||||||
detailed than "module systems are hairy". These truths are not self-evident;
|
|
||||||
we rely on research, active experimentation and lots of discussion. The goal
|
|
||||||
of this section is to save ourselves from rehashing that which was hashed
|
|
||||||
previously.
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
|
|
||||||
@item Kent Dybvig's module system
|
|
||||||
|
|
||||||
A paper is available at
|
|
||||||
@uref{http://www.cs.indiana.edu/~dyb/papers/popl99.ps.gz,
|
|
||||||
http://www.cs.indiana.edu/~dyb/papers/popl99.ps.gz}.
|
|
||||||
|
|
||||||
This was discussed in 2000-11 and 2000-12.
|
|
||||||
|
|
||||||
@item Distinction between Top-Level Environment and Module
|
|
||||||
|
|
||||||
These two are different beasts! Each of the following needs to be
|
|
||||||
well-defined with respect to both of these concepts: @code{eval},
|
|
||||||
@code{define}, @code{define-public}, @code{define-module}, @code{load},
|
|
||||||
working from REPL, top-level @code{begin}, [add here].
|
|
||||||
|
|
||||||
In guile-1.4, the distinction was not clear.
|
|
||||||
|
|
||||||
@item Current module system internals
|
|
||||||
|
|
||||||
@xref{Top,Module Internals,,module-snippets}, for implemetation
|
|
||||||
details of the module system up to and including guile-1.6.x.
|
|
||||||
|
|
||||||
@item [add here]
|
|
||||||
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@node Selection Criteria
|
|
||||||
@subsection Selection Criteria
|
|
||||||
|
|
||||||
@node Rationale Statements
|
|
||||||
@subsection Rationale Statements
|
|
||||||
|
|
||||||
@node Specification
|
|
||||||
@subsection Specification
|
|
||||||
|
|
||||||
|
|
||||||
@c devel/modules/desgin-notes.texi ends here
|
|
||||||
|
|
@ -1,288 +0,0 @@
|
||||||
Module Layout Proposal
|
|
||||||
======================
|
|
||||||
|
|
||||||
Martin Grabmueller
|
|
||||||
<mgrabmue@cs.tu-berlin.de>
|
|
||||||
Draft: 2001-03-11
|
|
||||||
|
|
||||||
Version: $Id: module-layout.text,v 1.1 2001-03-16 08:37:37 mgrabmue Exp $
|
|
||||||
|
|
||||||
* Table of contents
|
|
||||||
|
|
||||||
** Abstract
|
|
||||||
** Overview
|
|
||||||
*** What do we have now?
|
|
||||||
*** What should we change?
|
|
||||||
** Policy of module separation
|
|
||||||
*** Functionality
|
|
||||||
*** Standards
|
|
||||||
*** Importance
|
|
||||||
*** Compatibility
|
|
||||||
** Module naming
|
|
||||||
*** Scheme
|
|
||||||
*** Object oriented programming
|
|
||||||
*** Systems programming
|
|
||||||
*** Database programming
|
|
||||||
*** Text processing
|
|
||||||
*** Math programming
|
|
||||||
*** Network programming
|
|
||||||
*** Graphics
|
|
||||||
*** GTK+ programming
|
|
||||||
*** X programming
|
|
||||||
*** Games
|
|
||||||
*** Multiple names
|
|
||||||
*** Application modules
|
|
||||||
** Future ideas
|
|
||||||
|
|
||||||
|
|
||||||
* Abstract
|
|
||||||
|
|
||||||
This is a proposal for a new layout of the module name space. The
|
|
||||||
goal is to reduce (or even eliminate) the clutter in the current ice-9
|
|
||||||
module directory, and to provide a clean framework for splitting
|
|
||||||
libguile into subsystems, grouped by functionality, standards
|
|
||||||
compliance and maybe other characteristics.
|
|
||||||
|
|
||||||
This is not a completed policy document, but rather a collection of
|
|
||||||
ideas and proposals which still have to be decided. I will mention by
|
|
||||||
personal preference, where appropriate, but the final decisions are of
|
|
||||||
course up to the maintainers.
|
|
||||||
|
|
||||||
|
|
||||||
* Overview
|
|
||||||
|
|
||||||
Currently, new modules are added in an ad-hoc manner to the ice-9
|
|
||||||
module name space when the need for them arises. I think that was
|
|
||||||
mainly because no other directory for installed Scheme modules was
|
|
||||||
created. With the integration of GOOPS, the new top-level module
|
|
||||||
directory oop was introduced, and we should follow this practice for
|
|
||||||
other subsystems which share functionality.
|
|
||||||
|
|
||||||
DISCLAIMER: Please note that I am no expert on Guile's module system,
|
|
||||||
so be patient with me and correct me where I got anything wrong.
|
|
||||||
|
|
||||||
** What do we have now?
|
|
||||||
|
|
||||||
The module (oop goops) contains all functionality needed for
|
|
||||||
object-oriented programming with Guile (with a few exceptions in the
|
|
||||||
evaluator, which is clearly needed for performance).
|
|
||||||
|
|
||||||
Except for the procedures in the module (ice-9 rdelim), all Guile
|
|
||||||
primitives are currently located in the root module (I think it is the
|
|
||||||
module (guile)), and some procedures defined in `boot-9.scm' are
|
|
||||||
installed in the module (guile-user).
|
|
||||||
|
|
||||||
** What should we change?
|
|
||||||
|
|
||||||
In the core, there are a lot of primitive procedures which can cleanly
|
|
||||||
be grouped into subsystems, and then grouped into modules. That would
|
|
||||||
make the core library more maintainable, would ease seperate testing
|
|
||||||
of subsystems and clean up dependencies between subsystems.
|
|
||||||
|
|
||||||
|
|
||||||
* Policy of module separation
|
|
||||||
|
|
||||||
There are several possibilities to group procedures into modules.
|
|
||||||
|
|
||||||
- They could be grouped by functionality.
|
|
||||||
- They could be grouped by standards compliance.
|
|
||||||
- They could be grouped by level of importance.
|
|
||||||
|
|
||||||
One important group of modules should of course be provided
|
|
||||||
additionally:
|
|
||||||
|
|
||||||
- Compatibility modules.
|
|
||||||
|
|
||||||
So the first thing to decide is: Which of these policies should we
|
|
||||||
adopt? Personally, I think that it is not possible to cleanly use
|
|
||||||
exactly one of the possibilities, we will probably use a mixture of
|
|
||||||
them. I propose to group by functionality, and maybe use some
|
|
||||||
`bridge-modules', which make functionality available when the user
|
|
||||||
requests the modules for a given standard.
|
|
||||||
|
|
||||||
** Functionality
|
|
||||||
|
|
||||||
Candidates for the first possibility are groups of procedures, which
|
|
||||||
already are grouped in source files, such as
|
|
||||||
|
|
||||||
- Regular expression procedures.
|
|
||||||
- Network procedures.
|
|
||||||
- Systems programming procedures.
|
|
||||||
- Random number procedures.
|
|
||||||
- Math/numeric procedures.
|
|
||||||
- String-processing procedures.
|
|
||||||
- List-processing procedures.
|
|
||||||
- Character handling procedures.
|
|
||||||
- Object-oriented programming support.
|
|
||||||
|
|
||||||
** Standards
|
|
||||||
|
|
||||||
Guile now complies to R5RS, and I think that the procedures required
|
|
||||||
by this standards should always be available to the programmer.
|
|
||||||
People who do not want them, could always create :pure modules when
|
|
||||||
they need it.
|
|
||||||
|
|
||||||
On the other hand, the SRFI procedures fit nicely into a `group by
|
|
||||||
standards' scheme. An example which is already provided, is the
|
|
||||||
SRFI-8 syntax `receive'. Following that, we could provide two modules
|
|
||||||
for each SRFI, one named after the SRFI (like `srfi-8') and one named
|
|
||||||
after the main functionality (`receive').
|
|
||||||
|
|
||||||
** Importance
|
|
||||||
|
|
||||||
By importance, I mean `how important are procedures for the average
|
|
||||||
Guile user'. That means that procedures which are only useful to a
|
|
||||||
small group of users (the Guile developers, for example) should not be
|
|
||||||
immediately available at the REPL, so that they not confuse the user
|
|
||||||
when thay appear in the `apropos' output or the tab completion.
|
|
||||||
|
|
||||||
A good example would be debugging procedures (which also could be
|
|
||||||
added with a special command-line option), or low-level system calls.
|
|
||||||
|
|
||||||
** Compatibility
|
|
||||||
|
|
||||||
This group is for modules providing compatibility procedures. An
|
|
||||||
example would be a module for old string-processing procedures, which
|
|
||||||
could someday get overridden by incompatible SRFI procedures of the
|
|
||||||
same name.
|
|
||||||
|
|
||||||
|
|
||||||
* Module naming
|
|
||||||
|
|
||||||
Provided we choose to take the `group by functionality' approach, I
|
|
||||||
propose the following naming hierarchy (some of them were actually
|
|
||||||
suggested by Mikael Djurfeldt).
|
|
||||||
|
|
||||||
- Schame language related in (scheme)
|
|
||||||
- Object oriented programming in (oop)
|
|
||||||
- Systems programming in (system)
|
|
||||||
- Database programming in (database)
|
|
||||||
- Text processing in (text)
|
|
||||||
- Math/numeric programming in (math)
|
|
||||||
- Network programming in (network)
|
|
||||||
- Graphics programming in (graphics)
|
|
||||||
- GTK+ programming in (gtk)
|
|
||||||
- X programming in (xlib)
|
|
||||||
- Games in (games)
|
|
||||||
|
|
||||||
The layout of sub-hierarchies is up to the writers of modules, we
|
|
||||||
should not enforce a strict policy here, because we can not imagine
|
|
||||||
what will happen in this area.
|
|
||||||
|
|
||||||
** Scheme
|
|
||||||
|
|
||||||
(scheme r5rs) Complete R5RS procedures set.
|
|
||||||
(scheme safe) Safe modules.
|
|
||||||
(scheme srfi-1) List processing.
|
|
||||||
(scheme srfi-8) Multiple valuas via `receive'.
|
|
||||||
(scheme receive) dito.
|
|
||||||
(scheme and-let-star) and-let*
|
|
||||||
(scheme syncase) syntax-case hygienic macros (maybe included in
|
|
||||||
(scheme r5rs?).
|
|
||||||
(scheme slib) SLIB, for historic reasons in (scheme).
|
|
||||||
|
|
||||||
** Object oriented programming
|
|
||||||
|
|
||||||
Examples in this section are
|
|
||||||
(oop goops) For GOOPS.
|
|
||||||
(oop goops ...) For lower-level GOOPS functionality and utilities.
|
|
||||||
|
|
||||||
** Systems programming
|
|
||||||
|
|
||||||
(system shell) Shell utilities (glob, system etc).
|
|
||||||
(system process) Process handling.
|
|
||||||
(system file-system) Low-level filesystem support.
|
|
||||||
(system user) getuid, setpgrp, etc.
|
|
||||||
|
|
||||||
_or_
|
|
||||||
|
|
||||||
(system posix) All posix procedures.
|
|
||||||
|
|
||||||
** Database programming
|
|
||||||
|
|
||||||
In the database section, there should be sub-module hierarchies for
|
|
||||||
each supported database which contains the low-level code, and a
|
|
||||||
common database layer, which should unify access to SQL databases via a single interface a la Perl's DBMI.
|
|
||||||
|
|
||||||
(database postgres ...) Low-level database functionality.
|
|
||||||
(database oracle ...) ...
|
|
||||||
(database mysql ...) ...
|
|
||||||
(database msql ...) ...
|
|
||||||
(database sql) Common SQL accessors.
|
|
||||||
(database gdbm ...) ...
|
|
||||||
(database hashed) Common hashed database accessors (like gdbm).
|
|
||||||
(database util) Leftovers.
|
|
||||||
|
|
||||||
** Text processing
|
|
||||||
|
|
||||||
(text rdelim) Line oriented in-/output.
|
|
||||||
(text util) Mangling text files.
|
|
||||||
|
|
||||||
** Math programming
|
|
||||||
|
|
||||||
(math random) Random numbers.
|
|
||||||
(math primes) Prime numbers.
|
|
||||||
(math vector) Vector math.
|
|
||||||
(math algebra) Algebra.
|
|
||||||
(math analysis) Analysis.
|
|
||||||
(math util) Leftovers.
|
|
||||||
|
|
||||||
** Network programming
|
|
||||||
|
|
||||||
(network inet) Internet procedures.
|
|
||||||
(network socket) Socket interface.
|
|
||||||
(network db) Network database accessors.
|
|
||||||
(network util) ntohl, htons and friends.
|
|
||||||
|
|
||||||
** Graphics
|
|
||||||
|
|
||||||
(graphics vector) Generalized vector graphics handling.
|
|
||||||
(graphics vector vrml) VRML parsers etc.
|
|
||||||
(graphisc bitmap) Generalized bitmap handling.
|
|
||||||
(graphics bitmap ...) Bitmap format handling (TIFF, PNG, etc.).
|
|
||||||
|
|
||||||
** GTK+ programming
|
|
||||||
|
|
||||||
(gtk gtk) GTK+ procedures.
|
|
||||||
(gtk gdk) GDK procedures.
|
|
||||||
(gtk threads) gtktreads.
|
|
||||||
|
|
||||||
** X programming
|
|
||||||
|
|
||||||
(xlib xlib) Low-level XLib programming.
|
|
||||||
|
|
||||||
** Games
|
|
||||||
|
|
||||||
(games robots) GNU robots.
|
|
||||||
|
|
||||||
** Multiple names
|
|
||||||
|
|
||||||
As already mentioned above, I think that some modules should have
|
|
||||||
several names, to make it easier for the user to get the functionality
|
|
||||||
she needs. For example, a user could say: `hey, I need the receive
|
|
||||||
macro', or she could say: `I want to stick to SRFI syntax, so where
|
|
||||||
the hell is the module for SRFI-8?!?'.
|
|
||||||
|
|
||||||
** Application modules
|
|
||||||
|
|
||||||
We should not enforce policy on applications. So I propose that
|
|
||||||
application writers should be advised to place modules either in
|
|
||||||
application-specific directories $PREFIX/share/$APP/guile/... and name
|
|
||||||
that however they like, or to use the application's name as the first
|
|
||||||
part of the module name, e.g (gnucash import), (scwm background),
|
|
||||||
(rcalc ui).
|
|
||||||
|
|
||||||
* Future ideas
|
|
||||||
|
|
||||||
I have not yet come up with a good idea for grouping modules, which
|
|
||||||
deal for example with XML processing. They would fit into the (text)
|
|
||||||
module space, because most XML files contain text data, but they would
|
|
||||||
also fit into (database), because XML files are essentially databases.
|
|
||||||
|
|
||||||
On the other hand, XML processing is such a large field that it
|
|
||||||
probably is worth it's own top-level name space (xml).
|
|
||||||
|
|
||||||
|
|
||||||
Local Variables:
|
|
||||||
mode: outline
|
|
||||||
End:
|
|
||||||
|
|
@ -1,149 +0,0 @@
|
||||||
* Intro / Index (last modified: $Date: 2002-02-28 05:09:19 $)
|
|
||||||
|
|
||||||
This working document explains the design of the libguile API,
|
|
||||||
specifically the interface to the C programming language.
|
|
||||||
Note that this is NOT an API reference manual.
|
|
||||||
|
|
||||||
- Motivation
|
|
||||||
- History
|
|
||||||
- Decisions
|
|
||||||
- gh_ removal
|
|
||||||
- malloc policy
|
|
||||||
- [add here]
|
|
||||||
|
|
||||||
|
|
||||||
* Motivation
|
|
||||||
|
|
||||||
The file goals.text says:
|
|
||||||
|
|
||||||
Guile's primary aim is to provide a good extension language
|
|
||||||
which is easy to add to an application written in C for the GNU
|
|
||||||
system. This means that it must export the features of a higher
|
|
||||||
level language in a way that makes it easy not to break them
|
|
||||||
from C code.
|
|
||||||
|
|
||||||
Although it may no longer be a "primary aim", creating a stable API is
|
|
||||||
important anyway since without something defined, people will take libguile
|
|
||||||
and use it in ad-hoc ways that may cause them trouble later.
|
|
||||||
|
|
||||||
|
|
||||||
* History
|
|
||||||
|
|
||||||
The initial (in ttn's memory, which only goes back to guile-1.3.4) stab at an
|
|
||||||
API was known as the "gh_ interface", which provided "high-level" abstraction
|
|
||||||
to libguile w/ the premise of supporting multiple implementations at some
|
|
||||||
future date. In practice this approach resulted in many gh_* objects being
|
|
||||||
very slight wrappers for the underlying scm_* objects, so eventually this
|
|
||||||
maintenance burden outweighed the (as yet unrealized) hope for alternate
|
|
||||||
implementations, and the gh_ interface was deprecated starting in guile-1.5.x.
|
|
||||||
|
|
||||||
Starting w/ guile-1.7.x, in concurrence w/ an effort to make libguile
|
|
||||||
available to usloth windows platforms, the naked library was once again
|
|
||||||
dressed w/ the "SCM_API interface".
|
|
||||||
|
|
||||||
Here is a table of versions (! means planned):
|
|
||||||
|
|
||||||
guile libguile readline qthreads srfi-4 -13-14
|
|
||||||
---------------------------------------------------
|
|
||||||
1.3.4 6.0.0 0.0.0 0.0.0 - -
|
|
||||||
1.4 9.0.0 0.0.0 0.0.0 - -
|
|
||||||
1.4.1 10.0.0 TBD 15.0.0 - - !
|
|
||||||
1.6.x 15.0.0 10.0.0 15.0.0 1.0.0 1.0.0 !
|
|
||||||
|
|
||||||
Note: These are libtool-style versions: CURRENT:REVISION:AGE
|
|
||||||
|
|
||||||
|
|
||||||
* Decisions
|
|
||||||
|
|
||||||
** gh_ removal
|
|
||||||
|
|
||||||
At some point, we need to remove gh_ entirely: guile-X.Y.Z.
|
|
||||||
|
|
||||||
** malloc policy
|
|
||||||
|
|
||||||
Here's a proposal by ela:
|
|
||||||
|
|
||||||
I would like to propose the follow gh_() equivalents:
|
|
||||||
|
|
||||||
gh_scm2newstr() -> scm_string2str() in string.[ch]
|
|
||||||
gh_symbol2newstr() -> scm_symbol2str() in symbol.[ch]
|
|
||||||
|
|
||||||
Both taking the (SCM obj, char *context) and allocating memory via
|
|
||||||
scm_must_malloc(). Thus the user can safely free the returned strings
|
|
||||||
with scm_must_free(). The latter feature would be an improvement to the
|
|
||||||
previous gh_() interface functions, for which the user was told to free()
|
|
||||||
them directly. This caused problems when libguile.so used libc malloc()
|
|
||||||
and the calling application used its own standard free(), which might not
|
|
||||||
be libc free().
|
|
||||||
|
|
||||||
It seems to address the general question of: How should client programs use
|
|
||||||
malloc with respect to libguile? Some specific questions:
|
|
||||||
|
|
||||||
* Do you like the names of the functions? Maybe they should be named
|
|
||||||
scm_c_*() instead of scm_*().
|
|
||||||
* Do they make sense?
|
|
||||||
* Should we provide something like scm_c_free() for pointers returned by
|
|
||||||
these kind of functions?
|
|
||||||
|
|
||||||
The first proposal regarding a malloc policy has been rejected for the
|
|
||||||
following resons:
|
|
||||||
|
|
||||||
That would mean, users of guile - even on non M$ systems - would have to
|
|
||||||
keep track where their memory came from?
|
|
||||||
Assume there are users which have some kind of hash table where they store
|
|
||||||
strings in. The hash table is responsible for removing entries from the
|
|
||||||
table. Now, if you want to put strings from guile as well as other
|
|
||||||
strings into that table you would have to store a pointer to the
|
|
||||||
corresponding version of 'free' with every string? We should demand such
|
|
||||||
coding from all guile users?
|
|
||||||
|
|
||||||
The proposal itself read: For a clean memory interface of a client program
|
|
||||||
to libguile we use the following functions from libguile:
|
|
||||||
|
|
||||||
* scm_c_malloc -- should be used to allocate memory returned by some
|
|
||||||
of the SCM to C converter functions in libguile if the
|
|
||||||
client program does not supply memory
|
|
||||||
* scm_c_free -- must be used by the client program to free the memory
|
|
||||||
returned by the SCM to C converter functions in
|
|
||||||
libguile if the client program did not supply a buffer
|
|
||||||
* scm_c_realloc -- to be complete, do not know a real purpose yet
|
|
||||||
|
|
||||||
|
|
||||||
Yet another proposal regarding this problem reads as follows: We could make
|
|
||||||
life easier, if we supplied the following:
|
|
||||||
|
|
||||||
[in gc.h]
|
|
||||||
typedef void * (* scm_t_malloc_func) (size_t);
|
|
||||||
typedef void (* svz_t_free_func) (void *);
|
|
||||||
SCM_API scm_t_malloc_func scm_c_malloc;
|
|
||||||
SCM_API scm_t_free_func scm_c_free;
|
|
||||||
|
|
||||||
[in gc.c]
|
|
||||||
{
|
|
||||||
/* At some library initialization point. */
|
|
||||||
scm_c_malloc = malloc;
|
|
||||||
scm_c_free = free;
|
|
||||||
}
|
|
||||||
|
|
||||||
Then the SCM to C converters allocating memory to store their results use
|
|
||||||
scm_c_malloc() instead of simply malloc(). This way all libguile/Unix users
|
|
||||||
can stick to the previous free() policy, saying that you need to free()
|
|
||||||
pointers delivered by libguile. On the other hand M$-Windows users can pass
|
|
||||||
their own malloc()-function-pointer to the library and use their own free()
|
|
||||||
then. Basically this can be achieved in the following order:
|
|
||||||
|
|
||||||
{
|
|
||||||
char *str;
|
|
||||||
scm_boot_guile (...);
|
|
||||||
scm_c_malloc = malloc;
|
|
||||||
str = scm_c_string2str (obj, NULL, NULL);
|
|
||||||
free (str);
|
|
||||||
}
|
|
||||||
|
|
||||||
This policy is still discussed:
|
|
||||||
If there is one global variable scm_c_malloc, then setting it within one
|
|
||||||
thread may interfere with another thread that expects scm_c_malloc to be
|
|
||||||
set differently. In other words, you would have to introduce some locking
|
|
||||||
mechanism to guarantee that the sequence of setting scm_c_malloc and
|
|
||||||
calling scm_string2str can not be interrupted by a different thread that
|
|
||||||
sets scm_c_malloc to a different value.
|
|
||||||
|
|
@ -1,143 +0,0 @@
|
||||||
Implementation of shared substrings with fresh-copy semantics
|
|
||||||
=============================================================
|
|
||||||
|
|
||||||
Version: $Id: sharedstr.text,v 1.1 2000-08-26 20:55:21 mdj Exp $
|
|
||||||
|
|
||||||
Background
|
|
||||||
----------
|
|
||||||
|
|
||||||
In Guile, most string operations work on two other data types apart
|
|
||||||
from strings: shared substrings and read-only strings (which includes
|
|
||||||
symbols). One of Guile's sub-goals is to be a scripting language in
|
|
||||||
which string management is important. Read-only strings and shared
|
|
||||||
substrings were introduced in order to reduce overhead in string
|
|
||||||
manipulation.
|
|
||||||
|
|
||||||
We now want to simplify the Guile API by removing these two data
|
|
||||||
types, but keeping performance by allowing ordinary strings to share
|
|
||||||
storage.
|
|
||||||
|
|
||||||
The idea is to let operations like `symbol->string' and `substring'
|
|
||||||
return a pointer into the original string/symbol, thus avoiding the
|
|
||||||
need to copy the string.
|
|
||||||
|
|
||||||
Two of the problems which then arise are:
|
|
||||||
|
|
||||||
* If s2 is derived from s1, and therefore share storage with s1, a
|
|
||||||
modification to either s1 or s2 will affect the other.
|
|
||||||
|
|
||||||
* Guile is supposed to interact closely with many UNIX libraries in
|
|
||||||
which the NUL character is used to terminate strings. Therefore
|
|
||||||
Guile strings contain a NUL character at the end, in addition to the
|
|
||||||
string length (the latter of which is used by Guile's string
|
|
||||||
operations).
|
|
||||||
|
|
||||||
The solutions to these problems are to
|
|
||||||
|
|
||||||
* Copy a string with shared storage when it's modified.
|
|
||||||
|
|
||||||
* Copy a string with shared storage when it's being used as argument
|
|
||||||
to a C library call. (Copying implies inserting an ending NUL
|
|
||||||
character.)
|
|
||||||
|
|
||||||
But this leads to memory management problems. When is it OK to free
|
|
||||||
a character array which was allocated for a symbol or a string?
|
|
||||||
|
|
||||||
Abstract description of proposed solution
|
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
Definitions
|
|
||||||
|
|
||||||
STRING = <TYPETAG, LENGTH, CHARRECORDPTR, CHARPTR>
|
|
||||||
|
|
||||||
SYMBOL = <TYPETAG, LENGTH, CHARRECORDPTR, CHARPTR>
|
|
||||||
|
|
||||||
CHARRECORD = <PHASE, SHAREDFLAG, CHARS>
|
|
||||||
|
|
||||||
PHASE = black | white
|
|
||||||
|
|
||||||
SHAREDFLAG = private | shared
|
|
||||||
|
|
||||||
CHARS is a character array
|
|
||||||
|
|
||||||
CHARPTR points into it
|
|
||||||
|
|
||||||
Memory management
|
|
||||||
|
|
||||||
A string or symbol is initially allocated with its contents stored in
|
|
||||||
a character array in a character record. The string/symbol header
|
|
||||||
contains a pointer to this record. The initial value of the shared
|
|
||||||
flag in the character record is `private'.
|
|
||||||
|
|
||||||
The GC mark phases alternate between black and white---every second
|
|
||||||
phase is black, the rest are white. This is used to distinguish
|
|
||||||
whether a character record has been encountered before:
|
|
||||||
|
|
||||||
During a black mark phase, when the GC encounters a string or symbol,
|
|
||||||
it changes the PHASE and SHAREDFLAG marks of the corresponding
|
|
||||||
character record according to the following table:
|
|
||||||
|
|
||||||
<white, private> --> <black, private> (white => unconditionally
|
|
||||||
<white, shared> --> <black, private> set to <black, private>)
|
|
||||||
<black, private> --> <black, shared> (SHAREDFLAG changed)
|
|
||||||
<black, shared> --> <black, shared> (no change)
|
|
||||||
|
|
||||||
The behaviour of a white phase is quivalent with the color names
|
|
||||||
switched.
|
|
||||||
|
|
||||||
The GC sweep phase frees any unmarked string or symbol header and
|
|
||||||
frees its character record either if it is marked with the "wrong"
|
|
||||||
color (not matching the color of the last mark phase) or if its
|
|
||||||
SHAREDFLAG is `private'.
|
|
||||||
|
|
||||||
Copy-on-write
|
|
||||||
|
|
||||||
An attempt at mutating string contents leads to copying if SHAREDFLAG
|
|
||||||
is `shared'. Copying means making a copy of the character record and
|
|
||||||
mutating the CHARRECORDPTR and CHARPTR fields of the object header to
|
|
||||||
point to the copy.
|
|
||||||
|
|
||||||
Substring operation
|
|
||||||
|
|
||||||
When making a substring, a new string header is allocated, with new
|
|
||||||
contents for the LENGTH and CHARPTR fields.
|
|
||||||
|
|
||||||
Implementation details
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
* We store the character record consecutively with the character
|
|
||||||
array and lump the PHASE and SHAREDFLAG fields together into one
|
|
||||||
byte containing an integer code for the four possible states of the
|
|
||||||
PHASE and SHAREDFLAG fields. Another way of viewing it is that
|
|
||||||
these fields are represented as bits 1 and 0 in the "header" of the
|
|
||||||
character array. We let CHARRECORDPTR point to the first character
|
|
||||||
position instead of on this header:
|
|
||||||
|
|
||||||
CHARRECORDPTR
|
|
||||||
|
|
|
||||||
V
|
|
||||||
FCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
|
|
||||||
|
|
||||||
F = 0, 1, 2, 3
|
|
||||||
|
|
||||||
* We represent strings as the sub-types `simple-string' and
|
|
||||||
`substring'.
|
|
||||||
|
|
||||||
* In a simple string, CHARRECORDPTR and CHARPTR are represented by a
|
|
||||||
single pointer, so a `simple-string' is an ordinary heap cell with
|
|
||||||
TYPETAG and LENGTH in the CAR and CHARPTR in the CDR.
|
|
||||||
|
|
||||||
* substring:s are represented as double cells, with TYPETAG and LENGTH
|
|
||||||
in word 0, CHARRECORDPTR in word 1 and CHARPTR in word 2
|
|
||||||
(alternatively, we could store an offset from CHARRECORDPTR).
|
|
||||||
|
|
||||||
Problems with this implementation
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
* How do we make copy-on-write thread-safe? Is there a different
|
|
||||||
implementation which is efficient and thread-safe?
|
|
||||||
|
|
||||||
* If small substrings are frequently generated from large, temporary
|
|
||||||
strings and the small substrings are kept in a data structure, the
|
|
||||||
heap will still have to host the large original strings. Should we
|
|
||||||
simply accept this?
|
|
||||||
|
|
@ -1,592 +0,0 @@
|
||||||
* Introduction
|
|
||||||
|
|
||||||
Version: $Id: langtools.text,v 1.5 2000-08-13 04:47:26 mdj Exp $
|
|
||||||
|
|
||||||
This is a proposal for how Guile could interface with language
|
|
||||||
translators. It will be posted on the Guile list and revised for some
|
|
||||||
short time (days rather than weeks) before being implemented.
|
|
||||||
|
|
||||||
The document can be found in the CVS repository as
|
|
||||||
guile-core/devel/translation/langtools.text. All Guile developers are
|
|
||||||
welcome to modify and extend it according to the ongoing discussion
|
|
||||||
using CVS.
|
|
||||||
|
|
||||||
Ideas and comments are welcome.
|
|
||||||
|
|
||||||
For clarity, the proposal is partially written as if describing an
|
|
||||||
already existing system.
|
|
||||||
|
|
||||||
MDJ 000812 <djurfeldt@nada.kth.se>
|
|
||||||
|
|
||||||
* Language names
|
|
||||||
|
|
||||||
A translator for Guile is a certain kind of Guile module, implemented
|
|
||||||
in Scheme, C, or a mixture of both.
|
|
||||||
|
|
||||||
To make things simple, the name of the language is closely related to
|
|
||||||
the name of the translator module.
|
|
||||||
|
|
||||||
Languages have long and short names. The long form is simply the name
|
|
||||||
of the translator module: `(lang ctax)', `(lang emacs-lisp)',
|
|
||||||
`(my-modules foo-lang)' etc.
|
|
||||||
|
|
||||||
Languages with the long name `(lang IDENTIFIER)' can be referred to
|
|
||||||
with the short name IDENTIFIER, for example `emacs-lisp'.
|
|
||||||
|
|
||||||
* How to tell Guile to read code in a different language (than Scheme)
|
|
||||||
|
|
||||||
There are four methods of specifying which translator to use when
|
|
||||||
reading a file:
|
|
||||||
|
|
||||||
** Command option
|
|
||||||
|
|
||||||
The options to the guile command are parsed linearly from left to
|
|
||||||
right. You can change the language at zero or more points using the
|
|
||||||
option
|
|
||||||
|
|
||||||
-t, --language LANGUAGE
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
guile -t emacs-lisp -l foo -l bar -t scheme -l baz
|
|
||||||
|
|
||||||
will use the emacs-lisp translator while reading "foo" and "bar", and
|
|
||||||
the default translator (scheme) for "baz".
|
|
||||||
|
|
||||||
You can use this technique in a script together with the meta switch:
|
|
||||||
|
|
||||||
#!/usr/local/bin/guile \
|
|
||||||
-t emacs-lisp -s
|
|
||||||
!#
|
|
||||||
|
|
||||||
** Commentary in file
|
|
||||||
|
|
||||||
When opening a file for reading, Guile will read the first few lines,
|
|
||||||
looking for the string "-*- LANGNAME -*-", where LANGNAME can be
|
|
||||||
either the long or short form of the name.
|
|
||||||
|
|
||||||
If found, the corresponding translator is loaded and used to read the
|
|
||||||
file.
|
|
||||||
|
|
||||||
** File extension
|
|
||||||
|
|
||||||
Guile maintains an alist mapping filename extensions to languages.
|
|
||||||
Each entry has the form:
|
|
||||||
|
|
||||||
(REGEXP . LANGNAME)
|
|
||||||
|
|
||||||
where REGEXP is a string and LANGNAME a symbol or a list of symbols.
|
|
||||||
|
|
||||||
The alist can be accessed using `language-alist' which is exported
|
|
||||||
by the module `(core config)':
|
|
||||||
|
|
||||||
(language-alist) --> current alist
|
|
||||||
(language-alist ALIST) sets the alist to ALIST
|
|
||||||
(language-alist ALIST :prepend) prepends ALIST onto the current list
|
|
||||||
(language-alist ALIST :append) appends ALIST after current list
|
|
||||||
|
|
||||||
The `load' command will match filenames against this alist and choose
|
|
||||||
the translator to use accordingly.
|
|
||||||
|
|
||||||
There will be a default alist for common translators. For translators
|
|
||||||
not listed, the alist has to be extended in .guile just as Emacs users
|
|
||||||
extend auto-mode-alist in .emacs.
|
|
||||||
|
|
||||||
** Module header
|
|
||||||
|
|
||||||
You specify the language used by a module with the :language option in
|
|
||||||
the module header. (See below under "Module configuration language".)
|
|
||||||
|
|
||||||
* Module system
|
|
||||||
|
|
||||||
This section describes how the Guile module system is adapted to use
|
|
||||||
with other languages.
|
|
||||||
|
|
||||||
** Module configuration language
|
|
||||||
|
|
||||||
*** The `(config)' module
|
|
||||||
|
|
||||||
Guile has a sophisticated module system. We don't require each
|
|
||||||
translator implementation to implement its own syntax for modules.
|
|
||||||
That would be too much work for the implementor, and users would have
|
|
||||||
to learn the module system anew for each syntax.
|
|
||||||
|
|
||||||
Instead, the module `(config)' exports the module header form
|
|
||||||
`(define-module ...)'.
|
|
||||||
|
|
||||||
The config module also exports a number of primitives by which you can
|
|
||||||
customize the Guile library, such as `language-alist' and `load-path'.
|
|
||||||
|
|
||||||
*** Default module environment
|
|
||||||
|
|
||||||
The bindings of the config module is available in the default
|
|
||||||
interaction environment when Guile starts up. This is because the
|
|
||||||
config module is on the module use list for the startup environment.
|
|
||||||
|
|
||||||
However, config bindings are *not* available by default in new
|
|
||||||
modules.
|
|
||||||
|
|
||||||
The default module environment provides bindings from the R5RS module
|
|
||||||
only.
|
|
||||||
|
|
||||||
*** Module headers
|
|
||||||
|
|
||||||
The module header of the current module system is the form
|
|
||||||
|
|
||||||
(define-module NAME OPTION1 ...)
|
|
||||||
|
|
||||||
You can specify a translator using the option
|
|
||||||
|
|
||||||
:language LANGNAME
|
|
||||||
|
|
||||||
where LANGNAME is the long or short form of language name as described
|
|
||||||
above.
|
|
||||||
|
|
||||||
The translator is being fed characters from the module file, starting
|
|
||||||
immediately after the end-parenthesis of the module header form.
|
|
||||||
|
|
||||||
NOTE: There can be only one module header per file.
|
|
||||||
|
|
||||||
It is also possible to put the module header in a separate file and
|
|
||||||
use the option
|
|
||||||
|
|
||||||
:file FILENAME
|
|
||||||
|
|
||||||
to point out a file containing the actual code.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
foo.gm:
|
|
||||||
----------------------------------------------------------------------
|
|
||||||
(define-module (foo)
|
|
||||||
:language emacs-lisp
|
|
||||||
:file "foo.el"
|
|
||||||
:export (foo bar)
|
|
||||||
)
|
|
||||||
----------------------------------------------------------------------
|
|
||||||
|
|
||||||
foo.el:
|
|
||||||
----------------------------------------------------------------------
|
|
||||||
(defun foo ()
|
|
||||||
...)
|
|
||||||
|
|
||||||
(defun bar ()
|
|
||||||
...)
|
|
||||||
----------------------------------------------------------------------
|
|
||||||
|
|
||||||
** Repl commands
|
|
||||||
|
|
||||||
Up till now, Guile has been dependent upon the available bindings in
|
|
||||||
the selected module in order to do basic operations such as moving to
|
|
||||||
a different module, enter the debugger or getting documentation.
|
|
||||||
|
|
||||||
This is not acceptable since we want be able to control Guile
|
|
||||||
consistently regardless of in which module we are, and sinc we don't
|
|
||||||
want to equip a module with bindings which don't have anything to do
|
|
||||||
with the purpose of the module.
|
|
||||||
|
|
||||||
Therefore, the repl provides a special command language on top of
|
|
||||||
whatever syntax the current module provides. (Scheme48 and RScheme
|
|
||||||
provides similar repl command languages.)
|
|
||||||
|
|
||||||
[Jost Boekemeier has suggested the following alternative solution:
|
|
||||||
Commands are bindings just like any other binding. It is enough if
|
|
||||||
some modules carry command bindings (it's in fact enough if *one*
|
|
||||||
module has them), because from such a module you can use the command
|
|
||||||
(in MODULE) to walk into a module not carrying command bindings, and
|
|
||||||
then use CTRL-D to exit.
|
|
||||||
|
|
||||||
However, this has the disadvantage of mixing the "real" bindings with
|
|
||||||
command bindings (the module might want to use "in" for other
|
|
||||||
purposes), that CTRL-D could cause problems since for some channels
|
|
||||||
CTRL-D might close down the connection, and that using one type of
|
|
||||||
command ("in") to go "into" the module and another (CTRL-D) to "exit"
|
|
||||||
is more complex than simply "going to" a module.]
|
|
||||||
|
|
||||||
*** Repl command syntax
|
|
||||||
|
|
||||||
Normally, repl commands have the syntax
|
|
||||||
|
|
||||||
,COMMAND ARG1 ...
|
|
||||||
|
|
||||||
Input starting with arbitrary amount of whitespace + a comma thus
|
|
||||||
works as an escape syntax.
|
|
||||||
|
|
||||||
This syntax is probably compatible with all languages. (Note that we
|
|
||||||
don't need to activate the lexer of the language until we've checked
|
|
||||||
if the first non-whitespace char is a comma.)
|
|
||||||
|
|
||||||
(Hypothetically, if this would become a problem, we can provide means
|
|
||||||
of disabling this behaviour of the repl and let that particular
|
|
||||||
language module take sole control of reading at the repl prompt.)
|
|
||||||
|
|
||||||
Among the commands available are
|
|
||||||
|
|
||||||
*** ,in MODULE
|
|
||||||
|
|
||||||
Select module named MODULE, that is any new expressions typed by the
|
|
||||||
user after this command will be evaluated in the evaluation
|
|
||||||
environment provided by MODULE.
|
|
||||||
|
|
||||||
*** ,in MODULE EXPR
|
|
||||||
|
|
||||||
Evaluate expression EXPR in MODULE. EXPR has the syntax supplied by
|
|
||||||
the language used by MODULE.
|
|
||||||
|
|
||||||
*** ,use MODULE
|
|
||||||
|
|
||||||
Import all bindings exported by MODULE to the current module.
|
|
||||||
|
|
||||||
* Language modules
|
|
||||||
|
|
||||||
Since code written in any kind of language should be able to implement
|
|
||||||
most tasks, which may include reading, evaluating and writing, and
|
|
||||||
generally computing with, expressions and data originating from other
|
|
||||||
languages, we want the basic reading, evaluation and printing
|
|
||||||
operations to be independent of the language.
|
|
||||||
|
|
||||||
That is, instead of supplying separate `read', `eval' and `write'
|
|
||||||
procedures for different languages, a language module is required to
|
|
||||||
use the system procedures in the translated code.
|
|
||||||
|
|
||||||
This means that the behaviour of `read', `eval' and `write' are
|
|
||||||
context dependent. (See further "How Guile system procedures `read',
|
|
||||||
`eval', `write' use language modules" below.)
|
|
||||||
|
|
||||||
** Language data types
|
|
||||||
|
|
||||||
Each language module should try to use the fundamental Scheme data
|
|
||||||
types as far as this is possible.
|
|
||||||
|
|
||||||
Some data types have important differences in semantics between
|
|
||||||
languages, though, and all required data types may not exist in
|
|
||||||
Guile.
|
|
||||||
|
|
||||||
In such cases, the language module must supply its own, distinct, data
|
|
||||||
types. So, each language supported by Guile uses a certain set of
|
|
||||||
data types, with the basic Scheme data types as the intersection
|
|
||||||
between all sets.
|
|
||||||
|
|
||||||
Specifically, syntax trees representing source code expressions should
|
|
||||||
normally be a distinct data type.
|
|
||||||
|
|
||||||
** Foreign language escape syntax
|
|
||||||
|
|
||||||
Note that such data can flow freely between modules. In order to
|
|
||||||
accomodate data with different native syntaxes, each language module
|
|
||||||
provides a foreign language escape syntax. In Scheme, this syntax
|
|
||||||
uses the sharp comma extension specified by SRFI-10. The read
|
|
||||||
constructor is simply the last symbol in the long language name (which
|
|
||||||
is usually the same as the short language name).
|
|
||||||
|
|
||||||
** Example 1
|
|
||||||
|
|
||||||
Characters have the syntax in Scheme and in ctax. Lists currently
|
|
||||||
have syntax in Scheme but lack ctax syntax. Ctax doesn't have a
|
|
||||||
datatype "enum", but we pretend it has for this example.
|
|
||||||
|
|
||||||
The following table now shows the syntax used for reading and writing
|
|
||||||
these expressions in module A using the language scheme, and module B
|
|
||||||
using the language ctax (we assume that the foreign language escape
|
|
||||||
syntax in ctax is #LANGUAGE EXPR):
|
|
||||||
|
|
||||||
A B
|
|
||||||
|
|
||||||
chars #\X 'X'
|
|
||||||
|
|
||||||
lists (1 2 3) #scheme (1 2 3)
|
|
||||||
|
|
||||||
enums #,(ctax ENUM) ENUM
|
|
||||||
|
|
||||||
** Example 2
|
|
||||||
|
|
||||||
A user is typing expressions in a ctax module which imports the
|
|
||||||
bindings x and y from the module `(foo)':
|
|
||||||
|
|
||||||
ctax> x = read ();
|
|
||||||
1+2;
|
|
||||||
1+2;
|
|
||||||
ctax> x
|
|
||||||
1+2;
|
|
||||||
ctax> y = 1;
|
|
||||||
1
|
|
||||||
ctax> y;
|
|
||||||
1
|
|
||||||
ctax> ,in (guile-user)
|
|
||||||
guile> ,use (foo)
|
|
||||||
guile> x
|
|
||||||
#,(ctax 1+2;)
|
|
||||||
guile> y
|
|
||||||
1
|
|
||||||
guile>
|
|
||||||
|
|
||||||
The example shows that ctax uses a distinct representation for ctax
|
|
||||||
expressions, but Scheme integers for integers.
|
|
||||||
|
|
||||||
** Language module interface
|
|
||||||
|
|
||||||
A language module is an ordinary Guile module importing bindings from
|
|
||||||
other modules and exporting bindings through its public interface.
|
|
||||||
|
|
||||||
It is required to export the following variable and procedures:
|
|
||||||
|
|
||||||
*** language-environment --> ENVIRONMENT
|
|
||||||
|
|
||||||
Returns a fresh top-level ENVIRONMENT (a module) where expressions
|
|
||||||
in this language are evaluated by default.
|
|
||||||
|
|
||||||
Modules using this language will by default have this environment
|
|
||||||
on their use list.
|
|
||||||
|
|
||||||
The intention is for this procedure to provide the "run-time
|
|
||||||
environment" for the language.
|
|
||||||
|
|
||||||
*** native-read PORT --> OBJECT
|
|
||||||
|
|
||||||
Read next expression in the foreign syntax from PORT and return an
|
|
||||||
object OBJECT representing it.
|
|
||||||
|
|
||||||
It is entirely up to the language module to define what one
|
|
||||||
expression is, that is, how much to read.
|
|
||||||
|
|
||||||
In lisp-like languages, `native-read' corresponds to `read'. Note
|
|
||||||
that in such languages, OBJECT need not be source code, but could
|
|
||||||
be data.
|
|
||||||
|
|
||||||
The representation of OBJECT is also chosen by the language
|
|
||||||
module. It can consist of Scheme data types, data types distinct for
|
|
||||||
the language, or a mixture.
|
|
||||||
|
|
||||||
There is one requirement, however: Distinct data types must be
|
|
||||||
instances of a subclass of `language-specific-class'.
|
|
||||||
|
|
||||||
This procedure will be called during interactive use (the user
|
|
||||||
types expressions at a prompt) and when the system `read'
|
|
||||||
procedure is called at a time when a module using this language is
|
|
||||||
selected.
|
|
||||||
|
|
||||||
Some languages (for example Python) parse differently depending if
|
|
||||||
its an interactive or non-interactive session. Guile prvides the
|
|
||||||
predicate `interactive-port?' to test for this.
|
|
||||||
|
|
||||||
*** language-specific-class
|
|
||||||
|
|
||||||
This variable contains the superclass of all non-Scheme data-types
|
|
||||||
provided by the language.
|
|
||||||
|
|
||||||
*** native-write OBJECT PORT
|
|
||||||
|
|
||||||
This procedure prints the OBJECT on PORT using the specific
|
|
||||||
language syntax.
|
|
||||||
|
|
||||||
*** write-foreign-syntax OBJECT LANGUAGE NATIVE-WRITE PORT
|
|
||||||
|
|
||||||
Write OBJECT in the foreign language escape syntax of this module.
|
|
||||||
The object is specific to language LANGUAGE and can be written using
|
|
||||||
NATIVE-WRITE.
|
|
||||||
|
|
||||||
Here's an implementation for Scheme:
|
|
||||||
|
|
||||||
(define (write-foreign-syntax object language native-write port)
|
|
||||||
(format port "#(~A " language))
|
|
||||||
(native-write object port)
|
|
||||||
(display #\) port)
|
|
||||||
|
|
||||||
*** translate EXPRESSION --> SCHEMECODE
|
|
||||||
|
|
||||||
Translate an EXPRESSION into SCHEMECODE.
|
|
||||||
|
|
||||||
EXPRESSION can be anything returned by `read'.
|
|
||||||
|
|
||||||
SCHEMECODE is Scheme source code represented using ordinary Scheme
|
|
||||||
data. It will be passed to `eval' in an environment containing
|
|
||||||
bindings in the environment returned by `language-environment'.
|
|
||||||
|
|
||||||
This procedure will be called duing interactive use and when the
|
|
||||||
system `eval
|
|
||||||
|
|
||||||
*** translate-all PORT [ALIST] --> THUNK
|
|
||||||
|
|
||||||
Translate the entire stream of characters PORT until #<eof>.
|
|
||||||
Return a THUNK which can be called repeatedly like this:
|
|
||||||
|
|
||||||
THUNK --> SCHEMECODE
|
|
||||||
|
|
||||||
Each call will yield a new piece of scheme code. The THUNK signals
|
|
||||||
end of translation by returning the value *end-of-translation* (which
|
|
||||||
is tested using the predicate `end-of-translation?').
|
|
||||||
|
|
||||||
The optional argument ALIST provides compilation options for the
|
|
||||||
translator:
|
|
||||||
|
|
||||||
(debug . #t) means produce code suitable for debugging
|
|
||||||
|
|
||||||
This procedure will be called by the system `load' command and by
|
|
||||||
the module system when loading files.
|
|
||||||
|
|
||||||
The intensions are:
|
|
||||||
|
|
||||||
1. To let the language module decide when and in how large chunks
|
|
||||||
to do the processing. It may choose to do all processing at
|
|
||||||
the time translate-all is called, all processing when THUNK is
|
|
||||||
called the first time, or small pieces of processing each time
|
|
||||||
THUNK is called, or any conceivable combination.
|
|
||||||
|
|
||||||
2. To let the language module decide in how large chunks to output
|
|
||||||
the resulting Scheme code in order not to overload memory.
|
|
||||||
|
|
||||||
3. To enable the language module to use temporary files, and
|
|
||||||
whole-module analysis and optimization techniques.
|
|
||||||
|
|
||||||
*** untranslate SCHEMECODE --> EXPRESSION
|
|
||||||
|
|
||||||
Attempt to do the inverse of `translate'. An approximation is OK. It
|
|
||||||
is also OK to return #f. This procedure will be called from the
|
|
||||||
debugger, when generating error messages, backtraces etc.
|
|
||||||
|
|
||||||
The debugger uses the local evaluation environment to determine from
|
|
||||||
which module an expression come. This is how the debugger can know
|
|
||||||
which `untranslate' procedure to call for a given expression.
|
|
||||||
|
|
||||||
(This is used currently to decide whether which backtrace frames to
|
|
||||||
display. System modules use the option :no-backtrace to prevent
|
|
||||||
displaying of Guile's internals to the user.)
|
|
||||||
|
|
||||||
Note that `untranslate' can use source-properties set by `native-read'
|
|
||||||
to give hints about how to do the reverse translation. Such hints
|
|
||||||
could for example be the filename, and line and column numbers for the
|
|
||||||
source expression, or an actual copy of the source expression.
|
|
||||||
|
|
||||||
** How Guile system procedures `read', `eval', `write' use language modules
|
|
||||||
|
|
||||||
*** read
|
|
||||||
|
|
||||||
The idea is that the `read' exported from the R5RS library will
|
|
||||||
continue work when called from other languages, and will keep its
|
|
||||||
semantics.
|
|
||||||
|
|
||||||
A call to `read' simply means "read in an expression from PORT using
|
|
||||||
the syntax associated with that port".
|
|
||||||
|
|
||||||
Each module carries information about its language.
|
|
||||||
|
|
||||||
When an input port is created for a module to be read or during
|
|
||||||
interaction with a given module, this information is copied to the
|
|
||||||
port object.
|
|
||||||
|
|
||||||
read uses this information to call `native-read' in the correct
|
|
||||||
language module.
|
|
||||||
|
|
||||||
*** eval
|
|
||||||
|
|
||||||
[To be written.]
|
|
||||||
|
|
||||||
*** write
|
|
||||||
|
|
||||||
[To be written.]
|
|
||||||
|
|
||||||
* Error handling
|
|
||||||
|
|
||||||
** Errors during translation
|
|
||||||
|
|
||||||
Errors during translation are generated as usual by calling scm-error
|
|
||||||
(from Scheme) or scm_misc_error etc (from C). The effect of
|
|
||||||
throwing errors from within `translate-all' is the same as when they
|
|
||||||
are generated within a call to the THUNK returned from
|
|
||||||
`translate-all'.
|
|
||||||
|
|
||||||
scm-error takes a fifth argument. This is a property list (alist)
|
|
||||||
which you can use to pass extra information to the error reporting
|
|
||||||
machinery.
|
|
||||||
|
|
||||||
Currently, the following properties are supported:
|
|
||||||
|
|
||||||
filename filename of file being translated
|
|
||||||
line line number of errring expression
|
|
||||||
column column number
|
|
||||||
|
|
||||||
** Run-time errors (errors in SCHEMECODE)
|
|
||||||
|
|
||||||
This section pertains to what happens when a run-time error occurs
|
|
||||||
during evaluation of the translated code.
|
|
||||||
|
|
||||||
In order to get "foreign code" in error messages, make sure that
|
|
||||||
`untranslate' yields good output. Note the possibility of maintaining
|
|
||||||
a table (preferably using weak references) mapping SCHEMECODE to
|
|
||||||
EXPRESSION.
|
|
||||||
|
|
||||||
Note the availability of source-properties for attaching filename,
|
|
||||||
line and column number, and other, information, such as EXPRESSION, to
|
|
||||||
SCHEMECODE. If filename, line, and, column properties are defined,
|
|
||||||
they will be automatically used by the error reporting machinery.
|
|
||||||
|
|
||||||
* Proposed changes to Guile
|
|
||||||
|
|
||||||
** Implement the above proposal.
|
|
||||||
|
|
||||||
** Add new field `reader' and `translator' to all module objects
|
|
||||||
|
|
||||||
Make sure they are initialized when a language is specified.
|
|
||||||
|
|
||||||
** Use `untranslate' during error handling.
|
|
||||||
|
|
||||||
** Implement the use of arg 5 to scm-error
|
|
||||||
|
|
||||||
(specified in "Errors during translation")
|
|
||||||
|
|
||||||
** Implement a generic lexical analyzer with interface similar to read/rp
|
|
||||||
|
|
||||||
Mikael is working on this. (It might take a few days, since he is
|
|
||||||
busy with his studies right now.)
|
|
||||||
|
|
||||||
** Remove scm:eval-transformer
|
|
||||||
|
|
||||||
This is replaced by new fields in each module object (environment).
|
|
||||||
|
|
||||||
`eval' will instead directly the `transformer' field in the module
|
|
||||||
passed as second arg.
|
|
||||||
|
|
||||||
Internal evaluation will, similarly, use the transformer of the module
|
|
||||||
representing the top-level of the local environment.
|
|
||||||
|
|
||||||
Note that this level of transformation is something independent of
|
|
||||||
language translation. *This* is a hook for adding Scheme macro
|
|
||||||
packages and belong to the core language.
|
|
||||||
|
|
||||||
We also need to check the new `translator' field, potentially using
|
|
||||||
it.
|
|
||||||
|
|
||||||
** Package local environments as smobs
|
|
||||||
|
|
||||||
so that environment list structures can't leak out on the Scheme
|
|
||||||
level. (This has already been done in SCM.)
|
|
||||||
|
|
||||||
** Introduce new fields in input ports
|
|
||||||
|
|
||||||
These carries state information such as
|
|
||||||
|
|
||||||
*** which keyword syntax to support
|
|
||||||
|
|
||||||
*** whether to be case sensitive or not
|
|
||||||
|
|
||||||
*** which lexical grammar to use
|
|
||||||
|
|
||||||
*** whether the port is used in an interactive session or not
|
|
||||||
|
|
||||||
There will be a new Guile primitive `interactive-port?' testing for this.
|
|
||||||
|
|
||||||
** Move configuration of keyword syntax and case sensitivity to the read-state
|
|
||||||
|
|
||||||
Add new fields to the module objects for these values, so that the
|
|
||||||
read-state can be initialized from them.
|
|
||||||
|
|
||||||
*fixme* When? Why? How?
|
|
||||||
|
|
||||||
Probably as soon as the language has been determined during file loading.
|
|
||||||
|
|
||||||
Need to figure out how to set these values.
|
|
||||||
|
|
||||||
|
|
||||||
Local Variables:
|
|
||||||
mode: outline
|
|
||||||
End:
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue