Title

Library Files

Author

Derick Eddington

Status

This SRFI is currently in withdrawn status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-103@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.

Table of contents

Abstract

This SRFI defines a standard for locating files containing libraries with list-of-symbols library names, for unixes and Windows. It defines a standard for files containing R6RS libraries. It supports different Scheme dialects.

Rationale

For libraries to be portably organized, distributed, and available for importing, using prevalent file systems, a standard is needed for naming and finding the files containing libraries. The R6RS does not specify how libraries are to be made available for importing, and this SRFI addresses that by providing a standard for R6RS library files. Other dialects with list-of-symbols library names might need a standard for library files, and this SRFI addresses that by supporting such dialects.

Design

This SRFI provides a standard for locating files based on library names such that each symbol is used as a file-name component. List-of-symbols library names allow hierarchical grouping of libraries by shared name prefixes, which is useful for avoiding name conflicts with others' libraries and for organizing related libraries. Such library names are similar to file names which are a sequence of strings naming a file in a hierarchy of directories. This similarity is exploited to hierarchically organize library files in the way which corresponds to hierarchical library names.

This SRFI supports files which each contain only one library. This supports one-to-one mapping library-file names to library names, which supports knowing what libraries are available and where they are located, from only file names.

This SRFI provides a configurable sequence of searched directories and initializes it from a standard environment variable. This supports variable and multiple locations of library files, overlaying library files, and having different Scheme systems use the same library files.

This SRFI provides a configurable sequence of recognized file-name extensions and initializes it from a standard environment variable. This supports Scheme-system-specific libraries, multiple Scheme dialects, and using arbitrary extensions.

This SRFI specifies an ordering of multiple files matching a library name so the first-ordered file can be chosen.

To support portability of R6RS library files, this SRFI specifies a standard file format and file-name extension for them and requires R6RS systems to implement this standard.

Specification

Library Files

A library file is a file which contains a library and which has a name derived from the name of the contained library. Files conforming to this SRFI have one library per file.

A library-file name consists of, in order: possibly a searched-directory name, a sequence of components corresponding to the sequence of symbols in the contained library's name, and an extension. A relative library-file name is a library-file name without a searched-directory name. An absolute library-file name is a library-file name with a searched-directory name.

Searched Directories

The sequence of searched-directory names is used to find library files such that each directory name is prepended to each relative library-file name to make the set of file names of possible library files.

The operating-system environment variable SCHEME_LIB_PATH, if it is defined, is used to initialize the sequence. Its value is a string containing a sequence of directory names separated by the #\: character for unixes or the #\; character for Windows. Scheme systems may initialize the sequence to include additional directory names. Systems may have mechanisms to cause the variable to be ignored. Systems may have mechanisms to reconfigure the sequence after it is initialized.

File-Name Extensions

The sequence of recognized file-name extensions is used to find library files such that each extension is appended to each incomplete library-file name to make the set of file names of possible library files. Extensions need to have #\. as their first character if it is desired that extensions be separated from the file-name prefix by it.

The operating-system environment variable SCHEME_LIB_EXTENSIONS, if it is defined, is used to initialize the sequence. Its value is a string containing a sequence of extensions separated by the #\: character for unixes or the #\; character for Windows. Scheme systems may initialize the sequence to include additional extensions. Systems may have mechanisms to cause the variable to be ignored. Systems may have mechanisms to reconfigure the sequence after it is initialized.

Ordering and Choosing

The ordering of matching files is used to choose a file from a set of available files matching a library name. Multiple files might match a library name because of multiple searched directories or multiple recognized file-name extensions. Scheme systems may have other mechanisms to choose auxiliary files instead (e.g., compiled-code files) or different mechanisms to locate files for libraries with names considered special (e.g., (~ ---) located in users' home directory). If, for a system, no such auxiliary file is available and a library name is not considered special, the system must choose the first-ordered file according to this SRFI.

Matches in a directory which is ordered before another directory are ordered before matches in the other directory. For matches in the same directory, a match with an extension which is ordered before another extension is ordered before a match with the other extension.

Example:
Given this sequence of searched-directory names:
sd/c
sd/b
/sd/a
Given this sequence of recognized file-name extensions:
.acme-ext
.ext
Given this structure of directories and files:
/sd/a/
foo/
bar.acme-ext
bar.ext
bar.other-ext
zab.ext
sd/b/
foo/
bar.png
sd/c/
foo/
bar.ext
The order of files matching library name (foo bar) is:
sd/c/foo/bar.ext
/sd/a/foo/bar.acme-ext
/sd/a/foo/bar.ext
The first-ordered is:
sd/c/foo/bar.ext

R6RS Library Files

R6RS systems which implement this SRFI must conform to the following requirements. Files with name extension ".s6l", which each contain one library as an R6RS library form as the first syntactic datum which the R6RS get-datum procedure will read, must be supported. The ".s6l" extension must be implicitly included in the sequence of recognized file-name extensions, when the SCHEME_LIB_EXTENSIONS environment variable is not defined.

R6RS systems which desire to support system-specific libraries are encouraged to implicitly include, when SCHEME_LIB_EXTENSIONS is not defined, a file-name extension of the form ".acme-s6l", substituting the system's name for "acme", and to order such extension before ".s6l".

Dialects, Formats, and Extensions

Scheme is a family of dialects which use different file formats. File-name extensions which denote only that files are Scheme-related are not sufficient to distinguish library-file types. Extensions used for library-file names are encouraged to precisely and unambiguously denote file types; i.e., distinct dialects and formats are encouraged to have distinct extensions. Such extensions allow knowing the dialect/format/type of a file from its extension, and they allow different types of same-library-name files to coexist.

Precise extensions may be utilized by Scheme systems which support multiple dialects or file formats, to know how to handle different types of library files which are simultaneously used.

Precise extensions assist users and applications working with library files, by allowing them to know library-file types from library-file names.

Distinct extensions allow same-library-name files for different dialects to be in the same directory.

Distinct extensions allow avoiding having same-library-name files for another dialect shadow those for the desired dialect, when multiple dialects share the searched directories.

Reference Implementation

The reference implementation is provided as an R6RS library. It requires some R6RS bindings, SRFI 39: Parameter Objects, and SRFI 98: An Interface to Access Environment Variables.

A test program is provided as an R6RS program. It requires, in addition to the reference implementation, some R6RS bindings, SRFI 39: Parameter Objects, and SRFI 78: Lightweight Testing.

Issues

(Section which points out things to be resolved. This will not appear in the final SRFI.)

Acknowledgments

I thank everyone who influenced and commented on this SRFI. I thank the editor for editing this SRFI.

References

Revised6 Report on the Algorithmic Language Scheme
Michael Sperber, et al. (Editors)
http://www.r6rs.org/

Copyright

Copyright (C) Derick Eddington (2010). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Editor: David Van Horn