/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 
/* vim: set ts=2 et sw=2 tw=80: */
#if !defined(NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED)
#define NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED
/*
  Copyright (c) 2013 D. Richard Hipp

  This program is free software; you can redistribute it and/or
  modify it under the terms of the Simplified BSD License (also
  known as the "2-Clause License" or "FreeBSD License".)

  This program 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.

  Author contact information:
  drh@hwaci.com
  http://www.hwaci.com/drh/

  ******************************************************************************
  This file declares public APIs for working with fossil's persistent
  configuration settings.
*/

#include "fossil-core.h" /* MUST come first b/c of config macros */

#if defined(__cplusplus)
extern "C" {
#endif

/**
   A flag type for specifying which configuration database a given
   API should be applied to. Used by fsl_config_get_int32() and
   friends.
*/
enum fsl_confdb_t {
/**
   Signfies the global-level (per system user) configuration area.
*/
FSL_CONFDB_GLOBAL = 1,
/**
   Signfies the repository-level configuration area.
*/
FSL_CONFDB_REPO = 2,
/**
   Signfies the checkout-level (a.k.a. "local") configuration area.
*/
FSL_CONFDB_CKOUT = 3,
/**
   Signifies the versioned-level (via ".fossil-settings") configuration area.
*/
FSL_CONFDB_VERSIONED = 4,
/**
   Signifies the default-level (and other settings metadata) configuration area.
   This are is read-only, and only contains the publicly documented settings.
*/
FSL_CONFDB_METADATA = 5
};
typedef enum fsl_confdb_t fsl_confdb_t;

/**
   Returns the name of the db table associated with the given
   mode. Results are undefined if mode is an invalid value. The
   returned bytes are static and constant.
*/
FSL_EXPORT char const * fsl_config_table_for_role(fsl_confdb_t mode);

/**
   Returns a handle to the db associates with the given fsl_confdb_t
   value. Returns NULL if !f or if f has no db opened for that
   configuration role. Results are undefined if mode is an invalid
   value.
*/
FSL_EXPORT fsl_db * fsl_config_for_role(fsl_cx * f, fsl_confdb_t mode);

/**
   Returns the int32 value of a property from one of f's config
   dbs, as specified by the mode parameter. Returns dflt if !f, f
   does not have the requested config db opened, no entry is found,
   or on db-level errors.
*/
FSL_EXPORT fsl_int32_t fsl_config_get_int32( fsl_cx * f, fsl_confdb_t mode,
                                  fsl_int32_t dflt, char const * key );
/**
   int64_t counterpart of fsl_config_get_int32().
*/
FSL_EXPORT fsl_int64_t fsl_config_get_int64( fsl_cx * f, fsl_confdb_t mode,
                                  fsl_int64_t dflt, char const * key );

/**
   fsl_id_t counterpart of fsl_config_get_int32().
*/
FSL_EXPORT fsl_id_t fsl_config_get_id( fsl_cx * f, fsl_confdb_t mode,
                            fsl_id_t dflt, char const * key );
/**
   fsl_double_t counterpart of fsl_config_get_int32().
*/
FSL_EXPORT fsl_double_t fsl_config_get_double( fsl_cx * f, fsl_confdb_t mode,
                                    fsl_double_t dflt, char const * key );


/**
   Boolean countertpart of fsl_config_get_int32().

   fsl_str_bool() is used to determine the booleanness (booleanity?)
   of a given config option.
*/
FSL_EXPORT char fsl_config_get_bool( fsl_cx * f, fsl_confdb_t mode,
                                     char dflt, char const * key );

/**
   The string-type counterpart of fsl_config_get_int32().

   Returns a copy of the configuration value if it finds one, else
   returns NULL.

   The returned memory must eventually be freed using
   fsl_free(). If len is not NULL then it is set to the length of
   the returned string. Returns NULL for any sort of error or for a
   NULL db value.
*/
FSL_EXPORT char * fsl_config_get_text( fsl_cx * f, fsl_confdb_t mode,
                            char const * key, fsl_size_t * len );

/**
   Like fsl_config_get_text() with one notable exception: regardless
   of the mode parameter if key refers to a versionable property
   and such a property is readable in the current checkout, the
   contents of that versioned property is returned (as per
   fsl_config_get_versionable()), otherwise this behaves exactly
   like fsl_config_get_text().
*/
FSL_EXPORT char * fsl_config_get_text2( fsl_cx * f, fsl_confdb_t mode,
                             char const * key, fsl_size_t * len );


/**
   fsl_buffer counterpart of fsl_config_get_text(). Appends the
   value from the config table to b. Returns 0 on success,
   FSL_RC_NOT_FOUND if no row was found or the requested db is not
   opened, FSL_RC_OOM on allocation errror.
*/
FSL_EXPORT int fsl_config_get_buffer( fsl_cx * f, fsl_confdb_t mode,
                           char const * key, fsl_buffer * b );

/**
   fsl_buffer counterpart of fsl_config_get_text2(). Appends the
   value from the config table to b. Returns 0 on success,
   FSL_RC_NOT_FOUND if no row was found or the requested db is not
   opened, FSL_RC_OOM on allocation errror.
*/
FSL_EXPORT int fsl_config_get_buffer2( fsl_cx * f, fsl_confdb_t mode,
                            char const * key, fsl_buffer * b );


/**
   Sets a configuration variable in one of f's config databases, as
   specified by the mode parameter. Returns 0 on success.  val may
   be NULL. Returns FSL_RC_MISUSE if !f, f does not have that
   database opened, or !key, FSL_RC_RANGE if !key.

   If val is NULL then an SQL NULL is bound instead of an empty
   string.
*/
FSL_EXPORT int fsl_config_set_text( fsl_cx * f, fsl_confdb_t mode, char const * key, char const * val );

/**
   The blob counterpart of fsl_config_set_text(). If len is
   negative then fsl_strlen(mem) is used to determine the length of
   the memory.

   If mem is NULL then an SQL NULL is bound instead of an empty
   blob.
*/
FSL_EXPORT int fsl_config_set_blob( fsl_cx * f, fsl_confdb_t mode, char const * key,
                         void const * mem, fsl_int_t len );
/**
   int32 counterpart of fsl_config_set_text().
*/
FSL_EXPORT int fsl_config_set_int32( fsl_cx * f, fsl_confdb_t mode,
                          char const * key, fsl_int32_t val );
/**
   int64 counterpart of fsl_config_set_text().
*/
FSL_EXPORT int fsl_config_set_int64( fsl_cx * f, fsl_confdb_t mode,
                          char const * key, fsl_int64_t val );
/**
   fsl_id_t counterpart of fsl_config_set_text().
*/
FSL_EXPORT int fsl_config_set_id( fsl_cx * f, fsl_confdb_t mode,
                       char const * key, fsl_id_t val );
/**
   fsl_double counterpart of fsl_config_set_text().
*/
FSL_EXPORT int fsl_config_set_double( fsl_cx * f, fsl_confdb_t mode,
                           char const * key, fsl_double_t val );
/**
   Boolean counterpart of fsl_config_set_text().

   See fsl_str_bool() for what string values are considered to be
   "true" vs "false".
*/
FSL_EXPORT int fsl_config_set_bool( fsl_cx * f, fsl_confdb_t mode,
                         char const * key, char val );

/**
   "Unsets" (removes) the given key from the given configuration database.
   It is not considered to be an error if the config table does not
   contain that key.
*/
FSL_EXPORT int fsl_config_unset( fsl_cx * f, fsl_confdb_t mode, char const * key );

/**
   Begins (or recurses) a transaction on the given configuration
   database.  Returns 0 on success, non-0 on error. On success,
   fsl_config_transaction_end() must eventually be called with the
   same parameters to pop the transaction stack. Returns
   FSL_RC_MISUSE if no db handle is opened for the given
   configuration mode. Assuming all arguments are valid, this
   returns the result of fsl_db_transaction_end() and propagates
   any db-side error into the f object's error state.

   This is primarily intended as an optimization when an app is
   making many changes to a config database. It is not needed when
   the app is only making one or two changes.

   @see fsl_config_transaction_end()
   @see fsl_db_transaction_begin()
*/
FSL_EXPORT int fsl_config_transaction_begin(fsl_cx * f, fsl_confdb_t mode);

/**
   Pops the transaction stack pushed by
   fsl_config_transaction_begin(). If rollback is true then the
   transaction is set roll back, otherwise it is allowed to
   continue (if recursive) or committed immediately (if not
   recursive).  Returns 0 on success, non-0 on error. Returns
   FSL_RC_MISUSE if no db handle is opened for the given
   configuration mode. Assuming all arguments are valid, this
   returns the result of fsl_db_transaction_end() and propagates
   any db-side error into the f object's error state.

   @see fsl_config_transaction_begin()
   @see fsl_db_transaction_end()
*/
FSL_EXPORT int fsl_config_transaction_end(fsl_cx * f, fsl_confdb_t mode, char rollback);

/**
   Holds metadata for fossil-defined configuration settings.

   @see fsl_config_ctrl_get()
   @see fsl_config_has_versionable()
   @see fsl_config_get_versionable()
   @see fsl_config_key_is_valid()
   @see fsl_config_key_is_versionable()
   @see fsl_config_key_default_value()
*/  
struct fsl_config_ctrl {
  /** Name of the setting */
  char const *name;
  /**
     Historical (fossil(1)) internal variable name used by
     db_set(). Not currently used by this impl.
  */
  char const *var;
  /**
     Historical (HTML UI). Width of display.  0 for boolean values.
  */
  int width;
  /**
     Is this setting versionable?
  */
  int versionable;
  /**
     Default value
  */
  char const *def;
};
typedef struct fsl_config_ctrl fsl_config_ctrl;

/**
   If key is the name of a fossil-defined config key, this returns
   the fsl_config_ctrl value describing that configuration property,
   else it returns NULL.
*/
FSL_EXPORT fsl_config_ctrl const * fsl_config_ctrl_get(char const * key);

/**
   Returns true if key is the name of a config property
   as defined by fossil(1).
*/
FSL_EXPORT char fsl_config_key_is_valid(char const * key);


/**
   Returns true if key is the name of a versionable property,
   as defined by fossil(1).
*/
FSL_EXPORT char fsl_config_key_is_versionable(char const * key);

/**
   If key refers to a fossil-defined configuration setting, this
   returns its default value as a NUL-terminated string. Its bytes are
   static and immutable. Returns NULL if key is not a known
   configuration key.
*/
FSL_EXPORT char const * fsl_config_key_default_value(char const * key);

/**
   Tries to load a "versionable property" in a file named
   CKOUT/.fossil-settings/KEY, where CKOUT is the root directory of
   f's current checkout and key is the name of a versionable
   configuration setting.

   If it finds one and it can read the file's contents, it returns 0
   and assigns *pOut to the contents, which are owned by the caller,
   who must eventually fsl_free() them. As a special case, if an
   empty file is read, 0 is returned but *pOut will be NULL.

   On any sort of error, non-0 is returned. In the grand scheme of
   things, the inability to load a versionable setting is not truly
   any error, so f's error state is not updated by this function and
   clients are not expected to treat it as fatal unless perhaps it
   returns FSL_RC_OOM, in which case it likely is.

   Note that versionable properties are always treated as strings,
   and there is not (yet) a family of getter APIs for various value
   types as there is for the db-level configuration storage.

   Example usage:

   @code
   char const * rv = NULL;
   int rc = fsl_config_get_versionable(f, "ignore-glob", &rv);
   if(rc){
   // error. Just for example's sake:
   assert(!rv);
   }else{
   assert(rv);
   ...use rv...
   }
   @endcode

*/
FSL_EXPORT int fsl_config_get_versionable( fsl_cx * f, char const * key, char **pOut );

/**
   Returns true if f's current checkout contains the given
   versionable configuration setting, else false.

   @see fsl_config_ctrl
*/
FSL_EXPORT char fsl_config_has_versionable( fsl_cx * f, char const * key );

/**
   Populates li as a glob list from the given configuration key.
   Uses (versionable/repo/global) config settings, in that order.
   It is not an error if one or more of those sources is missing -
   they are simply skipped.

   Note that gets any new globs appended to it, as per
   fsl_glob_list_append(), as opposed to replacing any existing
   contents.

   Returns 0 on success, but that only means that there were no
   errors, not that any entries were necessarily added to li.

   Arguably a bug: this function does not open the global config if
   it was not already opened, but will use it if it is opened.  This
   function should arbuably open and close it in that case.
*/
FSL_EXPORT int fsl_config_globs_load(fsl_cx * f, fsl_list * li, char const * key);


#if defined(__cplusplus)
} /*extern "C"*/
#endif
#endif
/* NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED */