PostgreSQL Source Code  git master
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-2023, 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 #include "lib/stringinfo.h"
18 
19 typedef enum JsonTokenType
20 {
35 
36 typedef enum JsonParseErrorType
37 {
57  JSON_SEM_ACTION_FAILED, /* error should already be reported */
59 
60 
61 /*
62  * All the fields in this structure should be treated as read-only.
63  *
64  * If strval is not null, then it should contain the de-escaped value
65  * of the lexeme if it's a string. Otherwise most of these field names
66  * should be self-explanatory.
67  *
68  * line_number and line_start are principally for use by the parser's
69  * error reporting routines.
70  * token_terminator and prev_token_terminator point to the character
71  * AFTER the end of the token, i.e. where there would be a nul byte
72  * if we were using nul-terminated strings.
73  *
74  * JSONLEX_FREE_STRUCT/STRVAL are used to drive freeJsonLexContext.
75  */
76 #define JSONLEX_FREE_STRUCT (1 << 0)
77 #define JSONLEX_FREE_STRVAL (1 << 1)
78 typedef struct JsonLexContext
79 {
80  char *input;
83  char *token_start;
87  int lex_level;
89  int line_number; /* line number, starting from 1 */
90  char *line_start; /* where that line starts within input */
93 
95 typedef JsonParseErrorType (*json_ofield_action) (void *state, char *fname, bool isnull);
96 typedef JsonParseErrorType (*json_aelem_action) (void *state, bool isnull);
97 typedef JsonParseErrorType (*json_scalar_action) (void *state, char *token, JsonTokenType tokentype);
98 
99 
100 /*
101  * Semantic Action structure for use in parsing json.
102  *
103  * Any of these actions can be NULL, in which case nothing is done at that
104  * point, Likewise, semstate can be NULL. Using an all-NULL structure amounts
105  * to doing a pure parse with no side-effects, and is therefore exactly
106  * what the json input routines do.
107  *
108  * The 'fname' and 'token' strings passed to these actions are palloc'd.
109  * They are not free'd or used further by the parser, so the action function
110  * is free to do what it wishes with them.
111  *
112  * All action functions return JsonParseErrorType. If the result isn't
113  * JSON_SUCCESS, the parse is abandoned and that error code is returned.
114  * If it is JSON_SEM_ACTION_FAILED, the action function is responsible
115  * for having reported the error in some appropriate way.
116  */
117 typedef struct JsonSemAction
118 {
119  void *semstate;
130 
131 /*
132  * pg_parse_json will parse the string in the lex calling the
133  * action functions in sem at the appropriate points. It is
134  * up to them to keep what state they need in semstate. If they
135  * need access to the state of the lexer, then its pointer
136  * should be passed to them as a member of whatever semstate
137  * points to. If the action pointers are NULL the parser
138  * does nothing and just continues.
139  */
141  JsonSemAction *sem);
142 
143 /* the null action object used for pure validation */
145 
146 /*
147  * json_count_array_elements performs a fast secondary parse to determine the
148  * number of elements in passed array lex context. It should be called from an
149  * array_start action.
150  *
151  * The return value indicates whether any error occurred, while the number
152  * of elements is stored into *elements (but only if the return value is
153  * JSON_SUCCESS).
154  */
156  int *elements);
157 
158 /*
159  * initializer for JsonLexContext.
160  *
161  * If a valid 'lex' pointer is given, it is initialized. This can be used
162  * for stack-allocated structs, saving overhead. If NULL is given, a new
163  * struct is allocated.
164  *
165  * If need_escapes is true, ->strval stores the unescaped lexemes.
166  * Unescaping is expensive, so only request it when necessary.
167  *
168  * If need_escapes is true or lex was given as NULL, then the caller is
169  * responsible for freeing the returned struct, either by calling
170  * freeJsonLexContext() or (in backend environment) via memory context
171  * cleanup.
172  */
174  char *json,
175  int len,
176  int encoding,
177  bool need_escapes);
178 extern void freeJsonLexContext(JsonLexContext *lex);
179 
180 /* lex one token */
182 
183 /* construct an error detail string for a json error */
185 
186 /*
187  * Utility function to check if a string is a valid JSON number.
188  *
189  * str argument does not need to be nul-terminated.
190  */
191 extern bool IsValidJsonNumber(const char *str, int len);
192 
193 #endif /* JSONAPI_H */
#define PGDLLIMPORT
Definition: c.h:1326
uint32 bits32
Definition: c.h:504
#define token
Definition: indent_globs.h:126
PGDLLIMPORT JsonSemAction nullSemAction
Definition: jsonapi.c:57
struct JsonLexContext JsonLexContext
JsonParseErrorType(* json_struct_action)(void *state)
Definition: jsonapi.h:94
JsonParseErrorType(* json_aelem_action)(void *state, bool isnull)
Definition: jsonapi.h:96
JsonParseErrorType
Definition: jsonapi.h:37
@ JSON_SEM_ACTION_FAILED
Definition: jsonapi.h:57
@ JSON_EXPECTED_ARRAY_FIRST
Definition: jsonapi.h:41
@ JSON_EXPECTED_MORE
Definition: jsonapi.h:46
@ JSON_UNICODE_HIGH_SURROGATE
Definition: jsonapi.h:55
@ JSON_EXPECTED_COLON
Definition: jsonapi.h:43
@ JSON_EXPECTED_OBJECT_FIRST
Definition: jsonapi.h:47
@ JSON_UNICODE_CODE_POINT_ZERO
Definition: jsonapi.h:51
@ JSON_EXPECTED_STRING
Definition: jsonapi.h:49
@ JSON_UNICODE_ESCAPE_FORMAT
Definition: jsonapi.h:52
@ JSON_SUCCESS
Definition: jsonapi.h:38
@ JSON_UNICODE_UNTRANSLATABLE
Definition: jsonapi.h:54
@ JSON_EXPECTED_OBJECT_NEXT
Definition: jsonapi.h:48
@ JSON_ESCAPING_REQUIRED
Definition: jsonapi.h:40
@ JSON_EXPECTED_JSON
Definition: jsonapi.h:45
@ JSON_INVALID_TOKEN
Definition: jsonapi.h:50
@ JSON_ESCAPING_INVALID
Definition: jsonapi.h:39
@ JSON_EXPECTED_END
Definition: jsonapi.h:44
@ JSON_EXPECTED_ARRAY_NEXT
Definition: jsonapi.h:42
@ JSON_UNICODE_HIGH_ESCAPE
Definition: jsonapi.h:53
@ JSON_UNICODE_LOW_SURROGATE
Definition: jsonapi.h:56
JsonParseErrorType(* json_ofield_action)(void *state, char *fname, bool isnull)
Definition: jsonapi.h:95
char * json_errdetail(JsonParseErrorType error, JsonLexContext *lex)
Definition: jsonapi.c:1172
bool IsValidJsonNumber(const char *str, int len)
Definition: jsonapi.c:105
JsonParseErrorType pg_parse_json(JsonLexContext *lex, JsonSemAction *sem)
Definition: jsonapi.c:205
JsonTokenType
Definition: jsonapi.h:20
@ JSON_TOKEN_INVALID
Definition: jsonapi.h:21
@ JSON_TOKEN_COMMA
Definition: jsonapi.h:28
@ JSON_TOKEN_FALSE
Definition: jsonapi.h:31
@ JSON_TOKEN_END
Definition: jsonapi.h:33
@ JSON_TOKEN_TRUE
Definition: jsonapi.h:30
@ JSON_TOKEN_OBJECT_END
Definition: jsonapi.h:25
@ JSON_TOKEN_NULL
Definition: jsonapi.h:32
@ JSON_TOKEN_ARRAY_END
Definition: jsonapi.h:27
@ JSON_TOKEN_OBJECT_START
Definition: jsonapi.h:24
@ JSON_TOKEN_NUMBER
Definition: jsonapi.h:23
@ JSON_TOKEN_STRING
Definition: jsonapi.h:22
@ JSON_TOKEN_COLON
Definition: jsonapi.h:29
@ JSON_TOKEN_ARRAY_START
Definition: jsonapi.h:26
JsonParseErrorType json_lex(JsonLexContext *lex)
Definition: jsonapi.c:588
JsonParseErrorType(* json_scalar_action)(void *state, char *token, JsonTokenType tokentype)
Definition: jsonapi.h:97
JsonLexContext * makeJsonLexContextCstringLen(JsonLexContext *lex, char *json, int len, int encoding, bool need_escapes)
Definition: jsonapi.c:153
JsonParseErrorType json_count_array_elements(JsonLexContext *lex, int *elements)
Definition: jsonapi.c:245
void freeJsonLexContext(JsonLexContext *lex)
Definition: jsonapi.c:183
struct JsonSemAction JsonSemAction
const void size_t len
int32 encoding
Definition: pg_database.h:41
static void error(void)
Definition: sql-dyntest.c:147
char * input
Definition: jsonapi.h:80
bits32 flags
Definition: jsonapi.h:88
char * token_start
Definition: jsonapi.h:83
int input_encoding
Definition: jsonapi.h:82
StringInfo strval
Definition: jsonapi.h:91
char * token_terminator
Definition: jsonapi.h:84
char * prev_token_terminator
Definition: jsonapi.h:85
char * line_start
Definition: jsonapi.h:90
int lex_level
Definition: jsonapi.h:87
int input_length
Definition: jsonapi.h:81
int line_number
Definition: jsonapi.h:89
JsonTokenType token_type
Definition: jsonapi.h:86
json_struct_action array_end
Definition: jsonapi.h:123
json_struct_action object_start
Definition: jsonapi.h:120
json_ofield_action object_field_start
Definition: jsonapi.h:124
json_aelem_action array_element_start
Definition: jsonapi.h:126
json_scalar_action scalar
Definition: jsonapi.h:128
void * semstate
Definition: jsonapi.h:119
json_aelem_action array_element_end
Definition: jsonapi.h:127
json_struct_action array_start
Definition: jsonapi.h:122
json_struct_action object_end
Definition: jsonapi.h:121
json_ofield_action object_field_end
Definition: jsonapi.h:125
Definition: regguts.h:323