libutils-exception
Skill1 starsChanged 3 days agoMITView on GitHub
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.
- Installs packages
In this repository70 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-at-endSkill
- clarifySkill
- continue-workSkill
- exportSkill
- full-permissionSkill
- ideationSkill
- interactive-questionsSkill
- onboardSkill
- pauseSkill
- presentationSkill
- rtkSkill
- setup-contextSkill
- write-like-meSkill
- audit-bugsSkill
- audit-depsSkill
- audit-qualitySkill
- audit-securitySkill
- benchmarkSkill
- cmake-styleSkill
- cpp-classSkill
- cpp-commentsSkill
- cpp-projectSkill
- cpp-styleSkill
- better-explain-docSkill
- better-html-docSkill
- better-html-styleSkill
- better-protocol-docSkill
- docs-updateSkill
- explain-docSkill
- html-docSkill
- html-styleSkill
- protocol-docSkill
- readme-styleSkill
- reportSkill
- wiki-styleSkill
- ci-cdSkill
- git-commitSkill
- git-conventionsSkill
- pre-commitSkill
- legal-checkSkill
- legal-setupSkill
- licenseSkill
- libutils-installSkill
- libutils-setupSkill
- libutilsSkill
- python-classSkill
- python-commentsSkill
- python-projectSkill
- python-styleSkill
- auditSkill
- cppSkill
- devSkill
- docSkill
- gitSkill
- legalSkill
- pythonSkill
- setup-projectSkill
- styleSkill
- setup-studioSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
All in utils::exception, always included by <utils/utils.hpp> with #define _Exception before it (never the exception headers one by one).
- Very specific: line 139
Git: add include/exception/generated_external_exception_header.hpp to .gitignore (regenerated at each build when a JSON or the script …
- Very specific: line 153
Add the entry in the right file of cmake/config/exceptions/ (global/*.json for generic codes, utils/<section>.json for a section), same …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
libutils exceptions
<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).
Based on the libutils sources (include/utils/exception/, src/utils/exception/AException.cpp,
cmake/scripts/), the wiki page Exception (usage) and the real setup of context-forge.
Existing codes: ../libutils/reference/exception-codes.md (the libutils skill).
libutils freshness
First, once per conversation: the freshness check of the libutils skill (bash <libutils skill>/scripts/check.sh,
section "Freshness check" of libutils/SKILL.md). Outdated -> reuse the answer already given in this conversation,
else ask once (continue / update the installed libutils with libutils-install / the project's requirement with
libutils-setup / the skills reference) and remember it.
1. Classes
All in utils::exception, always included by <utils/utils.hpp> with #define _Exception before it (never the exception headers one by one).
| Class | Type set | Use |
IException (interface, inherits std::exception) | - | catch type |
AException (abstract) | - | base of every exception, restriction check, formated() |
ErrorException | Error | recoverable error (most used) |
WarningException | Warning | printed, not thrown in general |
NoneException | None | not an error: exit / stop the flow (InternalCode::Exit) |
FatalException | Error | Fatal (or type | Fatal) | prints and std::abort() in its constructor: it is never caught, no RAII cleanup |
CustomException | given type | any combination of Type |
Constructors (each one also exists with ExternalCode when the project generated its header;
loc defaults to std::source_location::current(), never pass it by hand):
ErrorException(InternalCode code = InternalCode::Undefined, loc); // same for Warning/None
ErrorException(InternalCode code, std::string info, loc);
FatalException(InternalCode code = Undefined, loc);
FatalException(InternalCode code, std::string info, loc);
FatalException(Type type, InternalCode code = Undefined, std::string info = "[None]", loc);
FatalException(const IException& e); // abort with an existing exception
CustomException(Type type = None, InternalCode code = Undefined, std::string info = "[None]", loc);
CustomException(Type type, std::string info, loc); // code UndefinedMethods (IException): formated(), what() (code message), info(), getType(), getCode()
(always an InternalCode, an external code is cast), isNone(), isFatal(), loc().
Type (bit flags, |, &, ^, ~ defined): None = 0b0001, Fatal = 0b0010, Error = 0b0100, Warning = 0b1000.
OK (0) / KO (-1) are defined by ExceptionDefine.hpp (if not already defined).
formated() output (colored, file path as a terminal hyperlink, module name when thrown from another binary/.so):
[Error] ...src/forge/Forge.cpp:97 (module) -> <message of the code>
-------------------------------------------
<function signature> = <info>
-------------------------------------------2. Usage patterns
// Throw: the code gives the message, the info gives the context
throw utils::exception::ErrorException(utils::exception::InternalCode::InvalidArgument, "got: " + value);
throw utils::exception::ErrorException(utils::exception::ExternalCode::Rules, "Parse error at " + file);
// Warning: print it, don't throw it
std::cerr << utils::exception::WarningException(utils::exception::InternalCode::UnknownId, id).formated() << std::endl;
onDebugVerboseC(std::cerr, utils::exception::ErrorException(utils::exception::ExternalCode::InvalidDirectory, "...").formated());
// Failsafe parameter: warn instead of throw
if (failsafe) {std::cerr << utils::exception::WarningException(code, s).formated() << std::endl; return false;}
else throw utils::exception::ErrorException(code, s);
// Catch: always the interface, print formated()
try {this->loadPlugin(path);}
catch (const utils::exception::IException& e) {onDebugVerboseC(std::cerr, e.formated());}
// main(): None + Exit = clean exit
} catch (const utils::exception::IException& e) {
if (e.isNone() && e.getCode() == utils::exception::InternalCode::Exit) return OK;
std::cerr << e.formated() << std::endl;
return KO;
}
// Compare with an external code
e.getCode() == static_cast<utils::exception::InternalCode>(utils::exception::ExternalCode::Rules)
// Wrap a third party / std error with context
catch (const std::exception& e) {throw utils::exception::ErrorException(utils::exception::InternalCode::ArgParserHook, e.what());}infogiven at the throw replaces the defaultinfoof the JSON; no info -> JSONinfoor"[None]".FatalException: only for unrecoverable states (it aborts at construction,throwis never reached). DefineFATALEXCEPTION_USAGE_WARNING(or_Warning) to get a compile warning on its use,NO_FATALEXCEPTION_USAGE_WARNING/_NoWarningto silence it.- Restrictions: each code allows some types. At construction
(type & restriction) != type->FatalException(InternalCode::ExceptionCodeRestriction)= abort. AFatalExceptionhas the typeError | Fatal: its code must allow bothFatalandError. Check the restrictions of a code (exception-codes.mdor the JSON) before using it with another exception class.
3. Add exception codes to a project (external codes)
Internal codes = libutils ones (InternalCode), external = the project ones (ExternalCode).
Checklist (files to copy are in templates/, identical to cpp_project_template / context-forge):
- Scripts: copy
templates/cmake/scripts/{const.py,generate_exception_header.py,requirements.txt}tocmake/scripts/.const.pyholds the paths (CONFIG_EXCEPTION = "cmake/config/exceptions/",GENERATED_EXCEPTION_HEADER = "include/exception/generated_external_exception_header.hpp") and theExternal*names: edit it only to change those paths. The script must run from the project root. - JSON: one or more
*.jsonanywhere undercmake/config/exceptions/(read recursively), exampletemplates/cmake/config/exceptions/global.json:{ "errors": [ { "code": "InvalidConfig", "message": "Error during the configuration parsing", "info": "Default info (optional, \"[None]\" when missing)", "restrictions": ["Fatal", "Error", "Warning"] } ] }code: PascalCase, unique in the whole project (a duplicate -> the script fails,exit 1).message: returned bywhat(), short, describes the error family.info(optional): default context returned byinfo().restrictions(optional, missing = all types allowed): any of"None","Warning","Error","Fatal". Usual sets:["Fatal", "Error"],["Fatal", "Error", "Warning"],["None"].
- CMake (
templates/exception.cmake, see thecmake-styleskill for the placement):find_package(Python3 REQUIRED), thefile(GLOB_RECURSE ... CONFIGURE_DEPENDS ...json)+add_custom_command(OUTPUT <header> ...)+add_custom_target(generated_external_exception_header ...)in Special Targets, then for every target using libutils (main target, plugins,unit_tests):target_include_directories(${TARGET} PRIVATE include include/exception) add_dependencies(${TARGET} generated_external_exception_header)include/exceptionmust be an include directory: libutils includes the header with#if __has_include(<generated_external_exception_header.hpp>), and its guardGENERATED_EXTERNAL_EXCEPTION_HEADER_Henables everyExternalCodeconstructor. - Git: add
include/exception/generated_external_exception_header.hppto.gitignore(regenerated at each build when a JSON or the script changes). - Use:
utils::exception::ExternalCode::InvalidConfigwith any exception class. Build once (cmake --build) before the IDE sees the new codes.
Notes:
- The generated header defines
ExternalCode(values = 64-bit hash of<code>ExternalCode),ExternalMessages,ExternalInfo,ExternalRestriction;AExceptionmerges them with the internal maps. - A project code with the same name as an internal one is a different code (different hash, its own
message/info/restrictions): don't duplicate a libutils code, use
InternalCode::Xdirectly. - The script runs
pip install -r requirements.txt(empty) when not root; Python 3 only needs the stdlib. - To get the codes as internal ones instead, rebuild libutils itself with the extra JSON (wiki tip).
4. Add a code inside libutils (internal)
- Add the entry in the right file of
cmake/config/exceptions/(global/*.jsonfor generic codes,utils/<section>.jsonfor a section), same format, unique name across all the files. - The libutils
const.pytargetsinclude/utils/exception/generated_internal_exception_header.hpp(Internal*names, also reads theTypeenum ofExceptionDefine.hpp), already wired in its CMake (generated_internal_exception_headertarget). - Rebuild, use
utils::exception::InternalCode::X, document it in the CHANGELOG (### Added) and regenerate thelibutilsskill reference (libutils/scripts/update.sh) after the commit.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

