NAME

Clownfish - A small OO language that forms symbiotic relationships with "host" languages.

PRIVATE API

Clownfish is a KinoSearch implementation detail. This documentation is partial -- enough for the curious hacker, but not a full API.

DESCRIPTION

Overview.

Clownfish is a small language for declaring an object oriented interface and a compiler which allows classes to be implemented either in C, in a "host" language, or a combination of both.

Why use Clownfish?

• Clownfish-based projects give users the ability to write full subclasses in any "host" language for which a binding has been prepared.

• Pure C Clownfish class implementations are very fast.

• Users can perform rapid prototyping in their language of choice, then port their classes to C either for speed or to make them available across multiple language platforms.

Object Model

Clownfish is single-inheritance and class based -- a minimalist design which makes it as compatible as possible with a broad range of hosts.

Subclasses may be created either at compile time or at run time.

C method invocation syntax.

Methods are differentiated from functions via capitalization: Boat_capsize() is a function, Boat_Capsize() is a method.

// Base method.
void
Boat_capsize(Boat *self)
{
    self->upside_down = true;
}

// Implementing function, in Boat/Battleship.c
void
Battleship_capsize(Battleship *self) 
{
    // Superclass method invocation.
    Boat_capsize_t capsize = (Boat_capsize_t)SUPER_METHOD(
        BATTLESHIP, Battleship, Capsize);
    capsize((Boat*)self);  

    // Subclass-specific behavior.
    Battleship_Sink(self);
}

// Implementing function, in Boat/RubberDinghy.c
void
RubDing_capsize(RubberDinghy *self) 
{
    // Superclass method invocation.
    Boat_capsize_t capsize = (Boat_capsize_t)SUPER_METHOD(
        RUBBERDINGHY, RubDing, Capsize);
    capsize((Boat*)self);  

    // Subclass-specific behavior.
    RubDing_Drift(self);
}

Class declaration syntax

[final] [inert] class CLASSNAME [cnick CNICK] 
    [inherits PARENT] [ : ATTRIBUTE ]* {

    [declarations]

}

Example:

class Boat::RubberDinghy cnick RubDing inherits Boat {
    
    public inert incremented RubberDinghy*
    new();
    
    void 
    Capsize(RubberDinghy *self);
}

• CLASSNAME - The name of this class. The last string of characters will be used as the object's C struct name.

• CNICK - A recognizable abbreviation of the class name, used as a prefix for every function and method.

• PARENT - The full name of the parent class.

• ATTRIBUTE - An arbitrary attribute, e.g. "dumpable", or perhaps "serializable". A class may have multiple attributes, each preceded by a colon.

Memory management

At present, memory is managed via a reference counting scheme, but this is not inherently part of Clownfish.

Namespaces, parcels, prefixes, and "short names"

There are two levels of namespacing in Clownfish: parcels and classes.

Clownfish classes intended to be published as a single unit may be grouped together using a "parcel". Parcel directives need to go at the top of each class file.

parcel Crustacean cnick Crust;

All symbols generated by Clownfish for classes within a parcel will be prefixed by varying capitalizations of the parcel's C-nickname or "cnick" in order to avoid namespace collisions with other projects.

Within a parcel, the last part of each class name must be unique.

class Crustacean::Lobster::Claw { ... }
class Crustacean::Crab::Claw    { ... } // Illegal, "Claw" already used

"Short names" -- names minus the parcel prefix -- will be auto-generated for all class symbols. When there is no danger of namespace collision, typically because no third-party non-system libraries are being pound-included, the short names can be used after a USE_SHORT_NAMES directive:

#define CRUST_USE_SHORT_NAMES

The USE_SHORT_NAMES directives do not affect class prefixes, only parcel prefixes.

// No short names.
crust_LobsterClaw *claw = crust_LobClaw_new();

// With short names.
#define CRUST_USE_SHORT_NAMES
LobsterClaw *claw = LobClaw_new();

Inclusion

C header code generated by the Clownfish compiler is written to a file with whose name is the same as the .cfh file, but with an extension of ".h". C code should pound-include "Crustacean/Lobster.h" for a class defined in "Crustacean/Lobster.cfh".

COPYRIGHT AND LICENSE

Copyright 2006-2011 Marvin Humphrey

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm KSx::Simple

perl -MCPAN -e shell
install KSx::Simple