nim-error-handling
Design clear Nim error-handling flows; when to raise exceptions vs return `Option`/`bool`, how to enforce non-raising contracts, and where to translate or record failures. Use when reviewing failure behavior, exception boundaries, recovery, or batch processing that needs per-item error reporting.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 5
- Forks
- 2
01 前言 Front Matter
- name
- nim-error-handling
- description
- Design clear Nim error-handling flows; when to raise exceptions vs return `Option`/`bool`, how to enforce non-raising contracts, and where to translate or record failures. Use when reviewing failure behavior, exception boundaries, recovery, or batch processing that needs per-item error reporting.
02 资源文件 1
- 参考文档references/batch_preview_boundary.md1.0 KB
03 SKILL.md 正文
Nim Error Handling
Rules
Choose the Failure Channel
- Return
boolwhen success or failure is the whole result. - Return
Option[T]when success returns a value but absence is expected. - Use
boolwith avarparameter only when filling or mutating caller-owned storage is part of the API. - Convert per-item failures into structured outcomes at the batch boundary. Keep intermediate steps exception-based.
Add Only Real Failure Paths
- Read what the current operation promises and how each called API reports failure.
- If a successful call guarantees valid output, do not add another raising nil, size, or range check.
- If a condition breaks no documented promise, remove the raising check and document the valid behavior.
- Report failure when the result cannot safely satisfy its API or the operation cannot meet its documented promise.
- If an operation requires a stronger guarantee than the API it calls, validate that guarantee in that operation.
Place Boundaries
- Let failures propagate through intermediate steps.
- Catch only where the handler can recover, translate, or record the failure.
- At a batch boundary, record recoverable per-item failures.
Choose Exception Types
- For a contract failure caused by caller input or the environment, raise the closest existing
CatchableError. - Separate
exceptbranches when handling differs. Group exception types when handling is identical. - Put child exception types before their parents in
exceptbranches. - Catch
CatchableErroronly when the boundary handles every recoverable error. Do not catch bareException. - Add a custom exception only when callers handle it differently. Derive it from the closest existing
CatchableErrorsubtype. - Do not use
Defectfor recoverable failures; it represents a programming bug and is not caught byCatchableError. - Use
assertfor conditions whose failure means a programming bug: preconditions, internal invariants, and state guards, as inassert s.opened, "next called before open". - Do not use range conversions for recoverable validation, e.g.
Positive(parseInt(s)); invalid values raiseRangeDefect.
Translate and Inspect Errors
- Translate errors only at module or subsystem boundaries. Add local context and preserve the original reason.
- If the handler only needs the message text, use
getCurrentExceptionMsg(). - If the handler needs exception fields, use
except X as e.
Cleanup and Contracts
- Use
try/finallyfor cleanup. - Use
{.raises: [].}when a proc must not raise. Leave raising procs unannotated.
Workflow
- Read the contracts. Note what this operation promises, how called APIs report failure, and what they guarantee on success.
- Decide whether failure is needed. Name the documented promise that the condition would break. If there is none, remove the check.
- Place the decision. Document valid behavior as success, or report failure in the first operation whose promise is broken.
- Place catch boundaries. Catch only where the handler can recover, translate, or record the failure.
- Enforce non-raising contracts. Add
{.raises: [].}only to procs that must not raise.
Common Mistakes
| Mistake | Why it is wrong |
|---|---|
Parent except before child |
First-match dispatch makes the child handler unreachable. |
Catching bare Exception |
Also catches Defect and can hide programming bugs. |
| Rechecking guaranteed output | Adds dead branches and can contradict the lower-level API. |
| Rejecting allowed behavior | Silently narrows the operation's contract. |
References
references/batch_preview_boundary.md— Per-item batch failures with reporting failures allowed to escape.
04 同仓库更多 Skills
run-tests
Runs the project unit tests and validation suites.
nimonyplugins
Build and debug Nimony compile-time plugins for code generation and DSL rewrites. Use when replacing Nim macros with Nimony plugins, writing or reviewing template, for-loop, module, type, or import plugins, or diagnosing NIF traversal and generated output.
nim-testing
Write and run deterministic Nim tests, including isolated test files, expected-exception checks, multi-configuration builds, and sanitizer integration. Use when setting up a Nim test suite, testing failure behavior, running tests across debug/release/danger modes, or adding AddressSanitizer support.
nim-style-guide
Write clear, consistent Nim code in a simple stdlib-aligned style, covering imports, naming, proc vs func vs template choices, local variables, constructors, formatting, and control flow. Use when writing new Nim code or reviewing a Nim module for readability, consistency, and low-noise style decisions.
nim-ownership-hooks
Implement and review Nim ARC/ORC ownership hooks for types that manually manage resources, including move-only, deep-copy, refcounted, and copy-on-write patterns. Use when a Nim type owns pointers, buffers, file descriptors, or custom heap memory and you need correct `=destroy`, `=copy`, `=dup`, `=sink`, or move semantics.
nim-mcp-tools
Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.