/***************************************************************************
 begin       : Tue Sep 09 2003
 copyright   : (C) 2003-2010 by Martin Preuss
 email       : martin@libchipcard.de

 ***************************************************************************
 *                                                                         *
 *   This library is free software; you can redistribute it and/or         *
 *   modify it under the terms of the GNU Lesser General Public            *
 *   License as published by the Free Software Foundation; either          *
 *   version 2.1 of the License, or (at your option) any later version.    *
 *                                                                         *
 *   This library 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     *
 *   Lesser General Public License for more details.                       *
 *                                                                         *
 *   You should have received a copy of the GNU Lesser General Public      *
 *   License along with this library; if not, write to the Free Software   *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 *                                                                         *
 ***************************************************************************/


#ifndef GWENHYWFAR_PATH_H
#define GWENHYWFAR_PATH_H

#include <gwenhywfar/gwenhywfarapi.h>
#include <gwenhywfar/types.h>
#include <gwenhywfar/buffer.h>


#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup MOD_PATH Paths
 * @ingroup MOD_PARSER
 *
 * @brief These functions work on general paths.
 *
 * A path consists of a list of elements separated by a slash, like in
 * <i>/element1/element2/element3</i>.
 * An element can either be a <i>group</i> or an <i>item</i>.
 * Groups can contain multiple items and groups, but an item can not contain
 * anything.
 * So there can at most be <strong>one</strong> item, and it must be the
 * last element.
 * An example of how to use these functions is given in the module
 * @ref MOD_DB. These functions can also be used with files and folders. In
 * this case a group corresponds to a folder and items correspond to files.
 */
/*@{*/

/**
 * @name Path Flags
 *
 * The path flags only use the lower word of the integer. The high word
 * may be used/interpreted by the called function.
 */
/*@{*/
/**
 * if this is set then all elements of the path must exist.
 */
#define GWEN_PATH_FLAGS_PATHMUSTEXIST          0x00000001
/**
 * if this is set then none of the elements of the path must exist.
 */
#define GWEN_PATH_FLAGS_PATHMUSTNOTEXIST       0x00000002

/**
 * if this bit is set then the whole path (at any depth!) will be created.
 * This may lead to double entries at any part of the path.
 * You need this in very rare cases, most likely you want
 * @ref GWEN_PATH_FLAGS_NAMEMUSTEXIST.
 */
#define GWEN_PATH_FLAGS_PATHCREATE             0x00000004

/**
 * if this bit is set then the last element of the path MUST exist.
 * This implies @ref GWEN_PATH_FLAGS_PATHMUSTEXIST
 */
#define GWEN_PATH_FLAGS_NAMEMUSTEXIST          0x00000008

/**
 * if this bit is set then the last element of the path MUST NOT exist.
 */
#define GWEN_PATH_FLAGS_NAMEMUSTNOTEXIST       0x00000010

/**
 * if this bit is set then the last element of the path is created in any
 * case (this is for groups).
 * This may lead to double entries of the last element.
 */
#define GWEN_PATH_FLAGS_CREATE_GROUP            0x00000020

/**
 * if this bit is set then the last element of the path is created in any
 * case (this is for variables).
 * This may lead to double entries of the last element.
 */
#define GWEN_PATH_FLAGS_CREATE_VAR              0x00000040

/**
 * a variable is wanted (if this bit is 0 then a group is wanted).
 * This flag is used internally, too. When the path handler function
 * is called by @ref GWEN_Path_Handle then this flag is modified
 * to reflect the type of the current path element.
 */
#define GWEN_PATH_FLAGS_VARIABLE                0x00000080


/**
 * all elements of the path are to be escaped.
 * This is usefull when used with file names etc. It makes sure that the
 * path elements presented to the path element handler function only
 * consist of alphanumeric characters. All other characters are escaped
 * using @ref GWEN_Text_Escape.
 */
#define GWEN_PATH_FLAGS_ESCAPE                  0x00000100

/** use the same flag for both escape and unescape */
#define GWEN_PATH_FLAGS_UNESCAPE                0x00000100

/* be more tolerant, don't escape common characters such as '.' */
#define GWEN_PATH_FLAGS_TOLERANT_ESCAPE         0x00000200

/**
 * Allow to also escape/unescape the last path element (otherwise it will
 * not be escaped/unescaped).
 */
#define GWEN_PATH_FLAGS_CONVERT_LAST            0x00000400

/**
 * Allows checking for root. If the path begins with a slash ('/') and this
 * flags is set the slash will be included in the first path element
 * passed to the element handler function. Additionally the flag
 * @ref GWEN_PATH_FLAGS_ROOT will be set. Otherwise there will be no check
 * and special treatment of root entries.
 */
#define GWEN_PATH_FLAGS_CHECKROOT               0x00000800

/**
 * This flag is only used with @ref GWEN_Path_HandleWithIdx to disable
 * index handling.
 */
#define GWEN_PATH_FLAGS_NO_IDX                  0x00001000

/**
 *
 */
#define GWEN_PATH_FLAGS_RFU1                    0x00002000


/**
 * @internal
 */
#define GWEN_PATH_FLAGS_INTERNAL                0x0000c000

/**
 * @internal
 * this is flagged for the path function. If this is set then the
 * element given is the last one, otherwise it is not.
 */
#define GWEN_PATH_FLAGS_LAST                    0x00004000

/**
 * @internal
 * this is flagged for the path function. If this is set then the
 * element given is within root (in this case the element passed to the
 * element handler funcion will start with a slash), otherwise it is not.
 */
#define GWEN_PATH_FLAGS_ROOT                    0x00008000

/*@}*/



typedef void* (*GWEN_PATHHANDLERPTR)(const char *entry,
                                     void *data,
                                     uint32_t flags);

typedef void* (*GWEN_PATHIDXHANDLERPTR)(const char *entry,
                                        void *data,
                                        int idx,
                                        uint32_t flags);


/**
 * This function works on a path according to the given flags.
 * For every element the given function is called.
 * A path consists of multiple elements separated by a slash ("/"),
 * e.g. "first/second/element".
 * This function is used by the DB module but may also be used for any
 * type of path handling (like creating all directories along a given path).
 * This function simply calls the given function for any element as long as
 * that function returns a non-zero value or the path ends.
 * The type of the returned value completely depends on the function called.
 * @return 0 on error, !=0 otherwise
 */
GWENHYWFAR_API
void *GWEN_Path_Handle(const char *path,
                       void *data,
                       uint32_t flags,
                       GWEN_PATHHANDLERPTR elementFunction);

GWENHYWFAR_API
void *GWEN_Path_HandleWithIdx(const char *path,
                              void *data,
                              uint32_t flags,
                              GWEN_PATHIDXHANDLERPTR elementFunction);


/**
 * Converts the given path according to the given flags.
 * You can use this function to escape, unescape or simply store  all path
 * elements within a buffer. The converted path will simply be appended to
 * the given buffer (without any leading slash).
 */
GWENHYWFAR_API
int GWEN_Path_Convert(const char *path,
                      GWEN_BUFFER *buffer,
                      uint32_t flags);


/*@}*/ /* defgroup */


#ifdef __cplusplus
}
#endif


#endif /* GWENHYWFAR_PATH_H */

