// The MIT License (MIT)
//
// Copyright (C) 2026 Scott Duensing
//
// 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 substantial 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.

// dvxPrefs.h  -- INI-based preferences system (read/write)
//
// Handle-based API: multiple INI files can be open simultaneously.
// Each prefsOpen/prefsLoad returns a handle that must be passed to
// all subsequent calls and freed with prefsClose when done.

#ifndef DVX_PREFS_H
#define DVX_PREFS_H

#include "platform/dvxPlat.h"

#include <stdbool.h>
#include <stdint.h>

// Canonical path of the system INI, relative to the DVX root.  Every
// component that reads or writes DVX.INI must use this macro so the
// location only has to change in one place.  Uses the platform path
// separator so displayed paths match the user's convention.
#define DVX_INI_PATH "CONFIG" DVX_PATH_SEP "DVX.INI"

// Opaque handle to a loaded preferences file.
typedef struct PrefsHandleT PrefsHandleT;

// Create an empty preferences handle (no file loaded). Useful for
// building a new INI from scratch before saving.
PrefsHandleT *prefsCreate(void);

// Load an INI file into a new handle. Returns NULL on allocation
// failure. If the file doesn't exist, returns a valid empty handle
// (all getters return defaults) with the path stored for prefsSave.
PrefsHandleT *prefsLoad(const char *filename);

// Save the in-memory state back to the file that was loaded.
bool prefsSave(PrefsHandleT *h);

// Save the in-memory state to a specific file.
bool prefsSaveAs(PrefsHandleT *h, const char *filename);

// Release all memory held by the handle.
void prefsClose(PrefsHandleT *h);

// Retrieve a string value. Returns defaultVal if the key is not present.
// The returned pointer is valid until the key is modified or prefsClose.
const char *prefsGetString(PrefsHandleT *h, const char *section, const char *key, const char *defaultVal);

// Retrieve an integer value.
int32_t prefsGetInt(PrefsHandleT *h, const char *section, const char *key, int32_t defaultVal);

// Retrieve a boolean value. Recognises "true"/"yes"/"1" and "false"/"no"/"0".
bool prefsGetBool(PrefsHandleT *h, const char *section, const char *key, bool defaultVal);

// Set a string value. Creates the section and key if they don't exist.
void prefsSetString(PrefsHandleT *h, const char *section, const char *key, const char *value);

// Set an integer value.
void prefsSetInt(PrefsHandleT *h, const char *section, const char *key, int32_t value);

// Set a boolean value (stored as "true"/"false").
void prefsSetBool(PrefsHandleT *h, const char *section, const char *key, bool value);

// Remove a key from a section. No-op if not found.
void prefsRemove(PrefsHandleT *h, const char *section, const char *key);

#endif
