iniparse.h

/*****************************************************************************\
*                                                                             *
*  FILENAME :     iniparse.h                                                  *
*                                                                             *
* --------------------------------------------------------------------------- *
*                                                                             *
*  DESCRIPTION : Contains diverse character buffer parsing functions          *
*                for a buffer that uses the data composition format.          *
*                                                                             *
* --------------------------------------------------------------------------- *
*                                                                             *
*  COPYRIGHT :   (c) 2026 Dipl.-Ing. Klaus Lux (Aachen, Germany)              *
*                                                                             *
* --------------------------------------------------------------------------- *
*                                                                             *
*  ORIGIN :      https://github.com/klux21/composition_parser                 *
*                                                                             *
* --------------------------------------------------------------------------- *
*                                                                             *
* This software is provided 'as-is', without any express or implied           *
* warranty. In no event will the authors be held liable for any damages       *
* arising from the use of this software.                                      *
*                                                                             *
* Permission is granted to anyone to use this software for any purpose,       *
* including commercial applications, and to alter it and redistribute it      *
* freely, subject to the following restrictions:                              *
*                                                                             *
* 1. The origin of this software must not be misrepresented; you must not     *
*    claim that you wrote the original software. If you use this software     *
*    in a product, an acknowledgment in the product documentation would be    *
*    appreciated but is not required.                                         *
* 2. Altered source versions must be plainly marked as such, and must not be  *
*    misrepresented as being the original software.                           *
* 3. This notice may not be removed or altered from any source distribution.  *
*                                                                             *
\*****************************************************************************/

#ifndef INIPARSE_H
#define INIPARSE_H


#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ------------------------------------------------------------------------- *\
   The struct INI_ENTRY holds the data of an INI file entry
\* ------------------------------------------------------------------------- */

typedef struct INI_ENTRY_S INI_ENTRY;
struct INI_ENTRY_S
{
   char * pName;      /* entry name */
   size_t NameSize;   /* length of name string (without trailing '\0') */
   char * pArg;       /* argument value of the entry */
   size_t ArgSize;    /* size of the argument data (without trailing '\0') */
};

/* ------------------------------------------------------------------------- *\
   pIniFileRead reads the content of an INI file into an allocated buffer.
   The returned buffer is terminated by a '\0' character and must be released
   using vIniDataFree after usage.
\* ------------------------------------------------------------------------- */

char * pIniFileRead(const char * IniFileName);

/* ------------------------------------------------------------------------- *\
   pIniFindSection searches a section in an INI file buffer. It returns a
   pointer to the begin of the sections content or nonzero if the section
   doesn't exist.
\* ------------------------------------------------------------------------- */

char * pIniFindSection(const char * pData,  /* pointer to an INI file data buffer to read */
                       const char * pName); /* INI file section name */

/* ------------------------------------------------------------------------- *\
  pIniFindNextSection searches the next section in given INI file buffer.
  It returns a pointer to the begin of the sections data or NULL if there
  doesn't exist any section within the data.
  The iterator that ppData points to will be set to the begin of the
  returned section or the character that stops the scan ('}' or '\0').
\* ------------------------------------------------------------------------- */

char * pIniFindNextSection(char **  ppData,            /* INI file data buffer */
                           char **  ppSectionName,     /* pointer to section name */
                           size_t * pSectionNameSize); /* pointer to section name length */

/* ------------------------------------------------------------------------- *\
   bIniEntryRead reads the next entry within an INI file section. It returns
   a pointer to an allocated PINI_ENTRY structure that contains the data of
   the first found entry. It fails, if no entry could be found before begin
   of the next section, if a terminating '\0' character was found or if the
   allocation of the return buffer has failed.
   The allocated name und argument data strings are zero terminated.
   If bUnescape is nonzero, then the entry name and its argument data
   are converted from a C like escape sequence format to binary format.
   ppData is set to the data that follows this entry withing the INI file.
   The returned pointer must be released using vIniDataFree after usage.
\* ------------------------------------------------------------------------- */

int bIniEntryRead(char **      ppData,     /* pointer to INI file data */
                  INI_ENTRY ** ppEntry,    /* storage for the allocated pointer */
                  int          bUnescape); /* whether or not replace C-style format escape sequences */

/* ------------------------------------------------------------------------- *\
   bIniEntryFind searces the next entry in a section and returns nonzero if
   an entry was found. * ppData will be set to to the begin of the next
   section entry or to the character that terminates the section.
   Argument strings to entries which contain spaces have to be enclosed in
   "" or '' in the section.
   Name or argument embracing quotes or braces will be not removed.
\* ------------------------------------------------------------------------- */

int bIniEntryFind(char **  ppData,         /* section data pointer */
                  char **  ppName,         /* returned pointer to entry name */
                  size_t * pNameSize,      /* will be set to the length of the name */
                  char **  ppArg,          /* pointer to the entries parameter string */
                  size_t * pArgSize,       /* length of parameter string */
                  int      bFindBlockEnd); /* whether to find the end of a block or just the begin */

/* ------------------------------------------------------------------------- *\
   bIniEntryCopy copies and unquotes an entry name and it's argument data
   into an allocated INI_ENTRY struct. The returned pointer must be released
   using vIniDataFree after usage. The allocated name und argument data
   strings are zero terminated.
\* ------------------------------------------------------------------------- */

int bIniEntryCopy(INI_ENTRY ** ppEntry,    /* pointer to storage for the allocated INI_ENTRY */
                  const char * pName,      /* pointer to entry name */
                  size_t       NameSize,   /* will be set to the length of the name */
                  const char * pArg,       /* pointer to the entries parameter string */
                  size_t       ArgSize,    /* length of parameter string */
                  int          bUnescape); /* whether to find the end of a block or just the begin */

/* ------------------------------------------------------------------------- *\
   vIniDataFree frees the data that was allocated using bIniEntryCopy,
   bIniEntryRead or pIniFileRead.
   It ensures a free at the sofware layer of the allocation.
\* ------------------------------------------------------------------------- */

void vIniDataFree(void * pv);

/* ------------------------------------------------------------------------- *\
   pFindBlockEnd returns a pointer to the first character after the block
   that pb points to. pb must not point to the inner of a quoted string,
   a comment or a section header.
\* ------------------------------------------------------------------------- */

char * pIniFindBlockEnd (const char * pb);

/* ------------------------------------------------------------------------- *\
   pIniFindectionEnd returns a pointer to the first character after the
   section that pb points to. pb must not point to the inner of a quoted
   string, a comment, or a section header.
\* ------------------------------------------------------------------------- */

char * pIniFindSectionEnd (const char * pb);

/* ------------------------------------------------------------------------- *\
   lIniGetStringValue converts an unterminated C style escaped string from
   INI file buffer to it's unescaped and unqoted value. DstLen has to be at
   maximum as large as SrcLen + 1 for a terminating '\0' character.
   The function returns the number of written bytes.
   Source and Destination buffer may overlap. If the destination pointer is
   NULL than the required buffer size is returned only.
\* ------------------------------------------------------------------------- */

size_t lIniGetStringValue(char *       pDst,    /* pointer to destination buffer */
                          const char * pSrc,    /* pointer to source buffer */
                          size_t       SrcLen); /* length of the source buffer */

/* ------------------------------------------------------------------------- *\
   lIniRemoveQuotes removes the quotes from a value read from INI file without
   replacing C-like escaped characters. The destination buffer length has to
   be at least as large as SrcLen + 1 (for a terminating '\0' character).
   The function returns the  number of bytes written to the destination string
   including the terminating '\0'. Source and destination buffer may overlap.
   If the destination is NULL than the required buffer size is returned only.
\* ------------------------------------------------------------------------- */

size_t lIniRemoveQuotes(char *       pDst,    /* pointer to destination buffer */
                        const char * pSrc,    /* pointer to source buffer */
                        size_t       SrcLen); /* length of source buffer */

/* ------------------------------------------------------------------------- *\
   strmemcmp compares a string content with a buffer content of a given size
   and returns like strcmp if any differences are found.
   (A strncmp() succeeds if the string is longer than the size.)
\* ------------------------------------------------------------------------- */

int strmemcmp(const char * pStr, const void * pBuffer, size_t BufferSize);

/* ------------------------------------------------------------------------- *\
   Extracts a C style character from a string and moves the string pointer to
   the end of the C style character definition. It does not move the pointer
   behind a string terminating '\0'.
   A '\u' is ignored and the backslash returned as the backslash for keeping
   '\u'. In case of other unknown sequences like '\#', '\[', '\]', '\{', '\}',
   '\*', '\;' or '\ ' the backslash is will be skipped and the subsequent
   character returned only.
\* ------------------------------------------------------------------------- */

char get_C_char(const char ** ppSrc);

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

#endif/* INIPARSE_H */


/* ========================================================================= *\
   E N D   O F   F I L E
\* ========================================================================= */