PostgreSQL Source Code  git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
jsonapi.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * jsonapi.h
4  * Declarations for JSON API support.
5  *
6  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  * src/include/common/jsonapi.h
10  *
11  *-------------------------------------------------------------------------
12  */
13 
14 #ifndef JSONAPI_H
15 #define JSONAPI_H
16 
17 typedef enum JsonTokenType
18 {
33 
34 typedef enum JsonParseErrorType
35 {
59  JSON_SEM_ACTION_FAILED, /* error should already be reported */
61 
62 /* Parser state private to jsonapi.c */
63 typedef struct JsonParserStack JsonParserStack;
65 
66 /*
67  * Don't depend on the internal type header for strval; if callers need access
68  * then they can include the appropriate header themselves.
69  */
70 #ifdef JSONAPI_USE_PQEXPBUFFER
71 #define jsonapi_StrValType PQExpBufferData
72 #else
73 #define jsonapi_StrValType StringInfoData
74 #endif
75 
76 /*
77  * All the fields in this structure should be treated as read-only.
78  *
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.
82  *
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.
88  *
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.
93  *
94  * JSONLEX_FREE_STRUCT/STRVAL are used to drive freeJsonLexContext.
95  */
96 #define JSONLEX_FREE_STRUCT (1 << 0)
97 #define JSONLEX_FREE_STRVAL (1 << 1)
98 typedef struct JsonLexContext
99 {
100  const char *input;
101  size_t input_length;
103  const char *token_start;
104  const char *token_terminator;
110  int line_number; /* line number, starting from 1 */
111  const char *line_start; /* where that line starts within input */
115  struct jsonapi_StrValType *strval; /* only used if need_escapes == true */
118 
120 typedef JsonParseErrorType (*json_ofield_action) (void *state, char *fname, bool isnull);
121 typedef JsonParseErrorType (*json_aelem_action) (void *state, bool isnull);
122 typedef JsonParseErrorType (*json_scalar_action) (void *state, char *token, JsonTokenType tokentype);
123 
124 
125 /*
126  * Semantic Action structure for use in parsing json.
127  *
128  * Any of these actions can be NULL, in which case nothing is done at that
129  * point, Likewise, semstate can be NULL. Using an all-NULL structure amounts
130  * to doing a pure parse with no side-effects, and is therefore exactly
131  * what the json input routines do.
132  *
133  * The 'fname' and 'token' strings passed to these actions are palloc'd.
134  * They are not free'd or used further by the parser, so the action function
135  * is free to do what it wishes with them.
136  *
137  * All action functions return JsonParseErrorType. If the result isn't
138  * JSON_SUCCESS, the parse is abandoned and that error code is returned.
139  * If it is JSON_SEM_ACTION_FAILED, the action function is responsible
140  * for having reported the error in some appropriate way.
141  */
142 typedef struct JsonSemAction
143 {
144  void *semstate;
155 
156 /*
157  * pg_parse_json will parse the string in the lex calling the
158  * action functions in sem at the appropriate points. It is
159  * up to them to keep what state they need in semstate. If they
160  * need access to the state of the lexer, then its pointer
161  * should be passed to them as a member of whatever semstate
162  * points to. If the action pointers are NULL the parser
163  * does nothing and just continues.
164  */
166  const JsonSemAction *sem);
167 
169  const JsonSemAction *sem,
170  const char *json,
171  size_t len,
172  bool is_last);
173 
174 /* the null action object used for pure validation */
176 
177 /*
178  * json_count_array_elements performs a fast secondary parse to determine the
179  * number of elements in passed array lex context. It should be called from an
180  * array_start action.
181  *
182  * The return value indicates whether any error occurred, while the number
183  * of elements is stored into *elements (but only if the return value is
184  * JSON_SUCCESS).
185  */
187  int *elements);
188 
189 /*
190  * initializer for JsonLexContext.
191  *
192  * If a valid 'lex' pointer is given, it is initialized. This can be used
193  * for stack-allocated structs, saving overhead. If NULL is given, a new
194  * struct is allocated.
195  *
196  * If need_escapes is true, ->strval stores the unescaped lexemes.
197  * Unescaping is expensive, so only request it when necessary.
198  *
199  * If need_escapes is true or lex was given as NULL, then the caller is
200  * responsible for freeing the returned struct, either by calling
201  * freeJsonLexContext() or (in backend environment) via memory context
202  * cleanup.
203  */
205  const char *json,
206  size_t len,
207  int encoding,
208  bool need_escapes);
209 
210 /*
211  * make a JsonLexContext suitable for incremental parsing.
212  * the string chunks will be handed to pg_parse_json_incremental,
213  * so there's no need for them here.
214  */
216  int encoding,
217  bool need_escapes);
218 
219 extern void freeJsonLexContext(JsonLexContext *lex);
220 
221 /* lex one token */
223 
224 /* construct an error detail string for a json error */
226 
227 /*
228  * Utility function to check if a string is a valid JSON number.
229  *
230  * str argument does not need to be nul-terminated.
231  */
232 extern bool IsValidJsonNumber(const char *str, size_t len);
233 
234 #endif /* JSONAPI_H */
#define PGDLLIMPORT
Definition: c.h:1321
uint32 bits32
Definition: c.h:526
const char * str
#define token
Definition: indent_globs.h:126
JsonParseErrorType pg_parse_json_incremental(JsonLexContext *lex, const JsonSemAction *sem, const char *json, size_t len, bool is_last)
Definition: jsonapi.c:809
bool IsValidJsonNumber(const char *str, size_t len)
Definition: jsonapi.c:337
struct JsonLexContext JsonLexContext
JsonParseErrorType(* json_struct_action)(void *state)
Definition: jsonapi.h:119
JsonParseErrorType(* json_aelem_action)(void *state, bool isnull)
Definition: jsonapi.h:121
JsonParseErrorType pg_parse_json(JsonLexContext *lex, const JsonSemAction *sem)
Definition: jsonapi.c:685
#define jsonapi_StrValType
Definition: jsonapi.h:73
JsonParseErrorType
Definition: jsonapi.h:35
@ JSON_OUT_OF_MEMORY
Definition: jsonapi.h:52
@ JSON_SEM_ACTION_FAILED
Definition: jsonapi.h:59
@ JSON_EXPECTED_ARRAY_FIRST
Definition: jsonapi.h:42
@ JSON_EXPECTED_MORE
Definition: jsonapi.h:47
@ JSON_UNICODE_HIGH_SURROGATE
Definition: jsonapi.h:57
@ JSON_EXPECTED_COLON
Definition: jsonapi.h:44
@ JSON_EXPECTED_OBJECT_FIRST
Definition: jsonapi.h:48
@ JSON_UNICODE_CODE_POINT_ZERO
Definition: jsonapi.h:53
@ JSON_INVALID_LEXER_TYPE
Definition: jsonapi.h:38
@ JSON_EXPECTED_STRING
Definition: jsonapi.h:50
@ JSON_UNICODE_ESCAPE_FORMAT
Definition: jsonapi.h:54
@ JSON_SUCCESS
Definition: jsonapi.h:36
@ JSON_UNICODE_UNTRANSLATABLE
Definition: jsonapi.h:56
@ JSON_EXPECTED_OBJECT_NEXT
Definition: jsonapi.h:49
@ JSON_ESCAPING_REQUIRED
Definition: jsonapi.h:41
@ JSON_EXPECTED_JSON
Definition: jsonapi.h:46
@ JSON_INVALID_TOKEN
Definition: jsonapi.h:51
@ JSON_ESCAPING_INVALID
Definition: jsonapi.h:40
@ JSON_INCOMPLETE
Definition: jsonapi.h:37
@ JSON_EXPECTED_END
Definition: jsonapi.h:45
@ JSON_EXPECTED_ARRAY_NEXT
Definition: jsonapi.h:43
@ JSON_UNICODE_HIGH_ESCAPE
Definition: jsonapi.h:55
@ JSON_NESTING_TOO_DEEP
Definition: jsonapi.h:39
@ JSON_UNICODE_LOW_SURROGATE
Definition: jsonapi.h:58
JsonParseErrorType(* json_ofield_action)(void *state, char *fname, bool isnull)
Definition: jsonapi.h:120
char * json_errdetail(JsonParseErrorType error, JsonLexContext *lex)
Definition: jsonapi.c:2311
PGDLLIMPORT const JsonSemAction nullSemAction
Definition: jsonapi.c:285
JsonTokenType
Definition: jsonapi.h:18
@ JSON_TOKEN_INVALID
Definition: jsonapi.h:19
@ JSON_TOKEN_COMMA
Definition: jsonapi.h:26
@ JSON_TOKEN_FALSE
Definition: jsonapi.h:29
@ JSON_TOKEN_END
Definition: jsonapi.h:31
@ JSON_TOKEN_TRUE
Definition: jsonapi.h:28
@ JSON_TOKEN_OBJECT_END
Definition: jsonapi.h:23
@ JSON_TOKEN_NULL
Definition: jsonapi.h:30
@ JSON_TOKEN_ARRAY_END
Definition: jsonapi.h:25
@ JSON_TOKEN_OBJECT_START
Definition: jsonapi.h:22
@ JSON_TOKEN_NUMBER
Definition: jsonapi.h:21
@ JSON_TOKEN_STRING
Definition: jsonapi.h:20
@ JSON_TOKEN_COLON
Definition: jsonapi.h:27
@ JSON_TOKEN_ARRAY_START
Definition: jsonapi.h:24
JsonParseErrorType json_lex(JsonLexContext *lex)
Definition: jsonapi.c:1498
JsonParseErrorType(* json_scalar_action)(void *state, char *token, JsonTokenType tokentype)
Definition: jsonapi.h:122
JsonLexContext * makeJsonLexContextCstringLen(JsonLexContext *lex, const char *json, size_t len, int encoding, bool need_escapes)
Definition: jsonapi.c:390
JsonParseErrorType json_count_array_elements(JsonLexContext *lex, int *elements)
Definition: jsonapi.c:744
void freeJsonLexContext(JsonLexContext *lex)
Definition: jsonapi.c:639
JsonLexContext * makeJsonLexContextIncremental(JsonLexContext *lex, int encoding, bool need_escapes)
Definition: jsonapi.c:488
struct JsonSemAction JsonSemAction
const void size_t len
int32 encoding
Definition: pg_database.h:41
static void error(void)
Definition: sql-dyntest.c:147
bits32 flags
Definition: jsonapi.h:109
int input_encoding
Definition: jsonapi.h:102
const char * prev_token_terminator
Definition: jsonapi.h:105
struct jsonapi_StrValType * strval
Definition: jsonapi.h:115
bool need_escapes
Definition: jsonapi.h:114
struct jsonapi_StrValType * errormsg
Definition: jsonapi.h:116
const char * input
Definition: jsonapi.h:100
const char * token_start
Definition: jsonapi.h:103
JsonParserStack * pstack
Definition: jsonapi.h:112
size_t input_length
Definition: jsonapi.h:101
JsonIncrementalState * inc_state
Definition: jsonapi.h:113
bool incremental
Definition: jsonapi.h:106
const char * line_start
Definition: jsonapi.h:111
int line_number
Definition: jsonapi.h:110
JsonTokenType token_type
Definition: jsonapi.h:107
const char * token_terminator
Definition: jsonapi.h:104
json_struct_action array_end
Definition: jsonapi.h:148
json_struct_action object_start
Definition: jsonapi.h:145
json_ofield_action object_field_start
Definition: jsonapi.h:149
json_aelem_action array_element_start
Definition: jsonapi.h:151
json_scalar_action scalar
Definition: jsonapi.h:153
void * semstate
Definition: jsonapi.h:144
json_aelem_action array_element_end
Definition: jsonapi.h:152
json_struct_action array_start
Definition: jsonapi.h:147
json_struct_action object_end
Definition: jsonapi.h:146
json_ofield_action object_field_end
Definition: jsonapi.h:150
Definition: regguts.h:323
static JsonSemAction sem