Functions and Classes

the building blocks of sophisticated software

A function is essentially a sub-program that does some particular task. We’ve already seen some of the functions built into MiniScript, such as time and range, and even print. There are many more of those, which will be documented in the next chapter. But the real power of a programming language comes from defining your own functions.

Beyond that, as a program grows in size and complexity, it becomes useful to start organizing it into classes. A class is basically a collection of functions and data, where objects of a class share the same functions but may have unique data.

Functions

A function in MiniScript is a special data type, at the same level as numbers, strings, lists, and maps. You can define a function with the function keyword, assign it to a variable, and then invoke it via that variable, just like the built-in functions. Here’s an example.

triple = function(n=1)
return n*3
end function
print triple // prints: 3
print triple(5) // prints: 15

This declares a function that triples any value given to it, and assigns that function to a variable called triple. The triple function is then invoked, with and without an argument. The syntax for declaring a function is:

function(parameters)
…
end function

where parameters is a comma-separated list of zero or more parameters, each of the form name or name=defaultValue. When a function is invoked, arguments will be matched up to the functions by position. If fewer arguments are given than parameters are defined, the remaining parameters are given their default values — and if no default value was defined for that parameter, then it is set to null.

Note that the parentheses after the function keyword are required only if there are parameters. In the case of a function with no parameters, the parentheses are not required (and by standard convention, should be omitted).

It’s important to understand that a function is itself a bit of data. It’s just that, whenever looking up the value of a variable, MiniScript checks for this special function data type; and if found, it invokes that function, rather than returning the function itself.

Usually that is exactly what is wanted, as in the example above. But occasionally you may want to copy the function reference, rather than invoking the function. You can do this by prepending your identifier with an @ (read “address of”). Example:

triple = function(n=1)
return n*3
end function
x = @triple
print x(5) // prints: 15

Here we’ve again declared a function and stored it in a variable called triple. Then we copy the address of that function into another variable called x. At this point we can invoke the function either way, via triple or via x, and both do exactly the same thing. Had we left out the @ on the assignment, MiniScript would have instead evaluated the function triple refers to, and assigned the result (3) to x.

Here’s a more realistic example. We’ll define a function called apply which can apply a given function to each element of a list. Then we can invoke this on a list with any function, simply by using @ to refer to the function we want to apply.

apply = function(lst, func)
result = lst[0:] // make a copy of the list
for i in indexes(result)
result[i] = func(result[i]) // apply func to each element
end for
return result // return modified result
end function
print apply([1, 2, 3], @triple) // prints: [3, 6, 9]

To summarize, you invoke a function by simply using any identifier that refers to it. You avoid this invocation, and refer instead to the function itself, by putting @ before the identifier.

Nested Functions

MiniScript allows you to define functions within functions. This is an advanced feature that most users may never need, but it can come in handy on occasion, especially in conjunction with something like the “apply” method above. Just as with any other local value, you might want to avoid cluttering the global namespace just for a function that you only use in one place. Here’s a simple example that assumes we have the apply method defined above.

doubleAll = function(lst)
f = function(x)
return x + x
end function
return apply(lst, @f)
end function

So inside the function referred to by the (global variable) doubleAll, we define another function, and assign it to the (local variable) f. Then we pass that function in as the second argument to the apply function (or more pedantically, to the function referred to by the apply global variable).

When you have a nested function like this, it can access the local variables of the function that contains it. Just as with global variables, it can do this without any prefix (as long as there isn’t some local variable with the same name getting in the way). But to assign to a variable of the outer function, you must use the special identifier outer. Here’s an example.

makeList = function(sep)
counter = 0
makeItem = function(item)
outer.counter = counter + 1
return counter + sep + item
end function
return [makeItem("a"), makeItem("b"), makeItem("c")]
end function
print makeList(". ")

Here, makeList refers to the outer function, and makeItem is the inner (nested) function. Notice how makeList has a local variable called counter, initialized to 0. But the inner function both reads that value, and updates it using outer.counter. Work through this code carefully to see if you can figure out what it prints… and then try it and see if you were right!

Again, this nested-function business is an advanced feature which beginners can safely forget about. But for advanced users, it is a language feature worth understanding.

Classes and Objects

MiniScript supports object-oriented programming (OOP) via prototype-based inheritance. That is, there is fundamentally no difference in MiniScript between a class and an object; the difference, when it exists at all, lives solely in the intent of the programmer.

A class or object is a map with a special __isa entry that points to the parent (prototype). This is an implementation detail you rarely need to worry about, because it is handled automatically by the following rules:

1. When you create a map using the special new operator, the __isa member is set for you.
2. When you look up an identifier in a map, MiniScript will walk the __isa chain looking for a map containing that identifier. The value returned is the first value found.
3. Finally, the isa operator also walks the __isa chain, and returns true if any map in that chain matches the right-hand operand. In other words, x isa y returns true if x is any subclass of y.

These simple rules provide everything needed for object-oriented programming. A series of „classes“ may be defined as maps containing functions and default data, which are inherited or overridden as needed. An „object“ is just another map, inherited from some class, which normally contains only custom data.

Let’s illustrate with an example. We’ll define a class called Shape, with a subclass called Square.

Shape = {}
Shape.sides = 0
Square = new Shape
Square.sides = 4

A base class is just an ordinary map; in this case, we added a sides entry with a value of 0, signifying that “sides” is a bit of data we expect every Shape to have. Then we created a subclass by using new Shape, and assigned this to Square. In Square, we overrode the value of sides (as all squares should have 4 sides).

Now let’s create an instance of our Square class, again by using new.

x = new Square
print x.sides // prints: 4

Notice how we’re using the traditional OOP terminology of “class” and “instance” for convenience, but in reality, there are just three maps — Shape is the prototype of Square, and Square is the prototype of x. The __isa member of each map points to the prototype, because we created them with new.

Now let’s add a function to the Shape class, which should work for any shape subclass or
object.

Shape.degrees = function()
return 180 * (self.sides - 2)
end function
print x.degrees // prints: 360

This example illustrates one additional rule important to object-oriented programming:

• When a function is invoked via dot indexing, it receives a special self variable that refers
  to the object on which it was invoked.

So in the example above, we invoked the degrees function as x.degrees, which looks for a member called “degrees” in x (and its prototypes via the __isa chain). And when that function is invoked, a special local variable called self is bound to the x object, i.e. the first map in the search chain. This allows class functions to access object data.

There is just one more bit of special support for object-oriented programming, and that is the super keyword. This is another built-in variable (similar to self) defined when you invoke a method via dot syntax, but when you call another method via super, it invokes that method on the base class, while keeping self bound to the same value as in the current function. In other words, super lets you call a superclass method, even if you’ve overridden it. Continuing the previous example, suppose we want to define a subclass of Square that always has 42 more degrees than nonmagical shapes would have:

MagicSquare = new Square
MagicSquare.degrees = function()
return super.degrees + 42
end function
y = new MagicSquare
print y.degrees // prints: 402

Notice how the MagicSquare.degrees function calls super.degrees. That causes MiniScript to walk the __isa chain, looking for the first implementation of degrees it can find. That would be Shape.degrees, so it invokes that, with a self still bound to y.

Extending the Built-In Types

There are maps that represent each of the basic data types: number, string, list, and map. These contain the built-in methods for those types. By adding new methods to one of these maps, you can add new methods usable with dot syntax on values of that type. For example, while there are built-in string methods .upper and .lower to convert a string to upper- or lower-case, there isn’t a method to capitalize a string — that is, convert only the first letter to uppercase. But you could add such a method in your program as follows.

string.capitalized = function()
if self.len < 2 then return self.upper
return self[0].upper + self[1:]
end function

The function itself is fairly simple: if our string (self) is less than 2 characters long, just uppercase the whole thing; otherwise uppercase the first letter, and append the rest. But because we have assigned this function to string.capitalized, that is, added it to the string map, we can call it with dot syntax on any string.

print "miniScript".capitalized // prints: MiniScript

There is one limitation to this trick. Numbers are a little different from other data types; MiniScript does not support dot syntax on numeric literals. So

x = 42
x.someMethod

works fine (assuming you have defined an appropriate number.someMethod function), but

42.someMethod

does not.