Incan feature inventory¶

Generated file

Do not edit this page by hand. If it looks wrong/outdated, update crates/incan_core/src/lang/features.rs and regenerate it.

Regenerate with: cargo run -p incan_core --bin generate_lang_reference

This page is a generated, present-tense atlas of user-facing Incan capabilities. It is intentionally higher-level than the generated language vocabulary tables: one feature can span syntax, type checking, stdlib source, manifests, tooling, and examples.

Use it when deciding whether code should use an existing Incan surface before adding wrappers, Rust fallbacks, or project-local conventions.

All features¶

Feature	Category	Since	Activation	Canonical forms	Summary	Prefer over	References
Namespaced stdlib imports and decorators	Stdlib	0.2	Import the relevant `std.*` module.	`from std.testing import assert_eq` `from std.web.routing import route` `@route("/hello")`	Standard-library APIs and compiler-owned decorators resolve through explicit `std.*` module paths.	Bare pre-0.2 stdlib names and ambient decorator magic.	Imports and modules, Standard library, Release 0.2
Rust interop boundary	Interop	0.2	Declare Rust dependencies in `incan.toml`; import through `rust` / `rust::` paths.	`from rust import uuid` `from rust::std::time import Instant` `type UserId = rusttype i64`	Incan can import Rust crates, bind Rust paths, declare `rusttype` wrappers, and model explicit interop edges.	Custom Rust backend modules used when ordinary Rust imports or wrappers are sufficient.	Rust interop, Rust types for Python developers, Release 0.2
Incan libraries and `pub::` imports	Libraries	0.2	Build libraries with `incan build --lib`; consume dependencies through `pub::` imports.	`from pub::mylib import my_function` `pub from session import Session`	Projects can publish public API manifests and downstream projects can import those public symbols.	Copying source files between projects or relying on private module paths.	Imports and modules, Release 0.2
Module static storage	Syntax	0.2	None.	`static hits: int = 0` `pub static registry: dict[str, int] = {}`	`static` declares live module-owned runtime storage, distinct from deeply immutable `const` values.	Module-level mutable state hidden behind ad hoc helper functions.	Static storage, Module state, Release 0.2
First-class function references	TypeSystem	0.2	None.	`handler: Callable[int, str] = label` `callbacks = [on_success, on_error]`	Named functions can be passed, stored, and typed with `Callable[...]` or function type syntax.	Closures or wrappers whose only job is to pass through an existing named function.	Functions and calls, Derives and traits, Release 0.2
Explicit call-site generics	TypeSystem	0.2	None.	`decode_rows[Order, _](path)` `session.read_csv[Order](path)`	Direct function and method calls can spell type arguments when inference needs help.	Adding throwaway typed locals or duplicate helper functions only to steer inference.	Derives and traits, Why call-site type arguments exist, Release 0.2
Abstract traits and supertraits	TypeSystem	0.2	None.	`trait OrderedCollection[T] with Collection[T]:` `def first(values: Collection[int]) -> int:`	Trait names are abstract annotation types, and traits can adopt supertraits with `with`.	Hidden generic bounds or duplicated method requirements when a trait annotation names the concept.	Derives and traits, Derives and traits explained
Source-defined derives and trait contracts	TypeSystem	0.2	Import the relevant `std.derives.`, `std.traits.`, or derivable module.	`@derive(json)` `model Row with Serialize:` `T with Clone`	Derive and trait surfaces are authored as named stdlib capability contracts rather than compiler folklore.	Backend-only helper shims or comments that claim derive behavior without source-visible contracts.	Derives and traits, std.derives, std.traits
Model field metadata and reflection	TypeSystem	0.2	None for field metadata; import `std.reflection` helpers when needed.	`name as "wire_name": str` `user.__fields__()`	Model fields can carry aliases/descriptions and reflection exposes typed `FieldInfo` metadata.	Stringly schema maps that duplicate model field names and wire aliases.	Reflection, std.reflection, Release 0.2
Value enums	TypeSystem	0.3	None.	`enum Level(str):` `WARN = "WARN"` `Level.from_value(raw)`	Enums can use `str` or `int` backing values while preserving enum type safety.	Loose string/int constants or duplicate parsing helpers around enum-like values.	Enums explained, Modeling with enums, Release 0.3
Union types and narrowing	TypeSystem	0.3	None.	`value: int \\| str` `if isinstance(value, int):` `match value:`	Closed anonymous unions support `Union[A, B]`, `A \\| B`, narrowing, and exhaustive match type patterns.	Untyped `Any`-like values, parallel option fields, or manual tag/payload models for closed alternatives.	Union types, Release 0.3
Validated newtypes and checked coercion	TypeSystem	0.3	None.	`type UserId = newtype int[ge=0]:` `Email.new(value)` `@no_implicit_coercion`	Newtypes can validate primitive constraints and participate in checked construction/coercion.	Raw primitives passed across APIs with comments describing expected invariants.	Newtypes, Book: newtypes, Release 0.3
Exact numeric types and conversions	TypeSystem	0.3	None.	`count: u32 = 1` `price: decimal[12, 2] = 19.99d` `small = value.try_resize()`	Exact integer widths, float widths, schema aliases, decimal precision/scale, and explicit resize policies are typed language surface.	Using broad `int`/`float` at wire, Rust interop, binary, or schema boundaries where representation matters.	Numeric semantics, Choosing numeric types, Release 0.3
`loop:` expressions and break values	Syntax	0.3	None.	`result = loop:` `break value`	Intentional infinite loops can produce values directly through `break <value>`.	Mutable sentinel initialization followed by later branch assignment.	Control flow, Book: control flow, Release 0.3
`if let` and `while let`	Syntax	0.3	None.	`if let Some(value) = maybe:` `while let Some(item) = iterator.next():`	Single-pattern control flow handles the common success-path case without full `match` scaffolding.	Verbose one-arm `match` blocks where the non-match path intentionally does nothing.	Control flow, Release 0.3
Pattern alternation	Syntax	0.3	None.	`Status.Pending \\| Status.Retrying => handle_waiting()`	`match` and `if let` patterns can share a branch across alternatives with compatible bindings.	Duplicated branch bodies for variants that have the same behavior.	Control flow, Release 0.3
Enum methods and trait adoption	TypeSystem	0.3	None.	`enum Direction with Display:` `def opposite(self) -> Direction:`	Enums can own methods, associated functions, and trait implementations directly in the enum body.	Detached helper functions for behavior that belongs to a closed enum.	Enums explained, Derives and traits, Release 0.3
Computed properties	Syntax	0.3	None.	`property display_name -> str:` `return self.first + " " + self.last`	Models, classes, and traits can expose field-like computed readers with `property`.	Zero-argument methods when callers should read a value-like member.	Computed properties, Models, Classes
Symbol, method, and variant aliases	Syntax	0.3	None.	`pub average = alias avg` `mean = avg` `WARNING = alias WARN`	Aliases expose another resolved name for the same declaration, method, or enum variant without duplicating behavior.	Wrapper functions or duplicated enum variants used only for compatibility names.	Symbol aliases, Imports and modules, Release 0.3
Callable presets with `partial`	Syntax	0.3	None.	`pub get = partial route(method="GET")` `set_alive = partial set_state(state=true)`	`partial` creates a callable surface from an existing callable by supplying named preset values.	Hand-written wrappers whose only job is to pass the same keyword defaults.	Callable presets, Callable presets explained, Release 0.3
Rest parameters, unpacking, and spreads	Syntax	0.3	None.	`def log(items: str, fields: str) -> None:` `f(xs, *kw)` `[prefix, item]` `{**base, "x": 1}`	Functions can capture `args` / `*kwargs`; calls and literals support typed unpack/spread forms.	Manually spelling every forwarding arity or merging collections one element at a time.	Functions and calls, Release 0.3
User-defined decorators	Syntax	0.3	None for user-defined decorators; compiler-owned decorators keep their documented imports.	`@logged` `@route("/users")` `@trace(level=Level.INFO)`	Decorators are ordinary callable values applied to functions and methods, including decorator factories.	Boilerplate wrapper declarations around every function that needs the same callable transform.	Language reference, Derives and traits, Release 0.3
Generators	Syntax	0.3	None.	`def numbers() -> Generator[int]:` `yield value` `(x * 2 for x in values)`	`yield`-based functions and generator expressions produce lazy `Generator[T]` values.	Eager list construction when callers only need lazy iteration.	Generators, Generators how-to, Release 0.3
Iterator adapters and terminal consumers	Stdlib	0.3	Use iterator values.	`values.iter().map(parse).filter(valid).collect()` `items.enumerate().take(10)` `numbers.fold(0, add)`	Iterator pipelines expose lazy adapters and explicit terminal consumers.	Manual loop accumulators for ordinary map/filter/fold pipeline shapes.	Collection protocols, Release 0.3
`Result[T, E]` combinators	Stdlib	0.3	Use `Result[T, E]` values.	`result.map(transform)` `result.and_then(validate)` `result.inspect(log_success)`	`Result` values support branch-local transforms, fallible chaining, recovery, and inspection taps.	Nested matches that only rewrap `Ok` / `Err` around one transformed branch.	std.result, Fallible and infallible paths, Release 0.3
Protocol hooks for core syntax	TypeSystem	0.3	Define compatible dunder hooks and adopt/document the corresponding trait vocabulary where useful.	`def __len__(self) -> int:` `def __iter__(self) -> Iterator[T]:` `def __call__(self, value: T) -> U:`	User-defined types can participate in truthiness, length, membership, iteration, indexing, assignment, and calls.	Special-casing custom types in caller code instead of giving the type the expected protocol.	Traits as language hooks, Collection protocols, Operators
Rust trait adoption from Incan	Interop	0.3	Import the Rust trait metadata and adopt with `with TraitName`.	`type UserId = rusttype i64 with Display:` `def fmt(self, f: Formatter) for Display -> Result[None, FmtError]:` `type Output for Add[int] = UserId`	Newtype and rusttype declarations can author Rust trait impls with Incan adoption syntax.	Writing Rust-shaped `impl Trait for Type` concepts in comments or custom backend code.	Rust interop, Derives and traits, Release 0.3
Targeted generated-Rust lint suppression	Interop	0.3	Use `@rust.allow(...)` on supported declarations.	`@rust.allow("dead_code")` `def helper() -> None:`	Generated Rust can receive narrow lint suppressions on individual items when source semantics require them.	Project-wide lint disables or broad generated-Rust allowance groups.	Rust interop, Release 0.3
Scoped DSL surfaces	Syntax	0.3	Import a vocab package that publishes scoped surface descriptors.	`query:` `.field` `\\|>` `sum(value)`	Library vocab crates can activate declaration, clause, glyph, leading-dot, and scoped symbol syntax inside their own DSL blocks.	Global parser changes for syntax that only belongs to one imported DSL.	Authoring vocab crates, Release 0.3
`std.collections` specialized containers	Stdlib	0.3	Import from `std.collections`.	`from std.collections import Deque, Counter, PriorityQueue` `queue = Deque[int]()`	Specialized containers cover deque, counter, default dict, ordered/sorted maps and sets, chain maps, and priority queues.	Encoding specialized container behavior in plain `list`, `dict`, or `set` plus ad hoc helpers.	std.collections, Choosing collections, Release 0.3
`std.graph` directed graph types	Stdlib	0.3	Import from `std.graph`.	`from std.graph import DiGraph, Dag` `graph = DiGraph[Task]()`	Graph types provide stable node/edge ids, DAG invariants, adjacency queries, traversal, and topological ordering.	Hand-rolled adjacency maps for ordinary dependency, plan, or workflow graphs.	std.graph, Release 0.3
`std.fs` filesystem APIs	Stdlib	0.3	Import from `std.fs` or submodules such as `std.fs.path`.	`from std.fs import Path` `Path("data").join("orders.csv")`	Path-centric filesystem APIs cover paths, files, metadata, traversal, globbing, copy/move/delete, and durability syncs.	One-off Rust filesystem wrappers for ordinary path and file work.	std.fs, File IO, Release 0.3
`std.io` in-memory binary streams	Stdlib	0.3	Import from `std.io`.	`from std.io import BytesIO, Endian` `stream.write(value, Endian.Little)`	Binary stream APIs cover `BytesIO`, endian-aware reads/writes, cursor helpers, delimiter operations, and buffer extraction.	Byte-twiddling helpers with unclear endian or cursor semantics.	std.io, Release 0.3
`std.json` dynamic JSON values	Stdlib	0.3	Import from `std.json`.	`from std.json import JsonValue` `JsonValue.parse(source)` `value["key"]` `value[0]`	`JsonValue` provides dynamic parse-inspect-transform JSON workflows with checked optional indexing, explicit shape inspection, mutation helpers, traversal, and typed-model interop.	Ad hoc dictionaries or over-modeled schemas for payloads whose shape is intentionally open.	std.json, Derives: Serialization, Release 0.3
`std.tempfile` temporary resources	Stdlib	0.3	Import from `std.tempfile`.	`NamedTemporaryFile.try_new()` `TemporaryDirectory.try_new()` `tmp.persist()`	Temporary files and directories are explicit resources with cleanup and persist semantics.	Manual random path generation or unchecked cleanup around temporary files.	std.tempfile, Release 0.3
`std.datetime` temporal values	Stdlib	0.3	Import from `std.datetime` modules or prelude.	`Date.utc_today()` `DateTime.utc_now()` `TimeDelta(days=1)`	Temporal APIs cover runtime timing, civil dates/times, fixed offsets, parsing/formatting, intervals, and calendar arithmetic.	Raw strings or integer timestamps inside code that has date/time semantics.	std.datetime, Dates and times, Dates and times how-to
`std.telemetry.core` data model	Stdlib	0.3	Import from `std.telemetry.core` or the `std.telemetry` prelude.	`from std.telemetry.core import TelemetryValue, Attributes` `TelemetryValue.string("ready")` `Attributes.from_string_fields(fields)`	Telemetry core provides structured values, attributes, resources, scopes, and trace context identifiers without configuring providers or exporters.	Stringifying structured observability fields before they reach logging or telemetry boundaries.	std.logging, Release 0.3
`std.logging` structured logging	Stdlib	0.3	Import from `std.logging`; ambient `log` is available for the current module logger.	`from std.logging import Level, basic_config` `log.info("started", fields={"component": "worker"})`	Structured logging includes levels, named loggers, bound fields, formatting, JSON rendering, and telemetry values.	Printing diagnostic strings or routing ordinary application logging through custom Rust shims.	std.logging, Release 0.3
Testing assertions and markers	Testing	0.3	Use `assert` directly; import marker/helper APIs from `std.testing`.	`assert value == expected` `assert call() raises ValueError` `@parametrize("case", cases)`	Tests can use language assertions, raises checks, helper assertions, fixtures, parametrization, and marker decorators.	Ad hoc panic helpers or external test metadata formats for ordinary Incan tests.	std.testing, Testing how-to, Release 0.3
`incan test` runner	Testing	0.3	Run `incan test`.	`module tests:` `incan test --list` `incan test --format json --junit report.xml`	The runner owns discovery, inline test modules, stable ids, selection, fixtures, parametrization, reporting, shuffling, and scheduling.	Project-local scripts that duplicate core test discovery and reporting behavior.	Tooling: testing, std.testing, Release 0.3
Async and await	Async	0.2	Import `std.async` or one of its submodules.	`from std.async.time import sleep` `async def main() -> None:` `await sleep(1)`	`async` and `await` are import-activated soft-keyword surfaces backed by `std.async` modules.	Threading async behavior through synchronous wrappers or relying on pre-0.2 ambient async syntax.	Async programming, std.async, Release 0.2
Async race and awaitability	Async	0.3	Import `std.async.race` or the relevant async prelude helpers.	`race for value:` `arm(task)` `race(arms)`	`Awaitable[T]`, `race for`, and helper-style race composition support first-ready async workflows.	Legacy `std.async.select` or hand-rolled polling loops.	Awaitable trait, Async programming, Release 0.3
Project lifecycle tooling	Tooling	0.3	Use `incan init`, `incan new`, `incan version`, or `incan env`.	`incan new greeter --yes` `incan version patch` `incan env test`	Project commands create scaffolds, manage versions, and run configured environments from `incan.toml`.	One-off project scaffolding scripts or manual version-file edits.	Project lifecycle, Project lifecycle how-to, Release 0.3
Checked API metadata	Tooling	0.3	Use `incan tools metadata api` or LSP metadata commands.	`incan tools metadata api src/lib.incn` `incan tools metadata model emit`	Typechecked public APIs can emit structured metadata for docs, manifests, hovers, and model bundle tooling.	Scraping source text or generated Rust when tooling needs API contracts.	Release 0.3, Project lifecycle
Formatter spacing and wrapping contract	Tooling	0.3	Run `incan fmt`.	`incan fmt src/main.incn` `incan fmt --check`	Formatter output has explicit vertical-spacing buckets, docstring normalization, comment attachment, and common wrapping rules.	Hand-maintained whitespace conventions that drift from the formatter.	Code style, Formatting how-to, Release 0.3

Feature details¶

Namespaced stdlib imports and decorators¶

Id: NamespacedStdlib
Category: Stdlib
Since: 0.2
RFC: RFC 022
Stability: Stable
Activation: Import the relevant std.* module.
Use instead of: Bare pre-0.2 stdlib names and ambient decorator magic.
References: Imports and modules, Standard library, Release 0.2

Standard-library APIs and compiler-owned decorators resolve through explicit std.* module paths.

Canonical forms:

from std.testing import assert_eq
from std.web.routing import route
@route("/hello")

Rust interop boundary¶

Id: RustInteropBoundary
Category: Interop
Since: 0.2
RFC: RFC 041
Stability: Stable
Activation: Declare Rust dependencies in incan.toml; import through rust / rust:: paths.
Use instead of: Custom Rust backend modules used when ordinary Rust imports or wrappers are sufficient.
References: Rust interop, Rust types for Python developers, Release 0.2

Incan can import Rust crates, bind Rust paths, declare rusttype wrappers, and model explicit interop edges.

Canonical forms:

from rust import uuid
from rust::std::time import Instant
type UserId = rusttype i64

Incan libraries and `pub::` imports¶

Id: IncanLibraries
Category: Libraries
Since: 0.2
RFC: RFC 031
Stability: Stable
Activation: Build libraries with incan build --lib; consume dependencies through pub:: imports.
Use instead of: Copying source files between projects or relying on private module paths.
References: Imports and modules, Release 0.2

Projects can publish public API manifests and downstream projects can import those public symbols.

Canonical forms:

from pub::mylib import my_function
pub from session import Session

Module static storage¶

Id: StaticStorage
Category: Syntax
Since: 0.2
RFC: RFC 052
Stability: Stable
Activation: None.
Use instead of: Module-level mutable state hidden behind ad hoc helper functions.
References: Static storage, Module state, Release 0.2

static declares live module-owned runtime storage, distinct from deeply immutable const values.

Canonical forms:

static hits: int = 0
pub static registry: dict[str, int] = {}

First-class function references¶

Id: FirstClassFunctions
Category: TypeSystem
Since: 0.2
RFC: RFC 035
Stability: Stable
Activation: None.
Use instead of: Closures or wrappers whose only job is to pass through an existing named function.
References: Functions and calls, Derives and traits, Release 0.2

Named functions can be passed, stored, and typed with Callable[...] or function type syntax.

Canonical forms:

handler: Callable[int, str] = label
callbacks = [on_success, on_error]

Explicit call-site generics¶

Id: CallSiteGenerics
Category: TypeSystem
Since: 0.2
RFC: RFC 054
Stability: Stable
Activation: None.
Use instead of: Adding throwaway typed locals or duplicate helper functions only to steer inference.
References: Derives and traits, Why call-site type arguments exist, Release 0.2

Direct function and method calls can spell type arguments when inference needs help.

Canonical forms:

decode_rows[Order, _](path)
session.read_csv[Order](path)

Abstract traits and supertraits¶

Id: AbstractTraits
Category: TypeSystem
Since: 0.2
RFC: RFC 042
Stability: Stable
Activation: None.
Use instead of: Hidden generic bounds or duplicated method requirements when a trait annotation names the concept.
References: Derives and traits, Derives and traits explained

Trait names are abstract annotation types, and traits can adopt supertraits with with.

Canonical forms:

trait OrderedCollection[T] with Collection[T]:
def first(values: Collection[int]) -> int:

Source-defined derives and trait contracts¶

Id: SourceDefinedDerivesTraits
Category: TypeSystem
Since: 0.2
RFC: RFC 024
Stability: Stable
Activation: Import the relevant std.derives.*, std.traits.*, or derivable module.
Use instead of: Backend-only helper shims or comments that claim derive behavior without source-visible contracts.
References: Derives and traits, std.derives, std.traits

Derive and trait surfaces are authored as named stdlib capability contracts rather than compiler folklore.

Canonical forms:

@derive(json)
model Row with Serialize:
T with Clone

Model field metadata and reflection¶

Id: ModelFieldMetadata
Category: TypeSystem
Since: 0.2
RFC: RFC 021
Stability: Stable
Activation: None for field metadata; import std.reflection helpers when needed.
Use instead of: Stringly schema maps that duplicate model field names and wire aliases.
References: Reflection, std.reflection, Release 0.2

Model fields can carry aliases/descriptions and reflection exposes typed FieldInfo metadata.

Canonical forms:

name as "wire_name": str
user.__fields__()

Value enums¶

Id: ValueEnums
Category: TypeSystem
Since: 0.3
RFC: RFC 032
Stability: Stable
Activation: None.
Use instead of: Loose string/int constants or duplicate parsing helpers around enum-like values.
References: Enums explained, Modeling with enums, Release 0.3

Enums can use str or int backing values while preserving enum type safety.

Canonical forms:

enum Level(str):
WARN = "WARN"
Level.from_value(raw)

Union types and narrowing¶

Id: UnionTypes
Category: TypeSystem
Since: 0.3
RFC: RFC 029
Stability: Stable
Activation: None.
Use instead of: Untyped Any-like values, parallel option fields, or manual tag/payload models for closed alternatives.
References: Union types, Release 0.3

Closed anonymous unions support Union[A, B], A | B, narrowing, and exhaustive match type patterns.

Canonical forms:

value: int | str
if isinstance(value, int):
match value:

Validated newtypes and checked coercion¶

Id: ValidatedNewtypes
Category: TypeSystem
Since: 0.3
RFC: RFC 017
Stability: Stable
Activation: None.
Use instead of: Raw primitives passed across APIs with comments describing expected invariants.
References: Newtypes, Book: newtypes, Release 0.3

Newtypes can validate primitive constraints and participate in checked construction/coercion.

Canonical forms:

type UserId = newtype int[ge=0]:
Email.new(value)
@no_implicit_coercion

Exact numeric types and conversions¶

Id: NumericTypeSystem
Category: TypeSystem
Since: 0.3
RFC: RFC 009
Stability: Stable
Activation: None.
Use instead of: Using broad int/float at wire, Rust interop, binary, or schema boundaries where representation matters.
References: Numeric semantics, Choosing numeric types, Release 0.3

Exact integer widths, float widths, schema aliases, decimal precision/scale, and explicit resize policies are typed language surface.

Canonical forms:

count: u32 = 1
price: decimal[12, 2] = 19.99d
small = value.try_resize()

`loop:` expressions and break values¶

Id: LoopExpressions
Category: Syntax
Since: 0.3
RFC: RFC 016
Stability: Stable
Activation: None.
Use instead of: Mutable sentinel initialization followed by later branch assignment.
References: Control flow, Book: control flow, Release 0.3

Intentional infinite loops can produce values directly through break <value>.

Canonical forms:

result = loop:
break value

`if let` and `while let`¶

Id: IfWhileLet
Category: Syntax
Since: 0.3
RFC: RFC 049
Stability: Stable
Activation: None.
Use instead of: Verbose one-arm match blocks where the non-match path intentionally does nothing.
References: Control flow, Release 0.3

Single-pattern control flow handles the common success-path case without full match scaffolding.

Canonical forms:

if let Some(value) = maybe:
while let Some(item) = iterator.next():

Pattern alternation¶

Id: PatternAlternation
Category: Syntax
Since: 0.3
RFC: RFC 071
Stability: Stable
Activation: None.
Use instead of: Duplicated branch bodies for variants that have the same behavior.
References: Control flow, Release 0.3

match and if let patterns can share a branch across alternatives with compatible bindings.

Canonical forms:

Status.Pending | Status.Retrying => handle_waiting()

Enum methods and trait adoption¶

Id: EnumMethodsTraits
Category: TypeSystem
Since: 0.3
RFC: RFC 050
Stability: Stable
Activation: None.
Use instead of: Detached helper functions for behavior that belongs to a closed enum.
References: Enums explained, Derives and traits, Release 0.3

Enums can own methods, associated functions, and trait implementations directly in the enum body.

Canonical forms:

enum Direction with Display:
def opposite(self) -> Direction:

Computed properties¶

Id: ComputedProperties
Category: Syntax
Since: 0.3
RFC: RFC 046
Stability: Stable
Activation: None.
Use instead of: Zero-argument methods when callers should read a value-like member.
References: Computed properties, Models, Classes

Models, classes, and traits can expose field-like computed readers with property.

Canonical forms:

property display_name -> str:
return self.first + " " + self.last

Symbol, method, and variant aliases¶

Id: SymbolAliases
Category: Syntax
Since: 0.3
RFC: RFC 083
Stability: Stable
Activation: None.
Use instead of: Wrapper functions or duplicated enum variants used only for compatibility names.
References: Symbol aliases, Imports and modules, Release 0.3

Aliases expose another resolved name for the same declaration, method, or enum variant without duplicating behavior.

Canonical forms:

pub average = alias avg
mean = avg
WARNING = alias WARN

Callable presets with `partial`¶

Id: CallablePresets
Category: Syntax
Since: 0.3
RFC: RFC 084
Stability: Stable
Activation: None.
Use instead of: Hand-written wrappers whose only job is to pass the same keyword defaults.
References: Callable presets, Callable presets explained, Release 0.3

partial creates a callable surface from an existing callable by supplying named preset values.

Canonical forms:

pub get = partial route(method="GET")
set_alive = partial set_state(state=true)

Rest parameters, unpacking, and spreads¶

Id: VariadicAndSpreadCalls
Category: Syntax
Since: 0.3
RFC: RFC 038
Stability: Stable
Activation: None.
Use instead of: Manually spelling every forwarding arity or merging collections one element at a time.
References: Functions and calls, Release 0.3

Functions can capture *args / **kwargs; calls and literals support typed unpack/spread forms.

Canonical forms:

def log(*items: str, **fields: str) -> None:
f(*xs, **kw)
[*prefix, item]
{**base, "x": 1}

User-defined decorators¶

Id: UserDefinedDecorators
Category: Syntax
Since: 0.3
RFC: RFC 036
Stability: Stable
Activation: None for user-defined decorators; compiler-owned decorators keep their documented imports.
Use instead of: Boilerplate wrapper declarations around every function that needs the same callable transform.
References: Language reference, Derives and traits, Release 0.3

Decorators are ordinary callable values applied to functions and methods, including decorator factories.

Canonical forms:

@logged
@route("/users")
@trace(level=Level.INFO)

Generators¶

Id: Generators
Category: Syntax
Since: 0.3
RFC: RFC 006
Stability: Stable
Activation: None.
Use instead of: Eager list construction when callers only need lazy iteration.
References: Generators, Generators how-to, Release 0.3

yield-based functions and generator expressions produce lazy Generator[T] values.

Canonical forms:

def numbers() -> Generator[int]:
yield value
(x * 2 for x in values)

Iterator adapters and terminal consumers¶

Id: IteratorAdapters
Category: Stdlib
Since: 0.3
RFC: RFC 088
Stability: Stable
Activation: Use iterator values.
Use instead of: Manual loop accumulators for ordinary map/filter/fold pipeline shapes.
References: Collection protocols, Release 0.3

Iterator pipelines expose lazy adapters and explicit terminal consumers.

Canonical forms:

values.iter().map(parse).filter(valid).collect()
items.enumerate().take(10)
numbers.fold(0, add)

`Result[T, E]` combinators¶

Id: ResultCombinators
Category: Stdlib
Since: 0.3
RFC: RFC 070
Stability: Stable
Activation: Use Result[T, E] values.
Use instead of: Nested matches that only rewrap Ok / Err around one transformed branch.
References: std.result, Fallible and infallible paths, Release 0.3

Result values support branch-local transforms, fallible chaining, recovery, and inspection taps.

Canonical forms:

result.map(transform)
result.and_then(validate)
result.inspect(log_success)

Protocol hooks for core syntax¶

Id: ProtocolHooks
Category: TypeSystem
Since: 0.3
RFC: RFC 068
Stability: Stable
Activation: Define compatible dunder hooks and adopt/document the corresponding trait vocabulary where useful.
Use instead of: Special-casing custom types in caller code instead of giving the type the expected protocol.
References: Traits as language hooks, Collection protocols, Operators

User-defined types can participate in truthiness, length, membership, iteration, indexing, assignment, and calls.

Canonical forms:

def __len__(self) -> int:
def __iter__(self) -> Iterator[T]:
def __call__(self, value: T) -> U:

Rust trait adoption from Incan¶

Id: RustTraitAdoption
Category: Interop
Since: 0.3
RFC: RFC 043
Stability: Stable
Activation: Import the Rust trait metadata and adopt with with TraitName.
Use instead of: Writing Rust-shaped impl Trait for Type concepts in comments or custom backend code.
References: Rust interop, Derives and traits, Release 0.3

Newtype and rusttype declarations can author Rust trait impls with Incan adoption syntax.

Canonical forms:

type UserId = rusttype i64 with Display:
def fmt(self, f: Formatter) for Display -> Result[None, FmtError]:
type Output for Add[int] = UserId

Targeted generated-Rust lint suppression¶

Id: RustAllow
Category: Interop
Since: 0.3
RFC: RFC 057
Stability: Stable
Activation: Use @rust.allow(...) on supported declarations.
Use instead of: Project-wide lint disables or broad generated-Rust allowance groups.
References: Rust interop, Release 0.3

Generated Rust can receive narrow lint suppressions on individual items when source semantics require them.

Canonical forms:

@rust.allow("dead_code")
def helper() -> None:

Scoped DSL surfaces¶

Id: ScopedDslSurfaces
Category: Syntax
Since: 0.3
RFC: RFC 040
Stability: Stable
Activation: Import a vocab package that publishes scoped surface descriptors.
Use instead of: Global parser changes for syntax that only belongs to one imported DSL.
References: Authoring vocab crates, Release 0.3

Library vocab crates can activate declaration, clause, glyph, leading-dot, and scoped symbol syntax inside their own DSL blocks.

Canonical forms:

query:
.field
|>
sum(value)

`std.collections` specialized containers¶

Id: StdCollections
Category: Stdlib
Since: 0.3
RFC: RFC 030
Stability: Stable
Activation: Import from std.collections.
Use instead of: Encoding specialized container behavior in plain list, dict, or set plus ad hoc helpers.
References: std.collections, Choosing collections, Release 0.3

Specialized containers cover deque, counter, default dict, ordered/sorted maps and sets, chain maps, and priority queues.

Canonical forms:

from std.collections import Deque, Counter, PriorityQueue
queue = Deque[int]()

`std.graph` directed graph types¶

Id: StdGraph
Category: Stdlib
Since: 0.3
RFC: RFC 047
Stability: Stable
Activation: Import from std.graph.
Use instead of: Hand-rolled adjacency maps for ordinary dependency, plan, or workflow graphs.
References: std.graph, Release 0.3

Graph types provide stable node/edge ids, DAG invariants, adjacency queries, traversal, and topological ordering.

Canonical forms:

from std.graph import DiGraph, Dag
graph = DiGraph[Task]()

`std.fs` filesystem APIs¶

Id: StdFs
Category: Stdlib
Since: 0.3
RFC: RFC 055
Stability: Stable
Activation: Import from std.fs or submodules such as std.fs.path.
Use instead of: One-off Rust filesystem wrappers for ordinary path and file work.
References: std.fs, File IO, Release 0.3

Path-centric filesystem APIs cover paths, files, metadata, traversal, globbing, copy/move/delete, and durability syncs.

Canonical forms:

from std.fs import Path
Path("data").join("orders.csv")

`std.io` in-memory binary streams¶

Id: StdIo
Category: Stdlib
Since: 0.3
RFC: RFC 056
Stability: Stable
Activation: Import from std.io.
Use instead of: Byte-twiddling helpers with unclear endian or cursor semantics.
References: std.io, Release 0.3

Binary stream APIs cover BytesIO, endian-aware reads/writes, cursor helpers, delimiter operations, and buffer extraction.

Canonical forms:

from std.io import BytesIO, Endian
stream.write(value, Endian.Little)

`std.json` dynamic JSON values¶

Id: StdJson
Category: Stdlib
Since: 0.3
RFC: RFC 051
Stability: Stable
Activation: Import from std.json.
Use instead of: Ad hoc dictionaries or over-modeled schemas for payloads whose shape is intentionally open.
References: std.json, Derives: Serialization, Release 0.3

JsonValue provides dynamic parse-inspect-transform JSON workflows with checked optional indexing, explicit shape inspection, mutation helpers, traversal, and typed-model interop.

Canonical forms:

from std.json import JsonValue
JsonValue.parse(source)
value["key"]
value[0]

`std.tempfile` temporary resources¶

Id: StdTempfile
Category: Stdlib
Since: 0.3
RFC: RFC 010
Stability: Stable
Activation: Import from std.tempfile.
Use instead of: Manual random path generation or unchecked cleanup around temporary files.
References: std.tempfile, Release 0.3

Temporary files and directories are explicit resources with cleanup and persist semantics.

Canonical forms:

NamedTemporaryFile.try_new()
TemporaryDirectory.try_new()
tmp.persist()

`std.datetime` temporal values¶

Id: StdDatetime
Category: Stdlib
Since: 0.3
RFC: RFC 058
Stability: Stable
Activation: Import from std.datetime modules or prelude.
Use instead of: Raw strings or integer timestamps inside code that has date/time semantics.
References: std.datetime, Dates and times, Dates and times how-to

Temporal APIs cover runtime timing, civil dates/times, fixed offsets, parsing/formatting, intervals, and calendar arithmetic.

Canonical forms:

Date.utc_today()
DateTime.utc_now()
TimeDelta(days=1)

`std.telemetry.core` data model¶

Id: StdTelemetryCore
Category: Stdlib
Since: 0.3
RFC: RFC 072
Stability: Stable
Activation: Import from std.telemetry.core or the std.telemetry prelude.
Use instead of: Stringifying structured observability fields before they reach logging or telemetry boundaries.
References: std.logging, Release 0.3

Telemetry core provides structured values, attributes, resources, scopes, and trace context identifiers without configuring providers or exporters.

Canonical forms:

from std.telemetry.core import TelemetryValue, Attributes
TelemetryValue.string("ready")
Attributes.from_string_fields(fields)

`std.logging` structured logging¶

Id: StdLogging
Category: Stdlib
Since: 0.3
RFC: RFC 072
Stability: Stable
Activation: Import from std.logging; ambient log is available for the current module logger.
Use instead of: Printing diagnostic strings or routing ordinary application logging through custom Rust shims.
References: std.logging, Release 0.3

Structured logging includes levels, named loggers, bound fields, formatting, JSON rendering, and telemetry values.

Canonical forms:

from std.logging import Level, basic_config
log.info("started", fields={"component": "worker"})

Testing assertions and markers¶

Id: TestingAssertions
Category: Testing
Since: 0.3
RFC: RFC 018
Stability: Stable
Activation: Use assert directly; import marker/helper APIs from std.testing.
Use instead of: Ad hoc panic helpers or external test metadata formats for ordinary Incan tests.
References: std.testing, Testing how-to, Release 0.3

Tests can use language assertions, raises checks, helper assertions, fixtures, parametrization, and marker decorators.

Canonical forms:

assert value == expected
assert call() raises ValueError
@parametrize("case", cases)

`incan test` runner¶

Id: TestRunner
Category: Testing
Since: 0.3
RFC: RFC 019
Stability: Stable
Activation: Run incan test.
Use instead of: Project-local scripts that duplicate core test discovery and reporting behavior.
References: Tooling: testing, std.testing, Release 0.3

The runner owns discovery, inline test modules, stable ids, selection, fixtures, parametrization, reporting, shuffling, and scheduling.

Canonical forms:

module tests:
incan test --list
incan test --format json --junit report.xml

Async and await¶

Id: AsyncAwait
Category: Async
Since: 0.2
RFC: RFC 023
Stability: Stable
Activation: Import std.async or one of its submodules.
Use instead of: Threading async behavior through synchronous wrappers or relying on pre-0.2 ambient async syntax.
References: Async programming, std.async, Release 0.2

async and await are import-activated soft-keyword surfaces backed by std.async modules.

Canonical forms:

from std.async.time import sleep
async def main() -> None:
await sleep(1)

Async race and awaitability¶

Id: AsyncRace
Category: Async
Since: 0.3
RFC: RFC 039
Stability: Stable
Activation: Import std.async.race or the relevant async prelude helpers.
Use instead of: Legacy std.async.select or hand-rolled polling loops.
References: Awaitable trait, Async programming, Release 0.3

Awaitable[T], race for, and helper-style race composition support first-ready async workflows.

Canonical forms:

race for value:
arm(task)
race(arms)

Project lifecycle tooling¶

Id: ProjectLifecycle
Category: Tooling
Since: 0.3
RFC: RFC 015
Stability: Stable
Activation: Use incan init, incan new, incan version, or incan env.
Use instead of: One-off project scaffolding scripts or manual version-file edits.
References: Project lifecycle, Project lifecycle how-to, Release 0.3

Project commands create scaffolds, manage versions, and run configured environments from incan.toml.

Canonical forms:

incan new greeter --yes
incan version patch
incan env test

Checked API metadata¶

Id: CheckedApiMetadata
Category: Tooling
Since: 0.3
RFC: RFC 048
Stability: Stable
Activation: Use incan tools metadata api or LSP metadata commands.
Use instead of: Scraping source text or generated Rust when tooling needs API contracts.
References: Release 0.3, Project lifecycle

Typechecked public APIs can emit structured metadata for docs, manifests, hovers, and model bundle tooling.

Canonical forms:

incan tools metadata api src/lib.incn
incan tools metadata model emit

Formatter spacing and wrapping contract¶

Id: FormatterContract
Category: Tooling
Since: 0.3
RFC: RFC 053
Stability: Stable
Activation: Run incan fmt.
Use instead of: Hand-maintained whitespace conventions that drift from the formatter.
References: Code style, Formatting how-to, Release 0.3

Formatter output has explicit vertical-spacing buckets, docstring normalization, comment attachment, and common wrapping rules.

Canonical forms:

incan fmt src/main.incn
incan fmt --check

Incan feature inventory¶

Contents¶

All features¶

Feature details¶

Namespaced stdlib imports and decorators¶

Rust interop boundary¶

Incan libraries and pub:: imports¶

Module static storage¶

First-class function references¶

Explicit call-site generics¶

Abstract traits and supertraits¶

Source-defined derives and trait contracts¶

Model field metadata and reflection¶

Value enums¶

Union types and narrowing¶

Validated newtypes and checked coercion¶

Exact numeric types and conversions¶

loop: expressions and break values¶

if let and while let¶

Pattern alternation¶

Enum methods and trait adoption¶

Computed properties¶

Symbol, method, and variant aliases¶

Callable presets with partial¶

Rest parameters, unpacking, and spreads¶

User-defined decorators¶

Generators¶

Iterator adapters and terminal consumers¶

Result[T, E] combinators¶

Protocol hooks for core syntax¶

Rust trait adoption from Incan¶

Targeted generated-Rust lint suppression¶

Scoped DSL surfaces¶

std.collections specialized containers¶

std.graph directed graph types¶

std.fs filesystem APIs¶

std.io in-memory binary streams¶

std.json dynamic JSON values¶

std.tempfile temporary resources¶

std.datetime temporal values¶

std.telemetry.core data model¶

std.logging structured logging¶

Testing assertions and markers¶

incan test runner¶

Async and await¶

Async race and awaitability¶

Project lifecycle tooling¶

Checked API metadata¶

Formatter spacing and wrapping contract¶

Incan libraries and `pub::` imports¶

`loop:` expressions and break values¶

`if let` and `while let`¶

Callable presets with `partial`¶

`Result[T, E]` combinators¶

`std.collections` specialized containers¶

`std.graph` directed graph types¶

`std.fs` filesystem APIs¶

`std.io` in-memory binary streams¶

`std.json` dynamic JSON values¶

`std.tempfile` temporary resources¶

`std.datetime` temporal values¶

`std.telemetry.core` data model¶

`std.logging` structured logging¶

`incan test` runner¶