/* tokenize.h */ /* remap Copyright (C) 2006 Fabrice Ducos, fabrice.ducos@icare.univ-lille1.fr This program 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 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. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef TOKENIZE_H #define TOKENIZE_H #ifdef __cplusplus extern "C" { #endif /** * enumeration of ::tokenize return codes */ typedef enum etok_type_ { ETOK_SUCCESS, ///< ::tokenize call was successfull, a_string matched the regexp 'pattern' ETOK_REGCOMP, ///< ::tokenize call failed on the compilation of the regexp 'pattern' (maybe 'pattern' is not a valid regexp) ETOK_MEMORY, ///< ::tokenize call failed on an internal calloc call ETOK_NOMATCH, ///< ::tokenize call failed, a_string did not match the regexp 'pattern' ETOK_ESPACE ///< ::tokenize call failed on an internal regexec call } etok_type; /** * a low-level function to parse 'a_string' using the regexp 'pattern', into an array of tokens (see below); * essentially called by ::parse_argument * * @param pattern (input) the regexp to be matched by 'a_string' * @param a_string (input) the string to parse * @param ntokens (output) a pointer to the number of tokens returned by the parsing * @param ptokens (output) a pointer to the array of tokens returned by the parsing (is allocated by ::tokenize and must be freed by the caller with ::free_tokens); * * A example will help to explain what this function actually does : * - size_t ntokens; * - char **tokens; * - tokenize(pattern, a_string, &ntokens, &tokens); * * After this call : * - tokens[0] will contain the entire string 'a_string' if it matched the regexp 'pattern'; * - if the regexp 'pattern' contains sub-regexp (between parenthesis), tokens[i] will contain the substring of 'a_string' matching the i-th sub-regexp * * @see parse_argument */ extern etok_type tokenize(const char *pattern, const char *a_string, size_t *ntokens, char ***ptokens); /** * frees the array of tokens allocated and filled by ::tokenize */ extern void free_tokens(size_t ntokens, char **tokens); #ifdef __cplusplus } #endif #endif