forked from Telodendria/Telodendria
Jordan Bancino
3a683dbb70
These are installed to the system and some compilers may not find the headers in the current directory if we don't do this, even though according to the C standard, either should work.
323 lines
11 KiB
C
323 lines
11 KiB
C
/*
|
|
* Copyright (C) 2022-2023 Jordan Bancino <@jordan:bancino.net>
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person
|
|
* obtaining a copy of this software and associated documentation files
|
|
* (the "Software"), to deal in the Software without restriction,
|
|
* including without limitation the rights to use, copy, modify, merge,
|
|
* publish, distribute, sublicense, and/or sell copies of the Software,
|
|
* and to permit persons to whom the Software is furnished to do so,
|
|
* subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be
|
|
* included in all copies or portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
|
|
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
|
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
* SOFTWARE.
|
|
*/
|
|
|
|
#ifndef CYTOPLASM_JSON_H
|
|
#define CYTOPLASM_JSON_H
|
|
|
|
/***
|
|
* @Nm Json
|
|
* @Nd A fully-featured JSON API.
|
|
* @Dd March 12 2023
|
|
* @Xr HashMap Array Stream
|
|
*
|
|
* .Nm
|
|
* is a fully-featured JSON API for C using the array and hash map
|
|
* APIs. It can parse JSON, ans serialize an in-memory structure to
|
|
* JSON. It build on the foundation of Array and HashMap because that's
|
|
* all JSON really is, just arrays and maps.
|
|
* .Nm
|
|
* also provides a structure for encapsulating an arbitrary value and
|
|
* identifying its type, making it easy for a strictly-typed language
|
|
* like C to work with loosely-typed JSON data.
|
|
* .Nm
|
|
* is very strict and tries to adhere as closely as possible to the
|
|
* proper definition of JSON. It will fail on syntax errors of any
|
|
* kind, which is fine for a Matrix homeserver that can just return
|
|
* M_BAD_JSON if anything in here fails, but this behavior may not be
|
|
* suitable for other purposes.
|
|
* .Pp
|
|
* This JSON implementation focuses primarily on serialization and
|
|
* deserialization to and from streams. It does not provide facilities
|
|
* for handling JSON strings; it only writes JSON to output streams,
|
|
* and reads them from input streams. Of course, you can use the
|
|
* POSIX
|
|
* .Xr fmemopen 3
|
|
* and
|
|
* .Xr open_memstream 3
|
|
* functions if you want to deal with JSON strings, but JSON is
|
|
* intended to be an exchange format. Data should be converted to JSON
|
|
* right when it is leaving the program, and converted from JSON to the
|
|
* in-memory format as soon as it is coming in.
|
|
* .Pp
|
|
* JSON objects are represented as hash maps consisting entirely of
|
|
* JsonValue structures, and arrays are represented as arrays
|
|
* consisting entirely of JsonValue structures. When generating a
|
|
* JSON object, any attempt to stuff a value into a hash map or array
|
|
* without first encoding it as a JsonValue will result in undefined
|
|
* behavior.
|
|
*/
|
|
|
|
#include "HashMap.h"
|
|
#include "Array.h"
|
|
#include "Stream.h"
|
|
#include "Int64.h"
|
|
|
|
#include <stdio.h>
|
|
#include <stddef.h>
|
|
|
|
#define JSON_DEFAULT -1
|
|
#define JSON_PRETTY 0
|
|
|
|
/**
|
|
* This opaque structure encapsulates all the possible types that can
|
|
* be stored in JSON. It is managed entirely by the functions defined
|
|
* in this API. It is important to note that strings, integers, floats,
|
|
* booleans, and the NULL value are all stored by value, but objects
|
|
* and arrays are stored by reference. That is, it doesn't store these
|
|
* itself, just pointers to them, however, the data
|
|
* .Em is
|
|
* freed when using
|
|
* .Fn JsonFree .
|
|
*/
|
|
typedef struct JsonValue JsonValue;
|
|
|
|
/**
|
|
* These are the types that can be used to identify a JsonValue
|
|
* and act on it accordingly.
|
|
*/
|
|
typedef enum JsonType
|
|
{
|
|
JSON_NULL, /* Maps to a C NULL */
|
|
JSON_OBJECT, /* Maps to a HashMap of JsonValues */
|
|
JSON_ARRAY, /* Maps to an Array of JsonValues */
|
|
JSON_STRING, /* Maps to a null-terminated C string */
|
|
JSON_INTEGER, /* Maps to an Int64 */
|
|
JSON_FLOAT, /* Maps to a C double */
|
|
JSON_BOOLEAN /* Maps to a C integer of either 0 or 1 */
|
|
} JsonType;
|
|
|
|
/**
|
|
* Determine the type of the specified JSON value.
|
|
*/
|
|
extern JsonType JsonValueType(JsonValue *);
|
|
|
|
/**
|
|
* Encode a JSON object as a JSON value that can be added to another
|
|
* object, or an array.
|
|
*/
|
|
extern JsonValue * JsonValueObject(HashMap *);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents an object. This function will
|
|
* return NULL if the value is not actually an object.
|
|
*/
|
|
extern HashMap * JsonValueAsObject(JsonValue *);
|
|
|
|
/**
|
|
* Encode a JSON array as a JSON value that can be added to an object
|
|
* or another array.
|
|
*/
|
|
extern JsonValue * JsonValueArray(Array *);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents an array. This function will
|
|
* return NULL if the value is not actually an array.
|
|
*/
|
|
extern Array * JsonValueAsArray(JsonValue *);
|
|
|
|
/**
|
|
* Encode a C string as a JSON value that can be added to an object or
|
|
* an array.
|
|
*/
|
|
extern JsonValue * JsonValueString(char *);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents a string. This function will
|
|
* return NULL if the value is not actually a string.
|
|
*/
|
|
extern char * JsonValueAsString(JsonValue *);
|
|
|
|
/**
|
|
* Encode a number as a JSON value that can be added to an object or
|
|
* an array.
|
|
*/
|
|
extern JsonValue * JsonValueInteger(Int64);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents a number. This function will
|
|
* return 0 if the value is not actually a number, which may be
|
|
* misleading. Check the type of the value before making assumptions
|
|
* about its value.
|
|
*/
|
|
extern Int64 JsonValueAsInteger(JsonValue *);
|
|
|
|
/**
|
|
* Encode a floating point number as a JSON value that can be added
|
|
* to an object or an array.
|
|
*/
|
|
extern JsonValue * JsonValueFloat(double);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents a floating point number. This
|
|
* function will return 0 if the value is not actually a floating
|
|
* point number, which may be misleading. Check the type of the value
|
|
* before making assumptions about its type.
|
|
*/
|
|
extern double JsonValueAsFloat(JsonValue *);
|
|
|
|
/**
|
|
* Encode a C integer according to the way C treats integers in boolean
|
|
* expressions as a JSON value that can be added to an object or an
|
|
* array.
|
|
*/
|
|
extern JsonValue * JsonValueBoolean(int);
|
|
|
|
/**
|
|
* Unwrap a JSON value that represents a boolean. This function will
|
|
* return 0 if the value is not actually a boolean, which may be
|
|
* misleading. Check the type of the value before making assumptions
|
|
* about its type.
|
|
*/
|
|
extern int JsonValueAsBoolean(JsonValue *);
|
|
|
|
/**
|
|
* This is a special case that represents a JSON null. Because the
|
|
* Array and HashMap APIs do not accept NULL values, this function
|
|
* should be used to represent NULL in JSON. Even though a small
|
|
* amount of memory is allocated just to be a placeholder for nothing,
|
|
* this keeps the APIs clean.
|
|
*/
|
|
extern JsonValue * JsonValueNull(void);
|
|
|
|
/**
|
|
* Free the memory being used by a JSON value. Note that this will
|
|
* recursively free all Arrays, HashMaps, and other JsonValues that are
|
|
* reachable from the given value, including any strings attached to
|
|
* this value.
|
|
*/
|
|
extern void JsonValueFree(JsonValue *);
|
|
|
|
/**
|
|
* Recursively duplicate the given JSON value. This returns a new
|
|
* JSON value that is completely identical to the specified value, but
|
|
* in no way connected to it.
|
|
*/
|
|
extern JsonValue * JsonValueDuplicate(JsonValue *);
|
|
|
|
/**
|
|
* Recursively duplicate the given JSON object. This returns a new
|
|
* JSON object that is completely identical to the specified object,
|
|
* but in no way connect to it.
|
|
*/
|
|
extern HashMap * JsonDuplicate(HashMap *);
|
|
|
|
/**
|
|
* Recursively free a JSON object by iterating over all of its values
|
|
* and freeing them using
|
|
* .Fn JsonValueFree .
|
|
*/
|
|
extern void JsonFree(HashMap *);
|
|
|
|
/**
|
|
* Encode the given string in such a way that it can be safely
|
|
* embedded in a JSON stream. This entails:
|
|
* .Bl -bullet -offset indent
|
|
* .It
|
|
* Escaping quotes, backslashes, and other special characters using
|
|
* their backslash escape.
|
|
* .It
|
|
* Encoding bytes that are not UTF-8 using escapes.
|
|
* .It
|
|
* Wrapping the entire string in double quotes.
|
|
* .El
|
|
* .Pp
|
|
* This function is only provided via the public
|
|
* .Nm
|
|
* API so that it is accessible to custom JSON encoders, such as the
|
|
* CanonicalJson encoder. This will typically be used for encoding
|
|
* object keys; to encode values, just use
|
|
* .Fn JsonEncodeValue .
|
|
* .Pp
|
|
* This function returns the number of bytes written to the stream,
|
|
* or if the stream is NULL, the number of bytes that would have
|
|
* been written.
|
|
*/
|
|
extern int JsonEncodeString(const char *, Stream *);
|
|
|
|
/**
|
|
* Serialize a JSON value as it would appear in JSON output. This is
|
|
* a recursive function that also encodes all child values reachable
|
|
* from the given value. This function is exposed via the public
|
|
* .Nm
|
|
* API so that it is accessible to custom JSON encoders. Normal users
|
|
* that are not writing custom encoders should in most cases just use
|
|
* .Fn JsonEncode
|
|
* to encode an entire object.
|
|
* .Pp
|
|
* The third parameter is an integer that represents the indent level
|
|
* of the value to be printed, or a negative number if pretty-printing
|
|
* should be disabled and JSON should be printed as minimized as
|
|
* possible. To pretty-print a JSON object, set this to
|
|
* .Va JSON_PRETTY .
|
|
* To get minified output, set it to
|
|
* .Va JSON_DEFAULT .
|
|
* .Pp
|
|
* This function returns the number of bytes written to the stream,
|
|
* or if the stream is NULL, the number of bytes that would have
|
|
* been written.
|
|
*/
|
|
extern int JsonEncodeValue(JsonValue *, Stream *, int);
|
|
|
|
/**
|
|
* Encode a JSON object as it would appear in JSON output, writing it
|
|
* to the given output stream. This function is recursive; it will
|
|
* serialize everything accessible from the passed object. The third
|
|
* parameter has the same behavior as described above.
|
|
* .Pp
|
|
* This function returns the number of bytes written to the stream,
|
|
* or if the stream is NULL, the number of bytes that would have
|
|
* been written.
|
|
*/
|
|
extern int JsonEncode(HashMap *, Stream *, int);
|
|
|
|
/**
|
|
* Decode a JSON object from the given input stream and parse it into
|
|
* a hash map of JSON values.
|
|
*/
|
|
extern HashMap * JsonDecode(Stream *);
|
|
|
|
/**
|
|
* A convenience function that allows the caller to retrieve and
|
|
* arbitrarily deep keys within a JSON object. It takes a root JSON
|
|
* object, the number of levels deep to go, and then that number of
|
|
* keys as a varargs list. All keys must have objects as values, with
|
|
* the exception of the last one, which is the value that will be
|
|
* returned. Otherwise, NULL indicates the specified path doas not
|
|
* exist.
|
|
*/
|
|
extern JsonValue * JsonGet(HashMap *, size_t,...);
|
|
|
|
/**
|
|
* A convenience function that allows the caller to set arbitrarily
|
|
* deep keys within a JSON object. It takes a root JSON object, the
|
|
* number of levels deep to go, and then that number of keys as a
|
|
* varargs list. All keys must have object as values, with the
|
|
* exception of the last one, which is the value that will be set.
|
|
* The value currently at that key, if any, will be returned.
|
|
* This function will create any intermediate objects as necessary to
|
|
* set the proper key.
|
|
*/
|
|
extern JsonValue * JsonSet(HashMap *, JsonValue *, size_t,...);
|
|
|
|
#endif /* CYTOPLASM_JSON_H */
|