aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 8d4d31d52e7903bcf34115d90390f20abfe209b5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
This directory contains the distribution of Scheme Library slib2d2.
Slib conforms to Revised^5 Report on the Algorithmic Language Scheme
and the IEEE P1178 specification.  Slib supports Unix and similar
systems, VMS, and MS-DOS.

The maintainer can be reached at agj @ alum.mit.edu.
	    http://swissnet.ai.mit.edu/~jaffer/SLIB.html

			       MANIFEST

  `README' is this file.  It contains a MANIFEST, INSTALLATION
	INSTRUCTIONS, and coding guidelines.
  `FAQ' Frequently Asked Questions and answers.
  `ChangeLog' documents changes to slib.
  `slib.texi' has documentation on library packages in TexInfo format.

  `Template.scm' Example configuration file.  Copy and customize to
	reflect your system.
  `bigloo.init' is a configuration file for Bigloo.
  `chez.init' is a configuration file for Chez Scheme.
  `DrScheme.init' is a configuration file for DrScheme.
  `elk.init' is a configuration file for ELK 2.1
  `gambit.init' is a configuration file for Gambit Scheme.
  `macscheme.init' is a configuration file for MacScheme.
  `mitscheme.init' is a configuration file for MIT Scheme.
  `pscheme.init' is configuration file for PocketScheme 0.2.5 (WinCE SIOD)
  `RScheme.init' is a configuration file for RScheme.
  `scheme2c.init' is a configuration file for DEC's scheme->c.
  `scheme48.init' is a configuration file for Scheme48.
  `s48-0_57.init is a configuration file for Scheme48-0.57.
  `scsh.init' is a configuration file for Scheme-Shell
  `scm.init' is a configuration file for SCM.
  `t3.init' is a configuration file for T3.1 in Scheme mode.
  `STk.init' is a configuration file for STk.
  `umbscheme.init' is a configuration file for umb-scheme.  
  `vscm.init' is a configuration file for VSCM.
  `guile.init' is a configuration file for guile.
  `mklibcat.scm' builds the *catalog* cache.
  `require.scm' has code which allows system independent access to
	the library files.

  `Bev2slib.scm' Converts Stephen Bevan's "*.map" files to SLIB catalog entries.
  `format.scm' has Common-Lisp style format.
  `formatst.scm' has code to test format.scm
  `pp.scm' has pretty-print.
  `ppfile.scm' has pprint-file and pprint-filter-file.
  `obj2str.scm' has object->string.
  `strcase.scm' has functions for manipulating the case of strings.
  `genwrite.scm' has a generic-write which is used by pp.scm,
	pp2str.scm and obj2str.scm
  `printf.scm' has printf, fprintf, and sprintf compatible with C.
  `scanf.scm' has scanf, fscanf, and sscanf compatible by C.
  `lineio' has line oriented input/output functions.
  `qp.scm' has printer safe for circular structures.
  `break.scm' has break and continue.
  `trace.scm' has trace and untrace for tracing function execution.
  `debug.scm' has handy higher level debugging aids.
  `strport.scm' has routines for string-ports.
  `strsrch.scm' search for chars or substrings in strings and ports.
  `differ.scm' An O(NP) Sequence Comparison Algorithm.

  `alist.scm' has functions accessing and modifying association lists.
  `hash.scm' defines hash, hashq, and hashv.
  `hashtab.scm' has hash tables.
  `sierpinski.scm' 2-dimensional coordinate hash.
  `soundex.scm' English name hash.
  `logical.scm' emulates 2's complement logical operations.
  `random.scm' has random number generator compatible with Common Lisp.
  `randinex.scm' has inexact real number distributions.
  `primes.scm' has primes and probably-prime?.
  `factor.scm' has factor.
  `root.scm' has Newton's and Laguerre's methods for finding roots.
  `minimize.scm' has Golden Section Search for minimum value.
  `cring.scm' extend + and * to custom commutative rings.
  `selfset.scm' sets single letter identifiers to their symbols.
  `determ.scm' compute determinant of list of lists.
  `charplot.scm' has procedure for plotting on character screens.
  `plottest.scm' has code to test charplot.scm.
  `tek40.scm' has routines for Tektronix 4000 series graphics.
  `tek41.scm' has routines for Tektronix 4100 series graphics.
  `getopt.scm' has posix-like getopt for parsing command line arguments. 
  `psxtime.scm' has Posix time conversion routines.
  `cltime.scm' has Common-Lisp time conversion routines.
  `timezone.scm' has the default time-zone, UTC.
  `tzfile.scm' reads sysV style (binary) timezone file.
  `comparse.scm' has shell-like command parsing.

  `rdms.scm' has code to construct a relational database from a base
	table implementation.
  `alistab.scm' has association list base tables.
  `dbutil.scm' has utilities for creating and manipulating relational
	databases.
  `htmlform.scm' generates HTML-3.2 with forms.
  `db2html.scm' convert relational database to hyperlinked tables and
	pages.
  `http-cgi.scm' serves WWW pages with HTTP or CGI.
  `uri.scm' encodes and decodes Uniform Resource Identifiers.
  `dbrowse.scm' browses relational databases.
  `paramlst.scm' has procedures for passing parameters by name.
  `getparam.scm' has procedures for converting getopt to parameters.
  `report.scm' prints database reports.
  `schmooz.scm' is a simple, lightweight markup language for
	interspersing Texinfo documentation with Scheme source code.
  `glob.scm' has filename matching and manipulation.
  `batch.scm' Group and execute commands on various operating systems.
  `makcrc.scm' Create Scheme procedure to calculate POSIX.2 checksums
	or other CRCs.

  `record.scm' a MITScheme user-definable datatypes package
  `promise.scm' has code from R4RS for supporting DELAY and FORCE.

  `repl.scm' has a read-eval-print-loop.
  `defmacex.scm' has defmacro:expand*.
  `mbe.scm' has "Macro by Example" define-syntax.
  `scmacro.scm' is a syntactic closure R4RS macro package.
	r4rsyn.scm, synclo.scm, synrul.scm have syntax definitions
	and support.
  `scmactst.scm' is code for testing SYNTACTIC CLOSURE macros.
  `scainit.scm' is a syntax-case R4RS macro package.
	scaglob.scm scamacr.scm scaoutp.scm scaexpp.scm have
	syntax definitions and support.  `syncase.sh' is a shell
	script for producing the SLIB version from the original.
  `macwork.scm' is a "Macros that work" package.
	mwexpand.scm mwdenote.scm mwsynrul.scm have support.
  `macrotst.scm' is code from R4RS for testing macros.

  `values.scm' is multiple values.
  `queue.scm' has queues and stacks.

  `object.scm' is an object system.
  `yasyn.scm' defines (syntax-rules) macros for object oriented programming.
  `collect.scm' is collection operators (like CL sequences).
  `priorque.scm' has code and documentation for priority queues.
  `wttree.scm' has weight-balanced trees.
  `wttest.scm' tests weight-balanced trees.
  `process.scm' has multi-processing primitives.
  `array.scm' has multi-dimensional arrays and sub-arrays.
  `arraymap.scm' has array-map!, array-for-each, and array-indexes.

  `sort.scm' has sorted?, sort, sort!, merge, and merge!.
  `tsort.scm' has topological-sort.
  `comlist.scm' has many common list and mapping procedures.
  `tree.scm' has functions dealing with trees.
  `coerce.scm' has coerce and type-of from Common-Lisp.
  `chap.scm' has functions which compare and create strings in
	"chapter order".

  `sc4opt.scm' has optional rev4 procedures.
  `sc4sc3.scm' has procedures to make a rev3 implementation run rev4
	code. 
  `sc2.scm' has rev2 procedures eliminated in subsequent versions.
  `mularg.scm' redefines - and / to take more than 2 arguments.
  `mulapply.scm' redefines apply to take more than 2 arguments.
  `ratize.scm' has function rationalize from Revised^4 spec.
  `trnscrpt.scm' has transcript-on and transcript-off from Revised^4 spec.
  `withfile.scm' has with-input-from-file and with-output-to-file from R4RS.
  `dynwind.scm' has dynamic-wind from R5RS.
  `eval.scm' has eval with environments from R5RS.
  `dwindtst.scm' has routines for characterizing dynamic-wind.
  `dynamic.scm' has DYNAMIC data type [obsolete].
  `fluidlet.scm' has fluid-let syntax.
  `structure.scm' has undocumented syntax-case macros.
  `byte.scm' has arrays of small integers.
  `nclients.scm' provides a Scheme interface to FTP and WWW Browsers.
  `pnm.scm' provides a Scheme interface to "portable bitmap" files.
  `simetrix.scm' provides SI Metric Interchange Format.
  `srfi.scm' implements Scheme Request for Implementation.
  `srfi-N.scm' implements srfi-N.

		      INSTALLATION INSTRUCTIONS

  There are four parts to installation:

   * Unpack the SLIB distribution.

   * Configure the Scheme implementation(s) to locate the SLIB
     directory.

   * Arrange for Scheme implementation to load its SLIB initialization
     file.

   * Build the SLIB catalog for the Scheme implementation.

Unpacking the SLIB Distribution
-------------------------------

  If the SLIB distribution is a Linux RPM, it will create the SLIB
directory `/usr/share/slib'.

  If the SLIB distribution is a ZIP file, unzip the distribution to
create the SLIB directory.  Locate this `slib' directory either in your
home directory (if only you will use this SLIB installation); or put it
in a location where libraries reside on your system.  On unix systems
this might be `/usr/share/slib', `/usr/local/lib/slib', or
`/usr/lib/slib'.  If you know where SLIB should go on other platforms,
please inform agj @ alum.mit.edu.

Configure Scheme Implementation to Locate SLIB
----------------------------------------------

  If the Scheme implementation supports `getenv', then the value of the
shell environment variable SCHEME_LIBRARY_PATH will be used for
`(library-vicinity)' if it is defined.  Currently, Chez, Elk,
MITScheme, scheme->c, VSCM, and SCM support `getenv'.  Scheme48
supports `getenv' but does not use it for determining
`library-vicinity'.  (That is done from the Makefile.)

  The `(library-vicinity)' can also be specified from the SLIB
initialization file or by implementation-specific means.

Loading SLIB Initialization File
--------------------------------

  Check the manifest in `README' to find a configuration file for your
Scheme implementation.  Initialization files for most IEEE P1178
compliant Scheme Implementations are included with this distribution.

  You should check the definitions of `software-type',
`scheme-implementation-version', `implementation-vicinity', and
`library-vicinity' in the initialization file.  There are comments in
the file for how to configure it.

  Once this is done, modify the startup file for your Scheme
implementation to `load' this initialization file.

Build New SLIB Catalog for Implementation
-----------------------------------------

  When SLIB is first used from an implementation, a file named
`slibcat' is written to the `implementation-vicinity' for that
implementation.  Because users may lack permission to write in
`implementation-vicinity', it is good practice to build the new catalog
when installing SLIB.

  To build (or rebuild) the catalog, start the Scheme implementation
(with SLIB), then:

     (require 'new-catalog)

Implementation-specific Instructions
------------------------------------

  Multiple implementations of Scheme can all use the same SLIB
directory.  Simply configure each implementation's initialization file
as outlined above.

 - Implementation: SCM
     The SCM implementation does not require any initialization file as
     SLIB support is already built into SCM.  See the documentation
     with SCM for installation instructions.

 - Implementation: VSCM
     From: Matthias Blume <blume @ cs.Princeton.EDU>
     Date: Tue, 1 Mar 1994 11:42:31 -0500

     Disclaimer: The code below is only a quick hack.  If I find some
     time to spare I might get around to make some more things work.

     You have to provide `vscm.init' as an explicit command line
     argument.  Since this is not very nice I would recommend the
     following installation procedure:

       1. run scheme

       2. `(load "vscm.init")'

       3. `(slib:dump "dumpfile")'

       4. mv dumpfile place-where-vscm-standard-bootfile-resides e.g.
          mv dumpfile /usr/local/vscm/lib/scheme-boot (In this case
          vscm should have been compiled with flag
          -DDEFAULT_BOOTFILE='"/usr/local/vscm/lib/scheme-boot"'.  See
          Makefile (definition of DDP) for details.)


 - Implementation: Scheme48
     To make a Scheme48 image for an installation under `<prefix>',

       1. `cd' to the SLIB directory

       2. type `make prefix=<prefix> slib48'.

       3. To install the image, type `make prefix=<prefix> install48'.
          This will also create a shell script with the name `slib48'
          which will invoke the saved image.

 - Implementation: PLT Scheme
 - Implementation: DrScheme
 - Implementation: MzScheme
     The `init.ss' file in the _slibinit_ collection is an SLIB
     initialization file.

     To use SLIB in MzScheme, set the SCHEME_LIBRARY_PATH environment
     variable to the installed SLIB location; then invoke MzScheme thus:

     `mzscheme -L init.ss slibinit'

 - Implementation: MIT Scheme
     `scheme -load ${SCHEME_LIBRARY_PATH}mitscheme.init'

 - Implementation: Guile
     `guile -l ${SCHEME_LIBRARY_PATH}guile.init'

			 PORTING INSTRUCTIONS

  If there is no initialization file for your Scheme implementation, you
will have to create one.  Your Scheme implementation must be largely
compliant with
  `IEEE Std 1178-1990',
  `Revised(4) Report on the Algorithmic Language Scheme', or
  `Revised(5) Report on the Algorithmic Language Scheme'
in order to support SLIB.

  `Template.scm' is an example configuration file.  The comments inside
will direct you on how to customize it to reflect your system.  Give
your new initialization file the implementation's name with `.init'
appended.  For instance, if you were porting `foo-scheme' then the
initialization file might be called `foo.init'.

  Your customized version should then be loaded as part of your scheme
implementation's initialization.  It will load `require.scm' from the
library; this will allow the use of `provide', `provided?', and
`require' along with the "vicinity" functions.  The rest of the
library will then be accessible in a system independent fashion.

  Please mail new working configuration files to `agj @ alum.mit.edu' so
that they can be included in the SLIB distribution.

			  CODING GUIDELINES

  All library packages are written in IEEE P1178 Scheme and assume that
a configuration file and `require.scm' package have already been
loaded.  Other versions of Scheme can be supported in library packages
as well by using, for example, `(provided? 'rev3-report)' or `(require
'rev3-report)'.

  `require.scm' defines `*catalog*', an association list of module
names and filenames.  When a new package is added to the library, an
entry should be added to `require.scm'.  Local packages can also be
added to `*catalog*' and even shadow entries already in the table.

  The module name and `:' should prefix each symbol defined in the
package.  Definitions for external use should then be exported by having
`(define foo module-name:foo)'.

  Submitted packages should not duplicate routines which are already in
SLIB files.  Use `require' to force those features to be supported in
your package.  Care should be taken that there are no circularities in
the `require's and `load's between the library packages.

  Documentation should be provided in Emacs Texinfo format if possible,
But documentation must be provided.