diff options
Diffstat (limited to 'src/templating/mustach.h')
| -rw-r--r-- | src/templating/mustach.h | 180 |
1 files changed, 129 insertions, 51 deletions
diff --git a/src/templating/mustach.h b/src/templating/mustach.h index ad952275c..1b44582d5 100644 --- a/src/templating/mustach.h +++ b/src/templating/mustach.h @@ -1,20 +1,9 @@ /* Author: José Bollo <jobol@nonadev.net> - Author: José Bollo <jose.bollo@iot.bzh> https://gitlab.com/jobol/mustach - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. + SPDX-License-Identifier: ISC */ #ifndef _mustach_h_included_ @@ -25,32 +14,77 @@ struct mustach_sbuf; /* see below */ /** * Current version of mustach and its derivates */ -#define MUSTACH_VERSION 99 +#define MUSTACH_VERSION 102 #define MUSTACH_VERSION_MAJOR (MUSTACH_VERSION / 100) #define MUSTACH_VERSION_MINOR (MUSTACH_VERSION % 100) /** - * Maximum nested imbrications supported + * Maximum nested section supported */ #define MUSTACH_MAX_DEPTH 256 /** + * Maximum nested template supported + */ +#define MUSTACH_MAX_NESTING 64 + +/** * Maximum length of tags in mustaches {{...}} */ -#define MUSTACH_MAX_LENGTH 1024 +#define MUSTACH_MAX_LENGTH 4096 /** - * mustach_itf - interface for callbacks + * Maximum length of delimitors (2 normally but extended here) + */ +#define MUSTACH_MAX_DELIM_LENGTH 8 + +/** + * Flags specific to mustach core + */ +#define Mustach_With_NoExtensions 0 +#define Mustach_With_Colon 1 +#define Mustach_With_EmptyTag 2 +#define Mustach_With_AllExtensions 3 + +/* + * Definition of error codes returned by mustach + */ +#define MUSTACH_OK 0 +#define MUSTACH_ERROR_SYSTEM -1 +#define MUSTACH_ERROR_UNEXPECTED_END -2 +#define MUSTACH_ERROR_EMPTY_TAG -3 +#define MUSTACH_ERROR_TAG_TOO_LONG -4 +#define MUSTACH_ERROR_BAD_SEPARATORS -5 +#define MUSTACH_ERROR_TOO_DEEP -6 +#define MUSTACH_ERROR_CLOSING -7 +#define MUSTACH_ERROR_BAD_UNESCAPE_TAG -8 +#define MUSTACH_ERROR_INVALID_ITF -9 +#define MUSTACH_ERROR_ITEM_NOT_FOUND -10 +#define MUSTACH_ERROR_PARTIAL_NOT_FOUND -11 +#define MUSTACH_ERROR_UNDEFINED_TAG -12 +#define MUSTACH_ERROR_TOO_MUCH_NESTING -13 + +/* + * You can use definition below for user specific error * - * All of this function should return a negative value to stop - * the mustache processing. The returned negative value will be - * then returned to the caller of mustach as is. + * The macro MUSTACH_ERROR_USER is involutive so for any value + * value = MUSTACH_ERROR_USER(MUSTACH_ERROR_USER(value)) + */ +#define MUSTACH_ERROR_USER_BASE -100 +#define MUSTACH_ERROR_USER(x) (MUSTACH_ERROR_USER_BASE-(x)) +#define MUSTACH_IS_ERROR_USER(x) (MUSTACH_ERROR_USER(x) >= 0) + +/** + * mustach_itf - pure abstract mustach - interface for callbacks * * The functions enter and next should return 0 or 1. * * All other functions should normally return MUSTACH_OK (zero). - * If it returns a negative value, it means an error that stop - * the process and that is reported to the caller. + * + * If any function returns a negative value, it means an error that + * stop the processing and that is reported to the caller. Mustach + * also has its own error codes. Using the macros MUSTACH_ERROR_USER + * and MUSTACH_IS_ERROR_USER could help to avoid clashes. * * @start: If defined (can be NULL), starts the mustach processing * of the closure, called at the very beginning before any @@ -92,18 +126,18 @@ struct mustach_sbuf; /* see below */ * the meaning of 'FILE *file' is abstract for mustach's process and * then you can use 'FILE*file' pass any kind of pointer (including NULL) * to the function 'fmustach'. An example of a such behaviour is given by - * the implementation of 'umustach_json_c'. + * the implementation of 'mustach_json_c_write'. * * @get: If defined (can be NULL), returns in 'sbuf' the value of 'name'. * As an extension (see NO_ALLOW_EMPTY_TAG), the 'name' can be * the empty string. In that later case an implementation can * return MUSTACH_ERROR_EMPTY_TAG to refuse empty names. - * If NULL and 'put' NULL the error MUSTACH_ERROR_INVALID_ITF + * If 'get' is NULL and 'put' NULL the error MUSTACH_ERROR_INVALID_ITF * is returned. * * @stop: If defined (can be NULL), stops the mustach processing * of the closure, called at the very end after all mustach - * processing occurerd. The status returned by the processing + * processing occurered. The status returned by the processing * is passed to the stop. * * The array below summarize status of callbacks: @@ -127,7 +161,7 @@ struct mustach_sbuf; /* see below */ * * The DUCK case runs on one leg. 'get' is not used if 'partial' is defined * but is used for 'partial' if 'partial' is NULL. Thus for clarity, do not use - * it that way but define 'partial' and let 'get' NULL. + * it that way but define 'partial' and let 'get' be NULL. * * The DANGEROUS case is special: it allows abstract FILE if 'partial' is defined * but forbids abstract FILE when 'partial' is NULL. @@ -167,6 +201,9 @@ struct mustach_itf { * Can be NULL. * * @closure: The closure to use for 'releasecb'. + * + * @length: Length of the value or zero if unknown and value null terminated. + * To return the empty string, let it to zero and let value to NULL. */ struct mustach_sbuf { const char *value; @@ -175,45 +212,84 @@ struct mustach_sbuf { void (*releasecb)(const char *value, void *closure); }; void *closure; + size_t length; }; -/* - * Definition of error codes returned by mustach +/** + * mustach_file - Renders the mustache 'template' in 'file' for 'itf' and 'closure'. + * + * @template: the template string to instantiate + * @length: length of the template or zero if unknown and template null terminated + * @itf: the interface to the functions that mustach calls + * @closure: the closure to pass to functions called + * @file: the file where to write the result + * + * Returns 0 in case of success, -1 with errno set in case of system error + * a other negative value in case of error. */ -#define MUSTACH_OK 0 -#define MUSTACH_ERROR_SYSTEM -1 -#define MUSTACH_ERROR_UNEXPECTED_END -2 -#define MUSTACH_ERROR_EMPTY_TAG -3 -#define MUSTACH_ERROR_TAG_TOO_LONG -4 -#define MUSTACH_ERROR_BAD_SEPARATORS -5 -#define MUSTACH_ERROR_TOO_DEEP -6 -#define MUSTACH_ERROR_CLOSING -7 -#define MUSTACH_ERROR_BAD_UNESCAPE_TAG -8 -#define MUSTACH_ERROR_INVALID_ITF -9 -#define MUSTACH_ERROR_ITEM_NOT_FOUND -10 -#define MUSTACH_ERROR_PARTIAL_NOT_FOUND -11 - -/* You can use definition below for user specific error */ -#define MUSTACH_ERROR_USER_BASE -100 -#define MUSTACH_ERROR_USER(x) (MUSTACH_ERROR_USER_BASE-(x)) +extern int mustach_file(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, FILE *file); /** - * fmustach - Renders the mustache 'template' in 'file' for 'itf' and 'closure'. + * mustach_fd - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'. * * @template: the template string to instantiate + * @length: length of the template or zero if unknown and template null terminated * @itf: the interface to the functions that mustach calls * @closure: the closure to pass to functions called - * \@file: the file where to write the result + * @fd: the file descriptor number where to write the result * * Returns 0 in case of success, -1 with errno set in case of system error * a other negative value in case of error. */ -extern int fmustach(const char *template, struct mustach_itf *itf, void *closure, FILE *file); +extern int mustach_fd(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, int fd); /** - * fmustach - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'. + * mustach_mem - Renders the mustache 'template' in 'result' for 'itf' and 'closure'. * * @template: the template string to instantiate + * @length: length of the template or zero if unknown and template null terminated + * @itf: the interface to the functions that mustach calls + * @closure: the closure to pass to functions called + * @result: the pointer receiving the result when 0 is returned + * @size: the size of the returned result + * + * Returns 0 in case of success, -1 with errno set in case of system error + * a other negative value in case of error. + */ +extern int mustach_mem(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, char **result, size_t *size); + +/*************************************************************************** +* compatibility with version before 1.0 +*/ +#ifdef __GNUC__ +#define DEPRECATED_MUSTACH(func) func __attribute__ ((deprecated)) +#elif defined(_MSC_VER) +#define DEPRECATED_MUSTACH(func) __declspec(deprecated) func +#elif !defined(DEPRECATED_MUSTACH) +#pragma message("WARNING: You need to implement DEPRECATED_MUSTACH for this compiler") +#define DEPRECATED_MUSTACH(func) func +#endif +/** + * OBSOLETE use mustach_file + * + * fmustach - Renders the mustache 'template' in 'file' for 'itf' and 'closure'. + * + * @template: the template string to instantiate, null terminated + * @itf: the interface to the functions that mustach calls + * @closure: the closure to pass to functions called + * @file: the file where to write the result + * + * Returns 0 in case of success, -1 with errno set in case of system error + * a other negative value in case of error. + */ +DEPRECATED_MUSTACH(extern int fmustach(const char *template, const struct mustach_itf *itf, void *closure, FILE *file)); + +/** + * OBSOLETE use mustach_fd + * + * fdmustach - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'. + * + * @template: the template string to instantiate, null terminated * @itf: the interface to the functions that mustach calls * @closure: the closure to pass to functions called * @fd: the file descriptor number where to write the result @@ -221,12 +297,14 @@ extern int fmustach(const char *template, struct mustach_itf *itf, void *closure * Returns 0 in case of success, -1 with errno set in case of system error * a other negative value in case of error. */ -extern int fdmustach(const char *template, struct mustach_itf *itf, void *closure, int fd); +DEPRECATED_MUSTACH(extern int fdmustach(const char *template, const struct mustach_itf *itf, void *closure, int fd)); /** - * fmustach - Renders the mustache 'template' in 'result' for 'itf' and 'closure'. + * OBSOLETE use mustach_mem * - * @template: the template string to instantiate + * mustach - Renders the mustache 'template' in 'result' for 'itf' and 'closure'. + * + * @template: the template string to instantiate, null terminated * @itf: the interface to the functions that mustach calls * @closure: the closure to pass to functions called * @result: the pointer receiving the result when 0 is returned @@ -235,7 +313,7 @@ extern int fdmustach(const char *template, struct mustach_itf *itf, void *closur * Returns 0 in case of success, -1 with errno set in case of system error * a other negative value in case of error. */ -extern int mustach(const char *template, struct mustach_itf *itf, void *closure, char **result, size_t *size); +DEPRECATED_MUSTACH(extern int mustach(const char *template, const struct mustach_itf *itf, void *closure, char **result, size_t *size)); #endif |