agentleFS
TsukiNi22TsukiNi22/ai-utils/skills/libutils/libutils-exception/SKILL.md

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

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
  1. Very specific:

    All in utils::exception, always included by <utils/utils.hpp> with #define _Exception before it (never the exception headers one by one).

    line 23
  2. Very specific:

    Git: add include/exception/generated_external_exception_header.hpp to .gitignore (regenerated at each build when a JSON or the script …

    line 139
  3. Very specific:

    Add the entry in the right file of cmake/config/exceptions/ (global/*.json for generic codes, utils/<section>.json for a section), same …

    line 153

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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).

ClassType setUse
IException (interface, inherits std::exception)-catch type
AException (abstract)-base of every exception, restriction check, formated()
ErrorExceptionErrorrecoverable error (most used)
WarningExceptionWarningprinted, not thrown in general
NoneExceptionNonenot an error: exit / stop the flow (InternalCode::Exit)
FatalExceptionError | Fatal (or type | Fatal)prints and std::abort() in its constructor: it is never caught, no RAII cleanup
CustomExceptiongiven typeany 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 Undefined

Methods (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());}
  • info given at the throw replaces the default info of the JSON; no info -> JSON info or "[None]".
  • FatalException: only for unrecoverable states (it aborts at construction, throw is never reached). Define FATALEXCEPTION_USAGE_WARNING (or _Warning) to get a compile warning on its use, NO_FATALEXCEPTION_USAGE_WARNING / _NoWarning to silence it.
  • Restrictions: each code allows some types. At construction (type & restriction) != type -> FatalException(InternalCode::ExceptionCodeRestriction) = abort. A FatalException has the type Error | Fatal: its code must allow both Fatal and Error. Check the restrictions of a code (exception-codes.md or 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):

  1. Scripts: copy templates/cmake/scripts/{const.py,generate_exception_header.py,requirements.txt} to cmake/scripts/. const.py holds the paths (CONFIG_EXCEPTION = "cmake/config/exceptions/", GENERATED_EXCEPTION_HEADER = "include/exception/generated_external_exception_header.hpp") and the External* names: edit it only to change those paths. The script must run from the project root.
  2. JSON: one or more *.json anywhere under cmake/config/exceptions/ (read recursively), example templates/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 by what(), short, describes the error family.
    • info (optional): default context returned by info().
    • restrictions (optional, missing = all types allowed): any of "None", "Warning", "Error", "Fatal". Usual sets: ["Fatal", "Error"], ["Fatal", "Error", "Warning"], ["None"].
  3. CMake (templates/exception.cmake, see the cmake-style skill for the placement): find_package(Python3 REQUIRED), the file(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/exception must be an include directory: libutils includes the header with #if __has_include(<generated_external_exception_header.hpp>), and its guard GENERATED_EXTERNAL_EXCEPTION_HEADER_H enables every ExternalCode constructor.
  4. Git: add include/exception/generated_external_exception_header.hpp to .gitignore (regenerated at each build when a JSON or the script changes).
  5. Use: utils::exception::ExternalCode::InvalidConfig with 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; AException merges 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::X directly.
  • 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)

  1. Add the entry in the right file of cmake/config/exceptions/ (global/*.json for generic codes, utils/<section>.json for a section), same format, unique name across all the files.
  2. The libutils const.py targets include/utils/exception/generated_internal_exception_header.hpp (Internal* names, also reads the Type enum of ExceptionDefine.hpp), already wired in its CMake (generated_internal_exception_header target).
  3. Rebuild, use utils::exception::InternalCode::X, document it in the CHANGELOG (### Added) and regenerate the libutils skill reference (libutils/scripts/update.sh) after the commit.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.