1/*-------------------------------------------------------------------------
4 * Declarations for JSON API support.
6 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
9 * src/include/common/jsonapi.h
11 *-------------------------------------------------------------------------
62/* Parser state private to jsonapi.c */
67 * Don't depend on the internal type header for strval; if callers need access
68 * then they can include the appropriate header themselves.
70#ifdef JSONAPI_USE_PQEXPBUFFER
71#define jsonapi_StrValType PQExpBufferData
73 #define jsonapi_StrValType StringInfoData
77 * All the fields in this structure should be treated as read-only.
79 * If strval is not null, then it should contain the de-escaped value
80 * of the lexeme if it's a string. Otherwise most of these field names
81 * should be self-explanatory.
83 * line_number and line_start are principally for use by the parser's
84 * error reporting routines.
85 * token_terminator and prev_token_terminator point to the character
86 * AFTER the end of the token, i.e. where there would be a nul byte
87 * if we were using nul-terminated strings.
89 * The prev_token_terminator field should not be used when incremental is
90 * true, as the previous token might have started in a previous piece of input,
91 * and thus it can't be used in any pointer arithmetic or other operations in
92 * conjunction with token_start.
94 * JSONLEX_FREE_STRUCT/STRVAL are used to drive freeJsonLexContext.
95 * JSONLEX_CTX_OWNS_TOKENS is used by setJsonLexContextOwnsTokens.
97 #define JSONLEX_FREE_STRUCT (1 << 0)
98 #define JSONLEX_FREE_STRVAL (1 << 1)
99 #define JSONLEX_CTX_OWNS_TOKENS (1 << 2)
113 const char *
line_start;
/* where that line starts within input */
122 * Function types for custom json parsing actions.
124 * fname will be NULL if the context has need_escapes=false, as will token for
125 * string type values.
134 * Semantic Action structure for use in parsing json.
136 * Any of these actions can be NULL, in which case nothing is done at that
137 * point, Likewise, semstate can be NULL. Using an all-NULL structure amounts
138 * to doing a pure parse with no side-effects, and is therefore exactly
139 * what the json input routines do.
141 * By default, the 'fname' and 'token' strings passed to these actions are
142 * palloc'd. They are not free'd or used further by the parser, so the action
143 * function is free to do what it wishes with them. This behavior may be
144 * modified by setJsonLexContextOwnsTokens().
146 * All action functions return JsonParseErrorType. If the result isn't
147 * JSON_SUCCESS, the parse is abandoned and that error code is returned.
148 * If it is JSON_SEM_ACTION_FAILED, the action function is responsible
149 * for having reported the error in some appropriate way.
166 * pg_parse_json will parse the string in the lex calling the
167 * action functions in sem at the appropriate points. It is
168 * up to them to keep what state they need in semstate. If they
169 * need access to the state of the lexer, then its pointer
170 * should be passed to them as a member of whatever semstate
171 * points to. If the action pointers are NULL the parser
172 * does nothing and just continues.
183/* the null action object used for pure validation */
187 * json_count_array_elements performs a fast secondary parse to determine the
188 * number of elements in passed array lex context. It should be called from an
189 * array_start action.
191 * The return value indicates whether any error occurred, while the number
192 * of elements is stored into *elements (but only if the return value is
199 * initializer for JsonLexContext.
201 * If a valid 'lex' pointer is given, it is initialized. This can be used
202 * for stack-allocated structs, saving overhead. If NULL is given, a new
203 * struct is allocated.
205 * If need_escapes is true, ->strval stores the unescaped lexemes.
207 * Setting need_escapes to true is necessary if the operation needs
208 * to reference field names or scalar string values. This is true of most
209 * operations beyond purely checking the json-validity of the source
212 * Unescaping is expensive, so only request it when necessary.
214 * If need_escapes is true or lex was given as NULL, then the caller is
215 * responsible for freeing the returned struct, either by calling
216 * freeJsonLexContext() or (in backends) via memory context cleanup.
225 * make a JsonLexContext suitable for incremental parsing.
226 * the string chunks will be handed to pg_parse_json_incremental,
227 * so there's no need for them here.
234 * Sets whether tokens passed to semantic action callbacks are owned by the
235 * context (in which case, the callback must duplicate the tokens for long-term
236 * storage) or by the callback (in which case, the callback must explicitly
237 * free tokens to avoid leaks).
239 * By default, this setting is false: the callback owns the tokens that are
240 * passed to it (and if parsing fails between the two object-field callbacks,
241 * the field name token will likely leak). If set to true, tokens will be freed
242 * by the lexer after the callback completes.
244 * Setting this to true is important for long-lived clients (such as libpq)
245 * that must not leak memory during a parse failure. For a server backend using
246 * memory contexts, or a client application which will exit on parse failure,
247 * this setting is less critical.
250 bool owned_by_context);
257/* construct an error detail string for a json error */
261 * Utility function to check if a string is a valid JSON number.
263 * str argument does not need to be nul-terminated.
267#endif /* JSONAPI_H */
JsonParseErrorType pg_parse_json_incremental(JsonLexContext *lex, const JsonSemAction *sem, const char *json, size_t len, bool is_last)
JsonLexContext * makeJsonLexContextIncremental(JsonLexContext *lex, int encoding, bool need_escapes)
bool IsValidJsonNumber(const char *str, size_t len)
struct JsonLexContext JsonLexContext
JsonParseErrorType(* json_struct_action)(void *state)
JsonParseErrorType(* json_aelem_action)(void *state, bool isnull)
JsonParseErrorType pg_parse_json(JsonLexContext *lex, const JsonSemAction *sem)
#define jsonapi_StrValType
@ JSON_EXPECTED_ARRAY_FIRST
@ JSON_UNICODE_HIGH_SURROGATE
@ JSON_EXPECTED_OBJECT_FIRST
@ JSON_UNICODE_CODE_POINT_ZERO
@ JSON_INVALID_LEXER_TYPE
@ JSON_UNICODE_ESCAPE_FORMAT
@ JSON_UNICODE_UNTRANSLATABLE
@ JSON_EXPECTED_OBJECT_NEXT
@ JSON_EXPECTED_ARRAY_NEXT
@ JSON_UNICODE_HIGH_ESCAPE
@ JSON_UNICODE_LOW_SURROGATE
JsonParseErrorType(* json_ofield_action)(void *state, char *fname, bool isnull)
JsonLexContext * makeJsonLexContextCstringLen(JsonLexContext *lex, const char *json, size_t len, int encoding, bool need_escapes)
void setJsonLexContextOwnsTokens(JsonLexContext *lex, bool owned_by_context)
PGDLLIMPORT const JsonSemAction nullSemAction
@ JSON_TOKEN_OBJECT_START
JsonParseErrorType json_lex(JsonLexContext *lex)
JsonParseErrorType(* json_scalar_action)(void *state, char *token, JsonTokenType tokentype)
char * json_errdetail(JsonParseErrorType error, JsonLexContext *lex)
JsonParseErrorType json_count_array_elements(JsonLexContext *lex, int *elements)
void freeJsonLexContext(JsonLexContext *lex)
struct JsonSemAction JsonSemAction
const char * prev_token_terminator
struct jsonapi_StrValType * strval
struct jsonapi_StrValType * errormsg
JsonIncrementalState * inc_state
const char * token_terminator
json_struct_action array_end
json_struct_action object_start
json_ofield_action object_field_start
json_aelem_action array_element_start
json_scalar_action scalar
json_aelem_action array_element_end
json_struct_action array_start
json_struct_action object_end
json_ofield_action object_field_end