Module Layout Proposal ====================== Martin Grabmueller Draft: 2001-03-11 Version: $Id: module-layout.text,v 1.1 2002/03/24 00:20:19 ttn 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: