菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use Atlas to initialize Nim projects, install or update Atlas-managed dependencies, configure dependency directories, inspect Atlas-generated nim.cfg paths, handle Atlas overrides, features, plugins, lockfiles, and local Nim environments. Use when setting up or repairing Nim dependency workflows that use Atlas instead of Nimble's global package path.
Design clear public Nim APIs for libraries and modules, including exported types, constructors, parameter ownership, lookup functions, error contracts, and container-style interfaces. Use when creating or reviewing a Nim library API, designing an exported module surface, or deciding how callers should construct, pass, access, and validate data.
Bind C libraries to Nim and make them build reliably across Linux, macOS, and Windows, including headers, types, linking, shared-library loading, and CI/release workflows. Use when wrapping a C dependency, fixing Nim FFI build issues, or setting up cross-platform GitHub Actions for a Nim native library project.
Turn low-level C FFI bindings into an idiomatic Nim API, with safer types, cleaner module boundaries, resource management, callbacks, enums, bitflags, and exception-based error handling. Use when building a high-level Nim wrapper around a C library or improving the usability of existing raw bindings.
Organize Nim modules and multi-step workflows with explicit state ownership, cohesive boundaries, narrow exports, and structured orchestration. Use when refactoring a large Nim file, splitting logic across modules, designing parser-style stateful code, or simplifying nested helpers and hidden mutable state.
Debug Nim compile failures, crashes, wrong results, macro expansion, ownership behavior, and unsafe-memory defects using focused reproduction, stack traces, inspection, compiler expansion, and sanitizers. Use when diagnosing runtime failures, release-only behavior, generic or macro issues, unexpected copies, pointer bugs, or memory leaks.
| name | nimonyplugins |
| description | 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. |
nimony with readlink -f "$(command -v nimony)"./bin/nimony, open
../src/nimony/lib/plugins.nim relative to the executable directory.
Otherwise open src/nimony/lib/plugins.nim under the executable directory.
Treat that file as the source of truth.nimony c invocation and cached executable, even when two paths
contain identical source. Warm builds reuse those executables.{.plugin: "path".} path is relative to the source file containing the
pragma, not the call site.There are five plugin kinds:
template f(...) {.plugin: "p".} receives
(stmts <template-name> <args...>). Use callArgs(root) to read the
arguments. Its output is semantically checked again.iterator f(...) {.plugin: "p".} receives
(forcall <iterator-name> (callargs ...) (unpackflat|unpacktup ...) <body>).
Use forLoopCallArgs, forLoopVars, and forLoopBody. The body is already
typed; transformed output is semantically checked again.{.plugin: "p".} receives the semantically checked full module and
must return the full module. Output is not checked again.type T {.plugin: "p".} = ... receives the full module through
loadPluginInput() and triggering definitions through
loadTypeDefinitions(). It must return the full module; output is not
checked again.import (path/foo) {.plugin: "p".} transforms an imported module.When multiple templates or iterators name the same plugin path, use
pluginName(root) to dispatch them inside that one executable.
Use the named protocol helpers to access template and for-loop inputs.
NifBuilder is the move-only nifcore.TokenBuf.NifCursor is a copyable, reference-counted, bounded read cursor.snapshot(tree) borrows a non-empty builder. The cursor keeps its observed
storage alive; later builder mutation detaches storage as needed.addTree borrows its child builder, so the child remains usable afterward.
saveTree accepts its completed output as a sink parameter.SymId and TagId are numeric handles local to shared plugin pools. Resolve
their names with symText and tagText.createTree().withTree SomeEnum, info:.openTree(tag, info) /
closeTree().n.info when deriving output from an input node. Use NoLineInfo
for synthetic output.addTree(dest, child) to append an entire child builder.addSubtree(dest, cursor) to copy without advancing and
takeTree(dest, cursor) to copy and advance.copyInto(dest, cursor): to copy a node head while transforming all
bounded children.bindSym for hygienic definition-scope symbol references.genSym() once and pass that
SymId to addSymDef and every corresponding addSymUse.TagLit; strings have kind StrLit.firstChild(n) returns a cursor bounded to the current node's children.skip(n) advances over one atom or complete subtree.into n: and loopInto n: require their bodies to consume all children.balancedTokens n: visits descendant TagLit nodes, excludes the root, and
leaves n advanced past the root.hasMore to test its bounds.keep, drop, and replace each consume one input child.keepTag and replaceHead bodies must consume every child.loopKeepTag preserves a node while iterating its children.peek restores the source cursor; writes to r.dest persist.(stmts <name> <args...>); consume or preserve
the leading name deliberately before processing arguments.errorTree(message, at) when user input violates the plugin's
contract.renderNode(cursor) and renderTree(builder) are debugging helpers that
omit line information.saveTree consumes a builder. saveReplacer writes the replacer output.plugins.nim used by the selected Nimony.loadPluginInput, loadTypeDefinitions, or loadReplacer.errorTree for invalid input, then write
the result with saveTree or saveReplacer.nimony when needed.| Mistake | Correction |
|---|---|
| Compiling the plugin module with Nim | Compile plugin modules and integration tests with Nimony |
| Traversing a template root as though every child were an argument | Use callArgs(root); the root also contains the invoked template name |
Confusing addSubtree with takeTree | Use addSubtree to preserve the cursor position and takeTree to advance it |
Leaving children unconsumed in into, keepTag, or replaceHead | Consume every bounded child in the body |
| Returning a transformed fragment from a module or type plugin | Return the complete module |
| Reusing a textual name for a generated local | Call genSym() once and use its SymId for the definition and every use |
Writing output during peek while treating it as a dry run | Keep peek read-only; it restores the source cursor but not r.dest |
references/template_plugin.md — A template plugin that generates an expression from literal
arguments.references/replacer_api.md — A selective call rewrite that preserves most input children.references/for_loop_plugin.md — A for-loop plugin that expands an already typed body.references/module_plugin.md — A module plugin that rewrites an already typed module.references/type_plugin.md — A type plugin for validation or rewrites driven by selected types.references/generated_symbols.md — genSym definition and use for collision-free locals.