#----------------------------------------
##
## @Synopsis Defines the Spell-Sorcery Interface
## @Copyright Copyright (C) 2004 The Source Mage Team <http://www.sourcemage.org>
## This library contains all sorcery functions which a spell may use.
## If the function isn't listed here, it may disapear without warning.
## If you use a funtion which isn't listed here, you'd better have a good reason.
## Better yet, raise a bug on the topic and the needed function will probably get
## added.
## @NOTE This library must not contain any logic. It is simply a set of wrapper functions.
##
#---------------------------------------------------------------------

#---------------------------------------------------------------------
## @NOTE The following list and the function definition should be in
## @NOTE alphabetical order. If this is not the case, please file a bug
#---------------------------------------------------------------------

#---------------------------------------------------------------------
# functions defined in here: (in alphabetical order)
#    acquire_src                    (libsummon)
#    config_query                   (libmisc)
#    config_query_list              (libmisc)
#    config_query_option            (libmisc)
#    config_query_string            (libmisc)
#    conflicts                      (libgrimoire)
#    default_sorcery_build          (build_api/...)
#    default_sorcery_download       (libsummon)
#    default_sorcery_install        (build_api/api2)   (BUILD_API==2 only)
#    default_sorcery_install_extras (build_api/api2)   (BUILD_API==2 only)
#    default_sorcery_post_build     (build_api/api1)   (BUILD_API==1 only)
#    default_sorcery_post_install   (build_api/api2)   (BUILD_API==2 only)
#    default_sorcery_transfer       (build_api/api2)   (BUILD_API==2 only)
#    default_sorcery_pre_build      (build_api/common)
#    default_sorcery_pre_install    (build_api/api2)   (BUILD_API==2 only)
#    depends                        (libdepends)
#    devoke_installwatch            (libtrack)
#    download_src                   (libsummon)
#    force_depends                  (libdepends)
#    gather_docs                    (build_api/common)
#    get_spell_provider             (libstate)
#    get_source_nums                (libmisc)
#    guess_compressor               (libunpack)
#    handle_changed_config          (libresurrect)
#    is_depends_enabled             (libstate)
#    installed_version              (libgrimoire)
#    install_config_file            (libresurrect)
#    invoke_installwatch            (libtrack)
#    list_add                       (libmisc)
#    list_find                      (libmisc)
#    list_remove                    (libmisc)
#    message                        (libmisc)
#    mk_source_dir                  (libgrimoire)
#    note_config_file               (libtrack)
#    on_cast                        (libtriggers)
#    on_dispel                      (libtriggers)
#    on_pre_cast                    (libtriggers)
#    on_pre_dispel                  (libtriggers)
#    optional_depends               (libdepends)
#    persistent_add                 (libmisc)
#    persistent_clear               (libmisc)
#    persistent_load                (libmisc)
#    persistent_remove              (libmisc)
#    persistent_save                (libmisc)
#    prepare_install                (libgrimoire)
#    provider_ok                    (libstate)
#    query                          (libmisc)
#    query_string                   (libmisc)
#    runtime_depends                (libdepends)
#    rm_source_dir                  (libgrimoire)
#    sedit                          (libmisc)
#    sub_depends                    (libdepends)
#    show_up_depends                (libdepends)
#    spell_exiled                   (libstate)
#    spell_held                     (libstate)
#    spell_installed                (libstate)
#    spell_ok                       (libstate)
#    suggest_depends                (libdepends)
#    track_manual                   (libtrack)
#    uncompress                     (libunpack)
#    unpack_file                    (libunpack)
#    unpack_file_simple             (libunpack)
#    using_gcc                      (libgcc2)
#    verify_file                    (libunpack)
#
# The following are implicitly defined for each spell file
# (filename is first lowercased):
# default_<filename>
# default_section_<filename>
# default_grimoire_<filename>
# default_sorcery_<filename>
#
# It is supported to have a file at the spell, section, or grimoire level,
# the more specific one overrides the less specific.
# Depending on context default_<filename> calls one of the default
# section, grimoire or sorcery functions. Calling it will always run the
# next level up.
#
# The default_section_<filename> and default_grimoire_<filename> functions
# first check for the filename (capitalized) in the section or grimoire.
# If it doesn't exist, default_<filename> is called (which runs the next
# step up).
#
# If the default_sorcery_<filename> function is not defined here, it is
# simply "true".
#
# Read-only variable that might be of use to a spell:
# SOURCE_CACHE, OPTS, BUILD HOST, INSTALL_ROOT
#
# The following can be modifies in BUILD, but nowhere else:
# CFLAGS, CXXFLAGS, CPPFLAGS, CC and LDFLAGS
#
# The following are set when a spell is loaded, you may use them, but
# not change them:
# SCRIPT_DIRECTORY SECTION_DIRECTORY GRIMOIRE SPELL_DIRECTORY SECTION
#
# global sorcery variables you should never use in a spell:
#
# (do not modify or read any of these for any reason, if you feel you
#  must look at one of them, talk to your local sorcery lead about getting
#  some sort of accessor functionality)
#
# TOP_LEVEL DISPLAY PATH TMP_DIR SAFE_CAST
# FAILED_LIST SUCCESS_LIST SPELL SPELLS spells MAKEFILE DEPS_ONLY
# CAST_PASS download_log IW_LOG SOLO QUIET INSTALL_QUEUE
# OVERRIDE_CFLAGS OVERRIDE_CXXFLAGS OVERRIDE_LDFLAGS NO_OPTIMIZATION_FLAGS
# DOT_PROGRESS VOYEUR_OVERRIDE RECONFIGURE RECAST_DOWN COMPILE RECAST_UP
# FORCE_DOWNLOAD SILENT FIX DEBUG SEPARATE
# CAST_HASH BACK_CAST_HASH CANNOT_CAST_HASH uncommitted_hash NEW_DEPENDS
# spell_depends DEPENDS_CONFIG UP_DEPENDS SPELL_CONFIG GRIMOIRE_DIR
# BUILD_API VOYEUR_STDOUT VOYEUR_STDERR C_LOG C_FIFO INST_LOG MD5_LOG
# INSTALLWATCHFILE INSTW_LOGFILE CAST_EXIT_STATUS
#
#---------------------------------------------------------------------


#---------------------------------------------------------------------
## @Type API
## @params Number portion of SOURCE[[:digit:]], eg '', "2", "3", etc.
## @See <@function var.lib.sorcery.modules.libsummon.html,real_acquire_src> for more details.
##
## Get a particular source, check first in $SOURCE_CACHE and respect
## FORCE_DOWNLOAD. Calls download_src if the file must be downloaded.
##
#---------------------------------------------------------------------
function acquire_src() {
    debug "libapi" "$FUNCNAME - $*"
    real_acquire_src "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_config_query> for more details.
## @param config file variable
## @param question
## @param default answer
##
## @return 0 in all cases
##
## Asks user for string, with default answer and timeout (like query)
## Return variable is also marked as persistent
## <pre>
## Example:
##    config_query DETAILED "Detailed questions ?" n; then
##    if [ $DETAILED == y ]; then
##        ....
##    fi
##    echo The reply for last question was: $DETAILED
## </pre>
##
#---------------------------------------------------------------------
function config_query () {
    debug "libapi" "config_query - $*"
    real_config_query "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_config_query_list> for more details.
## @param config file variable, return variable
## @param question
## @param elements, ...
##
## @return 0 in all cases
##
## Asks user for string, with numbered possibilities listed
## Return variable is also marked as persistent
## <pre>
## Example:
##    config_query_list COLOR "What color ?" "red" "white" "blue"
##    echo Your color is $COLOR
## </pre>
##
#---------------------------------------------------------------------
function config_query_list () {
    debug "libapi" "config_query_list - $*"
    real_config_query_list "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_config_query_option> for more details.
## @param config file variable
## @param question
## @param default answer [y|n]
## @param option_yes - can't be empty string
## @param option_no - can't be empty string
##
## @return 0 in all cases
##
## Asks user for string, with default answer and timeout (like query)
## The string is added to the variable
## If you want to use empty string, place there dummy string and remove
## it later by list_remove function. Also for one config variable, all
## option_yes and option_no have to be different.
## Return variable is also marked as persistent

## <pre>
## Example 1:
##    config_query_option OPT "Use X ?" y "--with-x" "--without-x"
##    config_query_option OPT "Use jpeg ?" y "--with-jpeg" "--do-not-use-jpeg"
##    echo All selected options together: $OPT
##
## Example 2:
## CONFIGURE:
## config_query_option ASK "Use X11 ?" y --with-x11 EMPTY1
## config_query_option ASK "Use Alsa ?" y --with-alsa EMPTY2
##
## BUILD:
## local TEMP="$ASK"
## list_remove TEMP EMPTY1 EMPTY2
## ./configure $TEMP
## ...
## </pre>
##
#---------------------------------------------------------------------
function config_query_option () {
    debug "libapi" "config_query_option - $*"
    real_config_query_option "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_config_query_string> for more details.
## @param config file variable, return variable
## @param question
## @param default answer
##
## @return 0 in all cases
##
## Asks user for string, with default answer and timeout (like query)
## Return variable is also marked as persistent
## <pre>
## Example:
##    config_query_string REAL_NAME "What is your real name ?" "nobody"
##    echo Hi $REAL_NAME
## </pre>
##
#---------------------------------------------------------------------
function config_query_string () {
    debug "libapi" "config_query_string - $*"
    real_config_query_string "$@"
}


#---------------------------------------------------------------------
## @param spell
## @param default answer to dispel query
## @Type API
## @See <@function var.lib.sorcery.modules.libdepends.html,real_conflicts> for more details.
## If the default answer is anything other than 'y' then 'n' is assumed.
## returns the given spellname if it is installed
#---------------------------------------------------------------------
function conflicts () {
    debug "libapi" "conflicts - $*"
    real_conflicts "$@"
}


#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_build> for more details.
## Used if no BUILD script is found for a spell
## Default build for BUILD_API==1 is:
## <pre>
##  ./configure  --build=$BUILD        \
##               --prefix=/usr         \
##               --sysconfdir=/etc     \
##               --localstatedir=/var  \
##               $OPTS                 &&
##  make                               &&
##  prepare_install                    &&
##  make    install
## </pre>
## Default build for BUILD_API==2 is:
## <pre>
##  ./configure  --build=$BUILD        \
##               --prefix=/usr         \
##               --sysconfdir=/etc     \
##               --localstatedir=/var  \
##               $OPTS                 &&
##  make
## </pre>
##
#---------------------------------------------------------------------
function default_sorcery_build () {
    debug "libapi" "default_sorcery_build - $*"
    real_default_sorcery_build "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libsummon.html,real_default_sorcery_download> for more details.
##
## Default download code, downloads each SOURCE[[:digit:]]*
##
#---------------------------------------------------------------------
function default_sorcery_download() {
    debug "libapi" "$FUNCNAME - $*"
    real_default_sorcery_download "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_install> for more details.
## Only defined for BUILD_API==2
## Used if no INSTALL script is found.
## Default install is:
## <pre>
##  make    install
## </pre>
##
#---------------------------------------------------------------------
function default_sorcery_install () {
    debug "libapi" "default_sorcery_install - $*"
    real_default_sorcery_install "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_install_extras> for more details.
## Only defined for BUILD_API==2
## Installs configuration files and documentation.
#---------------------------------------------------------------------
function default_sorcery_install_extras () {
    debug "libapi" "default_sorcery_install_extras - $*"
    real_default_sorcery_install_extras "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_post_build> for more details.
## Only defined for BUILD_API==1
## Installs configuration files and documentation.  Stops installwatch.
## Used if no POST_BUILD script is found for a spell.
## equivalent to default_sorcery_post_install in BUILD_API==2
##
#---------------------------------------------------------------------
function default_sorcery_post_build () {
    debug "libapi" "default_sorcery_post_build - $*"
    real_default_sorcery_post_build "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_post_install> for more details.
## Only defined for BUILD_API==2
## Puts the spell at the root of the stage root so manipulation of the
## installed files can happen
#---------------------------------------------------------------------
function default_sorcery_post_install () {
    debug "libapi" "default_sorcery_post_install - $*"
    real_default_sorcery_post_install "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_transfer> for more details.
## Only defined for BUILD_API==2
## Transfers the files from the stage area to the system. Default is
## transfer_staged_spell
#---------------------------------------------------------------------
function default_sorcery_transfer () {
    debug "libapi" "default_sorcery_transfer - $*"
    real_default_sorcery_transfer "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_pre_build> for more details.
## Creates the source directory and unpacks the source package into it.
## Used if no PRE_BUILD script is found for a spell.
#---------------------------------------------------------------------
function default_sorcery_pre_build () {
    debug "libapi" "default_sorcery_pre_build - $*"
    real_default_sorcery_pre_build "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_sorcery_pre_install> for more details.
## Only defined for BUILD_API==2
## Used if no PRE_INSTALL script is found.
## Default pre_install is:
## <pre>
##  prepare_install
## </pre>
##
#---------------------------------------------------------------------
function default_sorcery_pre_install () {
    debug "libapi" "default_sorcery_pre_install - $*"
    real_default_sorcery_pre_install "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell/service
## @param enabled options (optional)
## @param description (optional)
## @param grimoires (optional)
## @See <@function var.lib.sorcery.modules.libdepends.html,real_depends> for more details.
## Denotes that a spell requires another spell to work.
#---------------------------------------------------------------------
function depends () {
    debug "libapi" "depends - $*"
    real_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtrack.html,real_devoke_installwatch> for more details.
## Stops using installwatch
#---------------------------------------------------------------------
function devoke_installwatch () {
    debug "libapi" "devoke_installwatch - $*"
    real_devoke_installwatch "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtrack.html,real_devoke_stage_root> for more details.
## Stops using stage root
#---------------------------------------------------------------------
function devoke_stage_root () {
    debug "libapi" "devoke_stage_root - $*"
    real_devoke_stage_root "$@"
}

#---------------------------------------------------------------------
## @Type API
## @params Number portion of SOURCE[[:digit:]], eg '', "2", "3", etc.
## @See <@function var.lib.sorcery.modules.libsummon.html,real_download_src> for more details.
##
## Download a file. If the source is a file tree (eg from cvs or svn)
## then if there is an existing tarball, it will be unpacked, updated and
## repackaged as a tar.bz2. If the source is a simple file it will be
## downloaded as usual.
##
#---------------------------------------------------------------------
function download_src() {
    debug "libapi" "$FUNCNAME - $*"
    real_download_src "$@"
}
#---------------------------------------------------------------------
## @Type API
## @param spell to force depends on
## Causes a dependent spell to be recast when it might not otherwise be.
## This is intended to be called on an already enabled dependency. It can
## be thought of as an inverse of up_trigger (although it is *not* a
## trigger).
## <pre>
## Example 1:
##    depends foo &&
##    force_depends foo
## Example 2:
##    optional_depends foo --enable-foo --disable-foo "for foo support" &&
##    if is_depends_enabled $SPELL foo; then
##      force_depends foo
##    fi
## </pre>
#---------------------------------------------------------------------
function force_depends() {
    debug "libapi" "$FUNCNAME - $*"
    real_force_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.build_api.common.html,real_gather_docs> for more details.
## Gathers all documentation files from source archive and installs
## them as part of the spell
#---------------------------------------------------------------------
function gather_docs() {
    debug "libapi" "gather_docs - $*"
    real_gather_docs "$@"
}

#---------------------------------------------------------------------
## @Type API
## @params String to prefix on the results.
## @See <@function var.lib.sorcery.modules.libmisc.html,real_get_source_nums> for more details.
##
## Output a list of source numbers associated with the current spell.
## This is the number portion of SOURCE[[:digit:]], eg '', "2", "3", etc.
## A prefix may be given and it will be prepended to each result value.
##
#---------------------------------------------------------------------
function get_source_nums() {
    debug "libapi" "$FUNCNAME - $*"
    real_get_source_nums "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param Spell name
## @param Provider name
## @param If empty get the uncommited spell info, if anything else get
## info from the committed ($DEPENDS_STATUS) database. If the uncommited
## db doesnt exist (maybe we're not casting) use DEPENDS_STATUS instead.
##
## @See <@function var.lib.sorcery.modules.libstate.html,real_get_spell_provider,> for more details.
##
## @return 0 if a provider could be found 1 if not
## @stdout the provider name(s)
#---------------------------------------------------------------------
function get_spell_provider() {
    debug "libapi" "get_spell_provider - $*"
    real_get_spell_provider "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param filename
## @Stdout compressor
## @See <@function var.lib.sorcery.modules.libunpack.html,real_guess_compressor> for more details.
##
## Guesses what program was used to compress a file
## Return value is always success due to `file' workings
##
#---------------------------------------------------------------------
function guess_compressor () {
    debug "libapi" "guess_compressor - $*"
    real_guess_compressor "$@"
}

#------------------------------------------------------------------------
## @Type API
## @param from          File we might want to install
## @param to            File to replace
## @param savetime      Backup time if necessary
##
## @See <@function var.lib.sorcery.modules.libresurrect.html,real_handle_changed_config> for more details.
##
## Present the user with the following menu
## (0) trash $to and install over it
## (1) backup $to to $to.$savetime, install the new file in its place
## (2) leave $to in its place, copy the new file to $to.$savetime
## (3) do nothing
## (4) see a diff between $to and the new file
## choice 2 is currently the default, someday there will be a menu to
## choose what the default will be
#------------------------------------------------------------------------
function handle_changed_config() {
    debug "libapi" "handle_changed_config - $*"
    real_handle_changed_config "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell
## @param dependency
## @See <@function var.lib.sorcery.modules.libstate.html,is_depends_enabled> for more details.
## Returns whether or not a given dependency is enabled
##
#---------------------------------------------------------------------
function is_depends_enabled() {
    debug "libapi" "is_depends_enabled - $*"
    real_is_depends_enabled "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_install_version> for more details.
## Returns the current version of the given spell
##
#---------------------------------------------------------------------
function installed_version () {
    debug "libapi" "installed_version - $*"
    real_installed_version "$@"
}

#------------------------------------------------------------------------
## @Type API
## @param from          File we might want to install
## @param to            File to replace
## @param savetime      Backup time if necessary (optional, defaults to
##                      $(date +'%Y%m%d%H%M')
## @See <@function var.lib.sorcery.modules.libresurrect.html,real_install_config_file> for more details.
## Returns the current version of the given spell
#------------------------------------------------------------------------
function install_config_file() {
    debug "libapi" "install_config_file - $*"
    real_install_config_file "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtrack.html,real_invoke_installwatch> for more details.
## Starts using installwatch
#---------------------------------------------------------------------
function invoke_installwatch () {
    debug "libapi" "invoke_installwatch - $*"
    real_invoke_installwatch "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtrack.html,real_invoke_stage_root> for more details.
## Starts using stage root
#---------------------------------------------------------------------
function invoke_stage_root () {
    debug "libapi" "invoke_stage_root - $*"
    real_invoke_stage_root "$@"
}

#---------------------------------------------------------------------
## @param return_var
## @param elements, ...
## @See <@function var.lib.sorcery.modules.libmisc.html,real_list_remove> for more details.
##
## Removes from the list string(s). Strings are kept to be unique and
## are separated by spaces
## <pre>
## Example:
##    MY_LIST="--disable-static --enable-dynamic"
##    list_remove MY_LIST "--enable-dynamic"
## </pre>
##
#---------------------------------------------------------------------
function list_remove () {
    debug "libapi" "list_remove - $*"
    real_list_remove "$@"
}

#---------------------------------------------------------------------
## @param return_var
## @param elements, ...
## @See <@function var.lib.sorcery.modules.libmisc.html,real_list_add> for more details.
##
## Puts in the list string(s). Strings are kept to be unique and are
## separated by spaces
## <pre>
## Example:
##    list_add MY_LIST "--with-x"
##    list_add MY_LIST "--with-jpeg" $OTHER_OPTS
##    echo $MY_LIST
## </pre>
##
#---------------------------------------------------------------------
function list_add () {
    debug "libapi" "list_add - $*"
    real_list_add "$@"
}

#---------------------------------------------------------------------
## @param string
## @param elements, ...
## @See <@function var.lib.sorcery.modules.libmisc.html,real_list_find> for more details.
##
## return 0 at least one element is in list
## return 1 none of supplied elements is not in list
##
## Finds if at least one of the given elements is in the string. They
## can be delimited by spaces, tabs or newlines. The search elements
## must not contain any of these or they won't match. The matching is
## exact, regular expressions and globbing patterns are not supported.
##
## Warning, this function takes a real string, not a variable name as
## other list_* functions.
## <pre>
## Example:
##    if list_find "$MY_LIST" "--with-x"; then
##        ... we have to compile X components in
##    fi
## </pre>
##
#---------------------------------------------------------------------
function list_find () {
    debug "libapi" "list_find - $*"
    real_list_find "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param message to echo
## @Stdout message
## @See <@function var.lib.sorcery.modules.libmisc.html,real_message> for more details.
## echo's the given arguments if SILENT is not set.
##
#---------------------------------------------------------------------
function message () {
    debug "libapi" "message - $*"
    real_message "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param directory name
## @param [size]
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_mk_source_dir> for more details.
## Creates a tmpfs filesystem.  By default, the size is 1GB.
## The caller may optionally supply a size argument.
## <pre>
## Example1:  Create a 2GB mount at $SOURCE_DIRECTORY
##
##    mk_source_dir  $SOURCE_DIRECTORY  2g
##
## Example2:  Create a mount at /tmp/newdir, defaults to 1GB size
##
##    mk_source_dir  /tmp/newdir
## </pre>
#---------------------------------------------------------------------
function mk_source_dir () {
    debug "libapi" "mk_source_dir - $*"
    real_mk_source_dir "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtrack.html,real_note_config_file> for more details.
## @param spell file to check for modification
##
#---------------------------------------------------------------------
function note_config_file() {
    debug "libapi" "note_config_file - $*"
    real_note_config_file "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtriggers.html,real_on_cast> for more details.
## @param spell that triggers
## @param action
##
## Used by spells to make adding triggerse nice.
##
#---------------------------------------------------------------------
function on_cast () {
    debug "libapi" "on_cast - $*"
    real_on_cast "$@"
}



#---------------------------------------------------------------------
## @Type API
## @param spell that triggers
## @param action
## @See <@function var.lib.sorcery.modules.libtriggers.html,real_on_dispel> for more details.
##
## Used by spells to make adding triggers nice.
##
#---------------------------------------------------------------------
function on_dispel () {
    debug "libapi" "on_dispel - $*"
    real_on_dispel "$@"
}


#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libtriggers.html,real_on_pre_cast> for more details.
## @param spell that triggers
## @param action
##
## Used by spells to make adding triggerse nice.
##
#---------------------------------------------------------------------
function on_pre_cast () {
    debug "libapi" "on_pre_cast - $*"
    real_on_pre_cast "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell that triggers
## @param action
## @See <@function var.lib.sorcery.modules.libtriggers.html,real_on_pre_dispel> for more details.
##
## Used by spells to make adding triggerse nice.
##
#---------------------------------------------------------------------
function on_pre_dispel () {
    debug "libapi" "on_pre_dispel - $*"
    real_on_pre_dispel "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell/service
## @param enabled options (optional)
## @param disabled options (optional)
## @param description (optional)
## @param grimoires (optional)
## @See <@function var.lib.sorcery.modules.libdepends.html,real_optional_depends> for more details.
## Denotes that a spell can use another spell for additional functionality.
#---------------------------------------------------------------------
function optional_depends () {
    debug "libapi" "optional_depends - $*"
    real_optional_depends "$@"
}

#---------------------------------------------------------------------
## @param variables, ...
## @See <@function var.lib.sorcery.modules.libmisc.html,real_persistent_add> for more details.
##
## Adds variable names to the list of persistent variables
## <pre>
## Example:
##    persistent_add MY_VARIABLE
## </pre>
##
#---------------------------------------------------------------------
function persistent_add () {
    debug "libapi" "persistent_add - $*"
    real_persistent_add "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_persistent_clear> for more details.
## Unsets all persistent variables. Mainly usable as replacement of
## persistent_save for functions which can be called by nonroot users
## ( for example from 'gaze what' )
## <pre>
## Example:
##    persistent_clear
## </pre>
##
#---------------------------------------------------------------------
function persistent_clear () {
    debug "libapi" "persistent_clear - $*"
    real_persistent_clear "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_persistent_load> for more details.
## Loads persistent variables stored in file "$SPELL_CONFIG"
## <pre>
## Example:
##    persistent_load
## </pre>
##
#---------------------------------------------------------------------
function persistent_load () {
    debug "libapi" "persistent_load - $*"
    real_persistent_load "$@"
}

#---------------------------------------------------------------------
## @param variables, ...
## @See <@function var.lib.sorcery.modules.libmisc.html,real_persistent_remove> for more details.
##
## Removes variable names from the list of persistent variables
## <pre>
## Example:
##    persistent_remove MY_VARIABLE
## </pre>
##
#---------------------------------------------------------------------
function persistent_remove () {
    debug "libapi" "persistent_remove - $*"
    real_persistent_remove "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_persistent_save> for more details.
## Saves variables marked as persistent to file "$SPELL_CONFIG". The
## File is completely overwritten. Also unsets all persistent
## variables
## <pre>
## Example:
##    persistent_save
## </pre>
##
#---------------------------------------------------------------------
function persistent_save () {
    debug "libapi" "persistent_save - $*"
    real_persistent_save "$@"
}

#---------------------------------------------------------------------
## @param spell
## @param variable to read
## @param upvar
##
## finds the persistent var for a spell and sets the upvar to the value of the
## variable to read
## returns:
##          1 if the var doesn't exist in the file
##          2 if the tablet dir doesn't exist
##          3 if the persistent config file doesn't exist
##          4 if the EXPORTS file doesn't exist
##
#---------------------------------------------------------------------
function persistent_read () {
    debug "libapi" "persistent_read - $*"
    real_persistent_read "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_prepare_install> for more details.
## Prepares to install the spell.  Writes the boost lock file.  If the
## spell is installed already, the libraries are saved with
## save_libraries(), the binaries with save_binaries() and the spell is
## dispelled.  Usually called from the BUILD script of a spell.
##
#---------------------------------------------------------------------
function prepare_install () {
    debug "libapi" "prepare_install - $*"
    real_prepare_install "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param Provider name
## @See <@function var.lib.sorcery.modules.libstate.html,real_provider_ok> for more details.
##
## @return 0 if any provider of $1 is installed
#---------------------------------------------------------------------
function provider_ok() {
    debug "libapi" "provider_ok - $*"
    real_provider_ok "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param  [directory to remove]
## @Globals SOURCE_DIRECTORY
## Removes the given directory or SOURCE_DIRECTORY if no argument is
## given.
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_rm_source_dir> for more details.
##
#---------------------------------------------------------------------
function rm_source_dir() {
    debug "libapi" "rm_source_dir - $*"
    real_rm_source_dir "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libmisc.html,real_query> for more details.
## @param question
## @param default answer
##
## @return 0 on yes
## @return 1 on no
##
## Asks the user a yes/no question.  First argument is the question to
## ask, second argument is the default answer.  If a timeout occurs
## before the question is answered, the given default answer is
## applied.  Returns true or false based on the answer given.
##
#---------------------------------------------------------------------
function query () {
    debug "libapi" "query - $*"
    real_query "$@"
}

#---------------------------------------------------------------------
## @See <@function var.lib.sorcery.modules.libmisc.html,real_query_string> for more details.
## @param return_var
## @param question
## @param default answer
##
## @return 0 user supplied answer
## @return 1 default answer is used
##
## Asks user for string, with default answer and timeout (like query)
## <pre>
## Example:
##    query_string YOUR_HOST "What is your hostname ?" "localhost"
## </pre>
##
#---------------------------------------------------------------------
function query_string ()  {
    debug "libapi" "query_string  - $*"
    real_query_string "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell/service
## @param enabled options (optional)
## @param description (optional)
## @param grimoires (optional)
## @See <@function var.lib.sorcery.modules.libdepends.html,real_depends> for more details.
## Denotes that a spell requires another spell to work.
#---------------------------------------------------------------------
function runtime_depends () {
    debug "libapi" "runtime_depends - $*"
    real_runtime_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param sed command
## @param file
## @See <@function var.lib.sorcery.modules.libmisc.html,real_sedit> for more details.
##
## First argument is a sed command.  Second argument is a file.
## sedit performs the sed command on the file, modifiying the
## original file.  For example,
## <br>sedit "s/foo/bar/g" /tmp/somefile <br>
## will replace all occurances of foo with bar in /tmp/somefile.
## This function is often used in spells to make changes to source
## files before compiling.  See the sed man page for more information.
##
#---------------------------------------------------------------------
function sedit () {
    debug "libapi" "sedit - $*"
    real_sedit "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell name
## @param max depth
## @param fast (optional)
## @See <@function var.lib.sorcery.modules.libdepends.html,real_show_up_depends> for more details.
##
## @stdout recursively prints out the spell that depend on the specified spell
#---------------------------------------------------------------------
function show_up_depends() {
    debug "libapi" "spell_ok - $*"
    real_show_up_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell name
## @See <@function var.lib.sorcery.modules.libstate.html,real_spell_installed> for more details.
##
## @return 0 if the given spell's status is "installed"
#---------------------------------------------------------------------
function spell_installed () {
    debug "libapi" "spell_installed - $*"
    real_spell_installed "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell name
## @See <@function var.lib.sorcery.modules.libstate.html,real_spell_installed> for more details.
##
## @return 0 if the given spell's status is "held"
#---------------------------------------------------------------------
function spell_held() {
    debug "libapi" "spell_held - $*"
    real_spell_held "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell name
## @See <@function var.lib.sorcery.modules.libstate.html,real_spell_ok> for more details.
##
## @return 0 if the given spell's status is "installed" or "held"
#---------------------------------------------------------------------
function spell_ok() {
    debug "libapi" "spell_ok - $*"
    real_spell_ok "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell name
## @See <@function var.lib.sorcery.modules.libstate.html,real_spell_exiled> for more details.
##
## @return 0 if the given spell's status is "exiled"
#---------------------------------------------------------------------
function spell_exiled() {
    debug "libapi" "spell_ok - $*"
    real_spell_exiled "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell providing the sub-depends
## @param name of sub-depends
## @See <@function var.lib.sorcery.modules.libdepends
#---------------------------------------------------------------------
function sub_depends() {
    debug "libapi" "sub_depends - $*"
    real_sub_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param spell/service
## @param enabled options (optional)
## @param disabled options (optional)
## @param description (optional)
## @param grimoires (optional)
## @See <@function var.lib.sorcery.modules.libdepends.html,real_suggest_depends> for more details.
## Denotes that a spell can use another spell for additional functionality.
#---------------------------------------------------------------------
function suggest_depends () {
    debug "libapi" "suggest_depends - $*"
    real_suggest_depends "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param file to uncompress
## @See <@function var.lib.sorcery.modules.libunpack.html,real_uncompress> for more details.
##
## Given a file, uncompress runs the decompression program for that file,
## Note: zip is a special case because it doesn't work with streams.
##
#---------------------------------------------------------------------
function uncompress () {
    debug "libapi" "uncompress - $*"
    real_uncompress "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param SOURCE suffix
## @See <@function var.lib.sorcery.modules.libunpack.html,real_unpack_file> for more details.
##
## unpack_file takes the SOURCE suffix and figures out if it is supposed
## to hash or gpg check it -- then it does its dirty work and runs unpack_hash
## or unpack_gpg depending upon the circumstances.  That's the only argument it
## takes and needs: '' '2' '3', etc.  It is run in default_pre_build for the
## null argument only.  Custom unpacking still requires a custom PRE_BUILD.
##
## valid formats: vendor-provided gpg, guru-provided gpg, any
## hash-algorithm provided by gpg (currently md5, sha1, sha256, sha384,
## sha512, ripemd160
##
##           SOURCE=blah
##          SOURCE2=blah.asc
##       SOURCE_URL=http://blah.com/$SOURCE
##      SOURCE2_URL=http://blah.com/$SOURCE2
##       SOURCE_GPG=blah.gpg:$SOURCE2:UPSTREAM_KEY
##   SOURCE2_IGNORE=signature # for auditing purposes
##
##           SOURCE=blah
##       SOURCE_URL=http://blah.com/$SOURCE
##       SOURCE_GPG=swoolley.gpg:$SOURCE.asc:WORKS_FOR_ME
##
##           SOURCE=blah
##       SOURCE_URL=http://blah.com/$SOURCE
##           MD5[0]=d41d8cd98f00b204e9800998ecf8427e
##
##           SOURCE=blah
##       SOURCE_URL=http://blah.com/$SOURCE
##       SOURCE_HASH=md5:d41d8cd98f00b204e9800998ecf8427e:WORKS_FOR_ME
##
## In GPG mode:
##   Validates the verification level (the third parameter) and the
##   hash algorithm against user defined lists.
##   It finds the public key and signature using locate_spell_file,
##   Then it validates it at the beginning.
##   see unpack_gpg()
##
## In HASH mode:
##   Validates the verification level (the third parameter) and the
##   hash algorithm against user defined lists.
##   It uses gpg to calculate the hash value except for md5 and sha1, which
##   coreutils provides.
##   see unpack_hash()
##
## In IGNORE mode:
##   It checks for the following text:
##     volatile (for cvs/svn/any-other-scm)
##     unversioned (the source file changes frequently, but not a direct scm)
##     signature (for gnupg signatures)
##   as reasons for ignoring the source code validation.  Signatures
##   are silently ignored.  Everything else respects MD5SUM_DL.
##   see unpack_ignore
##
## Otherwise, it falls back to MISSING mode, see unpack_missing
##
## The default verification level is "WORKS_FOR_ME"
##
## Verification levels are, these indicate how much effort was put into
## validating the integrity of the source from the upstream vendor.
##   WORKS_FOR_ME No verification was done.
##   UPSTREAM_HASH Checked the upstream hash file
##   UPSTREAM_KEY Checked upstream (gpg) key, signature matched, but the
##                key was not validated
##   ESTABLISHED_UPSTREAM_KEY Upstream key was not validated against
##                            multiple independent sources, but has been
##                            in use for several years
##   VERIFIED_UPSTREAM_KEY Upstream key id was verified against multiple
##                         independent sources.
##   ID_CHECK_UPSTREAM_KEY Key was verified in person with a photo id check.
##
## Also if you want to include more than one signature, hash, etc, just put
## a 2, 3, 4, etc on the end of the variable like so:
##   SOURCE2_HASH2=...
##
## For cascading, currently it will still ask abort questions: a no abort
## will make it fail over all cascades; a yes abort will have it skip to
## the next cascades.  Missing binaries or other failures like that (error 200
## below) will silently fail over to the next check.  The cascade order is:
##  GPG, HASH, IGNORE, MISSING
##
## The cascade setup allows you to place a higher bit checksum earlier
## in the cascade and even if the binary doesn't work it will just print
## out an abort query which can be said no to and it will continue to
## fail over to the lower bit checksum that should be available in
## coreutils (like sha1/md5).  That's if you're not using gpg, which is
## preferred.  If multiple hashes are included of different ciphers, the
## user can abort on either that go bad, so it can be considered a
## security increase to have more than one, but only if the harder cipher
## is first in the cascade order, as the first successful hash match will
## go ahead and prompt an untarball.  It may change later, but for now we
## think the first successful match skipping the rest is least intrusive, and
## I'd need to add an interface element to let the user choose to run all
## checks on a single source.
##
#---------------------------------------------------------------------
function unpack_file () {
    debug "libapi" "unpack_file - $*"
    real_unpack_file "$@"
}

#---------------------------------------------------------------------
## @Type API
## @params Name of a file to unpack
## @See <@function var.lib.sorcery.modules.libunpack.html,real_unpack_file_simple> for more details.
##
## Interface to unpack a file without any verification.
##
#---------------------------------------------------------------------
function unpack_file_simple() {
    debug "libapi" "$FUNCNAME - $*"
    real_unpack_file_simple "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param SOURCE suffix
## @See <@function var.lib.sorcery.modules.libunpack.html,real_verify_file> for more details.
##
## verify_file takes the SOURCE suffix and verifies the file without
## unpacking it. It does not work with the old 'MD5[0]=...' style.
## Only with the "new" SOURCEn_(GPG|HASH|IGNORE) style.
##
#---------------------------------------------------------------------
function verify_file () {
    debug "libapi" "verify_file - $*"
    real_verify_file "$@"
}

#---------------------------------------------------------------------
## @param gcc version (digits and dots, followed by an optional +)
## @return 0 if the version of the installed gcc that will be used is equal
##             to the passed version
## @return 0 if the parameter is of the form "version+" and the version of the
##             installed gcc is at least "version"
## @return 1 otherwise
## @See <@function var.lib.sorcery.modules.libgcc.html,real_using_gcc> for more details.
##
## Checks if the system gcc version is equal to the passed version or
## when the version ends with a + marker, if it the system version is
## greater or equal to it.
## The gcc version is of the major.minor.patchlevel form, but trailing
## digits can be omitted and will default to 0 in the comparison.
##
## <pre>
## Example:
##    if using_gcc 4.3+; then # same as 4.3.0+
##      patch -p1 < $SPELL_DIRECTORY/gcc43-compilation-fixes.patch
##    elif using_gcc 4.0.0; then
##      # gcc 4.0.0 triggers a memleak when -O3 is used
##      CFLAGS=${CFLAGS/-O3/-O2}
##    fi
## </pre>
#---------------------------------------------------------------------
function using_gcc()  {
  debug "libapi" "$FUNCNAME - $*"
  real_using_gcc "$@"
}

#---------------------------------------------------------------------
## @Type API
## @param Target of the trigger
## @param Action to execute
## @See <@function var.lib.sorcery.modules.libdepends.html,real_up_triggers> for more details.
##
## Only allowed from UP_TRIGGERS file.
## Specify that the current spell should trigger the specifed action
## on the target spell. This is a shortcut for the TRIGGERS file in the
## target spell, this lets you specify lots of triggers easily.
##
#---------------------------------------------------------------------
function up_trigger() {
  debug "libapi" "$FUNCNAME - $*"
  real_up_trigger "$@"
}

#---------------------------------------------------------------------
## @Type API
## @params list of files to track manually
## @See <@function var.lib.sorcery.modules.libtrack.html,real_track_manual> for more details.
##
## Given a list of files it will notify installwatch of them.
## Useful for spells whose components are not dynamicly linked
## to glibc. Installwatch must be running for this to work.
#---------------------------------------------------------------------
function track_manual() {
    debug "libapi" "track_manual - $*"
    real_track_manual "$@"
}

#---------------------------------------------------------------------
## @License
##
## This software is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## This software is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this software; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
##
#---------------------------------------------------------------------
