# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

=encoding utf8

=head1 NAME

Clownfish - Apache Clownfish symbiotic object system

=head1 DESCRIPTION

The Apache Clownfish “symbiotic” object system pairs with “host” programming
language environments and facilitates the development of high performance
language extensions.

=head2 Features

=over

=item *

Support for multiple host languages.

=item *

Support for stand-alone C libraries and executables.

=item *

Subclassing and method overriding from the host language.

=item *

Support for host language idioms like named parameters or default argument
values.

=item *

Highly performant object system with lazy creation of host language objects.

=item *

Runtime with classes for commonly used data structures like strings, dynamic
arrays and hash tables.

=item *

Guaranteed ABI stability when adding or reordering methods or instance
variables.

=item *

Modularity.

=item *

Introspection.

=item *

Documentation generator.

=back

=head2 Planned features

=over

=item *

Support for more host languages.

=item *

Support for interfaces.

=back

=head2 Overview

Clownfish consists of two parts, the Clownfish compiler “CFC” and the
Clownfish runtime. CFC is a code generator that creates C header files, host
language bindings, initialization code and documentation from a set of
Clownfish header files. The generated code is compiled with other project
code and linked with the Clownfish runtime.

Clownfish header files have a C<.cfh> extension and define classes used within
the Clownfish object system. The object system is implemented in C and
supports single inheritance and virtual method dispatch. CFC creates a C
header file from each Clownfish header containing the C interface to Clownfish
objects. Functions and methods of objects are implemented in normal C source
files. Beyond the C level, CFC can generate host language bindings to make
Clownfish objects accessible from other programming languages. The compiler
also creates class documentation in various formats from comments contained in
Clownfish header files and standalone Markdown files.

The Clownfish runtime provides:

=over

=item *

The L<Obj|Clownfish::Obj> class which is the root of the class hierarchy.

=item *

Core data types like L<strings|Clownfish::String>,
L<dynamic arrays|Clownfish::Vector>, and L<hashes|Clownfish::Hash>.

=item *

The L<Class|Clownfish::Class> metaclass.

=item *

Some helper classes.

=back

=head2 Host language support

Bindings for the following hosts are under development:

=over

=item *

C (feature-complete)

=item *

Go (experimental)

=item *

Perl 5 (feature-complete)

=item *

Python 3 / CPython (nascent)

=item *

Ruby / MRI (nascent)

=back

=head2 Help wanted

The target audience for the current release of Clownfish is developers.
Clownfish is developed by the Apache Lucy community, where it is used to
provide host language bindings for the Lucy search engine library; we expect
that as Clownfish matures it will eventually spin off as an independent
project.  If you would like to contribute to Clownfish, please join the L<Lucy
developers mailing list|http://lucy.apache.org/mailing_lists>.

=head2 Documentation

=over

=item *

L<Working with Clownfish classes|Clownfish::Docs::ClassIntro>

=item *

L<Building Clownfish projects in C environments|Clownfish::Docs::BuildingProjects>

=item *

L<Writing Clownfish classes|Clownfish::Docs::WritingClasses>

=back

