use strict;
use warnings;

package Clownfish;
our $VERSION = '0.01';


=head1 NAME

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


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


=head2 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. 

=head2 Why use Clownfish?


=item *

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

=item *

Pure C Clownfish class implementations are very fast.

=item *

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.

=item *


=head2 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.


=head2 C method invocation syntax.

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

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

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

        // Subclass-specific behavior.

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

        // Subclass-specific behavior.

=head2 Class declaration syntax

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


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


=item * B<CLASSNAME> - The name of this class.  The last string of characters
will be used as the object's C struct name.

=item * B<CNICK> - A recognizable abbreviation of the class name, used as a
prefix for every function and method.

=item * B<PARENT> - The full name of the parent class.

=item * B<ATTRIBUTE> - An arbitrary attribute, e.g. "dumpable", or perhaps
"serializable".  A class may have multiple attributes, each preceded by a


=head2 Memory management

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

=head2 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:


The USE_SHORT_NAMES directives do not affect class prefixes, only parcel

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

=head2 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


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.