Dylan Design Notes

#33: Headers for Dylan Source Files	(Addition)

Version 1, January 1994
Copyright (c) 1993-1994, Apple Computer

This design note specifies a standard portable format for distributing 
Dylan source code.

-------------------------------------------------------------------

We introduce the notion of a Dylan source code file. A file has two 
parts, the header and the body.  The header comes before the body.

The body consists of zero or more outer expressions and comments, all of 
which must be in the same syntax.

The  header consists of zero or more keyword-value pairs, as follows:

1) The syntax of a keyword is as follows: a keyword is a letter, followed 
by zero or more letters, digits, and hyphens, followed by a colon, 
contains only characters from the ISO 646 7-bit character set, and is 
case-independent.

2) A keyword begins on a new line, and cannot be preceded by whitespace.

3) All text (excluding padding whitespace) between the keyword and the 
newline is considered to be the value.  Additional lines can be added by 
having the additional lines start with whitespace.  Leading whitespace is 
not part of the value.

4) Interpretation of the value is determined by the keyword.

5) Implementations must recognize and handle standardized keywords 
properly, unless the specification for a keyword explicitly states that 
it can be ignored.

6) When importing a file, implementations are free to ignore any 
non-standard keyword/value pair that they do not recognize.

7) When exporting a file, implementations must use standard keywords 
properly. Implementations are free to use non-standard keywords. 

8) The definition of a keyword may allow multiple occurrences of that 
keyword in a single file header.  If it does, it must specify the meaning 
of multiple occurrences.  If it does not, it is an error for the keyword 
to appear more than once.

The header cannot contain comments.

Blank lines may not appear in the header.  A blank line defines the end 
of the header and the beginning of the code body.  It is not part of the 
code body.

The following standard keywords are defined:
	
module:  module-name	        [Header keyword]	
Expressions in the file are associated with the named module.  This 
keyword is required.

author: arbitrary text	        [Header keyword]
copyright:arbitrary text        [Header keyword]
version: arbitrary text	        [Header keyword]

These are provided for standardization.  These are optional, and can be 
ignored by the implementation.

For example, a typical Dylan source file might look like this:

module:	quickdraw
author: 	J. Random Rect
        	Linear Wheels, Inc., "Where quality is a slogan!"
        	rect@linear.com
copyright: (c) 1993 Linear Wheels, Inc., All rights reserved
version: 	1.3 alpha (not fully tested)

define-constant $black-color ...
...

-------------------------------------------------------------------

Notes

Some sort of standard portable file format is needed to publish Dylan 
source code. Code will be shared among very different development 
environments, and although some will store code in a database, sharing 
will only be possible through some kind of files.  

This change will enhance ability to share code between development 
environments.   It will facilitate code-management tasks in file-based 
environments by formalizing code attributes like syntax, authorship, 
copyright, version control, etc.  It will facilitate management of code 
repositories (e.g. file servers, cd-roms, particularly in multi-platform 
environments) by providing readily browsable information to tools with 
minimal awareness of Dylan.

Keyword-value pairs are relatively easy for machines to parse and 
generate,and are relatively legible to humans.  Also, this allows for 
future extensions by adding keywords.
