Writing Classes

SuperCollider follows a pure object-oriented paradigm. It is not built on data types, but on objects, which respond to messages. A class is an object that holds information about how its objects (instances) respond to such messages. Writing a class gives a definition of this behavior.

This is an overview of idioms used in writing classes. It is not a tutorial on writing a system of interrelated classes. It gives an overview of some typical expressions. See also: Introduction to Objects, Messages, and Classes.

There is also an overview of the current full Class Tree.

Platform.userExtensionDir;   // Extensions available only to your user account

Platform.systemExtensionDir; // Extensions available to all users on the machine

Inheriting

To avoid having to write the same code several times, classes can inherit implementations from their superclasses.MyClass : SomeSuperclass { }

MyClass : SomeSuperclass {

​

}

Without specifying a superclass, Object is assumed as the default superclass.MyClass { // : Object is implied }

xxxxxxxxxx

MyClass { // : Object is implied

​

}

This is why in the above example, the message new can be called without being explicitly defined in the class.

Methods

Instance Methods

Each object instance responds to its instance methods. Instance methods are called in the local context of the object. Within instance methods, the keyword this refers to the instance itself.MyClass { instanceMethod { | argument | this.anotherInstanceMethod(argument) } anotherInstanceMethod { | argument | "hello instance".postln } }

xxxxxxxxxx

MyClass {

​

    instanceMethod { | argument |

        this.anotherInstanceMethod(argument)

    }

​

    anotherInstanceMethod { | argument |

        "hello instance".postln

    }

}

This could then be used as follows:a = MyClass.new // returns a new instance a.instanceMethod // posts "hello instance"

xxxxxxxxxx

a = MyClass.new // returns a new instance

a.instanceMethod // posts "hello instance"

To return from the method use ^ (caret). Multiple exit points also possible. If no ^ is specified, the method will return the instance (and in the case of Class methods, will return the class). There is no such thing as returning void in SuperCollider.MyClass { someMethod { ^returnObject } someOtherMethod { | aBoolean | if(aBoolean) { ^someObject } { ^someOtherObject } } }

xxxxxxxxxx

MyClass {

    someMethod {

        ^returnObject

    }

​

    someOtherMethod { | aBoolean |

        if(aBoolean) {

            ^someObject

        } {

            ^someOtherObject

        }

    }

​

}

Class Methods

An object's class methods are defined alongside its instance methods. They are specified with an asterisk (*) before the method name.

A Class is itself an object. It is what all instances of it have in common. Class methods are the instance methods of the object's class. That's why within class methods, the keyword this refers to the class.MyClass { *classMethod { | argument | this.anotherClassMethod(argument) } *anotherClassMethod { | argument | "hello class".postln } }

xxxxxxxxxx

MyClass {

    *classMethod { | argument |

        this.anotherClassMethod(argument)

    }

​

    *anotherClassMethod { | argument |

        "hello class".postln

    }

​

}

This could then be used as follows:MyClass.classMethod // posts "hello class"

xxxxxxxxxx

MyClass.classMethod // posts "hello class"

Overriding methods (overloading)

To change the behaviour inherited from the superclass, methods can be overridden. Note that an object looks always for the method it has defined first and then looks in the superclass. Here MyClass.value(2) will return 6, not 4:SomeSuperclass { calculate { |in| ^in * 2 } value { |in| ^this.calculate(in) } } MyClass : SomeSuperclass { calculate { |in| ^in * 3 } }

xxxxxxxxxx

SomeSuperclass {

    calculate { |in| ^in * 2 }

    value { |in| ^this.calculate(in) }

}

​

MyClass : SomeSuperclass {

    calculate { |in| ^in * 3 }

}

The keyword super can be used to call methods on the superclassSomeSuperclass { value { ^100.rand } } MyClass : SomeSuperclass { value { ^super.value * 2 } }

xxxxxxxxxx

SomeSuperclass {

​

    value {

        ^100.rand

    }

}

​

MyClass : SomeSuperclass {

​

    value {

        ^super.value * 2

    }

}

Instances

Object.new will return a new object. When overriding the class method .new you must call the superclass, which in turn calls its superclass, up until Object.new is called and an object is actually created and its memory allocated.MyClass { // this is a normal constructor method *new { | arga, argb, argc | ^super.new.init(arga, argb, argc) } init { | arga, argb, argc | // do initiation here } }

xxxxxxxxxx

MyClass {

​

    // this is a normal constructor method

    *new { | arga, argb, argc |

        ^super.new.init(arga, argb, argc)

    }

​

    init { | arga, argb, argc |

        // do initiation here

    }

}

In this case note that super.new called the method new on the superclass and returned a new object. Subsequently we are calling the .init method on that object, which is an instance method.

One easy way to copy the arguments passed to the instance variables when creating a class is to use Object: *newCopyArgs. This method will copy the arguments to the instance variables in the order that the variables were defined in the class, starting from the parent classes and working it's way down to the current class.MyClass { var a,b,c; *new { | a, b, c | ^super.newCopyArgs(a, b, c) } } MyChildClass : MyClass { var d; *new { | a, b, c, d | ^super.newCopyArgs(a, b, c, d) } }

xxxxxxxxxx

MyClass {

    var a,b,c;

​

    *new { | a, b, c |

        ^super.newCopyArgs(a, b, c)

    }

}

​

MyChildClass : MyClass {

    var d;

​

    *new { | a, b, c, d |

        ^super.newCopyArgs(a, b, c, d)

    }

}

Class variables are accessible within class methods and in any instance methods.MyClass { classvar myClassvar; instanceMethod { ^myClassvar } }

xxxxxxxxxx

MyClass {

    classvar myClassvar;

​

    instanceMethod {

        ^myClassvar

    }

}

Initializations on class level (e.g. to set up classvars) can be implemented by overloading the Class: *initClass method.MyClass { classvar myClassvar; *initClass { myClassvar = IdentityDictionary.new; } }

xxxxxxxxxx

MyClass {

    classvar myClassvar;

​

    *initClass {

        myClassvar = IdentityDictionary.new;

    }

}

Alternatives to inheritance

Overreliance on inheritance is usually a design flaw. Inheritance is mainly a way to organise code, and shouldn't be mistaken for a categorisation of objects. Two objects may respond to a message in different ways (polymorphism), and objects delegate control to ther objects they hold in their instance variables (object composition).

Polymorphism

See also: Polymorphism

Two completely unrelated objects can respond to the same messages and therefore be used together in the same code. For example, Function and Event have no common superclass apart from the general class Object. But both respond to the message play. Instead of inheriting all methods, you can simply implement some of the same methods in your class.MyClass { var count = 0; value { ^count = count + 1 } } // objects of this class will respond to the message "value", just like a function. a = MyClass.new; a.value; // returns 1

xxxxxxxxxx

MyClass {

    var count = 0;

    value {

        ^count = count + 1

    }

}

// objects of this class will respond to the message "value", just like a function.

a = MyClass.new;

a.value; // returns 1

Object Composition

Often, an object passes control to one of the objects it has in its instance variables. Because these objects can be of any kind, this is a very flexible way to achieve a wide range of functionalities. For example, a Button has an action instance variable, which may hold anything that responds to the message value.MyClass { var action; *new { |action| ^super.newCopyArgs(action) } value { |x| action.value(x); } } // depending on what "action" is, objects of this class will behave differently a = MyClass({ "hello." }); b = MyClass({ |i| log2(i) * sin(i * pi) }); a.value(8); b.value(8);

xxxxxxxxxx

MyClass {

    var action;

    *new { |action|

        ^super.newCopyArgs(action)

    }

    value { |x|

        action.value(x);

    }

}

​

// depending on what "action" is, objects of this class will behave differently

a = MyClass({ "hello." });

b = MyClass({ |i| log2(i) * sin(i * pi) });

a.value(8);

b.value(8);

Often, variables like action above are filled with custom objects that belong to MyClass. Thus, one will write many small classes that can be well combined in such a way. This is called "pluggable behavior".

Variables

Initializing variables directly

In a variable declaration, variables can be directly initialized. Only Literals may be used to initialize variables this way. This means that it is not possible to chain assignments (e.g. var x = 9; var y = x + 1).MyClass { classvar all = #[]; var x = 8; var y = #[1, 2, 3]; }

xxxxxxxxxx

MyClass {

    classvar all = #[];

    var x = 8;

    var y = #[1, 2, 3];

}

Variable Scope

An instance variable is accessible from all instance methods of this class and its subclasses. A class variable, by contrast, is accessible from all class and instance methods of this class and its subclasses. Instance variables will shadow class variables of the same name.MyClass { classvar x = 0, y = 1; var x = 1; *returnX { ^x } // returns 0 returnX { ^x } // returns 1 returnXY { ^x + y } // returns 2 }

xxxxxxxxxx

MyClass {

    classvar x = 0, y = 1;

    var x = 1;

​

    *returnX { ^x } // returns 0

    returnX { ^x } // returns 1

    returnXY { ^x + y } // returns 2

}

Subclasses can override class variable declarations (but not instance variables). Then the class variables of the superclass are not accessible in the subclass anymore.SomeSuperclass { classvar x = 0; returnX { ^x } returnXHere { ^x } } MyClass : SomeSuperclass { classvar x = 1; returnXHere { ^x } } // SomeSuperclass.returnXHere returns 0 // MyClass.returnXHere returns 1 // MyClass.returnX returns 0

xxxxxxxxxx

SomeSuperclass {

    classvar x = 0;

​

    returnX { ^x }

    returnXHere { ^x }

}

​

MyClass : SomeSuperclass {

    classvar x = 1;

​

    returnXHere { ^x }

}

​

// SomeSuperclass.returnXHere returns 0

// MyClass.returnXHere returns 1

// MyClass.returnX returns 0

Getters and Setters

SuperCollider demands that variables are not accessible outside of the class or instance. A method must be added to explicitly give access:MyClass : SomeSuperclass { var myVariable; variable { ^myVariable } variable_ { | newValue | myVariable = newValue; } }

xxxxxxxxxx

MyClass : SomeSuperclass {

    var myVariable;

​

    variable {

        ^myVariable

    }

​

    variable_ { | newValue |

        myVariable = newValue;

    }

}

These are referred to as getter and setter methods. SuperCollider allows these methods to be easily added by adding < or >.MyClass { var <getMe, >setMe, <>getMeOrSetMe; }

xxxxxxxxxx

MyClass {

    var <getMe, >setMe, <>getMeOrSetMe;

}

This provides the following methods:someObject.getMe; someObject.setMe_(value);

xxxxxxxxxx

someObject.getMe;

someObject.setMe_(value);

And it also allows us to say:someObject.setMe = value; someObject.getMeOrSetMe_(5); someObject.getMeOrSetMe;

xxxxxxxxxx

someObject.setMe = value;

​

someObject.getMeOrSetMe_(5);

someObject.getMeOrSetMe;

A getter or setter method created in this fashion may be overridden in a subclass by explicitly defining the method. Setter methods should take only one argument to support both ways of expression consistently. eg.MyClass { variable_ { | newValue | variable = newValue.clip(minval,maxval); } }

xxxxxxxxxx

MyClass {

​

    variable_ { | newValue |

        variable = newValue.clip(minval,maxval);

    }

​

}

A setter method should always return the receiver. This allows us to be sure that several setters can chained up.

Constants

Constants are variables, that, well, don't vary. They can only be assigned initially.MyClass { const <zero = 0; } MyClass.zero // returns 0

xxxxxxxxxx

MyClass {

    const <zero = 0;

}

​

MyClass.zero // returns 0

External method files

Methods may be added to Classes in separate files. This is equivalent to Categories in Objective-C. By convention, the file name starts with a lower case letter: the name of the method or feature that the methods are supporting.+ Class { newMethod { } *newClassMethod { } }

xxxxxxxxxx

+ Class {

​

    newMethod {

​

    }

​

    *newClassMethod {

​

    }

​

}

Slotted classes

Classes defined with [slot] can use the syntax myClass[...] which will call myClass.new and then this.add(each) for each item in the square brackets.MyClass[] { var <allOfThem; add { |item| allOfThem = allOfThem.add(item) } } a = MyClass[1, 2, 3]; a.allOfThem; // [1, 2, 3]

xxxxxxxxxx

MyClass[] {

    var <allOfThem;

    add { |item|

        allOfThem = allOfThem.add(item)

    }

}

​

a = MyClass[1, 2, 3];

a.allOfThem; // [1, 2, 3]

Printing to string

Printing custom messages to post window

By default when postln is called on an class instance the name of the class is printed in a post window. When postln or asString is called on a class instance, the class then calls printOn which by default returns just the object's class name. This should be overridden to obtain more useful information.MyTestPoint { var <x, <y; *new { |x, y| ^super.newCopyArgs(x, y) } printOn { | stream | stream << "MyTestPoint( " << x << ", " << y << " )"; } }

xxxxxxxxxx

MyTestPoint {

    var <x, <y;

​

    *new { |x, y|

        ^super.newCopyArgs(x, y)

    }

​

    printOn { | stream |

        stream << "MyTestPoint( " << x << ", " << y << " )";

    }

}

xxxxxxxxxx

a = MyTestPoint(2, 3)

Defining custom asCompileString behaviour

A call to asCompileString should return a string which when evaluated creates the exact same instance of the class. To define a custom behaviour one should either override storeOn or storeArgs. The method storeOn should return the string that evaluated creates the instance of the current object. The method storeArgs should return an array with the arguments to be passed to TheClass.new. In most cases this method can be used instead of storeOn.// either MyTestPoint { var <x, <y; *new { |x, y| ^super.newCopyArgs(x,y) } storeOn { | stream | // note that <<< stands for storeOn, and << for printOn. // we want x and y to be completely represented stream << "MyTestPoint.new(" <<< x << ", " <<< y << ")" } } // or MyTestPoint { var <x, <y; *new { |x, y| ^super.newCopyArgs(x,y) } storeArgs { | stream | ^[x, y] } }

xxxxxxxxxx

// either

MyTestPoint {

    var <x, <y;

​

    *new { |x, y|

        ^super.newCopyArgs(x,y)

    }

​

    storeOn { | stream |

        // note that <<< stands for storeOn, and << for printOn.

        // we want x and y to be completely represented

        stream << "MyTestPoint.new(" <<< x << ", " <<< y << ")"

    }

}

​

// or

MyTestPoint {

    var <x, <y;

​

    *new { |x, y|

        ^super.newCopyArgs(x,y)

    }

​

    storeArgs { | stream |

        ^[x, y]

    }

}

xxxxxxxxxx

MyTestPoint(2, 3).asCompileString;

Private Methods

Private methods are marked by a prefix pr, e.g. prBundleSize. This is just a naming convention; the message can still be called from anywhere. It is recommended to stick to convention and only call private methods from within the class that defines them.

Catching undefined method calls

When a message is received that is undefined, the receiver calls the method doesNotUnderstand. Normally this throws an error. By overriding doesNotUnderstand, it is possible to catch those calls and use them. For an example, see the class definition of IdentityDictionary.MyClass { doesNotUnderstand { | selector...args | (this.class ++ " does not understand method " ++ selector); if(UGen.findRespondingMethodFor(selector).notNil) { "But UGen understands this method".postln }; } }

xxxxxxxxxx

MyClass {

​

    doesNotUnderstand { | selector...args |

        (this.class ++ " does not understand method " ++ selector);

​

        if(UGen.findRespondingMethodFor(selector).notNil) {

            "But UGen understands this method".postln

        };

    }

}

xxxxxxxxxx

a = MyClass();

a.someMethodThatDoesNotExist