guile/devel/modules/module-layout.text

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: