#----------------------------------------
##
## @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
# 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_build          (build_api/...)   
#    default_download       (libsummon)
#    default_install        (build_api/api2)   (BUILD_API==2 only)
#    default_post_build     (build_api/api1)   (BUILD_API==1 only)
#    default_post_install   (build_api/api2)   (BUILD_API==2 only)
#    default_pre_build      (build_api/common)   
#    default_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)
#    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)   
#    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)
#    requires               (libdepends)
#    rm_source_dir          (libgrimoire)
#    sedit                  (libmisc)       
#    spell_exiled           (libstate)
#    spell_held             (libstate)
#    spell_installed        (libstate)
#    spell_ok               (libstate)
#    track_manual           (libtrack)
#    uncompress             (libunpack)
#    unpack                 (libunpack) (deprecated)
#    unpack_file            (libunpack)
#    unpack_file_simple     (libunpack)
#
# 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 BASE_URL 
# 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 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_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_build () {
    debug "libapi" "default_build - $*"
    real_default_build "$@"
}

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

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_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_install () {
    debug "libapi" "default_install - $*"
    real_default_install "$@"
}

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_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_post_install in BUILD_API==2
##
#---------------------------------------------------------------------
function default_post_build () {
    debug "libapi" "default_post_build - $*"
    real_default_post_build "$@"
}

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

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_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_pre_build () {
    debug "libapi" "default_pre_build - $*"
    real_default_pre_build "$@"
} 

#---------------------------------------------------------------------
## @Type API
## @See <@function var.lib.sorcery.modules.libgrimoire.html,real_default_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_pre_install () {
    debug "libapi" "default_pre_install - $*"
    real_default_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
## @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
## @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 "$@"
}

#---------------------------------------------------------------------
## @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 given elements is in the string. Warning,
## this function takes real string, not 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.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 "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() and the spell is dispelled.  Usually called from
## the BUILD sript 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 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
## @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 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 file to unpack 
## @param md5sum
## @See <@function var.lib.sorcery.modules.libunpack.html,real_unpack> for more details.
##
## Given a file, unpack runs the decompression program for that file,
## as well as untar'ing the file if appropriate and if the MD5
## matches.
## Note: zip is a special case because it doesn't work with streams.
##
#---------------------------------------------------------------------
function unpack () {
    debug "libapi" "unpack - $*"
    real_unpack "$@"
}

#---------------------------------------------------------------------
## @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 md5 or gpg/hash check it -- then it does its dirty work and runs
## unpack, unpack_gpg, or unpack_hash depending upon the circumstances.
##
#---------------------------------------------------------------------
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 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
##
#---------------------------------------------------------------------

