Wednesday, May 21, 2014

Hellcore Tutorial - Creating an API

This is a short tutorial on creating an $api object for Hellcore MOO.  This is useful for standard verbs or properties you might want to have on objects that aren't related by tree.

$api is a database that tracks the available APIs - standardized sets of verbs of properties to apply to other objects.

$interface is a definition for the API.  You @create an $interface to define the verbs and properties granted by the API.

@create $interface called linkable
@prop $api.linkable #<createdobjectnum>
@verb #<createdobjnum>:link this none none
@prop #<createdobjnum>:input_types {}

All the verbs and properties on the $interface you create should remain blank or unset - they are just to define that the interface has them.

$implementing_interface is where the actual verbs are written and any default property values set.  You have to set your previously created interface's .implementation property to the implementing interface in order to automatically apply the interface to objects.

@create $implementing_interface called linkable
;$api.linkable.implementation = #<createdimplementinginterface-objnum>

You then add verbs and properties to the implementing interface.  Example:

@verb #interface:link this none none
@program #interface:link
what = args[1];
what:aat(what:dnamec()+" beeps hella loud, because it's about to be linked to an input or output.");

The actual object being acted on is passed as the first argument.  Write the verb to act appropriate regardless of parentage.

Now that you have your interface, you can refer to it in code as $api.interfacename, and use it like so:

$api.interfacename:is_on(OBJ target) - check if the target implements $api.interfacename.
$api:implement_on(OBJ target) - apply the properties and verbs from the $implementing_interface to target.