TsukiNi22/ai-utils / skills/libutils/libutils-exception
libutils-exception
Verifiedlibutils 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.1 KB |
| requires.txt | markdown | 9 B |
| templates/cmake/config/exceptions/global.json | config | 581 B |
| templates/cmake/scripts/const.pyexecutable | script | 3.6 KB |
| templates/cmake/scripts/generate_exception_header.pyexecutable | script | 9.1 KB |
| templates/cmake/scripts/requirements.txt | manifest | 0 B |
| templates/exception.cmake | other | 1.1 KB |
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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |