Incan Documentation¶
New here? Start with: Start here.
Comparisons¶
If you are evaluating whether Incan belongs in a project, start with the direct comparisons. They explain where Incan is trying to win, where it loses today, and when Python, Rust, or Python compatibility tools are the better choice.
| Document | Description |
|---|---|
| Incan vs Python | Python-like ergonomics without Python's runtime and deployment model |
| Incan vs Rust | Rust-native output without writing every application layer in Rust |
| Incan vs Python compatibility tools | Why Incan is not RustPython, Codon, Nuitka, or Cython |
Tooling & Setup¶
How to install, configure, and use Incan Tooling.
| Document | Description |
|---|---|
| Getting Started | Installation and first steps |
| Editor Setup | IDE configuration and syntax highlighting |
| Language Server | LSP for diagnostics, hover, and go-to-definition |
| Formatting | Canonical Incan code style and formatting rules |
| Testing | Test runner (incan test) |
Language Guide¶
How to write Incan code: Language.
| Document | Description |
|---|---|
| the Book | The Incan Book (Walks you through the Basics from a-z) |
| Error Messages | Understanding and fixing compiler errors |
| Error Handling | Result, Option, and the ? operator |
| File I/O | Reading, writing files and path handling |
| Async Programming | Async/await with Tokio |
| Derives & Traits | Derive macros and trait system |
| Testing in Incan | Inline module tests:, assertions, fixtures, markers |
| Scopes & Name Resolution | Block scoping, shadowing, and how names are resolved |
| Imports & Modules | Module system, imports, and built-in functions |
| Rust Interop | Using Rust crates directly from Incan |
| Web Framework | Building web apps with Axum |
Derives Reference¶
| Document | Description |
|---|---|
| String Representation | Debug and Display |
| Comparison | Eq, Ord, Hash |
| Copying & Default | Clone, Copy, Default |
| Serialization | Serialize, Deserialize |
| Custom Behavior | Overriding derived behavior |
RFCs (Request for Comments)¶
Design proposals for upcoming features are recorded in the form of RFCs.
Tip: press Esc to clear.
| RFC | Status | Track | Title |
|---|---|---|---|
| RFC 000 | Done | closed / implemented | Incan Core Language RFC (Phase 1) |
| RFC 001 | Superseded | closed / superseded | Test Fixtures |
| RFC 002 | Superseded | closed / superseded | Parametrized Tests |
| RFC 003 | Superseded | closed / superseded | Frontend and WebAssembly Support |
| RFC 004 | Done | closed / implemented | async fixtures |
| RFC 005 | Done | closed / implemented | Rust Interop |
| RFC 006 | Done | closed / implemented | Python-style generators |
| RFC 007 | Superseded | closed / superseded | Inline Tests |
| RFC 008 | Done | closed / implemented | Const Bindings |
| RFC 009 | Done | closed / implemented | Numeric type system and builtin type registry |
| RFC 010 | Done | closed / implemented | Python-style tempfile standard library |
| RFC 011 | Done | closed / implemented | Precise Error Spans in F-Strings |
| RFC 012 | Superseded | closed / superseded | JsonValue, enum methods, and enum trait adoption |
| RFC 013 | Done | closed / implemented | Rust Crate Dependencies |
| RFC 014 | Rejected | proposed / active | user-facing runtime error behavior for generated code |
| RFC 015 | Done | closed / implemented | hatch-like tooling (project lifecycle CLI) |
| RFC 016 | Done | closed / implemented | loop and break <value> (Loop Expressions) |
| RFC 017 | Done | closed / implemented | Validated newtypes with implicit coercion (pydantic-like feel) |
| RFC 018 | Done | closed / implemented | language primitives for testing |
| RFC 019 | Done | closed / implemented | test runner, CLI, and ecosystem |
| RFC 020 | Done | closed / implemented | offline / locked / reproducible builds (Cargo policy + generated project contract) |
| RFC 021 | Done | closed / implemented | Model field metadata and schema-safe aliases |
| RFC 022 | Done | closed / implemented | Namespaced stdlib modules and compiler→stdlib handoff |
| RFC 023 | Done | closed / implemented | Compilable Stdlib & Rust Module Binding |
| RFC 024 | Done | closed / implemented | extensible derive protocol |
| RFC 025 | Done | closed / implemented | multi-instantiation trait dispatch |
| RFC 026 | Superseded | closed / superseded | User-Defined Trait Bridges |
| RFC 027 | Done | closed / implemented | incan-vocab — Library Vocabulary Registration Crate |
| RFC 028 | Done | closed / implemented | trait-based operator overloading |
| RFC 029 | Done | closed / implemented | union types and type narrowing |
| RFC 030 | Done | closed / implemented | std.collections — extended collection types |
| RFC 031 | Done | closed / implemented | Incan Library System — Phase 1 (Local Path Dependencies) |
| RFC 032 | Blocked (by RFC 033) | proposed / active | value enums — StrEnum and IntEnum |
| RFC 033 | Draft | proposed / active | ctx — typed configuration context |
| RFC 034 | Draft | proposed / active | incan.pub — The Incan Package Registry |
| RFC 035 | Done | closed / implemented | First-Class Named Function References |
| RFC 036 | Done | closed / implemented | user-defined decorators |
| RFC 037 | Planned | proposed / active | native web stdlib redesign |
| RFC 038 | Done | closed / implemented | Variadic Args and Unpacking (*args / **kwargs) |
| RFC 039 | Done | closed / implemented | race for awaitable concurrency |
| RFC 040 | Done | closed / implemented | Scoped DSL Surface Forms |
| RFC 041 | Done | closed / implemented | First-Class Rust Interop Authoring |
| RFC 042 | Done | closed / implemented | Traits Are Always Abstract |
| RFC 043 | Done | closed / implemented | Rust Trait Implementation from Incan |
| RFC 044 | Done | closed / implemented | Open-Ended Trait Methods |
| RFC 045 | Done | closed / implemented | Scoped DSL symbol surfaces |
| RFC 046 | Done | closed / implemented | Computed properties (property name -> Type) |
| RFC 047 | Done | closed / implemented | Lightweight directed graph types (stdlib) |
| RFC 048 | Done | closed / implemented | Checked contract metadata, Incan emit, and interrogation tooling |
| RFC 049 | Done | closed / implemented | if let and while let pattern control flow |
| RFC 050 | Done | closed / implemented | Enum methods and enum trait adoption |
| RFC 051 | Done | closed / implemented | JsonValue for std.json |
| RFC 052 | Done | closed / implemented | Module Static Storage |
| RFC 053 | Done | closed / implemented | Formatter vertical spacing (three blank-line buckets) |
| RFC 054 | Done | closed / implemented | Explicit call-site generic arguments for function and method calls |
| RFC 055 | Done | closed / implemented | std.fs — pathlib-shaped filesystem APIs with chunked file I/O |
| RFC 056 | Done | closed / implemented | std.io — in-memory byte streams and binary parsing helpers |
| RFC 057 | Done | closed / implemented | @rust.allow(...) — targeted Rust lint suppression for generated code |
| RFC 058 | Done | closed / implemented | std.datetime — temporal values, intervals, and runtime timing |
| RFC 059 | Done | closed / implemented | std.regex — regular expressions, matches, captures, and replacement |
| RFC 060 | Done | closed / implemented | std.uuid — UUID parsing, generation, and formatting |
| RFC 061 | Done | closed / implemented | std.compression — codec-based compression and decompression |
| RFC 062 | Draft | proposed / active | std.archive — archive container creation and extraction |
| RFC 063 | Draft | proposed / active | std.process — process spawning and command execution |
| RFC 064 | Done | closed / implemented | std.encoding — binary-text encoding and decoding utilities |
| RFC 065 | Done | closed / implemented | std.hash — stable hashing primitives for data and integrity workflows |
| RFC 066 | Draft | proposed / active | std.http — Incan-first HTTP client and request/response surface |
| RFC 067 | Draft | proposed / active | std.ci — deterministic CI and automation scripting primitives |
| RFC 068 | Done | closed / implemented | protocol hooks for core language syntax |
| RFC 069 | Done | closed / implemented | list.repeat Helper for Fixed-Length Initialization |
| RFC 070 | Done | closed / implemented | Result Combinators for Result[T, E] |
| RFC 071 | Done | closed / implemented | Pattern alternation in match and if let |
| RFC 072 | Done | closed / implemented | std.logging — logger acquisition, configuration, and structured events |
| RFC 073 | Draft | proposed / active | environment matrices and toolchain constraints |
| RFC 074 | Draft | proposed / active | template rendering and boilerplate provenance |
| RFC 075 | Draft | proposed / active | starter profiles and capability packs |
| RFC 076 | Draft | proposed / active | project mutation policy and recovery |
| RFC 077 | Draft | proposed / active | workspace and multi-package projects |
| RFC 078 | Draft | proposed / active | tool execution and typed workflow actions |
| RFC 079 | Draft | proposed / active | incan.pub artifact graph |
| RFC 080 | Draft | proposed / active | AI assets, models, prompts, evals, and agent metadata |
| RFC 081 | Draft | proposed / active | Language-shaped DSL embeddings |
| RFC 082 | Draft | proposed / active | Checked API documentation generation |
| RFC 083 | Done | closed / implemented | Symbol and method aliases |
| RFC 084 | Done | closed / implemented | RHS partial callable presets |
| RFC 085 | Planned | proposed / active | Field metadata and type-shaped constraints |
| RFC 086 | Planned | proposed / active | Schema descriptors and adapters |
| RFC 087 | Planned | proposed / active | Reusable field contracts and structural model composition |
| RFC 088 | Done | closed / implemented | Iterator adapter surface |
| RFC 089 | Draft | proposed / active | std.environ runtime environment access |
| RFC 090 | Draft | proposed / active | typed CLI framework |
| RFC 091 | Draft | proposed / active | Constrained integer newtype storage carriers |
| RFC 092 | Draft | proposed / active | Interactive Runtime Stdlib Contracts |
| RFC 093 | Draft | proposed / active | std.telemetry — OpenTelemetry-aligned observability |
| RFC 094 | Draft | proposed / active | Context managers |
| RFC 095 | Draft | proposed / active | span vocabulary blocks |
| RFC 096 | Draft | proposed / active | Declaration metadata blocks |
| RFC 097 | Draft | proposed / active | Rust-hosted Incan caller |
| RFC 098 | Draft | proposed / active | Native associated types for traits |
| RFC 099 | Draft | proposed / active | Generic trait-targeted methods |
| RFC 100 | Draft | proposed / active | std.re — Pythonic regular expressions |
| RFC 101 | Done | closed / implemented | std.collections.OrdinalMap — deterministic compact key-to-ordinal lookup |
| RFC 102 | Draft | proposed / active | Incan Semantic Layer Inspection Surface |
| RFC 103 | Draft | proposed / active | std.secrets — Secret strings, secret bytes, and redaction-safe values |
| RFC 104 | Draft | proposed / active | Ambient Runtime Capabilities and Receipts |
| RFC 105 | Draft | proposed / active | incan architect rule engine for design, safety, idiom, maintainability, and risk findings |
| RFC 106 | Draft | proposed / active | Compiler-backed agent context graph |
| RFC 107 | Draft | proposed / active | Type-directed library APIs and compile-time type tokens |
Compiler & Contributing¶
For contributors
Architecture and compiler-internals docs are primarily for contributors. If you’re learning the language, start with the Book and the Language Guide instead of RFCs.
Docs for contributors working on the compiler and language evolution:
| Document | Description |
|---|---|
| Roadmap | Tracks implementation status and near-term planning |
| RFCs | Design proposals for upcoming features are recorded in the form of RFCs |
| Contributing | Contributor documentation landing page |
| Compiler Architecture | Compilation pipeline, module layout, and internal stages |
| Extending the Language | When to add builtins vs new syntax; end-to-end checklists |
| Contributing Index | Contributor documentation landing page |