← Yeho system guidePublic language guide

Academy of Wisdom / living language atlas

Every Yeho
and YUI lever.

Learn the language from the first variable to native and GPU compute, then build native interfaces with YUI surfaces, components, controls, bindings, retained rendering, and accessibility. Search every feature and copy a working-shaped example into your own project.

How to read this language

Green and blue mean build. Purple means inspect the boundary.

Every topic is tied to the Yeho parser, machine-readable conformance edition, compiler fixtures, canonical language docs, or the public YUI candidate. Stable examples belong to the admitted core. Candidate examples belong to YUI's verified Windows x64 path while its remaining promotion gates stay visible. Oracle-only examples are never presented as Kyber product support.

59
feature lessons
91
syntax words mapped
37/37
conformance contracts covered

Language at a glance

The complete vocabulary map.

Keywords and syntax words 91
thingDeclare plain value data
classDeclare reference-shaped object data
interfaceDeclare a behavioral contract
thisRead the current instance
enumDeclare named cases
externalExpose a package declaration
usingImport a dotted package path
externDeclare a native C boundary
computeDeclare or access portable compute
dispatchLaunch a compute function
taskName or start asynchronous work
parallelRun admitted work concurrently
tunnelCarry a typed value between concurrent work
waitPause for time, a frame, a task, or a condition
stopRequest task cancellation
ifStart a boolean branch
elseProvide the next or fallback branch
matchBranch on a closed value shape
withBind a match payload
whileRepeat while a condition is true
loopRepeat until explicitly ended
forIterate a range or collection
fromStart a numeric range
inChoose the collection to iterate
atBind an iteration index
reverseTraverse a collection backward
whereFilter collection iteration
nextContinue the nearest loop
endExit the nearest loop
returnLeave a function with an optional value
yieldProduce a value in the oracle-only callable surface
requiresDeclare a precondition
ensuresDeclare a postcondition
invariantDeclare valid object state
tryStart oracle-only exception handling
catchHandle an oracle-only thrown error
throwRaise an oracle-only error
copyRequest an independent value binding
originalRequest an admitted original alias
memoryAddressRequest a reviewed address alias
extensionBind an extension receiver parameter
publicExpose a member publicly
internalExpose within a package
protectedExpose through inheritance
privateKeep a member inside its owner
staticAttach a member to the type
readonlyPrevent ordinary field replacement
initAllow initialization-only assignment
abstractRequire implementation on the oracle object surface
sealedClose further inheritance or override
finalClose further inheritance or override
overrideImplement an inherited method
extendsName a base class
inheritsAlternative base-class connector
implementsName class interfaces
delegateForward a method through a field
getAllow property reading
setAllow property replacement
ofConnect a container to its element type
toConnect map key/value or function input/output types
isTest a named type
asCast to a named type
andShort-circuit boolean conjunction
orShort-circuit boolean disjunction
awaitRead an admitted task result
trueBoolean true literal
falseBoolean false literal
nullNullable absence literal
functionDescribe an oracle-only function value or lambda
tupleDescribe a gated multi-value experiment
deconstructSplit a gated tuple into names
intoConnect deconstruction to its names
planQueue an oracle-only collection mutation
removeRemove a planned item
removeAtRemove a planned index
addAdd a planned item
addAtAdd a planned item at an index
doboxDeprecated spelling of thing
stringDeprecated spelling of text
returnsDeprecated spelling of ->
choiceRemoved spelling; use enum
channelRemoved spelling; use tunnel
exportRemoved spelling; use external
eventDeferred syntax; use functions, tasks, and tunnels
emitDeferred syntax; call a function or send through a tunnel
watchDeferred syntax; use an explicit update flow
assertUnavailable statement; use an explicit check and error
panicUnavailable fatal statement
constUnavailable declaration form
threadUnavailable source syntax; use task
endLoopsUnavailable broad loop escape
Built-in type families 64

Core

voidbooltextcharruneerror

Signed integers

int8int16intint32int64int128

Unsigned integers

byteuint8uint16uintuint32uint64uint128

Signed packed bits

bit1bit2bit3bit4bit5bit6bit7bit8

Unsigned packed bits

ubit1ubit2ubit3ubit4ubit5ubit6ubit7ubit8

Binary floats

float8float16floatfloat32float64float128

Signed decimals

decimal8decimal16decimaldecimal32decimal64decimal128

Unsigned decimals

udecimal8udecimal16udecimaludecimal32udecimal64udecimal128

Containers and handles

list of Tmap of K to Vset of Tbuffer of Ttasktask of Ttunnel of TcomputeTask

Migration and experiments

string (deprecated)tuple of A, B (gated)function of A to B (oracle only)
Operators 27

Arithmetic

+-*/

Comparison

==!=<<=>>=

Boolean

!andor

Bitwise

~&^|<<>>

Type

isas?

Structure

=->.[]()

Showing 59 of 59 feature lessons

01

Yeho and YUI chapter

Start and run

Projects, entry files, comments, separators, and the shortest path to a native program.

3 lessons
Stable

Project entry and source files

Part of the admitted Yeho Core 2026.1 surface.

A Yeho project starts in start.yh. Top-level statements are the program, so there is no ceremonial main function.

When to use it

Use start.yh for executable entry behavior and more .yh files for declarations you want the project to compile together.

Syntax
start.yh*.yh*.y*.yeho*.yo
start.yh
Console.Log("Hello from Yeho")

int answer = 40 + 2
Console.Log(Text.From(answer))
  • start.yh is canonical.
  • main.yh remains a deprecated compatibility fallback.
  • .ys is reserved for sandboxed YehoScript assets rather than ordinary project source.
Syntax words

start.yhproject.mech

Source of truthdocs/language/language-core.md §2; tests/compiler/kyber/hello-runtime/start.yh
Stable

Comments, newlines, and semicolons

Part of the admitted Yeho Core 2026.1 surface.

Line comments begin with //. Newlines normally separate statements, and semicolons are optional.

When to use it

Prefer one readable statement per line. Add semicolons only when they make a compact expression easier to scan.

Syntax
// commentstatementstatement;
Readable statements
// Explain why, not what the next token says.
int lives = 3
text hero = "Nova";
Console.Log(hero)
  • Blocks use braces.
  • Whitespace is not an ownership or control-flow signal.
Syntax words

//

Source of truthdocs/language/language-core.md §2.5; lexer and parser separator fixtures
Stable

Create, run, and build

Part of the admitted Yeho Core 2026.1 surface.

The workspace wrapper creates a project, checks it, runs it, or emits its native Windows x64 artifact.

When to use it

Use run during the creative loop, check for fast language feedback, and build when you need the actual executable.

Syntax
.\tools\yeho.ps1 new console <path> <name>.\tools\yeho.ps1 check <path>.\tools\yeho.ps1 run <path>.\tools\yeho.ps1 build <path>
PowerShell
.\tools\yeho.ps1 new console .\hello hello.app
.\tools\yeho.ps1 check .\hello
.\tools\yeho.ps1 run .\hello
.\tools\yeho.ps1 build .\hello
  • The current promoted product target is Windows x64.
  • Product builds lower through Forge and Kyber rather than generating C++.
Syntax words

newcheckrunbuild

Source of truthREADME.md §Quick start; tools/yeho.ps1
02

Yeho and YUI chapter

Values and types

Variables, assignment, literals, text, numbers, booleans, nullability, and the complete built-in type families.

5 lessons
Stable

Variables and assignment

Part of the admitted Yeho Core 2026.1 surface.

Types come before names. Declare with an initial value, then use = to replace the value.

When to use it

Use a narrow explicit type when the value is part of the program's meaning or machine contract.

Syntax
Type name = expressionname = expression
Declare and update
int score = 10
score = score + 5

text message = "Score: " + Text.From(score)
Console.Log(message)
  • Implicit untyped declarations are not admitted.
  • Compound assignment such as += is unavailable. Spell the complete assignment.
Syntax words

=

Source of truthdocs/language/language-core.md §3.6; tests/compiler/kyber/scalar-runtime/start.yh
Stable

Literals and escapes

Part of the admitted Yeho Core 2026.1 surface.

Yeho has text, character, integer, floating-point, boolean, and null literals with explicit escape sequences.

When to use it

Use literals for small values that are obvious at the point of use. Give repeated domain values a named field or function.

Syntax
"text"'c'423.146.02e23truefalsenull
Literal forms
text greeting = "hello\nworld"
char initial = 'Y'
int count = 42
float ratio = 1.5
bool ready = true
Pilot? selected = null
  • Supported escapes include \\, \n, \r, \t, \0, escaped quotes, and Unicode \u{...}.
  • Interpolated text and hex, binary, or separator numeric literals are not admitted.
Syntax words

truefalsenull

Source of truthdocs/language/language-core.md §2.6-2.9; lexer literal fixtures
Stable

Integer, bit, float, and decimal types

Part of the admitted Yeho Core 2026.1 surface.

Yeho exposes signed and unsigned integer widths, packed bit widths, binary floating point, and decimal families.

When to use it

Choose int for ordinary counts, explicit widths for ABI or storage contracts, float for binary math, and decimal when decimal meaning matters.

Syntax
int8 | int16 | int | int32 | int64 | int128byte | uint8 | uint16 | uint | uint32 | uint64 | uint128bit1..bit8 | ubit1..ubit8float8 | float16 | float | float32 | float64 | float128decimal8 | decimal16 | decimal | decimal32 | decimal64 | decimal128udecimal8 | udecimal16 | udecimal | udecimal32 | udecimal64 | udecimal128
Choose by meaning
int enemies = 12
uint64 fileBytes = 4096
float32 speed = 7.5
decimal64 price = 19.95
bit3 tinyState = 5
  • Not every width is equally accelerated on every backend.
  • Overflow and conversion behavior belongs to the type and target contract, not an implicit truthy conversion.
Syntax words

intuintbytebitfloatdecimaludecimal

Source of truthsrc/compiler/frontend/parser_types.cpp builtinTypeKind; docs/language/language-core.md §3.2
Stable

Text, char, rune, and bool

Part of the admitted Yeho Core 2026.1 surface.

text is an owned text value, char is a character literal unit, rune represents a Unicode scalar, and bool is true or false only.

When to use it

Use text for words and messages, rune when Unicode scalar identity matters, and bool for decisions.

Syntax
text name = "..."char name = 'x'rune name = ...bool name = true
Text and decisions
text name = "Ada"
char grade = 'A'
bool admitted = Text.Length(name) > 0 and grade == 'A'
Console.Log(Text.From(admitted))
  • text is the preferred spelling. string is deprecated.
  • Conditions require bool. Numbers, text, null, and collections are not truthy or falsy.
Syntax words

textcharrunebool

Source of truthdocs/language/language-core.md §3.2 and §3.7; memory-lifetime-unsafe-2026.1.json
Oracle only

Nullable types

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

A ? suffix declares a nullable reference-like value, but the complete flow analysis is not in the Kyber product path yet.

When to use it

Use only when deliberately running the comparison oracle. In Kyber-ready code, model absence explicitly with a bool, enum, or sentinel thing.

Syntax
Type? name = null
Oracle route
Pilot? selected = null

if selected == null
{
    Console.Log("No pilot selected")
}
Kyber-ready alternative
thing PilotSelection
{
    bool hasPilot
    text pilotName
}
  • Nullable reference flow is classified generated-C++ only in the 2026.1 conformance manifest.
  • Do not present parser acceptance as native product support.
Syntax words

?null

Source of truthdocs/language/conformance-2026.1.json: nullable-reference-flow
03

Yeho and YUI chapter

Data and objects

Things, classes, interfaces, fields, properties, visibility, inheritance, and invariants.

4 lessons
Stable

Things: plain value data

Part of the admitted Yeho Core 2026.1 surface.

thing defines plain value-shaped data. It is Yeho's default way to name a bundle of related fields.

When to use it

Start with thing for coordinates, settings, records, messages, and other data that should behave like a value.

Syntax
thing Name { Type field }Name value = Name(arguments...)
A small value
thing Point
{
    int x
    int y
}

Point spawn = Point(12, 8)
Console.Log(Text.From(spawn.x))
  • thing is preferred over the deprecated dobox alias.
  • Things can contain other things, which is how larger data maps stay understandable.
Syntax words

thing

Source of truthdocs/language/language-core.md §3.1; tests/compiler/kyber/thing-runtime/start.yh
Oracle only

Classes and interfaces

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

class models reference identity and methods; interface defines a behavioral surface. Full dispatch remains on the comparison oracle.

When to use it

Prefer thing and ordinary functions for Kyber-ready programs. Use class and interface only while evaluating the explicit oracle route.

Syntax
class Name { ... }interface Name { Action(); }class Child extends Parent implements Contract { ... }
Oracle route
interface Named
{
    Name() -> text;
}

final class Pilot implements Named
{
    text callsign

    Name() -> text
    {
        return this.callsign
    }
}
Kyber-ready alternative
thing Pilot
{
    text callsign
}

PilotName(Pilot pilot) -> text
{
    return pilot.callsign
}
  • Class and interface dispatch is generated-C++ only in Yeho Core 2026.1.
  • Generic classes and interfaces are not admitted even though the parser reserves research syntax.
Syntax words

classinterfaceextendsinheritsimplementsoverrideabstractsealedfinal

Source of truthdocs/language/conformance-2026.1.json: class-and-interface-dispatch; parser_declarations.cpp
Stable

Constructors, methods, static methods, and this

Part of the admitted Yeho Core 2026.1 surface.

A constructor is a same-name method inside a type. Instance methods can read this, while static methods belong to the type itself.

When to use it

Use a constructor to establish valid starting data, an instance method for behavior that belongs to one value, and static only when no instance state is needed.

Syntax
Name(Type value) { this.field = value }Method(...) -> Type { ... }static Method(...) -> Type { ... }
Construct and act
thing Point
{
    int x
    int y

    Point(int x = 0, int y = 0)
    {
        this.x = x
        this.y = y
    }

    Sum() -> int
    {
        return this.x + this.y
    }
}

Point point = Point(y: 5)
int total = point.Sum()
  • Stored constructor values follow declaration order for the current value-data ABI.
  • Class dispatch remains a separate oracle-only boundary even though plain-data constructors and direct admitted calls run through Kyber.
Syntax words

thisstatic

Source of truthtests/compiler/kyber/plain-data-constructor/start.yh; tests/compiler/kyber/legalized-call-forms/start.yh
Experimental

Fields, properties, and visibility

Implemented, but its contract can still change before promotion.

Members can be public, internal, protected, or private, with static, readonly, init, and get/set/init property shapes.

When to use it

Use fields for direct data. Use a property when read or write policy is part of the object's contract and you accept its experimental status.

Syntax
public Type fieldreadonly Type fieldType property { get; set; }Type property { get; init; }
Member shapes
thing Profile
{
    public text displayName
    readonly text id
    int level { get; set; }
    text createdBy { get; init; }
}
  • Properties require get and cannot combine set with init.
  • Computed property bodies are unavailable; current properties describe access shape.
Syntax words

publicinternalprotectedprivatestaticreadonlyinitgetset

Source of truthparser_declarations.cpp parseThingMemberModifiers and parseThingPropertyAccessors; conformance properties
04

Yeho and YUI chapter

Functions and calls

Declarations, returns, parameters, overloads, named arguments, defaults, contracts, and function values.

5 lessons
Stable

Function declarations and returns

Part of the admitted Yeho Core 2026.1 surface.

A function starts with its name, not a function keyword. Parameters are typed, -> names the return type, and a missing return type means void.

When to use it

Use small named functions to make actions and transformations obvious and testable.

Syntax
Name(Type parameter) { ... }Name(Type parameter) -> ReturnType { return value }
Value and void functions
Add(int left, int right) -> int
{
    return left + right
}

Celebrate(text name)
{
    Console.Log("Great work, " + name)
}

int total = Add(20, 22)
Celebrate("Nova")
  • The older returns spelling is deprecated; use ->.
  • Expression-bodied declarations are not admitted in the bootstrap compiler.
Syntax words

return->

Source of truthdocs/language/language-core.md §4.1; parser_declarations.cpp parseFunction
Stable

Defaults, named arguments, and overloads

Part of the admitted Yeho Core 2026.1 surface.

Trailing parameters can have defaults, calls can name arguments after positional ones, and functions can overload on admitted signatures.

When to use it

Use defaults for the common case, named arguments where a call would otherwise hide meaning, and overloads only when the operations are truly the same idea.

Syntax
Name(Type value = default)Name(positional, option: value)
A readable call
Move(text actor, int x, int y, bool animate = true)
{
    Console.Log(actor + " moved")
}

Move("Nova", 12, y: 7, animate: false)
  • Default parameters must trail required parameters.
  • After the first named argument, keep the remaining arguments named.
Syntax words

:

Source of truthdocs/language/language-core.md §4.2; parser_expressions.cpp parseCallArguments
Experimental

Requires, ensures, and invariants

Implemented, but its contract can still change before promotion.

Contracts attach executable meaning to valid inputs, promised outputs, and valid object state.

When to use it

Use contracts at important boundaries where callers and maintainers need one visible definition of correctness.

Syntax
Function(...) -> Type requires(condition) ensures(condition) { ... }invariant(condition)
A bounded operation
ClampPercent(int value) -> int
requires(value >= 0)
requires(value <= 100)
ensures(result >= 0 and result <= 100)
{
    return value
}
  • Errors and contracts are experimental in the current conformance edition.
  • Keep the condition deterministic and cheap enough to be useful as evidence.
Syntax words

requiresensuresinvariant

Source of truthparser_declarations.cpp parseContractClauses and parseThingInvariant; conformance errors-contracts
Stable

Extension functions

Part of the admitted Yeho Core 2026.1 surface.

Mark the first parameter extension to let an ordinary function use readable value.Method(...) call syntax.

When to use it

Use an extension when behavior conceptually belongs beside a type but you do not own or should not expand the type declaration.

Syntax
Function(Type extension value, ...) -> ReturnTypevalue.Function(...)
Add behavior without hiding the function
Magnitude(Point extension value, int offset = 0) -> int
{
    return value.x + value.y + offset
}

Point point = Point(1, 5)
int size = point.Magnitude(offset: 7)
  • extension is a binding mode on the first parameter.
  • The direct function remains explicit and testable even though call syntax reads like a method.
Syntax words

extension

Source of truthtests/compiler/kyber/legalized-call-forms/start.yh; parser_types.cpp parseParameters
Oracle only

Function values, lambdas, and local functions

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

Yeho has reserved syntax for typed function values and function(...) lambdas, but the feature is not in the Kyber product path.

When to use it

Use ordinary named top-level functions in product code. Explore function values only through the explicit comparison oracle.

Syntax
function of ParamType to ReturnTypefunction(Type name) -> Type { ... }
Oracle route
function of int to int double = function(int value) -> int
{
    return value * 2
}

int answer = double(21)
Kyber-ready alternative
Double(int value) -> int
{
    return value * 2
}

int answer = Double(21)
  • Lambdas and local functions are generated-C++ only.
  • Generic functions are unavailable.
Syntax words

functionofto

Source of truthadvanced-features-2026.1.json; conformance lambdas-local-functions
05

Yeho and YUI chapter

Expressions and decisions

Arithmetic, comparison, boolean logic, casts, enums, flags, and exhaustive match branches.

6 lessons
Stable

Arithmetic, comparison, and bit operators

Part of the admitted Yeho Core 2026.1 surface.

Scalar expressions use explicit arithmetic, comparison, bitwise, shift, and unary operators with ordinary precedence.

When to use it

Use parentheses when domain meaning is more important than remembering the precedence table.

Syntax
left + rightleft == rightbits << amount~bits
Scalar expressions
int damage = (baseDamage * multiplier) / 100
bool critical = damage >= 50
uint flags = (1 << 3) | (1 << 1)
bool exact = flags == 10
  • Operator overloading is unavailable.
  • Compound assignments such as += and ++ are unavailable. Write value = value + 1.
Syntax words

+-*/==!=<<=>>=&|^<<>>~

Source of truthparser_expressions.cpp precedence functions; conformance expressions.scalar
Stable

Boolean logic and short-circuiting

Part of the admitted Yeho Core 2026.1 surface.

Use !, and, and or with bool values. and and or short-circuit, so the right side runs only when needed.

When to use it

Put cheap or safety-critical guards first so later expressions run only inside their valid domain.

Syntax
!conditionleft and rightleft or right
Guard expensive or unsafe work
bool canEnter = hasKey and door.IsUnlocked()

if !canEnter or alarmActive
{
    Console.Log("Entry blocked")
}
  • The canonical unary spelling is !, not the editor grammar's historical not token.
  • There are no truthy or falsy conversions.
Syntax words

!andortruefalse

Source of truthparser_expressions.cpp parseOr/parseAnd/parseUnary; conformance control.boolean-conditions
Stable

If, else if, and else

Part of the admitted Yeho Core 2026.1 surface.

if branches on a bool expression. Parentheses around the condition are optional, and each branch uses a block.

When to use it

Use if for a small number of ordered decisions. Use match when one value has several named shapes or cases.

Syntax
if condition { ... }else if condition { ... }else { ... }
Ordered decisions
if score >= 100
{
    Console.Log("Master")
}
else if score >= 50
{
    Console.Log("Builder")
}
else
{
    Console.Log("Begin")
}
  • The condition must be bool.
  • Keep the most specific or highest-priority branch first.
Syntax words

ifelse

Source of truthparser_statements.cpp parseIfStatement; conformance control.boolean-conditions
Experimental

Enums, payloads, and match

Implemented, but its contract can still change before promotion.

enum names a closed set of cases. Payload cases can carry one typed value, and match selects a branch with an optional binding.

When to use it

Use an enum when the valid states are finite and you want the compiler and reader to see every named possibility.

Syntax
enum Name { Case, Payload(Type value) }match value { Case { ... } Payload with name { ... } else { ... } }
A state with data
enum Result
{
    Ready,
    Failed(text reason)
}

match result
{
    Ready { Console.Log("Ready") }
    Failed with reason { Console.Error(reason) }
    else { Console.Error("Unknown result") }
}
  • Plain enums are stable enough for ordinary use; richer payload matching remains experimental across targets.
  • The removed choice spelling is not accepted. Use enum.
Syntax words

enummatchwithelse

Source of truthparser_declarations.cpp parseEnumDecl; parser_statements.cpp parseMatchStatement; conformance payload-enum-patterns
Experimental

Flags enums

Implemented, but its contract can still change before promotion.

A [flags] enum represents combinable named bits. Test membership with .Has rather than treating a combination as one match case.

When to use it

Use flags for independent capabilities or state bits that can be combined.

Syntax
[flags] enum Name { A, B, C }value.Has(Name.Member)
Combine capabilities
[flags]
enum Permission
{
    Read,
    Write,
    Execute
}

Permission access = Permission.Read | Permission.Write
if access.Has(Permission.Write)
{
    Console.Log("Can write")
}
  • Flags enums cannot have payload members.
  • Use .Has for membership checks.
Syntax words

[flags]enumHas

Source of truthparser_core.cpp parseTopLevelEnum; language-core.md §5.6
Experimental

Type checks and casts

Implemented, but its contract can still change before promotion.

is asks whether a value has a named type; as requests a cast to that named type.

When to use it

Prefer designs that already know their types. Use is/as at admitted dynamic boundaries and keep failure handling explicit.

Syntax
value is Typevalue as Type
Named type boundary
if actor is Pilot
{
    Pilot pilot = actor as Pilot
    Console.Log(pilot.callsign)
}
  • Complete class/reference flow is oracle-only today, so this is not a general Kyber dynamic-object promise.
  • The target after is or as is currently a named type.
Syntax words

isas

Source of truthparser_expressions.cpp parseComparison; semantic/expr.cpp
06

Yeho and YUI chapter

Loops and iteration

While, infinite loops, range loops, collection loops, filters, indexes, and loop control.

4 lessons
Stable

While loops

Part of the admitted Yeho Core 2026.1 surface.

while repeats a block while its bool condition remains true.

When to use it

Use while when the stopping condition is more natural than a known collection or numeric range.

Syntax
while condition { ... }
Count until complete
int step = 0
while step < 4
{
    Console.Log(Text.From(step))
    step = step + 1
}
  • The condition must be bool.
  • Update the condition's inputs inside the loop unless an external event owns progress.
Syntax words

while

Source of truthparser_statements.cpp parseWhileStatement; Kyber loop runtime fixtures
Stable

Loop, next, and end

Part of the admitted Yeho Core 2026.1 surface.

loop creates an explicit indefinite loop. next skips to the next iteration and end exits the nearest loop.

When to use it

Use loop for event pumps or retry flows with clear exit points. Use while when one condition explains the whole lifetime.

Syntax
loop { ... }nextend
Controlled indefinite loop
int attempt = 0
loop
{
    attempt = attempt + 1
    if attempt < 3 { next }
    Console.Log("Connected")
    end
}
  • next and end target the nearest active loop.
  • The historical endLoops token is not supported.
Syntax words

loopnextend

Source of truthparser_statements.cpp parseLoopStatement and parseLoopControlStatement
Stable

Range for loops

Part of the admitted Yeho Core 2026.1 surface.

A range loop names its counter, start, exclusive or inclusive end, and optional step expression.

When to use it

Use a range when you need an index or a predictable number of iterations.

Syntax
for i from start < end { ... }for i from start <= end { ... }for (i from start < end i + step) { ... }
Exclusive and stepped ranges
for i from 0 < 4
{
    Console.Log(Text.From(i))
}

for (even from 0 <= 8 even + 2)
{
    Console.Log(Text.From(even))
}
  • < excludes the end; <= includes it.
  • The step is the next-value expression, such as i + 2.
Syntax words

forfrom

Source of truthparser_loops.cpp parseForStatement; tests/compiler/kyber/range-loop-runtime/start.yh
Stable

Collection loops, indexes, reverse, and where

Part of the admitted Yeho Core 2026.1 surface.

for can iterate collection values, expose an index, start that index elsewhere, reverse the traversal, or filter with where.

When to use it

Use collection iteration when you care about elements rather than storage positions.

Syntax
for item in collection { ... }for item at i in collection { ... }for item at i = 1 in reverse collection where condition { ... }for key to value in map { ... }
Values and indexes
list of int scores = [10, 20, 30]
for score at index in scores where score >= 20
{
    Console.Log(Text.Format("{0}: {1}", index, score))
}
Map key and value
map of text to int inventory = ["crystal" to 3, "key" to 1]
for name to amount in inventory
{
    Console.Log(name + ": " + Text.From(amount))
}
  • reverse appears after in and before the collection expression.
  • Map loops can bind key to value.
Syntax words

forinatreversewhereto

Source of truthparser_loops.cpp; language-core.md §8.3
07

Yeho and YUI chapter

Collections

Typed lists, maps, sets, literals, indexing, membership, and mutation.

3 lessons
Experimental

Lists

Implemented, but its contract can still change before promotion.

list of T is an ordered typed value container with literals, indexing, count, and explicit mutation methods.

When to use it

Use a list when order and duplicates matter.

Syntax
list of Type[value, value]list[index]list.Add(value)
Ordered values
list of text crew = ["Nova", "Mira"]
crew.Add("Sol")

if crew.Contains("Mira")
{
    Console.Log(crew[1])
}

Console.Log(Text.From(crew.count))
  • Collections are experimental in the 2026.1 conformance edition.
  • Index bounds remain part of the runtime contract.
Syntax words

listofcountAddRemoveContains

Source of truthlanguage-core.md §3.4; tests/compiler/kyber/list-runtime/start.yh
Experimental

Maps

Implemented, but its contract can still change before promotion.

map of K to V associates typed keys with typed values. Map literals use key to value pairs.

When to use it

Use a map for lookup by identity or name when sequential scanning would hide the intent.

Syntax
map of KeyType to ValueType[key to value, key to value]map[key]
Lookup table
map of text to int power = ["sun" to 100, "moon" to 70]
int sunPower = power["sun"]

if power.Contains("moon")
{
    Console.Log(Text.From(power["moon"]))
}
  • Map literals and list literals both use brackets; to distinguishes a map pair.
  • Collections are experimental.
Syntax words

mapoftoContainsRemove

Source of truthparser_types.cpp parseMapTypeRef; parser_expressions.cpp parseListOrMapLiteralExpression
Experimental

Sets

Implemented, but its contract can still change before promotion.

set of T stores unique typed values and supports membership and explicit mutation.

When to use it

Use a set when membership matters and duplicates do not.

Syntax
set of Typeset.Add(value)set.Contains(value)set.Remove(value)
Unique membership
set of text badges
badges.Add("builder")
badges.Add("builder")

if badges.Contains("builder")
{
    Console.Log("Badge earned")
}
  • Sets are experimental.
  • Use list when order or duplicates are meaningful.
Syntax words

setofAddRemoveContainscount

Source of truthparser_types.cpp parseSetTypeRef; language-core.md §3.4
08

Yeho and YUI chapter

Errors and contracts

Typed error values, preconditions, postconditions, invariants, and the current exception boundary.

2 lessons
Experimental

Typed error values

Implemented, but its contract can still change before promotion.

error is a typed value created with Error(type, message) and exposes type and message fields.

When to use it

Use an error value when failure needs to cross a function or task boundary with machine-readable identity and a human-readable explanation.

Syntax
error problem = Error(type, message)
Name the failure
error problem = Error("save.denied", "The project folder is read only")
Console.Error(problem.type + ": " + problem.message)
  • Errors and contracts are experimental.
  • Prefer stable error type strings that callers can test without parsing prose.
Syntax words

errorErrortypemessage

Source of trutherrors-tasks-effects-2026.1.json; language-core.md §6
Oracle only

Try, catch, and throw

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

The parser models try, catch, and throw, but exception control flow is not part of the Kyber product route today.

When to use it

For Kyber-ready code, return explicit result data or task failure state. Use try/catch only in an explicitly selected oracle run.

Syntax
throw Error(type, message)try { ... } catch problem { ... }
Oracle route
try
{
    throw Error("map.missing", "The map could not be found")
}
catch problem
{
    Console.Error(problem.message)
}
Kyber-ready result
thing LoadResult
{
    bool ok
    text value
    error problem
}
  • try-catch-throw is generated-C++ only in Yeho Core 2026.1.
  • There is no admitted finally, panic, or assert statement.
Syntax words

trycatchthrow

Source of truthconformance-2026.1.json: try-catch-throw; parser_statements.cpp
09

Yeho and YUI chapter

Memory and lifetime

Ordinary values, explicit copies, original aliases, address aliases, buffers, and the unsafe boundary.

2 lessons
Experimental

Ordinary, copy, original, and memoryAddress

Implemented, but its contract can still change before promotion.

Binding modes make value transfer and aliases visible at function and loop boundaries.

When to use it

Use ordinary parameters by default, copy for an explicit independent value, original for an admitted source alias, and memoryAddress only at a reviewed low-level boundary.

Syntax
Function(Type value)Function(Type copy value)Function(Type original value)Function(Type memoryAddress value)
Make alias intent visible
AppendValue(list of int original values, int value)
{
    values.Add(value)
}

Snapshot(Profile copy source) -> Profile
{
    return source
}
  • Alias modes are restricted by type and target.
  • Task aliases are rejected. memoryAddress is not a general raw-pointer escape hatch.
Syntax words

copyoriginalmemoryAddressextension

Source of truthmemory-lifetime-unsafe-2026.1.json; parser_types.cpp parseParameters
Experimental

Buffers

Implemented, but its contract can still change before promotion.

buffer of T is a shared resource shape used for explicit data movement and compute boundaries.

When to use it

Use buffers when a runtime or accelerator needs a bounded block of typed elements rather than an ordinary value collection.

Syntax
buffer of Type name
Compute boundary
compute AddOne(buffer of int values)
{
    int index = compute.index
    if index < values.count
    {
        values[index] = values[index] + 1
    }
}
  • Buffers are shared resources with explicit lifecycle and visibility contracts.
  • Raw allocation, free, pointer arithmetic, volatile, MMIO, and memory fences are unavailable as general language syntax.
Syntax words

bufferof

Source of truthmemory-lifetime-unsafe-2026.1.json; accelerator positive fixtures
10

Yeho and YUI chapter

Tasks, time, and tunnels

Asynchronous work, delayed starts, waits, cancellation, parallel blocks, and bounded communication.

3 lessons
Experimental

Tasks and delayed work

Implemented, but its contract can still change before promotion.

task starts a named function asynchronously, can carry a typed result, and can be delayed with after.

When to use it

Use a task when useful work can progress independently and you can define completion, failure, cancellation, and ownership.

Syntax
task name = task Work()task of Type name = task Work()task name = task after 100ms Work()await name
Start and await
LoadScore() -> int
{
    return 42
}

task of int loading = task LoadScore()
wait loading
int score = await loading
Console.Log(Text.From(score))
  • Task, parallel, and tunnel behavior varies by target and remains experimental.
  • Do not discard a task unless its lifecycle and failure are intentionally unobserved.
Syntax words

taskofafterawait

Source of trutherrors-tasks-effects-2026.1.json; tests/compiler/errors-tasks-effects/task-lifecycle/start.yh
Experimental

Wait, stop, and parallel

Implemented, but its contract can still change before promotion.

wait can pause for a duration, frame, task, or condition. stop requests cancellation, and parallel scopes concurrent branches.

When to use it

Use the narrowest wait that explains progress. Treat stop as a lifecycle request, not proof that cleanup already finished.

Syntax
wait 100mswait 1swait nextFramewait 2 frameswait taskNamewait until conditionstop taskNameparallel { ... }
Time and completion
task worker = task DoWork()
wait until worker.finished

if worker.failed
{
    Console.Error(worker.error.message)
}

wait nextFrame
  • Supported duration units are target-validated.
  • parallel failure and cleanup semantics are covered by dedicated fixtures, but the feature is experimental.
Syntax words

waituntilnextFrameframesstopparallel

Source of truthparser_statements.cpp parseWaitStatement; errors-tasks-effects fixtures
Experimental

Tunnels

Implemented, but its contract can still change before promotion.

tunnel carries typed values between concurrent work with capacity-one FIFO handoff and backpressure.

When to use it

Use a tunnel when producers and consumers should communicate without sharing an unbounded mutable queue.

Syntax
tunnel of Type nametunnel<Type> namename.Send(value)name.Receive()
Bounded handoff
tunnel<int> values

Produce()
{
    values.Send(42)
}

task producer = task Produce()
wait until values.hasValue
int answer = values.Receive()
  • The channel keyword was removed. Use tunnel.
  • Tunnels are capacity one, FIFO, and backpressured in the current contract.
Syntax words

tunnelofSendReceivehasValue

Source of trutherrors-tasks-effects-2026.1.json; tests/compiler/errors-tasks-effects/tunnel-handoff/start.yh
11

Yeho and YUI chapter

CPU and GPU compute

Portable compute functions, execution tags, dispatch, buffers, indexes, completion, and restrictions.

2 lessons
Experimental

Compute functions and execution tags

Implemented, but its contract can still change before promotion.

compute defines a portable data-parallel kernel. [auto], [cpu], or [gpu] states the admitted execution preference.

When to use it

Use compute for bounded element-wise or parallel work that can obey the restricted portable kernel contract.

Syntax
compute Name(buffer of Type values, ...) { ... }[gpu] compute Name(...) { ... }
Portable kernel
[auto]
compute AddOffset(buffer of int values, int amount)
{
    int index = compute.index
    if index < values.count
    {
        values[index] = values[index] + amount
    }
}
  • Exactly one execution tag is allowed.
  • A [gpu] request is not proof of GPU execution. Promotion evidence must name the actual backend and device path.
Syntax words

compute[auto][cpu][gpu]compute.index

Source of truthparser_core.cpp parseTopLevelCompute; tests/compiler/accelerator/vulkan-positive/start.yh
Experimental

Dispatch and computeTask

Implemented, but its contract can still change before promotion.

dispatch launches a compute function and returns a computeTask whose finished, failed, and error state can be inspected.

When to use it

Keep the task handle whenever later work depends on completion, failure, or measured execution.

Syntax
computeTask job = dispatch Kernel(arguments)wait jobwait until job.finished
Launch and check
computeTask job = dispatch AddOffset(values, 5)
wait until job.finished

if job.failed
{
    Console.Error(job.error.message)
}
  • Compute dispatch shape and backend admission are validated.
  • A completed task can still represent a failed kernel; inspect failed when correctness depends on it.
Syntax words

dispatchcomputeTaskwaitfinishedfailederror

Source of truthparser_expressions.cpp parseDispatchStartExpression; accelerator runtime fixtures
12

Yeho and YUI chapter

Packages and native interop

Using declarations, package visibility, manifests, C ABI declarations, effects, and target boundaries.

3 lessons
Stable

Using and external declarations

Part of the admitted Yeho Core 2026.1 surface.

using imports a dotted package path. external makes an eligible top-level declaration visible outside its package.

When to use it

Use using for a dependency you actually call and external only for the smallest intentional package API.

Syntax
using package.pathexternal thing Name { ... }external Function(...) { ... }
Package surface
using graphics.image
using compute.tensor

external Describe(text name) -> text
{
    return "Hello " + name
}
  • external applies only to top-level type, function, extern, or compute declarations.
  • The old export spelling is rejected. Use external.
Syntax words

usingexternal

Source of truthparser_core.cpp run and parseTopLevelCallableOrStatement; conformance packages.using-external
Stable

project.mech

Part of the admitted Yeho Core 2026.1 surface.

project.mech declares project identity, source roots, packages, target intent, and feature gates such as tuple experiments.

When to use it

Add a manifest when the project needs more than the default entry-file convention or when a feature must be explicitly admitted.

Syntax
project manifest beside start.yh
Minimal console project
package = "hello.app"
version = "0.1.0"
languageEdition = "yeho-core-2026.1"

[app]
kind = "console"
  • Normal projects omit backend so the candidate SDK selects Kyber.
  • Feature gates use experiments = ["feature-name"] and are deliberate compatibility boundaries.
Syntax words

project.mechpackageversionlanguageEditionexperiments

Source of truthdocs/language/project-mech.md; project resolution fixtures
Experimental

C ABI interop

Implemented, but its contract can still change before promotion.

extern c declares an external function with cdecl by default and optional stdcall or sysv conventions.

When to use it

Use C interop at a narrow adapter boundary after confirming the exact target ABI and admitted scalar types.

Syntax
extern c Name(Type parameter) -> ReturnTypeextern c stdcall Name(...)
A narrow declaration
extern c cdecl NativeTickCount() -> uint64

uint64 tick = NativeTickCount()
  • The bootstrap compiler supports only extern c.
  • Interop beyond admitted scalars is experimental and must match the target ABI exactly.
Syntax words

externccdeclstdcallsysv

Source of truthparser_declarations.cpp parseExternFunction; conformance extern-c-beyond-admitted-scalars
13

Yeho and YUI chapter

YUI apps and surfaces

Create a native YUI project, connect its manifest, and author the first retained application surface.

3 lessons
Candidate

Create and run a YUI application

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

YUI is Yeho's native retained UI system. One command creates a project with Yeho behavior, a .yui interface, and a Kyber-ready Windows x64 application path.

When to use it

Use the YUI project template when you want a native application whose controls, layout, interaction, accessibility data, and rendering are owned by Yeho rather than HTML or native OS widgets.

Syntax
.\tools\yeho.ps1 new yui <path> <package>.\tools\yeho.ps1 check <path>.\tools\yeho.ps1 run <path>
PowerShell
.\tools\yeho.ps1 new yui .\hello-yui hello.yui
.\tools\yeho.ps1 check .\hello-yui
.\tools\yeho.ps1 run .\hello-yui
  • The generated project contains project.mech, start.yh, and ui/app.yui.
  • YUI draws its own controls. Windows supplies the window, input, text, accessibility projection, graphics context, and presentation services.
Syntax words

newyuicheckrun

Source of truthREADME.md §Create a project; docs/teaching/first-yui-app.md
Candidate

Connect a .yui entry in project.mech

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

The project manifest declares a frontend application and points to one deterministic .yui entry document. The SDK selects Kyber, so product manifests do not name a generated-C++ backend.

When to use it

Use this frontend block for every authored YUI application, then add only the packages the application actually consumes.

Syntax
[app] kind = "frontend"[frontend] kind = "yui"entry = "ui/app.yui"
project.mech
manifestVersion = "2"
package = "hello.yui"
version = "0.1.0"
osTarget = "windows"
archTarget = "x64"

[app]
kind = "frontend"
console = false

[frontend]
kind = "yui"
entry = "ui/app.yui"

[[dependencies]]
package = "frontend.yui"
version = "0.2.0"

[[dependencies]]
package = "ui"
version = "0.2.0"
  • Imports are project-local, path safe, deterministic, and cycle checked.
  • The current promoted YUI product target is Windows x64.
Syntax words

project.mechfrontendentrydependencies

Source of truthdocs/yui/authoring.md; examples/yui/yeho-yui-first-surface/project.mech
Candidate

Surfaces, layouts, and widgets

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

A surface is the root of an authored interface. Layout containers such as column, row, grid, stack, dock, overlay, and panel organize semantic widgets without turning the file into pixel-by-pixel drawing code.

When to use it

Start with the smallest surface and one clear layout container. Add nested layout only when it expresses a real visual or interaction relationship.

Syntax
surface Name { ... }column Name { ... }row Name { ... }WidgetKind Name { property = value }
ui/app.yui
surface App {
    layout = column

    column Content {
        label Greeting { text = "Hello from YUI" }
        button Continue { text = "Continue" }
    }
}
  • The compiler validates widget names, properties, bindings, commands, and source spans before rendering.
  • Programmatic definitions and .yui documents lower to the same typed widget model and retained scene.
Syntax words

surfacecolumnrowpanellayout

Source of truthdocs/teaching/first-yui-app.md; packages/frontend/yui/widget-definitions.inc
14

Yeho and YUI chapter

YUI components and controls

Typed state, commands, properties, slots, reusable components, controls, layouts, and event bindings.

3 lessons
Candidate

Typed state, commands, and event bindings

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

State names the values a surface reads. Commands name actions the application can perform. Widget bindings connect them explicitly, so an event is not a hidden string callback.

When to use it

Declare state for interface values and commands for application actions, then connect a control through its value, command, or on-event properties.

Syntax
state Name { path = Type }commands Name { path = command }onClick = command.pathvalue = state.path
State and action flow
commands EditorCommands {
    editor.save = command
}

state EditorState {
    document.title = text
}

surface Editor {
    column Content {
        label Title { text = document.title }
        button Save {
            text = "Save"
            command = editor.save
            onClick = editor.save
        }
    }
}
  • Event properties include click, change, input, submit, focus, blur, selection, open, close, edit, resize, and sort paths.
  • Unknown bindings and missing commands fail before the first frame.
Syntax words

statecommandscommandonClickonChangeonInputonSubmit

Source of truthsrc/compiler/yui_schema.cpp; examples/yui/yeho-yui-first-surface/ui/app.yui
Candidate

Reusable components, typed properties, and slots

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

A project-local component can expose required or defaulted properties and named content slots. It imports like ordinary source and needs no compiler registration or global component catalog.

When to use it

Extract a component when several surfaces share the same UI meaning, or when one interface region deserves its own typed contract.

Syntax
import "path/component.yui"component Name { ... }property name { type = text required = true }slot Content { required = true }
A reusable section
component SettingsSection {
    property heading { type = text required = true }
    property tone { type = text default = "quiet" }
    slot Content { required = true }
}
Import and fill the slot
import "components/settings-section.yui"

surface Settings {
    SettingsSection Profile {
        heading = "Profile"
        slot Content {
            textBox Name { label = "Display name" value = profile.name }
        }
    }
}
  • Create a starter component with .\tools\yeho.ps1 widget Name .\project.
  • Component expansion retains source spans so diagnostics can point back to authored code.
Syntax words

importcomponentpropertyslotrequireddefaultbinding

Source of truthdocs/yui/authoring.md; examples/yui/yeho-yui-authored-settings/ui/components/settings-section.yui
Candidate

Controls, forms, navigation, and large data

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

YUI's public widget vocabulary covers ordinary controls, forms, menus, overlays, navigation, tables, property editors, virtual lists, creator surfaces, and loading, empty, or error presentations.

When to use it

Choose the widget whose semantic role matches the job. Compose project-specific meaning from public controls instead of adding product vocabulary to the compiler.

Syntax
textField Name { ... }selectField Name { ... }virtualList Name { ... }dataGrid Name { ... }
A small production-shaped form
commands ProfileCommands {
    profile.edit = command
    profile.save = command
    profile.changeTheme = command
}

state ProfileState {
    profile.name = "Ada"
}

surface Profile {
    layout = column
    column ProfileForm {
        textField Name {
            label = "Display name"
            value = profile.name
            placeholder = "Name"
            required = true
            onInput = profile.edit
            onSubmit = profile.save
        }
        selectField Theme {
            label = "Theme"
            value = "Dark"
            options = "Dark,Light,System"
            onChange = profile.changeTheme
        }
        button Save { text = "Save profile" onClick = profile.save }
    }
}
  • The canonical widget table records semantic role, interactivity, and leaf or container shape.
  • Application concepts stay in reusable project-local components rather than becoming global widgets.
Syntax words

textFieldtoggleslidermenudialogvirtualListtabledataGridviewport

Source of truthpackages/frontend/yui/widget-definitions.inc; examples/yui/yeho-yui-component-gallery/ui/app.yui
15

Yeho and YUI chapter

YUI rendering and access

The custom retained renderer, semantic accessibility tree, inspection path, performance model, and current platform boundary.

3 lessons
Candidate

Retained custom rendering and exact damage

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

YUI owns one retained scene and renderer-neutral display commands. A mutation lowers only dirty owners, while semantic-only changes can update accessibility state without creating paint work.

When to use it

Treat state mutation as the source of exact visual and semantic work. Use inspection reports to verify what became dirty instead of rebuilding the whole interface by habit.

Syntax
state mutation -> dirty ownerdirty owner -> retained fragmentfragment + damage -> custom rendererunchanged tick -> zero lowering and presentation
Inspect before optimizing
.\tools\yeho.ps1 inspect .\hello-yui
.\tools\yeho.ps1 build .\hello-yui
.\tools\yeho.ps1 package .\hello-yui
  • The command and resource contract covers clears, shapes, borders, text, icons, images, clips, transforms, layers, and targets.
  • Layout, theme, or density identity changes require an explicit reseed rather than hidden global work inside a dirty frame.
Syntax words

retained scenedirty ownerdamagedisplay commandsresources

Source of truthdocs/yui/rendering-performance.md; docs/yui/testing-inspection-and-migration.md
Candidate

One semantic tree for interaction and accessibility

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

The same semantic nodes drive pointer and keyboard interaction, focus, accessible roles and names, visible state, bounds, commands, and custom rendering state.

When to use it

Give every interactive control a clear semantic widget kind, visible label, deterministic command, and explicit disabled, selected, required, invalid, busy, or empty state when it applies.

Syntax
label = "Accessible name"required = truedisabled = state.pathcommand = action.path
Meaning and behavior together
commands ProfileCommands {
    profile.edit = command
    profile.save = command
}

surface Profile {
    column Form {
        textField Name {
            label = "Display name"
            value = profile.name
            required = true
            onInput = profile.edit
        }
        button Save {
            text = "Save profile"
            command = profile.save
            onClick = profile.save
        }
    }
}
  • Windows projects the semantic tree through its accessibility bridge without replacing YUI controls with native widgets.
  • Keyboard-only, screen-reader, high-contrast, IME, clipboard, DPI, and recovery workflows remain explicit promotion evidence rather than inferred support.
Syntax words

labeldescriptionrequireddisabledfocusedselectedinvalidloadingempty

Source of truthdocs/yui/interaction-accessibility.md; docs/yui/text-media-i18n.md
Candidate

Inspect YUI truth and respect the candidate boundary

Part of the public YUI Windows x64 candidate, with remaining promotion gates stated explicitly.

Readable and JSON inspection expose expanded widgets, bindings, semantic nodes, layout, display commands, resources, dirty receipts, damage, provider selection, and diagnostics without mutating the application.

When to use it

Inspect whenever authored output, binding ownership, renderer work, or a target claim is unclear. Keep public claims on the verified Windows x64 route until another provider earns equivalent evidence.

Syntax
yehoc <project> --dump-yuiyehoc <project> --dump-yui-json.\tools\yeho.ps1 inspect <project>
Human and machine-readable models
.\build\yehoc.exe .\hello-yui --dump-yui
.\build\yehoc.exe .\hello-yui --dump-yui-json
.\tools\yeho.ps1 inspect .\hello-yui
  • The public package stack is ui -> frontend.yui -> frontend.yui.host.window -> frontend.yui.host.windows.
  • Portable contracts are architecture, not proof of Linux, Android, Apple, XR, every font feature, every media codec, or production accessibility certification.
Syntax words

inspect--dump-yui--dump-yui-jsonWindows x64provider

Source of truthdocs/yui/package-boundaries.md; docs/yui/testing-inspection-and-migration.md; src/main.cpp
16

Yeho and YUI chapter

Tools and inspection

Create, check, run, build, format, test, inspect, package, and expose compiler truth.

2 lessons
Stable

Check and inspect compiler truth

Part of the admitted Yeho Core 2026.1 surface.

Compiler flags expose the parsed program, semantic model, project resolution, target check, truth report, and native bridge.

When to use it

Inspect the earliest layer that disagrees with your intent instead of debugging only the final executable.

Syntax
yehoc <project> --checkyehoc <project> --dump-astyehoc <project> --dump-sema
Evidence ladder
yehoc .\hello --check
yehoc .\hello --dump-project
yehoc .\hello --dump-ast
yehoc .\hello --dump-sema
yehoc .\hello --dump-truth
yehoc .\hello --dump-native-bridge
  • Check validates without generating a binary.
  • Inspection output is a diagnostic contract and can evolve with the candidate edition.
Syntax words

--check--check-target--dump-ast--dump-sema--dump-truth--dump-project--dump-native-bridge

Source of truthdocs/language/language-core.md §2.10 and §11
Stable

Format, lint, test, inspect, and package

Part of the admitted Yeho Core 2026.1 surface.

The Yeho wrapper keeps common engineering actions under one predictable command surface.

When to use it

Run the narrow command during iteration and the repository verification profile before treating a change as evidence.

Syntax
.\tools\yeho.ps1 <command> <project>
Tooling loop
.\tools\yeho.ps1 format .\hello
.\tools\yeho.ps1 lint .\hello
.\tools\yeho.ps1 test .\hello
.\tools\yeho.ps1 inspect .\hello
.\tools\yeho.ps1 package .\hello
  • Use widget for YUI component workflows.
  • A passing narrow test is evidence only for the behavior it actually exercises.
Syntax words

formatlinttestinspectpackagewidget

Source of truthREADME.md; tools/yeho.ps1
17

Yeho and YUI chapter

Experiments and boundaries

Opt-in tuples, deprecated spellings, removed syntax, and features Yeho deliberately does not pretend to ship.

6 lessons
Oracle only

Tuples and deconstruction

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

Tuple values are an opt-in experiment, gated by tuple-values, and currently run only through generated C++.

When to use it

Prefer a named thing when the values have domain meaning. Use tuples only for deliberate compiler research behind the feature gate.

Syntax
tuple of Type, Typetuple(value, value)deconstruct value into first, second
Gated experiment
SplitScore(text name, int score) -> tuple of text, int
{
    return tuple(name, score)
}

tuple of text, int pair = SplitScore("Ava", 7)
deconstruct pair into player, score
Preferred domain model
thing PlayerScore
{
    text player
    int score
}
  • Requires the tuple-values project gate.
  • The fallback is a named thing with fields that preserve meaning.
Syntax words

tupleofdeconstructinto

Source of truthadvanced-features-2026.1.json; tests/compiler/experiments/tuple-opt-in/start.yh
Oracle only

Yielding functions

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

yield can produce a sequence of values from one function, but the final lowering operation is deliberately rejected by Kyber today.

When to use it

Return a concrete list in Kyber-ready code. Use yield only in the explicit comparison lane while studying the future generator contract.

Syntax
yield expression
Oracle route
Collect() -> list of int
{
    yield 4
    yield 7
}

list of int values = Collect()
Kyber-ready alternative
Collect() -> list of int
{
    return [4, 7]
}
  • Forge records yield as a distinct semantic operation.
  • The generated C++ comparison fixture executes it; Kyber rejects the final-deferred operation explicitly.
Syntax words

yield

Source of truthtests/compiler/forge-contract/yield/start.yh; docs/tooling/forge-v2-contract.md
Oracle only

Planned collection mutation

Available only through the explicitly selected generated C++ comparison route, not the Kyber product path.

plan remove, removeAt, add, and addAt describe mutations to apply around iteration without mutating the active traversal directly.

When to use it

For Kyber-ready code, collect intended changes separately and apply them after the loop.

Syntax
plan remove expressionplan removeAt indexplan add valueplan addAt index value
Oracle route
for score in scores
{
    if score < 0
    {
        plan remove score
    }
}
Kyber-ready alternative
list of int kept
for score in scores
{
    if score >= 0
    {
        kept.Add(score)
    }
}
scores = kept
  • Planned loop mutation is generated-C++ only.
  • The explicit two-phase alternative is easy to inspect and portable across current targets.
Syntax words

planremoveremoveAtaddaddAt

Source of truthconformance-2026.1.json: planned-loop-mutations; parser_statements.cpp
Deprecated

Deprecated migration spellings

Still recognized for migration. New code should use the documented replacement.

dobox, string, returns, and main.yh are accepted only to help older code move to the current language.

When to use it

Do not use these in new code. Replace them when touching an older file.

Syntax
dobox -> thingstring -> textreturns -> ->main.yh -> start.yh
Current spelling
thing Message
{
    text body
}

Length(text value) -> int
{
    return Text.Length(value)
}
  • Class honor-language aliases are also deprecated; use class.
  • The compiler diagnostics should point to the canonical spelling.
Syntax words

doboxstringreturnsmain.yh

Source of truthconformance-2026.1.json deprecated features; language-core.md
Not admitted

Deliberately unavailable language features

Intentionally unavailable today. The guide gives the supported alternative.

Yeho Core 2026.1 explicitly does not admit generics, slices, interpolation, alternate numeric literals, compound assignment, computed properties, operator overloading, truthiness, or raw allocation/free.

When to use it

Use the simple supported forms shown here. Treat a compiler rejection as a boundary, not an invitation to advertise unfinished syntax.

Syntax
Generic algorithm -> concrete function or named thingSlice/view -> list, buffer, start + countInterpolation -> Text.Formatvalue += 1 -> value = value + 1Computed property -> methodTruthiness -> explicit bool conditionAllocation/free -> owned value or runtime resource API
Supported alternatives
count = count + 1
text label = Text.Format("Score: {0}", score)

bool hasItems = items.count > 0
if hasItems
{
    Console.Log(label)
}
  • Unavailable means no stable or experimental product contract exists.
  • The exact list is machine-readable in the conformance manifest.
Syntax words

genericsslicesinterpolation+=operatormallocfree

Source of truthdocs/language/conformance-2026.1.json unavailable classifications
Not admitted

Removed and reserved statement words

Intentionally unavailable today. The guide gives the supported alternative.

Several readable ideas are intentionally not source-language features yet. The compiler rejects them with a supported replacement instead of silently inventing behavior.

When to use it

Use the replacement that makes ownership and flow explicit. Revisit dedicated syntax only after it earns a compiler, runtime, and verification contract.

Syntax
choice -> enumchannel -> tunnelexport -> externalevent / emit / watch -> functions + tasks + tunnelsassert -> explicit if + error resultthread -> taskconst -> ordinary typed field or variableendLoops -> structured return, error, or narrow loop control
Explicit event-shaped flow
tunnel of text notices

Publish(text message)
{
    notices.Send(message)
}

task publisher = task Publish("ready")
wait until notices.hasValue
text notice = notices.Receive()
  • panic, assert, fatal, exception subclasses, and finally are not admitted error syntax.
  • Dedicated event, emit, and watch syntax is deferred in favor of ordinary values, functions, tasks, and tunnels.
Syntax words

choicechannelexporteventemitwatchassertpanicfatalfinallyconstthreadendLoops

Source of truthparser_core.cpp and parser_statements.cpp rejection diagnostics; language-core.md §13.4