The Smalltalk fileOut format

Introduction

This document describes the format used for source and object interchange.
That format is based on an ascii representation of objects and can be used to transport source code and objects to another Smalltalk/X system or between different Smalltalk dialects.
The format was originally defined for ST-80 [4] and is compatible with ST-80, Digitalk, VisualWorks, VisualAge, Squeak/Pharo, GNU Smalltalk and of course, Smalltalk/X (plus many others, I guess).

Chunk files are typically used for source code transportation, although they can also be used to store/retrieve general objects. Some applications use this to save user settings or history items.

In Smalltalk/X, chunk files are used as Smalltalk source code files (which can be loaded with fileIn or compiled with the stc compiler), as interchange format for code and for storage in a source code management system, such as CVS, SVN or Mercurial.

Definition

A file in this format consists of so called chunks of text. These are delimited by single exclamation marks (!) and all exclamation marks within a chunk are doubled (!!). Doubled exclamation marks may not contain a space in between.

A chunk consisting of whitespace only is called an empty chunk.

With the exception of method chunks which follow a "methodsFor:" chunk (described below), each non empty chunk must represent a syntactically correct Smalltalk expression or statement list (expressions separated by full-stops).

Objects

Objects are stored as a chunk which, when evaluated, recreates the original object. Typically, an object's storeString is used for that purpose. For everything except literal objects (Number constants, String constants or Symbols), the storeString consists of a #new or #basicNew message, followed by messages to set the instance variables. For example, a storeString chunk for a Set with 1,2 and 4 as elements looks like:

    (Set new add:1; add:2; add:3; yourself)
    !

Self referencing or otherwise recursive objects can (usually) not be represented in this format. Those must be transported via another mechanism: either the Binary Object Format, or an XML representation. Both are supported by corresponding class libraries and protocol.

Class definitions

Class definition chunks consist of a message that create the original class. Typically, it is one of the subclass creation messages defined in Class.
A class definition chunk may look like:

    Object subclass:#Foo
	   instanceVariableNames:'foo bar'
	   classVariableNames:''
	   poolDictionaries:''
	   category:'Demos'
    !

(again notice: this really IS a normal message send to the Object class. In a browser, search for implementors of it and find an implementation in or above the Class class)

ST/V uses a variant of the above (it does not support class categories). ST/X also supports those in both the incremental and the batch compilers:

    Foo subclass:#Bar
	   instanceVariableNames:'baz'
	   classVariableNames:''
	   poolDictionaries:''
    !

ST/X allows classes to be declared private for some other class; a private class is only visible to its owning class. If both a private class AND a non-private class with the same name (say "Foo") exist, the identifier "Foo" will refer to the private class within the owning class, and to the global class everywhere else.
To access the global class within the owning class, use a namespace override construct, such as "Smalltalk::Foo".
Private classes are declared with:

    SomeSuperclass subclass:#NameOfClass
	   instanceVariableNames:''
	   classVariableNames:''
	   privateIn:OwningClass
    !

Support for private classes is an ST/X feature - it may not be available on other smalltalk systems.

Method definitions

Method definitions consist of an initial methodsFor: chunk, followed by one or more method chunks. When evaluated at fileIn time, the first chunk will create an instance of ClassCategoryReader which itself will continue to read and compile the method chunks up to an empty chunk.
Typical method definitions look like:

    !Foo methodsFor:'examples'!

    foo
	"this is the foo method"

	^ 'foo'
    !

    bar
	"this is the bar method"

	^ 'bar'
    ! !

Notice the empty chunk at the end.

ST/V uses a variant of the above (it also lacks method categories). This is also supported by both the incremental and the batch compilers in ST/X:

    !Bar methods!

    foo
	"this is the foo method"

	^ 'foo'
    !

    bar
	"this is the bar method"

	^ 'bar'
    ! !

<cg at exept.de>

Doc $Revision: 1.23 $ $Date: 2021/03/13 18:24:51 $