diff options
29 files changed, 0 insertions, 1467 deletions
diff --git a/devel/ChangeLog b/devel/ChangeLog deleted file mode 100644 index e69de29bb..000000000 --- a/devel/ChangeLog +++ /dev/null diff --git a/devel/README b/devel/README deleted file mode 100644 index e69de29bb..000000000 --- a/devel/README +++ /dev/null diff --git a/devel/build/README b/devel/build/README deleted file mode 100644 index e69de29bb..000000000 --- a/devel/build/README +++ /dev/null diff --git a/devel/build/guile-projects-entry b/devel/build/guile-projects-entry deleted file mode 100644 index e69de29bb..000000000 --- a/devel/build/guile-projects-entry +++ /dev/null diff --git a/devel/build/pre-inst-guile.text b/devel/build/pre-inst-guile.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/build/pre-inst-guile.text +++ /dev/null diff --git a/devel/build/recording-api.text b/devel/build/recording-api.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/build/recording-api.text +++ /dev/null diff --git a/devel/build/snarf-macros.text b/devel/build/snarf-macros.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/build/snarf-macros.text +++ /dev/null diff --git a/devel/extension/dynamic-root.text b/devel/extension/dynamic-root.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/extension/dynamic-root.text +++ /dev/null diff --git a/devel/gc/README b/devel/gc/README deleted file mode 100644 index e69de29bb..000000000 --- a/devel/gc/README +++ /dev/null diff --git a/devel/gc/gc+callcc.text b/devel/gc/gc+callcc.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/gc/gc+callcc.text +++ /dev/null diff --git a/devel/htbmc-commentary.text b/devel/htbmc-commentary.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/htbmc-commentary.text +++ /dev/null diff --git a/devel/htbmc.text b/devel/htbmc.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/htbmc.text +++ /dev/null diff --git a/devel/memory.text b/devel/memory.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/memory.text +++ /dev/null diff --git a/devel/modules/design-notes.texi b/devel/modules/design-notes.texi deleted file mode 100644 index a8853e594..000000000 --- a/devel/modules/design-notes.texi +++ /dev/null @@ -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 diff --git a/devel/modules/module-layout.text b/devel/modules/module-layout.text deleted file mode 100644 index c088ad822..000000000 --- a/devel/modules/module-layout.text +++ /dev/null @@ -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: diff --git a/devel/modules/module-snippets.texi b/devel/modules/module-snippets.texi deleted file mode 100644 index e69de29bb..000000000 --- a/devel/modules/module-snippets.texi +++ /dev/null diff --git a/devel/modules/signatures.scm b/devel/modules/signatures.scm deleted file mode 100644 index e69de29bb..000000000 --- a/devel/modules/signatures.scm +++ /dev/null diff --git a/devel/modules/signatures.texi b/devel/modules/signatures.texi deleted file mode 100644 index e69de29bb..000000000 --- a/devel/modules/signatures.texi +++ /dev/null diff --git a/devel/policy/api.text b/devel/policy/api.text deleted file mode 100644 index b53a8613f..000000000 --- a/devel/policy/api.text +++ /dev/null @@ -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. diff --git a/devel/policy/exceptions.text b/devel/policy/exceptions.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/policy/exceptions.text +++ /dev/null diff --git a/devel/policy/goals.text b/devel/policy/goals.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/policy/goals.text +++ /dev/null diff --git a/devel/policy/names.text b/devel/policy/names.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/policy/names.text +++ /dev/null diff --git a/devel/policy/plans.text b/devel/policy/plans.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/policy/plans.text +++ /dev/null diff --git a/devel/policy/principles.text b/devel/policy/principles.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/policy/principles.text +++ /dev/null diff --git a/devel/strings/sharedstr.text b/devel/strings/sharedstr.text deleted file mode 100644 index f568c3ebf..000000000 --- a/devel/strings/sharedstr.text +++ /dev/null @@ -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? diff --git a/devel/translation/langtools.text b/devel/translation/langtools.text deleted file mode 100644 index ac07ce034..000000000 --- a/devel/translation/langtools.text +++ /dev/null @@ -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: diff --git a/devel/translation/lisp-and-scheme.text b/devel/translation/lisp-and-scheme.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/translation/lisp-and-scheme.text +++ /dev/null diff --git a/devel/vm/ior/ior-intro.text b/devel/vm/ior/ior-intro.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/vm/ior/ior-intro.text +++ /dev/null diff --git a/devel/vm/ior/ior.text b/devel/vm/ior/ior.text deleted file mode 100644 index e69de29bb..000000000 --- a/devel/vm/ior/ior.text +++ /dev/null |