Macro Support for Squeak

Macros is a framework which provides compile-time macros for Squeak. It is primarily focused on macros that need to generate additional methods or check constraints. Basic integration with OmniBrowser and the Squeak Debugger is provided.

Already exemplarily implemented use-cases are:

• optional parameters
• protocol delegation
• automatically created setters and getters
• immutable classes
• sealed classes
• ...

How to Install

Environment
	4.1, 4.2
	Any
	Any
Sources
	​ConfigurationOfMacros
	​Macros
	CTM
	CTMOB optional
	​OmniBrowser optional
Misc
	​Macros@SqueakSource

Use the Metacello configuration or just load the CTM package (CTM stands for compile-time metaprogramming). If you also want OmniBrowser support, load the CTMOB package, too.

You can find the following categories in the packages:

CTM-Core

core implemenation including the event listener

CTM-Operations

supported operations, currently those for methods

CTM-Tests

some basic tests, all should pass

CTM-Examples

basic macros, see the class documentation of each for details

CTMOB

OmniBrowser support

How to Use

Applying Macros

To apply macros, just add pragmas to methods and classes. Method pragmas are added in the usual way, between the signature line and the code; class pragmas are added by placing them above the subclass: call in the class definition window. Examples:

withAll: aNumberArray
<shortcuts: #with count: 3>

	^ self new addAll: aNumberArray

<immutable>
Object subclass: #Klasse1
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Playground'

Creating New Macros

To create a macro you have to subclass the CTMMacro class. The first thing to do is to decide on which pragmas the macro should listen. You need to implement at least one of those two methods:

matchMethodPragma: aPragma

This should return true if the macro wants to process a method annotated with aPragma or false otherwise. Additionally the method can be used to store additional information that are found in the pragma, e.g. pragma parameters.

matchClassPragma: aPragma

Same as matchMethodPragma: but for classes and their pragmas.

Depending on the use-case and the decision you made above, implement one or more of the following methods which are called when an event in a relevant entity occurs:

methodAdded: aMethod in: aClass

methodCompiled: aCompiledMethod in: aClass from: anOldCompiledMethodOrNil

methodModified: aMethod in: aClass from: anOldMethod

methodRemoved: aMethod in: aClass

Those are called if a method event occurred.

classAdded: aClass

classCompiled: aClass from: anOldClassOrNil

classModified: aClass from: anOldClass

classRemoved: aClass

Those are called if a class event occurred.

To perform actions on the classes and methods related to the entity in the event, the methods should return a collection of CTMOperation elements. At this time, only method operations are implemented. You can add methods to classes or remove them using the following operation constructors:

CTMMethodOperation class>>add: aSelector in: aClass for: aClassOrMethod with: aSourceString

returns an operation to add a method to a class, the parameters should be self-explanatory

CTMMethodOperation class>>remove: aSelector in: aClass

removes a method from a class in the same way

See the CTM-Examples category for some macro implementations.

How to Extend

For starters, be aware that some of the components are deeply integrated with the Squeak system. There are a significant number of extension and override methods.

The basic control flow is as follows:
The CTMEventListener singleton is registered as a listener for all system events. Its event: method dispatches the events to methodEvent: and classEvent:. Those two methods find a all relevant macros, run them and finally execute the generated operations when no conflicts occurred.

One common way to extend the system is to support more kinds of tracked operations. To implement those, you have to subclass CTMOperation. Its four methods should be self-explanatory.

Acknowledgments

To date, the following people contributed to this project:

• Michael Grünewald
• Stefan Richter