====== Smalltalk Transform ======

The transformation classes and how to use them.

===== Smalltalk is not Smalltalk =====

While all Smalltalk dialects share the same message sending paradigm with the same basic syntax. Many dialects extended the syntax (VW: namespace and literal bindings, Squeak: dynamic array, Amber: literal dictionaries, etc.). 

The basic class library (Object, Number, Collection, Class etc.) with standardized selectors are the same in all dialects. But each one extends the library and classes with their own ways of doing things.

There are some cross dialect libraries like Glorp.

The UI, at the other end, is very different in all dialects, so that porting is almost impossible.

===== Defining Changes =====

Changes are defined on different levels according to the organization of the code: 
  * **Methods** On the lowest level we deal with source code and its transformation.
  * **Classes** Which methods are transformed and how and do the instvars change?
  * **Packages** Which classes to file out; what to load as prerequisite; changes to the hierarchy.
  * **Project** The top-level object fully describing all transformations. Prerequisites, pundles and namespace-to-prefix mapping.
==== Methods ====

The source code is in methods which syntax may be different in the target system.

There are 3 kinds of changes concerning methods:
  * **Ignore** This method of the source system should not be written to the target system. <code Smalltalk>Ignore method: #asPDF</code>
  * **Add** This method is added to the target system. The method does not exist in the target system. <code Smalltalk>Add method: #asPDF code: #_gs_asPDF</code>
  * **Replace** This method of the source system is replaced by the body of the target method <code Smalltalk>Replace method: #asString code: #_gs_asString</code>
    * **Rewrite** The body of the source method is transformed by a Rewrite rule <code Smalltalk>Rewrite method: #pdfVersion rule: #replaceDottedName</code>

**''Add''** and **''Replace''** refer to code in a method private for the target dialect. The body of the ''#code'' method is combined with the selector given by ''#method''.

Example:

The VW method #isLiteral in Object is:

<code Smalltalk>isLiteral
	"Answer whether the receiver has a literal text form 
	recognized by the compiler."
	^false</code>

But in Gemstone, the method should be: (this method is defined as extension to ''Object'' in package ''[Gemstone Fileout PDFtalk]'')

<code Smalltalk>_gs_isLiteral
	^self literalString notNil</code>

With the transformation

<code Smalltalk>ClassChange
	classReference: #{Object}
	instanceChanges: (Array with: (Add method: #isLiteral code: #_gs_isLiteral))</code>

the following is written out as new method for ''Object'' in Gemstone:

<code Smalltalk>isLiteral
	^self literalString notNil</code>

In case that the target class is not in the source system, the code is defined in a special placeholder class: **''CodeHolder''**. The methods here should have the proper protocol and be on the class or instance side.


==== Classes ====

Changes related to classes.

=== ClassChange ===

Changes related to classes defined or extended by the package.

<code Smalltalk>ClassChange
	classReference: 	<class reference>
	superclassName: 	<Symbol>
	options: 		<Array of: String>
	instanceChanges: 	<Array of: MethodChange>
	classChanges: 		<Array of: MethodChange></code>

**classReference** :: the class of this change

**superclassName** :: ???

**options** :: Gemstone class definition options

**instanceChanges** :: instance method changes

**classChanges** :: class method changes

=== SystemClassChange ===

Changes related to classes in the target dialect.

<code Smalltalk>SystemClassChange
	className: 		<Symbol>
	instanceChanges: 	<Array of: MethodChange>
	classChanges: 		<Array of: MethodChange></code>

**className** :: The name of the class in the target dialect

**instanceChanges** :: instance method changes

**classChanges** :: class method changes


==== Packages ====

Changes related to a package or bundle.

<code Smalltalk>PackageChange
	unusedClasses: 		<Array of: class reference>
	newSuperclasses: 	<Dictionary key: class reference value: Symbol>
	newClassNames: 		<???>
	hierarchyChanges: 	<Array of: ClassChange>
	localChanges: 		<Array of: ClassChange>
	extensions: 		<Array of: SystemClassChange></code>

**unusedClasses** :: classes not to be filed out. Accumulates in a project: specified in one package, applied to all following packages.

**newSuperclasses** :: classes with their target dialect superclass

**newClassNames** :: (preparation for class renamings - not done or used yet)

**hierarchyChanges** :: class changes for a class hierarchy

**localChanges** :: class changes for classes defined or extended in the package

**extensions** :: system class changes for classes only defined in the target system

==== Projects ====

Changes related to a project with several packages and/or bundles.

Classes are renamed across the whole project.

(to be defined)

===== To do =====

Notes for myself for changes in the next version.

  * Class renamings. A project scoped operation where all references to a class must be rewritten
  * multiple rewrites. Serveral rewrites should be applied to one method source
  * Dialect namespaces. Each dialect should have it's own namespace so that target code loads without warnings
  * Usage detection. For recuring transformations, I want to find out which rules are not used anymore
  * Define classes first. References to unloaded classes cause an error in Gemstone. Allows forward references.