# ***********************************************
# 
# !!!! 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::Docs::ClassIntro - Working with Apache Clownfish classes in C

=head1 DESCRIPTION

=head2 Inititalizing Clownfish parcels

Every Clownfish parcel must be initialized before it is used. The
initialization function is named C<{parcel_nick}_bootstrap_parcel> and
takes no arguments.

Example:

    cfish_bootstrap_parcel();

=head2 Including the generated header file

To use Clownfish classes from C code, the header file generated by the
Clownfish compiler must be included. The name of the C header is
derived from the name of the Clownfish C<.cfh> header. It can also be
found in the class documentation.

Typically, the “short name macro” should be defined before including a
Clownfish header. Its name is derived from the parcel nickname and has
the form C<{PARCEL_NICK}_USE_SHORT_NAMES>. If the short name macro is in
effect, you don’t have to worry about parcel prefixes.

Example:

    #define CFISH_USE_SHORT_NAMES
    
    #include <Clownfish/String.h>
    #include <Clownfish/Vector.h>

=head2 Function and method prefixes

Clownfish classes can have a “nickname” – a shorter version of the
class name that is used for function and method prefixes. The nickname
can be found in the class documentation.

For example the String class has the nickname C<Str>.

=head2 Creating objects

A Clownfish object is an opaque struct referenced by pointer.

Most classes come with one or more constructors. On the C level, a
constructor is simply an “inert” function of a class that returns a
new object. In Clownfish parlance, an inert function is any function
in a class that isn’t a method, similar to static methods in Java or
static member functions in C++.

Example:

    // Notice the use of nickname "Str" in the constructor prefix.
    String *name = Str_newf("%s %s", first, last);

=head2 Calling methods

Calling methods is straightforward. The invocant is always passed as
first argument.

    // Notice the use of nickname "Str" in the method prefix.
    size_t len = Str_Length(name);

Method names always start with an uppercase letter.

=head2 Memory management

Clownfish uses reference counting to manage memory. Constructors, but
also some methods, return an “incremented” object. If you’re done with
an incremented object, you must decrease its reference count to avoid
leaking memory. Use the C<DECREF> macro to release an object:

    DECREF(name);

Some other methods return non-incremented objects. If you want to retain
a reference to such an object, you must increase its reference count
using the C<INCREF> macro to make sure it won’t be destroyed too early:

    obj = INCREF(obj);

This invocation of INCREF must be matched by a DECREF when you’re done
with the object.

Some methods, for example in container classes, take “decremented”
objects as arguments. From the caller’s perspective, passing a
decremented argument is equivalent to passing a non-decremented argument
and calling DECREF afterwards. Typically, this avoids a call to DECREF
in the calling code. But sometimes, it must be compensated with an
INCREF.

=head2 Further reading

=over

=item *

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

=item *

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

=back

