FSClass

FSClass is a "meta-class" that allows programmers to create new classes directly in F-Script, instead of having to write them in Objective-C. Methods are implemented with F-Script Blocks, and data is stored as Cocoa-compliant Key-Value properties.

FSClass creates 100% real Cocoa classes; if you use FSClass to create a class 'Foobar', then Foobar will be a fully legitimate class like NSObject or NSString. Method calling is very efficient: in most cases, the FSClass framework inserts only a handful of instructions between the invocation of the method in F-Script and the execution of the Block that implements the method.

To create a class in F-Script, we first create a new "class object", then add properties and methods directly to it. Individual objects are created by asking the class object for a new instance. No additional syntax or keywords are necessary, so the core F-Script language is unaffected and classes can be created programmatically. This approach will be familiar to anyone who has created classes in JavaScript using prototyping:

// Declare the class and create a constructor
function Circle(r) {
    this.radius = r;
};

"Create the class"
Circle := FSClass newClass:'Circle'.

// accessor methods for radius - 
//  not strictly necessary
Circle.prototype.setRadius = function(r) {
    this.radius = r;
};

Circle.prototype.getRadius = function() {
    return this.radius;
};

"add radius property - automatically generates
    accessor methods"
Circle addProperty:'radius'.

"Create a class factory method"
Circle onClassMessage:#circleWithRadius:
    do:[ :self :radius | |instance|
        instance := self alloc init.
        instance setRadius:radius.
        instance
].

"Declare a constant"
Circle addClassProperty:'pi' withValue:3.14159.

// Geometry methods
Circle.prototype.area = function() {
    return Math.PI * this.radius * this.radius;
};

Circle.prototype.circumference = function() {
    return 2 * Math.pi * this.radius;
};

"Geometry methods"
Circle onMessage:#area do:[ :self |
    (self radius raisedTo:2) * Circle pi.
].

Circle onMessage:#circumference do:[ :self |
    self radius * 2 * Circle pi.
].

// class method - compare circles based on size
Circle.compare = function(circleA,circleB) {
    return circleA.compareTo(circleB);
};

// instance comparison method
Circle.prototype.compareTo = function(circle) {
    if (this.radius==circle.radius) {
        return 0;
    }
    else if (this.radius>circle.radius) {
        return -1;
    }
    else {
        return 1;
    }
}

"Comparison Method"
Circle onMessage:#compare: do:[ :self :otherCircle |
    (self radius) compare:(otherCircle radius)
].

// create and use a Circle
circle1 = new Circle(5.0);
circle1.setRadius(4.0);

alert("Circle area is : " + circle1.area);

circle2 = new Circle(5.0);

if (Circle.compare(circle1,circle2) > 0) {
    alert("circle2 is bigger than circle1");
}
else {
    alert("circle2 is bigger than circle1");
}

"create and use a Circle"
circle1 := Circle circleWithRadius:5.0.
circle1 setRadius:4.0.

sys log:'Circle area is: ' ++ (circle1 area description).

circle2 := Circle circleWithRadius:5.0.

((circle1 compare:circle2) = NSOrderedAscending) ifTrue:[
    sys log:'circle2 is bigger than circle1'.
]
ifFalse:[
    sys log:'circle1 is bigger than circle2'.
].

Note the following differences:

• In the JavaScript example, the get/set methods for the radius variable are not necessary, because variables can be directly accessed, i.e. circle = new Circle(); circle.radius = 5;. But in F-Script, we have to use methods, which addProperty: creates for us.
• this is a special keyword in JavaScript, but in F-Script, self is explicitly declared as the first parameter, even though it does not have a slot (i.e. a semicolon) in the message name. Explicit "self" parameters are used the same way in Perl and Python.
• Instead of a constructor method, we declare a class method circleWithRadius: that returns a new circle, like the NSNumber methods numberWithInt: or numberWithDouble:. Inside the factory method code, we use the regular Cocoa methods alloc init to actually create the object. The factory method must explicitly return instance.
• We declare pi as a class property of Circle, which lets us work around Objective-C's lack of namespace support.
• When adding methods to a class, we use the compact block form (e.g. #doMethod:withArg:) to specify the method's selector.

Here is an example of how to add methods to a class with FSClass:

Greeter := FSClass newClass:'Greeter'.

Greeter addProperty:'defaultGreeting'.

"factory creation method. sets a default greeting"
Greeter onClassMessage:#greeter do:[ :self | |instance|
    instance := self alloc init.
    instance setDefaultGreeting:'Hi there!'.
    instance
].

Greeter onMessage:#sayHello do:[ :self |
    sys log:'Hello!'.
].

Greeter onMessage:#sayDefaultGreeting do:[ :self |
    sys log:(self defaultGreeting).
].

Greeter onMessage:#sayGreeting: do:[ :self :greeting |
    sys log:greeting.
].


"Create a Greeter by using the class factory method"
myGreeter := Greeter greeter.

"Print 'Hello!'"
myGreeter sayHello.

"Print 'Hi there!'"
myGreeter sayDefaultGreeting.


"Print 'Bonjour!'"
myGreeter sayGreeting:'Bonjour!'.


"Save default greeting and print 'Good Morning!'"
defaultGreeting := myGreeter defaultGreeting.
myGreeter setDefaultGreeting:'Good Morning!'.
myGreeter sayDefaultGreeting.

"Print 'Hi there!'"
myGreeter sayGreeting:defaultGreeting.

Blocks supplied as method implementations must take :self as an explicit first parameter, in the same way that methods are written in Perl and Python. In the case of class methods, :self will be the class object, just as in Objective-C. All following parameters should correspond to the slots for arguments in the selector. In the above example, the sayGreeting: message only has a slot for one argument (as it has only one colon), but the block supplied for it must take two parameters. self is only the customary name for the receiver parameter; you may use any name you like.

Instance data for F-Script objects are always hidden behind accessor/mutator methods. You create a property by adding it to an existing class object. Instances can then use the Cocoa-style methods propertyName and setPropertyName: to access it:

NewClass := FSClass newClass.

NewClass addProperty:'foobar'.

"Use array messaging to add multiple properties at once"
NewClass addProperty: @ { 'propA', 'propB', 'propC' }.


inst := NewClass alloc init.

inst setFoobar:5.

"Logs '5' to the console"
sys log:(inst foobar).

Objective-C 2.0 uses the term "property" to refer to an instance variable declared in a specific way, with special attributes and a new access syntax. Properties created in F-Script are different; creating a property for an F-Script class only allocates space in the object and creates the accessor/mutator method pair. There is no special syntax, and none of the Objective-C 2.0 attributes (such as copy or readonly) can be applied.

When you create a class in Objective-C, the instance variables are packed into a C-like structure that makes property access very fast. In 64-bit applications, the property access is slightly slower, but has the advantage that adding ivars to parent classes will not break child classes.

Objects of FSClass-created classes are different, in that they store all of their properties in a dictionary, similar to objects in other scripting languages like Perl and Ruby. This makes them much more flexible, as you can add properties to a class after it has been created. However, it introduces significant overhead to accessing the properties: every call to myObj foo requires the FSClass runtime to convert the message name to a string, look up that key in an NSDictionary, and possibly convert the value before returning it.

FSClass 2.1 introduced an optional solution to this problem with 'fast-ivar' classes. If you know the names of all instance properties at the time of class creation, you can specify them in the call to newClass:

FastIvarClass := FSClass newClass:'FastIvarClass' properties:{'propA', 'propB', 'propC'}.

myFastInstance := FastIvarClass alloc init.

myFastInstance setPropA:5.

Instances of FastIvarClass will have their member variables stored directly inside the object, just like Objective-C objects. The accessor methods for these properties will look directly in the object for the values; this reduces the access and mutation overhead to a fraction of their normal costs. Otherwise, instances of FastIvarClass will work exactly as instances of regular FSClasses.

Default values can be added after class creation using the method setDefaultValue:forProperty:. Alternately, property names and defaults can be specified at class creation by passing a dictionary to the method FSClass newClass:name propertiesWithDefaults:propsDictionary. Attempting to add properties to a fast-ivar class with the methods -addProperty: or -addProperty:withDefault: will throw exceptions.

Using fast-ivar classes has an additional debugging benefit: fast ivars will show up in tools that list member variables, like object browsers or XCode's gdb interface.

Regular and fast-ivar classes can be mixed through inheritance: if a fast-ivar class inherits from a regular class, the parent class's properties will stay in the dictionary, but the child's properties will be accessed directly.

FSClass properties are Key-Value Coding compliant, so they can also be accessed with the indirect KVC methods:

KVTestClassA := FSClass newClass:'KVTestClassA'.
KVTestClassA addProperty:'propA'.

KVTestClassB := FSClass newClass:'KVTestClassB'.
KVTestClassB addProperty:'propB'.

kvInstance := KVTestClassA alloc init.

"These two lines are equivalent:"
kvInstance setPropA:5.
kvInstance setValue:5 forKey:'propA'.

"These two lines are equivalent:"
sys log:(kvInstance propA).
sys log:(kvInstance valueForKey:'propA').



"We can also do key paths"
subValue := KVTestClassB alloc init.

kvInstance setPropA:subValue.

"These two lines are equivalent:"
kvInstance propA setPropB:10.
kvInstance setValue:10 forKeyPath:'propA.propB'.

"These two lines are equivalent:"
sys log:(kvInstance propA propB).
sys log:(kvInstance valueForKeyPath:'propA.propB').

"This line will result in a runtime violation because the method is not defined:"
[ kvInstance setFoo:'a string' ]
onException:[ :e |
    sys log:('Caught an exception: ' ++ e description).
].

"This line will result in a call to valueForUndefinedKey:,
    which will then throw an NSUnknownKeyException"
[ kvInstance setValue:'a string' forKey:'foo' ]
onException:[ :e |
    sys log:('Caught an exception: ' ++ e description).
].

As shown above, once a new class has been created, instances should be created by calling factory methods:

ExampleClass := FSClass newClass:'MyClass'.

"add properties and methods to ExampleClass"
"..."

ExampleClass onClassMessage:#newExample do:[ :self | |instance|
    "Physically instantiate the object using regular alloc init"
    "FSClass 3.0 uses garbage collection, so autorelease is no longer necessary"
    instance := self alloc init.

    "Perform any necessary setup"
    "..."

    "Return the new instance"
    instance
].


"Create a new instance"
myInstance := ExampleClass newExample.

To create a new object, use the standard Cocoa methods alloc init. FSClass 3.0 uses the garbage collection system introduced in Leopard and supported by F-Script 2.0, so autorelease is no longer necessary.