2013-03-29 19:12:13 +01:00
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* jsonapi.h
|
|
|
|
* Declarations for JSON API support.
|
|
|
|
*
|
2016-01-02 19:33:40 +01:00
|
|
|
* Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group
|
2013-03-29 19:12:13 +01:00
|
|
|
* Portions Copyright (c) 1994, Regents of the University of California
|
|
|
|
*
|
|
|
|
* src/include/utils/jsonapi.h
|
|
|
|
*
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef JSONAPI_H
|
|
|
|
#define JSONAPI_H
|
|
|
|
|
|
|
|
#include "lib/stringinfo.h"
|
|
|
|
|
|
|
|
typedef enum
|
|
|
|
{
|
|
|
|
JSON_TOKEN_INVALID,
|
|
|
|
JSON_TOKEN_STRING,
|
|
|
|
JSON_TOKEN_NUMBER,
|
|
|
|
JSON_TOKEN_OBJECT_START,
|
|
|
|
JSON_TOKEN_OBJECT_END,
|
|
|
|
JSON_TOKEN_ARRAY_START,
|
|
|
|
JSON_TOKEN_ARRAY_END,
|
|
|
|
JSON_TOKEN_COMMA,
|
|
|
|
JSON_TOKEN_COLON,
|
|
|
|
JSON_TOKEN_TRUE,
|
|
|
|
JSON_TOKEN_FALSE,
|
|
|
|
JSON_TOKEN_NULL,
|
2014-04-04 17:26:01 +02:00
|
|
|
JSON_TOKEN_END
|
2013-05-29 22:58:43 +02:00
|
|
|
} JsonTokenType;
|
2013-03-29 19:12:13 +01:00
|
|
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
* All the fields in this structure should be treated as read-only.
|
|
|
|
*
|
|
|
|
* If strval is not null, then it should contain the de-escaped value
|
|
|
|
* of the lexeme if it's a string. Otherwise most of these field names
|
|
|
|
* should be self-explanatory.
|
|
|
|
*
|
|
|
|
* line_number and line_start are principally for use by the parser's
|
|
|
|
* error reporting routines.
|
|
|
|
* token_terminator and prev_token_terminator point to the character
|
|
|
|
* AFTER the end of the token, i.e. where there would be a nul byte
|
|
|
|
* if we were using nul-terminated strings.
|
|
|
|
*/
|
|
|
|
typedef struct JsonLexContext
|
|
|
|
{
|
|
|
|
char *input;
|
|
|
|
int input_length;
|
|
|
|
char *token_start;
|
|
|
|
char *token_terminator;
|
|
|
|
char *prev_token_terminator;
|
|
|
|
JsonTokenType token_type;
|
|
|
|
int lex_level;
|
|
|
|
int line_number;
|
|
|
|
char *line_start;
|
|
|
|
StringInfo strval;
|
|
|
|
} JsonLexContext;
|
|
|
|
|
|
|
|
typedef void (*json_struct_action) (void *state);
|
|
|
|
typedef void (*json_ofield_action) (void *state, char *fname, bool isnull);
|
|
|
|
typedef void (*json_aelem_action) (void *state, bool isnull);
|
|
|
|
typedef void (*json_scalar_action) (void *state, char *token, JsonTokenType tokentype);
|
|
|
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Semantic Action structure for use in parsing json.
|
|
|
|
* Any of these actions can be NULL, in which case nothing is done at that
|
|
|
|
* point, Likewise, semstate can be NULL. Using an all-NULL structure amounts
|
|
|
|
* to doing a pure parse with no side-effects, and is therefore exactly
|
|
|
|
* what the json input routines do.
|
2014-05-09 10:32:28 +02:00
|
|
|
*
|
|
|
|
* The 'fname' and 'token' strings passed to these actions are palloc'd.
|
|
|
|
* They are not free'd or used further by the parser, so the action function
|
|
|
|
* is free to do what it wishes with them.
|
2013-03-29 19:12:13 +01:00
|
|
|
*/
|
2013-07-20 12:38:31 +02:00
|
|
|
typedef struct JsonSemAction
|
2013-03-29 19:12:13 +01:00
|
|
|
{
|
|
|
|
void *semstate;
|
|
|
|
json_struct_action object_start;
|
|
|
|
json_struct_action object_end;
|
|
|
|
json_struct_action array_start;
|
|
|
|
json_struct_action array_end;
|
|
|
|
json_ofield_action object_field_start;
|
|
|
|
json_ofield_action object_field_end;
|
|
|
|
json_aelem_action array_element_start;
|
|
|
|
json_aelem_action array_element_end;
|
|
|
|
json_scalar_action scalar;
|
2013-07-20 12:38:31 +02:00
|
|
|
} JsonSemAction;
|
2013-03-29 19:12:13 +01:00
|
|
|
|
|
|
|
/*
|
|
|
|
* parse_json will parse the string in the lex calling the
|
|
|
|
* action functions in sem at the appropriate points. It is
|
|
|
|
* up to them to keep what state they need in semstate. If they
|
|
|
|
* need access to the state of the lexer, then its pointer
|
|
|
|
* should be passed to them as a member of whatever semstate
|
|
|
|
* points to. If the action pointers are NULL the parser
|
|
|
|
* does nothing and just continues.
|
|
|
|
*/
|
2013-07-20 12:38:31 +02:00
|
|
|
extern void pg_parse_json(JsonLexContext *lex, JsonSemAction *sem);
|
2013-03-29 19:12:13 +01:00
|
|
|
|
Support JSON negative array subscripts everywhere
Previously, there was an inconsistency across json/jsonb operators that
operate on datums containing JSON arrays -- only some operators
supported negative array count-from-the-end subscripting. Specifically,
only a new-to-9.5 jsonb deletion operator had support (the new "jsonb -
integer" operator). This inconsistency seemed likely to be
counter-intuitive to users. To fix, allow all places where the user can
supply an integer subscript to accept a negative subscript value,
including path-orientated operators and functions, as well as other
extraction operators. This will need to be called out as an
incompatibility in the 9.5 release notes, since it's possible that users
are relying on certain established extraction operators changed here
yielding NULL in the event of a negative subscript.
For the json type, this requires adding a way of cheaply getting the
total JSON array element count ahead of time when parsing arrays with a
negative subscript involved, necessitating an ad-hoc lex and parse.
This is followed by a "conversion" from a negative subscript to its
equivalent positive-wise value using the count. From there on, it's as
if a positive-wise value was originally provided.
Note that there is still a minor inconsistency here across jsonb
deletion operators. Unlike the aforementioned new "-" deletion operator
that accepts an integer on its right hand side, the new "#-" path
orientated deletion variant does not throw an error when it appears like
an array subscript (input that could be recognized by as an integer
literal) is being used on an object, which is wrong-headed. The reason
for not being stricter is that it could be the case that an object pair
happens to have a key value that looks like an integer; in general,
these two possibilities are impossible to differentiate with rhs path
text[] argument elements. However, we still don't allow the "#-"
path-orientated deletion operator to perform array-style subscripting.
Rather, we just return the original left operand value in the event of a
negative subscript (which seems analogous to how the established
"jsonb/json #> text[]" path-orientated operator may yield NULL in the
event of an invalid subscript).
In passing, make SetArrayPath() stricter about not accepting cases where
there is trailing non-numeric garbage bytes rather than a clean NUL
byte. This means, for example, that strings like "10e10" are now not
accepted as an array subscript of 10 by some new-to-9.5 path-orientated
jsonb operators (e.g. the new #- operator). Finally, remove dead code
for jsonb subscript deletion; arguably, this should have been done in
commit b81c7b409.
Peter Geoghegan and Andrew Dunstan
2015-07-18 02:56:13 +02:00
|
|
|
/*
|
|
|
|
* json_count_array_elements performs a fast secondary parse to determine the
|
|
|
|
* number of elements in passed array lex context. It should be called from an
|
|
|
|
* array_start action.
|
|
|
|
*/
|
2016-06-10 00:02:36 +02:00
|
|
|
extern int json_count_array_elements(JsonLexContext *lex);
|
Support JSON negative array subscripts everywhere
Previously, there was an inconsistency across json/jsonb operators that
operate on datums containing JSON arrays -- only some operators
supported negative array count-from-the-end subscripting. Specifically,
only a new-to-9.5 jsonb deletion operator had support (the new "jsonb -
integer" operator). This inconsistency seemed likely to be
counter-intuitive to users. To fix, allow all places where the user can
supply an integer subscript to accept a negative subscript value,
including path-orientated operators and functions, as well as other
extraction operators. This will need to be called out as an
incompatibility in the 9.5 release notes, since it's possible that users
are relying on certain established extraction operators changed here
yielding NULL in the event of a negative subscript.
For the json type, this requires adding a way of cheaply getting the
total JSON array element count ahead of time when parsing arrays with a
negative subscript involved, necessitating an ad-hoc lex and parse.
This is followed by a "conversion" from a negative subscript to its
equivalent positive-wise value using the count. From there on, it's as
if a positive-wise value was originally provided.
Note that there is still a minor inconsistency here across jsonb
deletion operators. Unlike the aforementioned new "-" deletion operator
that accepts an integer on its right hand side, the new "#-" path
orientated deletion variant does not throw an error when it appears like
an array subscript (input that could be recognized by as an integer
literal) is being used on an object, which is wrong-headed. The reason
for not being stricter is that it could be the case that an object pair
happens to have a key value that looks like an integer; in general,
these two possibilities are impossible to differentiate with rhs path
text[] argument elements. However, we still don't allow the "#-"
path-orientated deletion operator to perform array-style subscripting.
Rather, we just return the original left operand value in the event of a
negative subscript (which seems analogous to how the established
"jsonb/json #> text[]" path-orientated operator may yield NULL in the
event of an invalid subscript).
In passing, make SetArrayPath() stricter about not accepting cases where
there is trailing non-numeric garbage bytes rather than a clean NUL
byte. This means, for example, that strings like "10e10" are now not
accepted as an array subscript of 10 by some new-to-9.5 path-orientated
jsonb operators (e.g. the new #- operator). Finally, remove dead code
for jsonb subscript deletion; arguably, this should have been done in
commit b81c7b409.
Peter Geoghegan and Andrew Dunstan
2015-07-18 02:56:13 +02:00
|
|
|
|
2013-03-29 19:12:13 +01:00
|
|
|
/*
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
* constructors for JsonLexContext, with or without strval element.
|
2013-03-29 19:12:13 +01:00
|
|
|
* If supplied, the strval element will contain a de-escaped version of
|
|
|
|
* the lexeme. However, doing this imposes a performance penalty, so
|
|
|
|
* it should be avoided if the de-escaped lexeme is not required.
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
*
|
|
|
|
* If you already have the json as a text* value, use the first of these
|
|
|
|
* functions, otherwise use makeJsonLexContextCstringLen().
|
2013-03-29 19:12:13 +01:00
|
|
|
*/
|
|
|
|
extern JsonLexContext *makeJsonLexContext(text *json, bool need_escapes);
|
Introduce jsonb, a structured format for storing json.
The new format accepts exactly the same data as the json type. However, it is
stored in a format that does not require reparsing the orgiginal text in order
to process it, making it much more suitable for indexing and other operations.
Insignificant whitespace is discarded, and the order of object keys is not
preserved. Neither are duplicate object keys kept - the later value for a given
key is the only one stored.
The new type has all the functions and operators that the json type has,
with the exception of the json generation functions (to_json, json_agg etc.)
and with identical semantics. In addition, there are operator classes for
hash and btree indexing, and two classes for GIN indexing, that have no
equivalent in the json type.
This feature grew out of previous work by Oleg Bartunov and Teodor Sigaev, which
was intended to provide similar facilities to a nested hstore type, but which
in the end proved to have some significant compatibility issues.
Authors: Oleg Bartunov, Teodor Sigaev, Peter Geoghegan and Andrew Dunstan.
Review: Andres Freund
2014-03-23 21:40:19 +01:00
|
|
|
extern JsonLexContext *makeJsonLexContextCstringLen(char *json,
|
2014-05-06 18:12:18 +02:00
|
|
|
int len,
|
|
|
|
bool need_escapes);
|
2013-03-29 19:12:13 +01:00
|
|
|
|
2014-12-01 17:28:45 +01:00
|
|
|
/*
|
|
|
|
* Utility function to check if a string is a valid JSON number.
|
|
|
|
*
|
|
|
|
* str agrument does not need to be nul-terminated.
|
|
|
|
*/
|
2015-05-24 03:35:49 +02:00
|
|
|
extern bool IsValidJsonNumber(const char *str, int len);
|
2014-12-01 17:28:45 +01:00
|
|
|
|
2013-03-29 19:12:13 +01:00
|
|
|
#endif /* JSONAPI_H */
|