Skip to content

TsukiNi22/ai-utils / skills/libutils/libutils-exception

libutils-exception

Verified

libutils exception handling (utils::exception) - IException/AException, Error/Warning/None/Fatal/CustomException, InternalCode vs ExternalCode, Type, restrictions, formated() output, throw/catch/print patterns - and how to add new exception codes to a project (cmake/config/exceptions/*.json, generate_exception_header.py + const.py, CMake custom command, include/exception/generated_external_exception_header.hpp). Use whenever throwing, catching or printing a libutils exception, choosing an exception code, or adding/editing exception codes, the exception JSON config, the generator script or the generated_*_exception_header of a project.

templates/cmake/scripts/generate_exception_header.py

View on GitHub
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

 ██╗  ██╗ █████╗ ██████╗ ████████╗ █████╗ ███╗   ██╗██╗ █████╗
 ╚██╗██╔╝██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗████╗  ██║██║██╔══██╗
  ╚███╔╝ ███████║██████╔╝   ██║   ███████║██╔██╗ ██║██║███████║
  ██╔██╗ ██╔══██║██╔══██╗   ██║   ██╔══██║██║╚██╗██║██║██╔══██║
 ██╔╝ ██╗██║  ██║██║  ██║   ██║   ██║  ██║██║ ╚████║██║██║  ██║
 ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝

Edition:
##  28/07/2026 by Tsukini

File Name:
##  generate_exception_header.py

File Description:
##  Generate the exception header from the config file
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

##### Import #####
# Import that can't be in the try
from const import RETURN, ERROR, VALUES, FILES, NAMES
from sys import exit, stderr, stdout
from os import geteuid

# Try to install dependencies (failsafe)
try:
    # Avoid pip install when running as root or without any requirement
    with open(FILES.REQUIREMENTS, "r", encoding="utf-8") as f:
        has_requirements = any(line.strip() and not line.strip().startswith("#") for line in f)
    if has_requirements and geteuid() != 0:
        from sys import executable
        from subprocess import check_call
        check_call([executable, "-m", "ensurepip", "--upgrade"])
        check_call([executable, "-m", "pip", "install", "-r", FILES.REQUIREMENTS])
    elif has_requirements:
        stdout.write("Running as root: skipping Python dependency installation\n")
except Exception: pass

# Import that can be checked
try:
    from hashlib import sha256 # Used to identify different error
    from pathlib import Path # Used to create & edit files and to get the file name
    import json # Used to get the json data
    import re # Used for pattern matching
except ImportError as e:
    stderr.write(f"Import Error ({__file__}): {e}\n")
    stderr.write(f"Auto generated header '{FILES.GENERATED_EXCEPTION_HEADER}': FAIL\n")
    exit(ERROR.FATAL)

# Check if the program is call and not imported
if __name__ != "__main__":
    stderr.write(f"The {__file__} can only be executed and not imported!\n")
    stderr.write(f"Auto generated header '{FILES.GENERATED_EXCEPTION_HEADER}': FAIL\n")
    exit(ERROR.FATAL)

##### Tools #####
def uint64_hash(s: str) -> int:
    digest = sha256(s.encode()).digest()
    value = int.from_bytes(digest[:8], "big") # 8 octets = 64 bits
    return 1 + (value % VALUES.SIZE_MAX) # limit values

##### Program #####
# Recuperation of the data
data = {} # {code: [message, info, restriction], ...}
for json_file in Path(FILES.CONFIG_EXCEPTION).rglob("*.json"):
    with json_file.open("r", encoding="utf-8") as f:
        json_content = json.load(f)
        for error in json_content.get("errors", []):
            if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", error["code"]) or error["code"] == "Undefined":
                stderr.write(f"Invalid error code in '{json_file}': '{error['code']}' (C++ identifier, 'Undefined' is reserved)\n")
                stderr.write(f"Auto generated header '{FILES.GENERATED_EXCEPTION_HEADER}': FAIL\n")
                exit(RETURN.KO)
            for t in error.get("restrictions", []):
                if t not in VALUES.EXCEPTION_TYPE:
                    stderr.write(f"Unknown restriction '{t}' for the error code '{error['code']}' (ignored)\n")
            if data.__contains__(error["code"]):
                stderr.write(f"Duplicated error code encoutered in data extraction '{error['code']}'\n")
                stderr.write(f"Auto generated header '{FILES.GENERATED_EXCEPTION_HEADER}': FAIL\n")
                exit(RETURN.KO)
            data[error["code"]] = [error["message"], error["info"] if error.__contains__("info") else "[None]", error["restrictions"] if error.__contains__("restrictions") else []]

# Format the data
code_str = ""
message_str = ""
info_str = ""
restriction_str = ""
data_list = list(data.items())
for i, (code, [message, info, restriction]) in enumerate(data_list):
    # code
    code_str += f"    {code} = {uint64_hash(code + NAMES.CODE_SECTION)}ull,"
    # message
    escaped_message = message.replace('\\', r'\\').replace('"', r'\"').replace('\n', r'\n')
    message_str += f'    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::{code}, "{escaped_message}"}},'
    # info
    escaped_info = info.replace('\\', r'\\').replace('"', r'\"').replace('\n', r'\n')
    info = ("nullptr" if escaped_info == "[None]" else f'"{escaped_info}"')
    info_str += f'    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::{code}, {info}}},'
    # restriction
    value = 0
    types = ""
    for j in range(len(restriction)):
        t = restriction[j]
        value |= VALUES.EXCEPTION_TYPE.get(t, 0)
        if VALUES.EXCEPTION_TYPE.get(t, 0) != 0: types += t + (", " if j != len(restriction) - 1 else "")
    restriction_str += f"    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::{code}, {value:#0{len(VALUES.EXCEPTION_TYPE) + 2}b}}}, // allow: {'All' if types == '' else types}"
    # End of line
    if i != len(data_list) - 1:
        code_str += "\n"
        info_str += "\n"
        message_str += "\n"
        restriction_str += "\n"

# Build the restriction comment
restriction_lines = [
    f"// 0b{0:0{len(VALUES.EXCEPTION_TYPE)}b} = {'no restriction':<16}(allow all)",
]
for name in VALUES.EXCEPTION_TYPE:
    restriction_lines.append(f"// {VALUES.EXCEPTION_TYPE[name]:#0{len(VALUES.EXCEPTION_TYPE) + 2}b} = {name:<16}(allow {name})")
restriction_str_comment = "\n".join(restriction_lines)

# Create the file
header = Path(FILES.GENERATED_EXCEPTION_HEADER)

# Build of the content
content = f"""
/**************************************************************\\
Edition (auto):
##  --/--/---- by {Path(__file__).name}

File Name:
##  @file {header.name}

File Description:
##  Header auto generated by the python script at compilation
##  Generated from the files in '{FILES.CONFIG_EXCEPTION}'
##  Used for exception code & message definition
\\**************************************************************/

#ifndef {NAMES.GUARD + Path(FILES.GENERATED_EXCEPTION_HEADER).stem.upper()}_H
    #define {NAMES.GUARD + Path(FILES.GENERATED_EXCEPTION_HEADER).stem.upper()}_H

    //----------------------------------------------------------------//
    /* INCLUDE */

    #include <unordered_map>    // std::unordered_map
    #include <iterator>         // std::size
    #include <cstddef>          // std::size_t
    #include <cstdint>          // std::uint8_t

namespace {NAMES.EXCEPTION_SCOPE} {{ // namespace start
//----------------------------------------------------------------//
/* ENUM */

/* Definition of the different exception code */
enum class {NAMES.CODE_SECTION}: std::size_t {{
    Undefined = 0,
{code_str}
}};

/* Corresponding exception message for each code */
inline const std::unordered_map<{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}, const char*> {NAMES.MESSAGES_SECTION} = {{
    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::Undefined, "An undefined error has occured"}},
{message_str}
}};

/* Potential default info: nullptr same as "[None]" */
inline const std::unordered_map<{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}, const char*> {NAMES.INFO_SECTION} = {{
    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::Undefined, nullptr}},
{info_str}
}};

/* Potential restriction on exception code */
{restriction_str_comment}
inline const std::unordered_map<{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}, const std::uint8_t> {NAMES.RESTRICTION_SECTION} = {{
    {{{NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::Undefined, 0b0000}}, // allow: All
{restriction_str}
}};

// Check at the compile time the correspondece between the message & code
/*
static_assert(std::size({NAMES.MESSAGES_SECTION}) == static_cast<std::size_t>({NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::CODE_SENTINEL), "The message array doesn't correspond to the available exception codes");
static_assert(std::size({NAMES.INFO_SECTION}) == static_cast<std::size_t>({NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::CODE_SENTINEL), "The info array doesn't correspond to the available exception codes");
static_assert(std::size({NAMES.RESTRICTION_SECTION}) == static_cast<std::size_t>({NAMES.EXCEPTION_SCOPE}::{NAMES.CODE_SECTION}::CODE_SENTINEL), "The restriction array doesn't correspond to the available exception codes");
*/

}} // namespace end
#endif /* {NAMES.GUARD + Path(FILES.GENERATED_EXCEPTION_HEADER).stem.upper()}_H */
"""

# Write the file content
header.parent.mkdir(parents=True, exist_ok=True)
header.write_text(content)

# Success
print(f"Auto generated header '{FILES.GENERATED_EXCEPTION_HEADER}': SUCCESS")
exit(RETURN.OK)
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall