AGENT SKILL

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

03 SKILL.md 正文

Nim Error Handling

Rules

Choose the Failure Channel

  • Return bool when success or failure is the whole result.
  • Return Option[T] when success returns a value but absence is expected.
  • Use bool with a var parameter 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 except branches when handling differs. Group exception types when handling is identical.
  • Put child exception types before their parents in except branches.
  • Catch CatchableError only when the boundary handles every recoverable error. Do not catch bare Exception.
  • Add a custom exception only when callers handle it differently. Derive it from the closest existing CatchableError subtype.
  • Do not use Defect for recoverable failures; it represents a programming bug and is not caught by CatchableError.
  • Use assert for conditions whose failure means a programming bug: preconditions, internal invariants, and state guards, as in assert s.opened, "next called before open".
  • Do not use range conversions for recoverable validation, e.g. Positive(parseInt(s)); invalid values raise RangeDefect.

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/finally for cleanup.
  • Use {.raises: [].} when a proc must not raise. Leave raising procs unannotated.

Workflow

  1. Read the contracts. Note what this operation promises, how called APIs report failure, and what they guarantee on success.
  2. Decide whether failure is needed. Name the documented promise that the condition would break. If there is none, remove the check.
  3. Place the decision. Document valid behavior as success, or report failure in the first operation whose promise is broken.
  4. Place catch boundaries. Catch only where the handler can recover, translate, or record the failure.
  5. 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

Vyrnexis
Vyrnexis/nim-agent-template

run-tests

Runs the project unit tests and validation suites.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

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.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

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.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

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.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

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.

★ 5
Vyrnexis
Vyrnexis/nim-agent-template

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.

★ 5