API

===============
API Definitions
===============

Having a clean API is important when working on production quality projects.
The larger the project, the more necessary it is that the API be clean and
easily understandable. Cauldron is not a large project, but still benefits from
having an API that is clean. Not only does it make things easier for new
developers to adapt to the project, it will also help to keep the namespace
separated from other Source Mage GNU/Linux components, as well as whatever
might be defined by the user, thus preventing naming collisions. Additionally,
it can help reduce errors in programming due to confusion of one variable with
another. If the subcomponents are all appropriately named, then it will be
clear whether you are calling the correct function (if you are programming
something for enchantment, you probably shouldn't be calling any function
prefixed with "cauldron_" for example). If you are contributing to any part of
the Cauldron codebase, you are asked to adhere to the following guidelines when
naming functions and variables.

Where it makes sense, I have loosely modeled the Cauldron API after the OpenGL
API because I consider the OpenGL API to be an excellent example of a clean and
efficient API. Familiarity with the OpenGL API is however not required to code
or understand the Cauldron API.

This API specification may be updated or altered at any time under the
discretion of Cauldron Lead or by vote of the Cauldron Team. The voting may be
informal, until formal voting is required, in which case this statement would
be amended.

In the context of the API, "cauldron" refers to the cauldron suite itself.
Anything pertaining to installers is referred to collectively as "enchantment"
(the enchantment suite).

 * Global variables (including those sourced from the config files) are to be
 in all UPPERCASE, must start with a letter, and can contain only letters,
 underscores, and trailing numbers
 - in regexp, [A-Z][A-Z_]*[0-9]*
 * Global variables should be defined in the relevant config file
 (etc/cauldron/cauldron.conf for cauldron and
 etc/enchantment/enchantment.conf for enchantment)

 * Local variables are to be in all lowercase, must begin with a letter, and
 can contain only letters, underscores, and trailing numbers
 - in regexp, [a-z][a-z_]*[0-9]*
 * Local variables should be defined at the top of the function which scopes
 them, and MUST be defined before being used.

 * Functions are to be in all lowercase, unless there is a very good reason to
 uppercase (initial portions must still be lowercased, i.e. initial_LATER or
 initial_Later), and any uppercasing needs to be approved
 - in regexp, [a-z][a-z_]*

 * All cauldron API functions are to be prefixed with cauldron_
 * All cauldron API variables are to be prefixed with CAULDRON_

 * All enchantment API functions are to be prefixed with enchant_
 * All enchantment API variables are to be prefixed with ENCHANT_

 * All potion API functions are to be prefixed with enchant_potion_
 * All potion API variables are to be prefixed with ENCHANT_POTION_

 * Other API variables and functions are to be prefixed in accordance with what
 makes sense for where those functions and variables are defined. For
 example, in the common library liberror, functions are prefixed with
 liberror_.

 * Functions which logically group together (i.e., functions that operate
 specifically on modules themselves) should share a common prefix in addition
 to the library prefix (i.e., enchant_module_enter and enchant_module_exit
 have the common prefix module_)
 - in regexp terms: libprefix_(commonprefix_)*name

 * Functions should be preceded by verbose comments to describe the use of the
 function, formatted for use with bashdoc

The above are general rules that should always be followed, unless there is a
clear reason for deviating from them. There is one case where the naming rules
can always be safely broken, and that is with variables defined as local.

================================================================================
Example:

#-------------------------------------------------------------------------------
## @param target_spells
##
## Performs cast on the list of spells needed for installation to the target
## system. "target_spells" is a list of spells that will be needed to install
## into the target system from the iso.
##
#-------------------------------------------------------------------------------
function cauldron_build_iso_system() {
 local target_spells=$1
 local spell

 # Since we will be installing from the running ISO system instead of a giant
 # tarball, for each spell we only need to make sure that the cache file is
 # available. This will require that the ISO sorcery has caching enabled. The
 # caching should really be turned on from the very beginning though...
 [[ "$ARCHIVE" == "off" ]] && return $CERR_ARCHIVE
 cauldron_chroot_init
 for spell in $TARGET_SPELLS
 do
 # Cheap cop-out to get the cache generated - cast the spell to generate the
 # cache, and then dispel it from the system so that it isn't wasting space
 # on the ISO filesystem (any spells cast here should be those not required
 # for the functioning of the ISO itself, only to be installed to the target
 # system).
 ${CAULDRON_CHROOT} ${CAULDRON_CAST} $spell
 ${CAULDRON_CHROOT} ${CAULDRON_DISPEL} $spell
 done
 cauldron_chroot_done
 return $CERR_OK
}
================================================================================

In the comment block preceding the function definition, the parameters are
defined according to the bashdoc specification, and following that is clear
text which explains the purpose of the function and what the parameters will be
used for. The function definition is preceded by the "function" keyword so that
bashdoc can properly identify the function definition. The function name is
prefixed by "cauldron_" since this is a cauldron function (incidentally, this
function is defined in libcauldron). Local variable copies of the API-named
parameters are made as shorthand notations for the full API names.

** Though it is not required, all contributing developers are strongly urged to
document functions internally as well, as shown in the example.