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.

Subclasses are created with the method newClass:parent:, which takes an as its argument an FSClass object or an Objective-C class object like NSMutableDictionary. You can also use subclass: to get a subclass directly from the parent. All methods (and, in the case of FSClass parents, properties with default values) are inherited from the superclass. To override a method implemented by a superclass, simply call onMessage:do: with the same selector and a different block:

Car := FSClass newClass:'Car'.

Car addProperty:'speed' withDefault:0.

Car onClassMessage:#car do:[ :self |
    "The class's only property has a default, so we can just return a new instance"
    "+alloc will take care of setting the property defaults; -init will call the NSObject init method"
    self alloc init.
].

Car onMessage:#drive do:[ :self |
    set setSpeed:50.
].

Car onMessage:#park do:[ :self |
    self setSpeed:0.
].

"Create a faster subclass of Car"
SportsCar := FSClass newClass:'SportsCar' parent:Car.

"Equivalent command to create a subclass would be:
    SportsCar := Car subclass:'SportsCar'.
"

SportsCar onClassMessage:#sportsCar do:[ :self |
    self alloc init
].


"Override drive to go faster"
SportsCar onMessage:#drive do:[ :self |
    self setSpeed:80.
].

"No need to override park"

Properties are also inherited by subclasses. Unlike with compiled classes like Java or C++, classes at different levels of an inheritance hierarchy cannot have properties with the same name. This is because all properties in F-Script are accessed through methods, and all methods are inherited. If you try to add a property to a subclass that conflicts with a property already declared in a superclass, it will throw an exception; the reverse is not true. In short, if class Child with property bar inherits from Parent with property foo, Parent addProperty:'bar' will work, but Child addProperty:'foo' will not.

F-Script 2.0 introduces a reserved super keyword, but FSClass needs additional context that this keyword does not provide. Particularly, the super-class method invocation needs to know the class of the current Block. This information, which is also needed in languages like Objective-C, Java, and C++, is normally provided by the compiler. Because the F-Script interpreter does not know about FSClass, you must supply this context manually, as the second argument to the method doSuperMethod:currentClass:. The first argument should be the selector of the method you want to call, and any arguments can be passed using the keywords with:, similar to the syntax for executing blocks.

Up to this point, all of our class factories have performed initialization inside the factory method, which prevents using superclass initialization methods. A solution is to separate instantiation and initialization by creating a private _init method that is called from the class factory to initialize the object. This init method can then call the superclass init method, and so on up the class hierarchy. The superclass initialization method is sometimes called the designated initializer.

It is very important that the top-level initializer code use the Cocoa method init, to ensure that the object is properly registered with the Cocoa runtime system.

The following example shows how to create a subclass and call superclass methods, including initialization methods:

SuperClass := FSClass newClass:'SuperClass'.

SuperClass addProperty:'foo'.

"The initializer is private, hence the underscore.
 This method is the *designated initializer* for SuperClass"
SuperClass onMessage:#_initWithFoo: do:[ :self :fooValue |
    self init.  "Cocoa's init method should be called first"
    self setFoo:fooValue.
    self
].

"Only this class method should be called by users"
SuperClass onClassMessage:#superObjectWithFoo: do:[ :self :fooValue |
    "Actual initialization is handled in the _init method"
    self alloc _initWithFoo:fooValue
].

SuperClass onMessage:#doThing do:[ :self |
    sys log:'Hi from SuperClass! foo:' ++ (self foo description).
].

SuperClass onMessage:#doStuff do:[ :self |
    sys log:'Bonjour from SuperClass! foo:' ++ (self foo description).
].


"Create a subclass"
SubClass := FSClass newClass:'SubClass' withParent:SuperClass.

SubClass addProperty:'bar'.


"This initializer calls the superclass's init: method"
SubClass onMessage:#_initWithBar: do:[ :self :barValue |
    "Call the designated initializer with a default foo value"
    "We have to specify which class this Block is attached to"
    "  so that the runtime has the proper context"
    self := self doSuperMethod:#_initWithFoo: with:5.
    self setBar:barValue.
    self
].

"Only this class factory method should be called by users"
SubClass onClassMessage:#subObjectWithBar: do:[ :self :barValue |
    "Actual initialization is handled in the _init method"
    self alloc init _initWithBar:barValue
].


"Execute superclass's doThing first"
SubClass onMessage:#doThing do:[ :self |
    self doSuperMethod:#doThing currentClass:SubClass
    sys log:'Hi from SubClass! bar:' ++ (self bar description)
].


sub := SubClass subObjectWithBar:10.

" Prints 'Bonjour from SuperClass! foo:5"
sub doStuff.

"Prints 'Hi from SuperClass! foo:5' 'Hi from SubClass! bar:10'"
sub doThing.

This syntax for using superclass methods has changed from earlier versions of FSClass. The old system (using the method super:) did not work properly and conflicts with a new reserved keyword. It has been completely removed.

Besides factory methods, classes can also have functions and data attached directly to them. This example shows how to create a counter that keeps track of how many instances have been created:

Car := FSClass newClass:'Car'.

Car addProperty:'type'.

"Counter - would be a static variable in C++/Java"
Car addClassProperty:'count' withValue:0.
Car onClassMessage:#createdCarCount do:[ :class |
    class count
].

Car onClassMessage:#carWithModel: do:[ :self :type | |car|
    Car setCount:(Car count + 1).
    car := self alloc init.
    car setType:type.
    car
].

car1 := Car carWithModel:'sedan'.
car2 := Car carWithModel:'SUV'.

"Prints '2 cars have been created'."
sys log:(Car createdCarCount description) ++ ' cars have been created'.

Like instance properties or methods, class properties and methods are inherited by subclasses.

One of the most useful language features of Objective-C is categories: the ability to add methods to a class piecemeal, after the class has been declared, even after it has been compiled! In FSClass 3.0, all classes, including those written in Objective-C, have the same method-addition abilities. This includes Cocoa classes for which the source code is not available:

"This code uses the regular expression method -replace:with: from the fscript Unix tool."
NSString onMessage:#bork do:[ :self |
    ((self replace:'W' with:'V') replace:'w' with:'v') replace:'o' with:'oo'
].

"Prints 'Helloo voorld!'"
out println:('Hello world!' bork).

The method -bork will now be available to all instances of NSString, even through the NSString source code is not available, and is in a different language.

Objective-C classes have all the introspection and modification methods as those created in F-Script, with the exception that you cannot add instance variables; calling +addProperty: or +addProperty:withDefault: will throw exceptions.

The ability to add arbitrary methods to Foundation classes in F-Script is extremely powerful, especially when combined with F-Script's flexible syntax. For example, many languages like LISP, Ruby, and PHP have a 'pairing operator', which takes two objects and returns a simple object that pairs them together. With a class proxy, we can add that capability to NSObject and make it available to every single object in the Cocoa codesphere:

"Create a simple Pair class"
Pair := FSClass newClass:'Pair' properties:{'first', 'second'}.
Pair onClassMessage:#pair:with: do:[ :self :first :second | |newPair|
    newPair := self alloc init.
    newPair setFirst:first; setSecond:second.
    newPair
].
"Simple description: (obj1, objc2)"
Pair onMessage:#description do:[ :self |
    '(' ++ self first description ++ ', ' ++ self second description ++ ')'
].

"Add a pairing operator to NSObject, and thus to all classes"
NSObject onMessage:#operator_equal_greater: do:[ :self :second |
    Pair pair:self with:second.
].


"Now we can pair any two objects together"
myPair := 1 => 5.

"Prints '(1, 5)'"
sys log:myPair description.

"Like Foundation collection objects, Pairs are heterogeneous"
myMixedPair := 'hello!' => 5.

(Note that, due to F-Script's strict left-to-right precedence rules, the pairing arrow cannot be chained to create a LISP-style linked list).

Proxies can make Foundation classes much more convenient to use. One problem with Objective-C is that method names tend to be verbose; a simple dictionary lookup/set in most languages is only a few characters, but requires the long methods -objectForKey: and -setObject:forKey: in Cocoa. This makes dictionary-heavy Cocoa code much more cumbersome than equivalent code in Perl or Python. The following example shows how we can use F-Script categories to add abbreviations to NSDictionary, including a subscript operator and a set operator that takes a Pair:

"Add a C++ style subscript operator - will be inherited by NSMutableDictionary"
NSDictionary onMessage:#operator_hyphen_greater: do:[ :self :key |
    self objectForKey:key
].

"Add a set: method that takes a pair"
NSMutableDictionary onMessage:#set: do:[ :self :pair |
    self setObject:(pair second) forKey:(pair first).
].


"Now using a dictionary is much easier"
dict := NSMutableDictionary dictionary.

dict set: 'keyA'=>6.
dict set: 'keyB'=>'hello'.

sys log:'keyA: ' ++ (dict->'keyA') description.
sys log:'keyB: ' ++ (dict->'keyB') description.

For a longer example, see the file examples/Switch.fs in the FSClass sources directory. This file shows how a switch statement can be added to the F-Script language, solely by adding methods to existing Foundation classes.

FSClass classes are fully reflective. The following methods provide information about methods, classes, and inheritance relationships:

• propertyNames
• allPropertyNames
• methods
• allMethods
• methodNames
• allMethodNames
• blockForSelector:
• blockForClassSelector:
• methodImplementor:
• classPropertyNames
• allClassPropertyNames
• classMethods
• allClassMethods

Because classes created with FSClass are full participants in the Cocoa runtime system, they can be used from pre-compiled Objective-C code, although a little bit of indirection is needed. Say that we have created a FSClass named Foobarizer. The following code will get a reference to the class and create a new instance of it:

// We can't actually use the class name 'Foobarizer' because
// the compiler will complain that it is undefined
Class FoobarizerClass = NSClassFromString(@"Foobarizer");

// Create an instance - we have to pass an object as argument, not a plain int
id fooInstance = [FoobarizerClass foobarizerWithFoo:[NSNumber numberWithInt:10]];

// this line will produce a compiler warning that -foobarize: is undefined
id result = [fooInstance foobarize:@"a string"];

// we can also run methods indirectly
[fooInstance performSelector:@sel(setFoo:) withObject:[NSNumber numberWithInt:27]];

If you use FSClass objects inside Objective-C, remember that all FSClass method parameters are objects. You will have to wrap numbers and other primitives inside NSNumber or other classes if you wish to use them as arguments; the automatic conversion of the F-Script runtime is not available.

Also note that XCode will likely complain that it cannot find declarations of the methods that you use with the FSClass-derived class, unless they happen to already be implemented by another class. These warnings are annoying, but will not affect the functioning of the program (of course, if you did misspell a method name, your program will crash at runtime!) In the warning message, XCode will also say it is assuming that the return and argument types are all id, which in this case is accurate.

None currently known.