@amxts/core 0.1.0

package/amxmodx/base/include/json.inc

@@ -0,0 +1,777 @@
+// vim: set ts=4 sw=4 tw=99 noet:
+//
+// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
+// Copyright (C) The AMX Mod X Development Team.
+//
+// This software is licensed under the GNU General Public License, version 3 or higher.
+// Additional exceptions apply. For full license details, see LICENSE.txt or visit:
+//     https://alliedmods.net/amxmodx-license
+
+//
+// JSON Natives
+//
+
+#if defined _json_included
+	#endinput
+#endif
+#define _json_included
+
+#pragma reqlib json
+#if !defined AMXMODX_NOAUTOLOAD
+	#pragma loadlib json
+#endif
+
+/*
+ * JSON types
+ */
+enum JSONType
+{
+	JSONError   = -1,
+	JSONNull    = 1,
+	JSONString  = 2,
+	JSONNumber  = 3,
+	JSONObject  = 4,
+	JSONArray   = 5,
+	JSONBoolean = 6
+};
+
+/*
+ * JSON invalid handle
+ */
+enum JSON
+{
+	Invalid_JSON = -1
+}
+
+/**
+ * Helper macros for checking type
+ */
+#define json_is_object(%1)   (%1 != Invalid_JSON && json_get_type(%1) == JSONObject)
+#define json_is_array(%1)    (%1 != Invalid_JSON && json_get_type(%1) == JSONArray)
+#define json_is_string(%1)   (%1 != Invalid_JSON && json_get_type(%1) == JSONString)
+#define json_is_number(%1)   (%1 != Invalid_JSON && json_get_type(%1) == JSONNumber)
+#define json_is_bool(%1)     (%1 != Invalid_JSON && json_get_type(%1) == JSONBoolean)
+#define json_is_null(%1)     (%1 != Invalid_JSON && json_get_type(%1) == JSONNull)
+#define json_is_true(%1)     (%1 != Invalid_JSON && json_is_bool(%1) && json_get_bool(%1))
+#define json_is_false(%1)    (%1 != Invalid_JSON && json_is_bool(%1) && !json_get_bool(%1))
+
+/**
+ * Parses JSON string or a file that contains JSON.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param string            String to parse
+ * @param is_file           True to treat string param as filename, false otherwise
+ * @param with_comments     True if parsing JSON includes comments (it will ignore them), false otherwise
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_parse(const string[], bool:is_file = false, bool:with_comments = false);
+
+/**
+ * Checks if the first value is the same as the second one.
+ *
+ * @param value1            JSON handle
+ * @param value2            JSON handle
+ *
+ * @return                  True if they are the same, false otherwise
+ * @error                   If passed value is not a valid handle
+ */
+native bool:json_equals(const JSON:value1, const JSON:value2);
+
+/**
+ * Validates json by checking if object have identically named
+ * fields with matching types.
+ *
+ * @note                    Schema {"name":"", "age":0} will validate
+ *                          {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"},
+ *                          but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}.
+ *
+ * @note                    In case of arrays, only first value in schema
+ *                          is checked against all values in tested array.
+ *
+ * @note                    Empty objects ({}) validate all objects,
+ *                          empty arrays ([]) validate all arrays,
+ *                          null validates values of every type.
+ *
+ * @param schema            JSON handle
+ * @param value             JSON handle
+ *
+ * @return                  True if passed value is valid, false otherwise
+ * @error                   If a schema handle or value handle is invalid
+ */
+native bool:json_validate(const JSON:schema, const JSON:value);
+
+/**
+ * Gets value's parent handle.
+ *
+ * @note                  Parent's handle needs to be freed using json_free() native.
+ *
+ * @param value           JSON handle
+ *
+ * @return                Parent's handle
+ */
+native JSON:json_get_parent(const JSON:value);
+
+/**
+ * Gets JSON type of passed value.
+ *
+ * @param value             JSON handle
+ *
+ * @return                  JSON type (JSONType constants)
+ * @error                   If a value handle is invalid
+ */
+native JSONType:json_get_type(const JSON:value);
+
+/**
+ * Inits an empty object.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_object();
+
+/**
+ * Inits an empty array.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_array();
+
+/**
+ * Inits string data.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param value             String that the handle will be initialized with
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_string(const value[]);
+
+/**
+ * Inits a number.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param value             Integer number that the handle will be initialized with
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_number(value);
+
+/**
+ * Inits a real number.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param value             Real number that the handle will be initialized with
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_real(Float:value);
+
+/**
+ * Inits a boolean value.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param value             Boolean value that the handle will be initialized with
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_bool(bool:value);
+
+/**
+ * Inits a null.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ */
+native JSON:json_init_null();
+
+/**
+ * Creates deep copy of passed value.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param value             JSON handle to be copied
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ * @error                   If passed value is not a valid handle
+ */
+native JSON:json_deep_copy(const JSON:value);
+
+/**
+ * Frees handle.
+ *
+ * @param handle            JSON handle to be freed
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid handle
+ */
+native bool:json_free(&JSON:handle);
+
+/**
+ * Gets string data.
+ *
+ * @param value             JSON handle
+ * @param buffer            Buffer to copy string to
+ * @param maxlen            Maximum size of the buffer
+ *
+ * @return                  The number of cells written to the buffer
+ * @error                   If passed value is not a valid handle
+ */
+native json_get_string(const JSON:value, buffer[], maxlen);
+
+/**
+ * Gets a number.
+ *
+ * @param value             JSON handle
+ *
+ * @return                  Number
+ * @error                   If passed value is not a valid handle
+ */
+native json_get_number(const JSON:value);
+
+/**
+ * Gets a real number.
+ *
+ * @param value             JSON handle
+ *
+ * @return                  Real number
+ * @error                   If passed value is not a valid handle
+ */
+native Float:json_get_real(const JSON:value);
+
+/**
+ * Gets a boolean value.
+ *
+ * @param value             JSON handle
+ *
+ * @return                  Boolean value
+ * @error                   If passed value is not a valid handle
+ */
+native bool:json_get_bool(const JSON:value);
+
+/**
+ * Gets a value from the array.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ * @error                   If passed handle is not a valid array
+ */
+native JSON:json_array_get_value(const JSON:array, index);
+
+/**
+ * Gets string data from the array.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ * @param buffer            Buffer to copy string to
+ * @param maxlen            Maximum size of the buffer
+ *
+ * @return                  The number of cells written to the buffer
+ * @error                   If passed handle is not a valid array
+ */
+native json_array_get_string(const JSON:array, index, buffer[], maxlen);
+
+/**
+ * Gets a number from the array.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ *
+ * @return                  The number as integer
+ * @error                   If passed handle is not a valid array
+ */
+native json_array_get_number(const JSON:array, index);
+
+/**
+ * Gets a real number from the array.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ *
+ * @return                  The number as float
+ * @error                   If passed handle is not a valid array
+ */
+native Float:json_array_get_real(const JSON:array, index);
+
+/**
+ * Gets a boolean value from the array.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ *
+ * @return                  Boolean value
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_get_bool(const JSON:array, index);
+
+/**
+ * Gets count of the elements in the array.
+ *
+ * @param array             Array handle
+ *
+ * @return                  Number of elements in the array
+ * @error                   If passed handle is not a valid array
+ */
+native json_array_get_count(const JSON:array);
+
+/**
+ * Replaces an element in the array with value.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ * @param value             JSON handle to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_value(JSON:array, index, const JSON:value);
+
+/**
+ * Replaces an element in the array with string data.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ * @param string            String to copy
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_string(JSON:array, index, const string[]);
+
+/**
+ * Replaces an element in the array with number.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ * @param number            Number to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_number(JSON:array, index, number);
+
+/**
+ * Replaces an element in the array with real number.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ * @param number            Real number to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_real(JSON:array, index, Float:number);
+
+/**
+ * Replaces an element in the array with boolean value.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ * @param boolean           Boolean value to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_bool(JSON:array, index, bool:boolean);
+
+/**
+ * Replaces an element in the array with null.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array to be replaced
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_replace_null(JSON:array, index);
+
+/**
+ * Appends a value in the array.
+ *
+ * @param array             Array handle
+ * @param value             JSON handle to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_value(JSON:array, const JSON:value);
+
+/**
+ * Appends string data in the array.
+ *
+ * @param array             Array handle
+ * @param string            String to copy
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_string(JSON:array, const string[]);
+
+/**
+ * Appends a number in the array.
+ *
+ * @param array             Array handle
+ * @param number            Number to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_number(JSON:array, number);
+
+/**
+ * Appends a real number in the array.
+ *
+ * @param array             Array handle
+ * @param number            Real number to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_real(JSON:array, Float:number);
+
+/**
+ * Appends a boolean value in the array.
+ *
+ * @param array             Array handle
+ * @param boolean           Boolean value to set
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_bool(JSON:array, bool:boolean);
+
+/**
+ * Appends a null in the array.
+ *
+ * @param array             Array handle
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_append_null(JSON:array);
+
+/**
+ * Removes an element from the array.
+ *
+ * @note                    Order of values in array may change during execution.
+ *
+ * @param array             Array handle
+ * @param index             Position in the array (starting from 0)
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_remove(JSON:array, index);
+
+/**
+ * Removes all elements from the array.
+ *
+ * @param array             Array handle
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid array
+ */
+native bool:json_array_clear(JSON:array);
+
+/**
+ * Gets a value from the object.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ * @error                   If passed handle is not a valid object
+ */
+native JSON:json_object_get_value(const JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Gets string data from the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param buffer            Buffer to copy string to
+ * @param maxlen            Maximum size of the buffer
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  The number of cells written to the buffer
+ * @error                   If passed handle is not a valid object
+ */
+native json_object_get_string(const JSON:object, const name[], buffer[], maxlen, bool:dot_not = false);
+
+/**
+ * Gets a number from the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  Number
+ * @error                   If passed handle is not a valid object
+ */
+native json_object_get_number(const JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Gets a real number from the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  Real number
+ * @error                   If passed handle is not a valid object
+ */
+native Float:json_object_get_real(const JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Gets a boolean value from the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  Boolean value
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_get_bool(const JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Gets count of the keys in the object.
+ *
+ * @param object            Object handle
+ *
+ * @return                  Keys count
+ * @error                   If passed handle is not a valid object
+ */
+native json_object_get_count(const JSON:object);
+
+/**
+ * Gets name of the object's key.
+ *
+ * @param object            Object handle
+ * @param index             Position from which get key name
+ * @param buffer            Buffer to copy string to
+ * @param maxlen            Maximum size of the buffer
+ *
+ * @return                  The number of cells written to the buffer
+ * @error                   If passed handle is not a valid object
+ */
+native json_object_get_name(const JSON:object, index, buffer[], maxlen);
+
+/**
+ * Gets a value at the specified position from the object.
+ *
+ * @note                    Needs to be freed using json_free() native.
+ *
+ * @param object            Object handle
+ * @param index             Position from which get key name
+ *
+ * @return                  JSON handle, Invalid_JSON if error occurred
+ * @error                   If passed handle is not a valid object
+ */
+native JSON:json_object_get_value_at(const JSON:object, index);
+
+/**
+ * Checks if the object has a value with a specific name and type.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param type              Type of value, if JSONError type will not be checked
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if has, false if not
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_has_value(const JSON:object, const name[], JSONType:type = JSONError, bool:dot_not = false);
+
+/**
+ * Sets a value in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param value             JSON handle to set
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_value(JSON:object, const name[], const JSON:value, bool:dot_not = false);
+
+/**
+ * Sets string data in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param string            String to copy
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_string(JSON:object, const name[], const string[], bool:dot_not = false);
+
+/**
+ * Sets a number in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param number            Number to set
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_number(JSON:object, const name[], number, bool:dot_not = false);
+
+/**
+ * Sets a real number in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param number            Real number to set
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_real(JSON:object, const name[], Float:number, bool:dot_not = false);
+
+/**
+ * Sets a boolean value in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param boolean           Boolean value to set
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_bool(JSON:object, const name[], bool:boolean, bool:dot_not = false);
+
+/**
+ * Sets a null in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ * @note                    It also removes the old value if any.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_set_null(JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Removes a key and its value in the object.
+ *
+ * @note                    If dot notation is used some values may be inaccessible
+ *                          because valid names in JSON can contain dots.
+ *
+ * @param object            Object handle
+ * @param name              Key name
+ * @param dot_not           True to use dot notation, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_remove(JSON:object, const name[], bool:dot_not = false);
+
+/**
+ * Removes all keys and their values in the object.
+ *
+ * @param object            Object handle
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid object
+ */
+native bool:json_object_clear(JSON:object);
+
+/**
+ * Gets size of serialization.
+ *
+ * @param value             JSON handle
+ * @param pretty            True to count size for pretty format, false to not
+ * @param null_byte         True to include null byte, false to not
+ *
+ * @return                  Size of serialized string
+ * @error                   If passed handle is not a valid value
+ */
+native json_serial_size(const JSON:value, bool:pretty = false, bool:null_byte = false);
+
+/**
+ * Copies serialized string to the buffer.
+ *
+ * @param value             JSON handle
+ * @param buffer            Buffer to copy string to
+ * @param maxlen            Maximum size of the buffer
+ * @param pretty            True to format pretty JSON string, false to not
+ *
+ * @return                  The number of cells written to the buffer
+ * @error                   If passed handle is not a valid value
+ */
+native json_serial_to_string(const JSON:value, buffer[], maxlen, bool:pretty = false);
+
+/**
+ * Copies serialized string to the file.
+ *
+ * @param value             JSON handle
+ * @param file              Path to the file
+ * @param pretty            True to format pretty JSON string, false to not
+ *
+ * @return                  True if succeed, false otherwise
+ * @error                   If passed handle is not a valid value
+ */
+native bool:json_serial_to_file(const JSON:value, const file[], bool:pretty = false);