tempest/resources/3rdparty/pantheios-1.0.1-beta214/include/shwild/shwild.h

/* /////////////////////////////////////////////////////////////////////////
 * File:    shwild/shwild.h
 *
 * Purpose: Root header file for the shwild library
 *
 * Created: 17th June 2005
 * Updated: 19th December 2011
 *
 * Home:    http://shwild.org/
 *
 * Copyright (c) 2005-2011, Matthew Wilson and Sean Kelly
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * - Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - Neither the names of Matthew Wilson and Sean Kelly nor the names of
 *   any contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


/** \file shwild/shwild.h [C/C++] This is the root file of the shwild C-API
 */

#ifndef SHWILD_INCL_SHWILD_H_SHWILD
#define SHWILD_INCL_SHWILD_H_SHWILD

/* /////////////////////////////////////////////////////////////////////////
 * Version information
 */

#ifndef SHWILD_DOCUMENTATION_SKIP_SECTION
# define SHWILD_VER_SHWILD_H_SHWILD_MAJOR       1
# define SHWILD_VER_SHWILD_H_SHWILD_MINOR       2
# define SHWILD_VER_SHWILD_H_SHWILD_REVISION    20
# define SHWILD_VER_SHWILD_H_SHWILD_EDIT        30
#endif /* !SHWILD_DOCUMENTATION_SKIP_SECTION */

/** \def SHWILD_VER_MAJOR
 * The major version number of shwild
 */

/** \def SHWILD_VER_MINOR
 * The minor version number of shwild
 */

/** \def SHWILD_VER_REVISION
 * The revision version number of shwild
 */

/** \def SHWILD_VER
 * The current composite version number of shwild
 */

#ifndef SHWILD_DOCUMENTATION_SKIP_SECTION
# define SHWILD_VER_0_9_1       0x00090100
# define SHWILD_VER_0_9_2       0x00090200
# define SHWILD_VER_0_9_3       0x00090300
# define SHWILD_VER_0_9_4       0x00090400
# define SHWILD_VER_0_9_5       0x00090500
# define SHWILD_VER_0_9_6       0x00090600
# define SHWILD_VER_0_9_7       0x00090700
# define SHWILD_VER_0_9_8       0x00090800
# define SHWILD_VER_0_9_9       0x00090900
# define SHWILD_VER_0_9_10      0x00090a00
# define SHWILD_VER_0_9_11      0x00090b00
# define SHWILD_VER_0_9_12      0x00090cff
# define SHWILD_VER_0_9_13      0x00090dff
# define SHWILD_VER_0_9_14      0x00090eff
# define SHWILD_VER_0_9_15      0x00090fff
# define SHWILD_VER_0_9_16      0x000910ff
# define SHWILD_VER_0_9_17      0x000911ff
# define SHWILD_VER_0_9_18      0x000912ff
# define SHWILD_VER_0_9_19      0x000913ff
# define SHWILD_VER_0_9_20      0x000914ff
#endif /* !SHWILD_DOCUMENTATION_SKIP_SECTION */

#define SHWILD_VER_MAJOR        0
#define SHWILD_VER_MINOR        9
#define SHWILD_VER_REVISION     20

#define SHWILD_VER              SHWILD_VER_0_9_20

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#include <stddef.h>     /* for size_t */

/* /////////////////////////////////////////////////////////////////////////
 * Documentation
 */

/** \defgroup group__shwild_api shwild API
 * The shwild Public API
 *
 * The types, constants and functions that constitute the shwild API. Users of
 * the shwild library will use only these functions to effect pattern creation
 * and matching.
 */

/** \defgroup group__shwild_api__c_api C API
 * \ingroup group__shwild_api
 * These types, constants and functions form the core of the shwild API.
 */

/* /////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

/** Handle type for use in declaring opaque handles to compiled patterns
 * \ingroup group__shwild_api__c_api
 */
struct shwild_handle_t_;

/** Handle to compiled pattern.
 * \ingroup group__shwild_api__c_api
 *
 * Used by shwild_compile_pattern(), shwild_match_pattern() and shwild_destroy_pattern()
 */
typedef struct shwild_handle_t_* shwild_handle_t;

/** Length-aware string.
 * \ingroup group__shwild_api__c_api
 *
 * This structure is used within the library to provide higher efficiency. In order
 * to maximise efficiency, there are equivalent versions of all API functions that
 * allow application code to specify string arguments as string slices, including
 * shwild_match_s(), shwild_compile_pattern_s() and shwild_match_pattern_s().
 */
struct shwild_slice_t
{
    size_t      len;    /*!< Number of characters in the slice. */
    char const* ptr;    /*!< Pointer to the first character in the slice. May be NULL if len == 0. */

#ifdef __cplusplus
public:
    /** Initialises members to default value */
    shwild_slice_t();
    /** Copies members from another slice instance */
    shwild_slice_t(shwild_slice_t const& rhs);
    /** Initialises members from the given parameters
     * 
     * \param n The number of characters in the string to be sliced
     * \param s Pointer to the first character in the string to be sliced. May be NULL only if n == 0.
     */
    shwild_slice_t(size_t n, char const* s);
#endif /* __cplusplus */
};
#ifndef SHWILD_DOCUMENTATION_SKIP_SECTION
typedef struct shwild_slice_t   shwild_slice_t;
#endif /* !SHWILD_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Constants and definitions
 */

/** \defgroup group__shwild_api__flags Pattern Control Flags
 * \ingroup group__shwild_api
 * These flags control the pattern matching behaviour:
 *
 * 1. Escape character. This is to recognise \ as an escape character, escaping
 *     any following character.
 *
 *     This is on by default, but may be suppressed by 
 *     SHWILD_F_SUPPRESS_BACKSLASH_ESCAPE.
 *
 * 2. Range support. This recognises [] as delimiting a range of possible 
 *      characters that may sustitute for a single character.
 *
 *     This is on by default, but may be suppressed by 
 *     SHWILD_F_SUPPRESS_RANGE_SUPPORT.
 *
 * 3. Range continuum support. This recognises a continuum of characters or
 *     numbers, e.g. [3-5m-q] === [345mnopq]
 *
 *     This is on by default, but may be suppressed by 
 *     SHWILD_F_SUPPRESS_RANGE_CONTINUUM_SUPPORT.
 * @{
 */

#define SHWILD_F_SUPPRESS_RANGE_SUPPORT                             (0x0001)    /*!< Suppresses the recognition of ranges. [ and ] are treated as literal characters (and need no escaping). */
#define SHWILD_F_SUPPRESS_BACKSLASH_ESCAPE                          (0x0002)    /*!< Suppresses the use of backslash interpretation as escape. \ is treated as a literal character. */
#define SHWILD_F_SUPPRESS_RANGE_CONTINUUM_SUPPORT                   (0x0004)    /*!< Suppresses the recognition of range continuums, i.e. [0-9]. */
#define SHWILD_F_SUPPRESS_RANGE_CONTINUUM_HIGHLOW_SUPPORT           (0x0008)    /*!< Suppresses the recognition of reverse range continuums, i.e. [9-0], [M-D]. */
#define SHWILD_F_SUPPRESS_RANGE_CONTINUUM_CROSSCASE_SUPPORT         (0x0010)    /*!< Suppresses the recognition of cross-case range continuums, i.e. [h-J] === [hijHIJ]. */
#define SHWILD_F_SUPPRESS_RANGE_LITERAL_WILDCARD_SUPPORT            (0x0020)    /*!< Suppresses the recognition of ? and * as literal inside range. */
#define SHWILD_F_SUPPRESS_RANGE_LEADTRAIL_LITERAL_HYPHEN_SUPPORT    (0x0040)    /*!< Suppresses the recognition of leading/trailing hyphens as literal inside range. */
#define SHWILD_F_SUPPRESS_RANGE_NOT_SUPPORT                         (0x0400)    /*!< Suppresses the use of a leading ^ to mean not any of the following, i.e. [^0-9] means do not match a digit. */
#define SHWILD_F_IGNORE_CASE                                        (0x0200)    /*!< Comparison is case-insensitive. */

#if 0
/* Not currently supported. */
#define SHWILD_F_ALLOW_RANGE_LITERAL_BRACKET_SUPPORT                (0x0080)    /*!< Treats [ and ] as literal inside range. ] only literal if immediately preceeds closing ]. NOT CURRENTLY SUPPORTED. */
#define SHWILD_F_ALLOW_RANGE_QUANTIFICATION_SUPPORT                 (0x0100)    /*!< Allows quantification of the wildcards, with trailing escaped numbers, as in [a-Z]\2-10. All chars in 0-9- become range specifiers. These are separated from actual pattern digits by []. NOT CURRENTLY SUPPORTED. */
#define SHWILD_F_FNM_PATHNAME_SEMANTICS                             (0x0800)    /*!< Will only match / (and \ on Win32) characters with literals, not via any wildcard substitutions. */
#endif /* 0 */

/** @} */

/** \defgroup group__shwild_api__result_codes shwild Results Codes
 * \ingroup group__shwild_api
 * These codes represent the 
 *
 * @{
 */

#define SHWILD_RC_SUCCESS               (0)                             /*!< Operating completed successfully */
#define SHWILD_RC_ERROR_BASE_           (-2000)
#define SHWILD_RC_ALLOC_ERROR           (SHWILD_RC_ERROR_BASE_ - 1)     /*!< Memory exhaustion. */
#define SHWILD_RC_PARSE_ERROR           (SHWILD_RC_ERROR_BASE_ - 2)     /*!< Parsing error. */
#define SHWILD_RC_UNSPECIFIED           (SHWILD_RC_ERROR_BASE_ - 3)     /*!< Unspecified exception. */

/** @} */

/* /////////////////////////////////////////////////////////////////////////
 * C API
 */

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */

/** Initialises the shwild API
 *
 * \return Status indicating whether initialisation was successful
 * \retval <0 An error
 * \retval >=0 Initialisation was successful
 */
int shwild_init(void);

/** Uninitialises the shwild API
 *
 * \remarks Must be called once for each successful call to shwild_init().
 */
void shwild_uninit(void);

/** Matches a string against an shwild pattern
 * \ingroup group__shwild_api__c_api
 *
 * \param pattern The shwild pattern against which matching will be performed
 * \param string The string to match against the pattern
 * \param flags Flags which moderate the search.
 *
 * \return Status indicating whether the string matched against the given pattern
 * \retval <0 An error code (one of SHWILD_RC_*)
 * \retval 0 The string matched the pattern
 * \retval non-0 The string did not match the pattern
 */
int shwild_match(char const* pattern, char const* string, unsigned flags);

/** Synonym for shwild_match() using length-aware string arguments
 * \ingroup group__shwild_api__c_api
 */
int shwild_match_s(shwild_slice_t const* pattern, shwild_slice_t const* string, unsigned flags);

/** Compiles a pattern into an efficient form for use in multiple match operations
 * \ingroup group__shwild_api__c_api
 *
 * \param pattern The shwild pattern against which matching will be performed
 * \param flags Flags which moderate the search.
 * \param phCompiledPattern Pointer to a variable to hold the compiled pattern
 *
 * \return Status indicating whether the operating completed successfully
 * \retval <0 The operation failed
 * \retval >=0 The operation succeeded. The value indicates the number of match 
 *   sub-components created to represent the pattern. The compiled pattern must
 *   be destroyed when it is no longer needed, by shwild_destroy_pattern(), to 
 *   avoid memory leaks.
 */
int shwild_compile_pattern(char const* pattern, unsigned flags, shwild_handle_t* phCompiledPattern);

/** Synonym for shwild_compile_pattern() using length-aware string arguments
 * \ingroup group__shwild_api__c_api
 */
int shwild_compile_pattern_s(shwild_slice_t const* pattern, unsigned flags, shwild_handle_t* phCompiledPattern);

/** Matches a string against against a pre-compiled shwild pattern
 * \ingroup group__shwild_api__c_api
 *
 * \param hCompiledPattern The precompiled shwild pattern against which matching will be performed
 * \param string The string to match against the pattern
 *
 * \return Status indicating whether the string matched against the given pattern
 * \retval 0 The string did not match the pattern
 * \retval non-0 The string matched against the pattern
 */
int shwild_match_pattern(shwild_handle_t hCompiledPattern, char const* string);

/** Synonym for shwild_match_pattern() using length-aware string arguments
 * \ingroup group__shwild_api__c_api
 */
int shwild_match_pattern_s(shwild_handle_t hCompiledPattern, shwild_slice_t const* string);

/** Releases all resources associated with a pre-compiled shwild pattern
 * \ingroup group__shwild_api__c_api
 *
 * \param hCompiledPattern The pattern to be destroyed.
 */
void shwild_destroy_pattern(shwild_handle_t hCompiledPattern);

#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#if !defined(__cplusplus) && \
    !defined(SHWILD_DOCUMENTATION_SKIP_SECTION) && \
    !defined(SHWILD_NO_NAMESPACE)
# define SHWILD_NO_NAMESPACE
#endif /* __cplusplus, etc. */

#if !defined(SHWILD_NO_NAMESPACE)
/** The shwild/C++ namespace - \c shwild - that contains wrappers for the 
 * \link group__shwild_api__c_api C API\endlink. */
namespace shwild
{
#endif /* !SHWILD_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * C++ functions
 */

#ifdef __cplusplus

/** \defgroup group__shwild_api__cpp_api C++ API
 * \ingroup group__shwild_api
 * The C++ API provides convenient overloads of the 
 *   \ref group__shwild_api__c_api functions for use in C++, along with the
 *   Pattern class that provides a convenient interface to compiled patterns.
 * @{
 */

/** C++ synonym for shwild_slice_t
 * \ingroup group__shwild_api__cpp_api
 */
typedef shwild_slice_t  slice_t;

/** C++ overload synonym for shwild_match()
 * \ingroup group__shwild_api__cpp_api
 */
inline int match(char const* pattern, char const* string, unsigned flags = 0)
{
    return shwild_match(pattern, string, flags);
}
/** C++ overload synonym for shwild_compile_pattern()
 * \ingroup group__shwild_api__cpp_api
 */
inline int compile_pattern(char const* pattern, unsigned flags, shwild_handle_t* phCompiledPattern)
{
    return shwild_compile_pattern(pattern, flags, phCompiledPattern);
}
/** C++ overload synonym for shwild_match_pattern()
 * \ingroup group__shwild_api__cpp_api
 */
inline int match_pattern(shwild_handle_t hCompiledPattern, char const* string)
{
    return shwild_match_pattern(hCompiledPattern, string);
}
/** C++ overload synonym for shwild_destroy_pattern()
 * \ingroup group__shwild_api__cpp_api
 */
inline void destroy_pattern(shwild_handle_t hCompiledPattern)
{
    shwild_destroy_pattern(hCompiledPattern);
}

/** @} */

#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#if !defined(SHWILD_NO_NAMESPACE)
} /* namespace shwild */
#endif /* !SHWILD_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Implementation
 */

#ifndef SHWILD_DOCUMENTATION_SKIP_SECTION

# ifdef __cplusplus

#  if defined(__BORLANDC__) && \
      __BORLANDC__ >= 0x0582
#   pragma warn -8026
#  endif /* compiler */


inline shwild_slice_t::shwild_slice_t()
    : len(0)
    , ptr(NULL)
{}
inline shwild_slice_t::shwild_slice_t(shwild_slice_t const& rhs)
    : len(rhs.len)
    , ptr(rhs.ptr)
{}
inline shwild_slice_t::shwild_slice_t(size_t n, char const* s)
    : len(n)
    , ptr(s)
{}

#  if defined(__BORLANDC__) && \
      __BORLANDC__ >= 0x0582
#   pragma warn .8026
#  endif /* compiler */

# endif /* __cplusplus */

#endif /* !SHWILD_DOCUMENTATION_SKIP_SECTION */

/* ////////////////////////////////////////////////////////////////////// */

#endif /* !SHWILD_INCL_SHWILD_H_SHWILD */

/* ///////////////////////////// end of file //////////////////////////// */