/*
 * libfud
 * Copyright 2024 Dominick Allen
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef LIBFUD_HPP
#define LIBFUD_HPP

#include "fud_array.hpp"
#include "fud_allocator.hpp"
#include "fud_result.hpp"
#include "fud_status.hpp"
#include "fud_string.hpp"

#include <cstdint>

/** @file */

namespace fud {

constexpr size_t GIT_REV_CHARS = 13;

struct FUD {
    uint8_t major;
    uint8_t minor;
    uint8_t patch;
    Array<char, GIT_REV_CHARS> revision;
};

/** \brief Get the version of FUD including git revision.
 *
 * \returns FUD object with verison information.
 */
FUD fud();

/**
 * \brief Get an environmental variable if it exists.
 *
 * \param[in] name The name of the variable to look up.
 * \param[in] allocator The allocator used by the string returned.
 *
 * \returns The value of the string bound to the variable if it exists.
 * \returns FudStatus::NullPointer if name is a null pointer.
 * \returns FudStatus::NotFound if no binding for the variable exists.
 */
Result<String, FudStatus> getEnv(const char* name, Allocator* allocator= &globalFudAllocator);

/** \brief A concept requiring the object T to have a method c_str returning a
 * pointer to a C string. */
template <typename T>
concept CStringRepr = requires(T strObj) {
    { strObj.c_str() } -> std::convertible_to<const char*>;
};

/**
 * \brief Get an environmental variable if it exists.
 *
 * \tparam T A type which has a method c_str returning a pointer convertible to
 * a C string.
 * \param[in] name The name of the variable to look up.
 * \param[in] allocator The allocator used by the string returned.
 *
 * \returns @getEnv return values.
 */
template <CStringRepr T>
Result<String, FudStatus> getEnv(const T& name, Allocator* allocator = &globalFudAllocator)
{
    return getEnv(name.c_str(), allocator);
}

/** \mainpage libfud
 *
 * \section intro_sec Introduction
 *
 * libfud is an exception-free, UB-minimizing, library for safely making system
 * calls, handling UTF8 encoded strings, and managing containers with user
 * controlled allocators.
 *
 * \subsection design_principles Design Principles
 *
 * - Full control over allocations, even the default allocator.
 * - Zero exceptions, zero exceptions to zero exceptions.
 * - Assertions in production release for invariants.
 * - Configurable run-time assertions for indexing.
 * - Safe API for users intolerant to run-time assertions for indexing.
 * - Readable, understandable code.
 * - Minimize undefined behavior in the API to a subset which is only decidable at
 *   run-time.
 * - Minimize runtime undefined behavior as much as possible.
 *
 * \subsection rel_mature_features Relatively Mature Features
 *
 * - Statically sized Array
 * - StringView
 *
 * \subsection unstable_features Unstable Features
 *
 * - Customizable allocator model
 * - Dynamically sized Vector taking an allocator
 * - Dynamically sized String taking an allocator
 * - Unicode support with UTF8 encoding
 * - format à la =std::format=
 * - Wrappers around C files
 *
 */

} // namespace fud

#endif