native_yyjson_helpers.h

Go to the documentation of this file.

/**
 * @file
 * @brief Declares shared helper wrappers around vendored yyjson parsing and serialization APIs.
 */
 
#ifndef PHAROS_NATIVE_YYJSON_HELPERS_H
#define PHAROS_NATIVE_YYJSON_HELPERS_H
 
#include "yyjson.h"
 
/** @name Shared yyjson helper APIs
 * @{ 
 */
 
/**
 * @brief Parses a JSON file into an owned yyjson document.
 * @param path Path to the JSON file.
 * @return Parsed document, or NULL on read or parse failure.
 * @note The caller owns the returned document and must release it with
 *       `native_json_doc_free()`.
 */
yyjson_doc *native_json_doc_load_file(const char *path);
 
/**
 * @brief Parses JSON text into an owned yyjson document.
 * @param text NUL-terminated JSON text.
 * @return Parsed document, or NULL on parse failure.
 * @note The caller owns the returned document and must release it with
 *       `native_json_doc_free()`.
 */
yyjson_doc *native_json_doc_load_text(const char *text);
 
/**
 * @brief Releases a document returned by the native yyjson helpers.
 * @param doc Document to free. NULL is allowed.
 */
void native_json_doc_free(yyjson_doc *doc);
 
/**
 * @brief Looks up a key from a JSON object value.
 * @param obj Object value to inspect.
 * @param key Key name to resolve.
 * @return Matching value, or NULL when the object or key is invalid or absent.
 * @note Returned values are borrowed from the source document.
 */
yyjson_val *native_json_obj_get(yyjson_val *obj, const char *key);
 
/**
 * @brief Looks up an array-valued key from a JSON object value.
 * @param obj Object value to inspect.
 * @param key Key name to resolve.
 * @return Matching array value, or NULL when absent or not an array.
 * @note Returned values are borrowed from the source document.
 */
yyjson_val *native_json_obj_get_array(yyjson_val *obj, const char *key);
 
/**
 * @brief Duplicates a string-valued key from a JSON object.
 * @param obj Object value to inspect.
 * @param key Key name to resolve.
 * @return Newly allocated duplicated string, or NULL when absent, not a string,
 *         or allocation fails.
 * @note The caller owns the returned string and must free it with `free()`.
 */
char *native_json_obj_get_string_dup(yyjson_val *obj, const char *key);
 
/**
 * @brief Reads a numeric object member or returns a fallback value.
 * @param obj Object value to inspect.
 * @param key Key name to resolve.
 * @param default_value Value returned when the key is absent or not numeric.
 * @param found_out Optional output flag set to non-zero when a numeric value was
 *                  found and consumed, otherwise 0.
 * @return Numeric value converted to `long`, or `default_value` on failure.
 */
long native_json_obj_get_long_default(
    yyjson_val *obj,
    const char *key,
    long default_value,
    int *found_out);
 
/**
 * @brief Finds a migration record by `migration_id` under a fixture root.
 * @param root Root object that may contain a `migrations` array.
 * @param migration_id Migration identifier to match.
 * @return Matching migration object, or NULL when not found.
 * @note Returned values are borrowed from the source document.
 */
yyjson_val *native_json_find_migration_by_id(
    yyjson_val *root,
    const char *migration_id);
 
/**
 * @brief Finds a backend record by `backend` name under a fixture root.
 * @param root Root object that may contain a `backends` array.
 * @param backend_name Backend name to match.
 * @return Matching backend object, or NULL when not found.
 * @note Returned values are borrowed from the source document.
 */
yyjson_val *native_json_find_backend_by_name(
    yyjson_val *root,
    const char *backend_name);
 
/**
 * @brief Serializes a JSON value to compact JSON text.
 * @param value Value to serialize.
 * @return Newly allocated compact JSON string, or NULL on serialization failure.
 * @note The caller owns the returned string and must free it with `free()`.
 */
char *native_json_serialize_compact_dup(yyjson_val *value);
 
/**
 * @brief Converts a JSON string array into newline-delimited text.
 * @param array_value Array whose elements must all be JSON strings.
 * @return Newly allocated newline-delimited string, or NULL when the input is
 *         invalid or allocation fails.
 * @note The caller owns the returned string and must free it with `free()`.
 */
char *native_json_string_array_lines_dup(yyjson_val *array_value);
 
/** @} */
 
#endif