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 dataclassDeclare reference-shaped object datainterfaceDeclare a behavioral contractthisRead the current instanceenumDeclare named casesexternalExpose a package declarationusingImport a dotted package pathexternDeclare a native C boundarycomputeDeclare or access portable computedispatchLaunch a compute functiontaskName or start asynchronous workparallelRun admitted work concurrentlytunnelCarry a typed value between concurrent workwaitPause for time, a frame, a task, or a conditionstopRequest task cancellationifStart a boolean branchelseProvide the next or fallback branchmatchBranch on a closed value shapewithBind a match payloadwhileRepeat while a condition is trueloopRepeat until explicitly endedforIterate a range or collectionfromStart a numeric rangeinChoose the collection to iterateatBind an iteration indexreverseTraverse a collection backwardwhereFilter collection iterationnextContinue the nearest loopendExit the nearest loopreturnLeave a function with an optional valueyieldProduce a value in the oracle-only callable surfacerequiresDeclare a preconditionensuresDeclare a postconditioninvariantDeclare valid object statetryStart oracle-only exception handlingcatchHandle an oracle-only thrown errorthrowRaise an oracle-only errorcopyRequest an independent value bindingoriginalRequest an admitted original aliasmemoryAddressRequest a reviewed address aliasextensionBind an extension receiver parameterpublicExpose a member publiclyinternalExpose within a packageprotectedExpose through inheritanceprivateKeep a member inside its ownerstaticAttach a member to the typereadonlyPrevent ordinary field replacementinitAllow initialization-only assignmentabstractRequire implementation on the oracle object surfacesealedClose further inheritance or overridefinalClose further inheritance or overrideoverrideImplement an inherited methodextendsName a base classinheritsAlternative base-class connectorimplementsName class interfacesdelegateForward a method through a fieldgetAllow property readingsetAllow property replacementofConnect a container to its element typetoConnect map key/value or function input/output typesisTest a named typeasCast to a named typeandShort-circuit boolean conjunctionorShort-circuit boolean disjunctionawaitRead an admitted task resulttrueBoolean true literalfalseBoolean false literalnullNullable absence literalfunctionDescribe an oracle-only function value or lambdatupleDescribe a gated multi-value experimentdeconstructSplit a gated tuple into namesintoConnect deconstruction to its namesplanQueue an oracle-only collection mutationremoveRemove a planned itemremoveAtRemove a planned indexaddAdd a planned itemaddAtAdd a planned item at an indexdoboxDeprecated spelling of thingstringDeprecated spelling of textreturnsDeprecated spelling of ->choiceRemoved spelling; use enumchannelRemoved spelling; use tunnelexportRemoved spelling; use externaleventDeferred syntax; use functions, tasks, and tunnelsemitDeferred syntax; call a function or send through a tunnelwatchDeferred syntax; use an explicit update flowassertUnavailable statement; use an explicit check and errorpanicUnavailable fatal statementconstUnavailable declaration formthreadUnavailable source syntax; use taskendLoopsUnavailable broad loop escapeBuilt-in type families 64
Core
voidbooltextcharruneerrorSigned integers
int8int16intint32int64int128Unsigned integers
byteuint8uint16uintuint32uint64uint128Signed packed bits
bit1bit2bit3bit4bit5bit6bit7bit8Unsigned packed bits
ubit1ubit2ubit3ubit4ubit5ubit6ubit7ubit8Binary floats
float8float16floatfloat32float64float128Signed decimals
decimal8decimal16decimaldecimal32decimal64decimal128Unsigned decimals
udecimal8udecimal16udecimaludecimal32udecimal64udecimal128Containers and handles
list of Tmap of K to Vset of Tbuffer of Ttasktask of Ttunnel of TcomputeTaskMigration and experiments
string (deprecated)tuple of A, B (gated)function of A to B (oracle only)Operators 27
Arithmetic
+-*/Comparison
==!=<<=>>=Boolean
!andorBitwise
~&^|<<>>Type
isas?Structure
=->.[]()Showing 59 of 59 feature lessons
Yeho and YUI chapter
Start and run
Projects, entry files, comments, separators, and the shortest path to a native program.
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.
Use start.yh for executable entry behavior and more .yh files for declarations you want the project to compile together.
start.yh*.yh*.y*.yeho*.yoConsole.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.
start.yhproject.mech
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.
Prefer one readable statement per line. Add semicolons only when they make a compact expression easier to scan.
// commentstatementstatement;// 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.
//
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.
Use run during the creative loop, check for fast language feedback, and build when you need the actual executable.
.\tools\yeho.ps1 new console <path> <name>.\tools\yeho.ps1 check <path>.\tools\yeho.ps1 run <path>.\tools\yeho.ps1 build <path>.\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++.
newcheckrunbuild
Yeho and YUI chapter
Values and types
Variables, assignment, literals, text, numbers, booleans, nullability, and the complete built-in type families.
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.
Use a narrow explicit type when the value is part of the program's meaning or machine contract.
Type name = expressionname = expressionint 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.
=
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.
Use literals for small values that are obvious at the point of use. Give repeated domain values a named field or function.
"text"'c'423.146.02e23truefalsenulltext 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.
truefalsenull
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.
Choose int for ordinary counts, explicit widths for ABI or storage contracts, float for binary math, and decimal when decimal meaning matters.
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 | udecimal128int 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.
intuintbytebitfloatdecimaludecimal
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.
Use text for words and messages, rune when Unicode scalar identity matters, and bool for decisions.
text name = "..."char name = 'x'rune name = ...bool name = truetext 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.
textcharrunebool
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.
Use only when deliberately running the comparison oracle. In Kyber-ready code, model absence explicitly with a bool, enum, or sentinel thing.
Type? name = nullPilot? selected = null
if selected == null
{
Console.Log("No pilot selected")
}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.
?null
Yeho and YUI chapter
Data and objects
Things, classes, interfaces, fields, properties, visibility, inheritance, and invariants.
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.
Start with thing for coordinates, settings, records, messages, and other data that should behave like a value.
thing Name { Type field }Name value = Name(arguments...)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.
thing
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.
Prefer thing and ordinary functions for Kyber-ready programs. Use class and interface only while evaluating the explicit oracle route.
class Name { ... }interface Name { Action(); }class Child extends Parent implements Contract { ... }interface Named
{
Name() -> text;
}
final class Pilot implements Named
{
text callsign
Name() -> text
{
return this.callsign
}
}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.
classinterfaceextendsinheritsimplementsoverrideabstractsealedfinal
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.
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.
Name(Type value) { this.field = value }Method(...) -> Type { ... }static Method(...) -> Type { ... }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.
thisstatic
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.
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.
public Type fieldreadonly Type fieldType property { get; set; }Type property { get; init; }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.
publicinternalprotectedprivatestaticreadonlyinitgetset
Yeho and YUI chapter
Functions and calls
Declarations, returns, parameters, overloads, named arguments, defaults, contracts, and function values.
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.
Use small named functions to make actions and transformations obvious and testable.
Name(Type parameter) { ... }Name(Type parameter) -> ReturnType { return value }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.
return->
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.
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.
Name(Type value = default)Name(positional, option: value)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.
:
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.
Use contracts at important boundaries where callers and maintainers need one visible definition of correctness.
Function(...) -> Type requires(condition) ensures(condition) { ... }invariant(condition)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.
requiresensuresinvariant
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.
Use an extension when behavior conceptually belongs beside a type but you do not own or should not expand the type declaration.
Function(Type extension value, ...) -> ReturnTypevalue.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.
extension
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.
Use ordinary named top-level functions in product code. Explore function values only through the explicit comparison oracle.
function of ParamType to ReturnTypefunction(Type name) -> Type { ... }function of int to int double = function(int value) -> int
{
return value * 2
}
int answer = double(21)Double(int value) -> int
{
return value * 2
}
int answer = Double(21)- Lambdas and local functions are generated-C++ only.
- Generic functions are unavailable.
functionofto
Yeho and YUI chapter
Expressions and decisions
Arithmetic, comparison, boolean logic, casts, enums, flags, and exhaustive match branches.
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.
Use parentheses when domain meaning is more important than remembering the precedence table.
left + rightleft == rightbits << amount~bitsint 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.
+-*/==!=<<=>>=&|^<<>>~
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.
Put cheap or safety-critical guards first so later expressions run only inside their valid domain.
!conditionleft and rightleft or rightbool 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.
!andortruefalse
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.
Use if for a small number of ordered decisions. Use match when one value has several named shapes or cases.
if condition { ... }else if condition { ... }else { ... }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.
ifelse
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.
Use an enum when the valid states are finite and you want the compiler and reader to see every named possibility.
enum Name { Case, Payload(Type value) }match value { Case { ... } Payload with name { ... } else { ... } }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.
enummatchwithelse
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.
Use flags for independent capabilities or state bits that can be combined.
[flags] enum Name { A, B, C }value.Has(Name.Member)[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.
[flags]enumHas
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.
Prefer designs that already know their types. Use is/as at admitted dynamic boundaries and keep failure handling explicit.
value is Typevalue as Typeif 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.
isas
Yeho and YUI chapter
Loops and iteration
While, infinite loops, range loops, collection loops, filters, indexes, and loop control.
While loops
Part of the admitted Yeho Core 2026.1 surface.
while repeats a block while its bool condition remains true.
Use while when the stopping condition is more natural than a known collection or numeric range.
while condition { ... }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.
while
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.
Use loop for event pumps or retry flows with clear exit points. Use while when one condition explains the whole lifetime.
loop { ... }nextendint 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.
loopnextend
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.
Use a range when you need an index or a predictable number of iterations.
for i from start < end { ... }for i from start <= end { ... }for (i from start < end i + step) { ... }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.
forfrom
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.
Use collection iteration when you care about elements rather than storage positions.
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 { ... }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 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.
forinatreversewhereto
Yeho and YUI chapter
Collections
Typed lists, maps, sets, literals, indexing, membership, and mutation.
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.
Use a list when order and duplicates matter.
list of Type[value, value]list[index]list.Add(value)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.
listofcountAddRemoveContains
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.
Use a map for lookup by identity or name when sequential scanning would hide the intent.
map of KeyType to ValueType[key to value, key to value]map[key]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.
mapoftoContainsRemove
Sets
Implemented, but its contract can still change before promotion.
set of T stores unique typed values and supports membership and explicit mutation.
Use a set when membership matters and duplicates do not.
set of Typeset.Add(value)set.Contains(value)set.Remove(value)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.
setofAddRemoveContainscount
Yeho and YUI chapter
Errors and contracts
Typed error values, preconditions, postconditions, invariants, and the current exception boundary.
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.
Use an error value when failure needs to cross a function or task boundary with machine-readable identity and a human-readable explanation.
error problem = Error(type, message)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.
errorErrortypemessage
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.
For Kyber-ready code, return explicit result data or task failure state. Use try/catch only in an explicitly selected oracle run.
throw Error(type, message)try { ... } catch problem { ... }try
{
throw Error("map.missing", "The map could not be found")
}
catch problem
{
Console.Error(problem.message)
}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.
trycatchthrow
Yeho and YUI chapter
Memory and lifetime
Ordinary values, explicit copies, original aliases, address aliases, buffers, and the unsafe boundary.
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.
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.
Function(Type value)Function(Type copy value)Function(Type original value)Function(Type memoryAddress value)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.
copyoriginalmemoryAddressextension
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.
Use buffers when a runtime or accelerator needs a bounded block of typed elements rather than an ordinary value collection.
buffer of Type namecompute 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.
bufferof
Yeho and YUI chapter
Tasks, time, and tunnels
Asynchronous work, delayed starts, waits, cancellation, parallel blocks, and bounded communication.
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.
Use a task when useful work can progress independently and you can define completion, failure, cancellation, and ownership.
task name = task Work()task of Type name = task Work()task name = task after 100ms Work()await nameLoadScore() -> 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.
taskofafterawait
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.
Use the narrowest wait that explains progress. Treat stop as a lifecycle request, not proof that cleanup already finished.
wait 100mswait 1swait nextFramewait 2 frameswait taskNamewait until conditionstop taskNameparallel { ... }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.
waituntilnextFrameframesstopparallel
Tunnels
Implemented, but its contract can still change before promotion.
tunnel carries typed values between concurrent work with capacity-one FIFO handoff and backpressure.
Use a tunnel when producers and consumers should communicate without sharing an unbounded mutable queue.
tunnel of Type nametunnel<Type> namename.Send(value)name.Receive()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.
tunnelofSendReceivehasValue
Yeho and YUI chapter
CPU and GPU compute
Portable compute functions, execution tags, dispatch, buffers, indexes, completion, and restrictions.
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.
Use compute for bounded element-wise or parallel work that can obey the restricted portable kernel contract.
compute Name(buffer of Type values, ...) { ... }[gpu] compute Name(...) { ... }[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.
compute[auto][cpu][gpu]compute.index
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.
Keep the task handle whenever later work depends on completion, failure, or measured execution.
computeTask job = dispatch Kernel(arguments)wait jobwait until job.finishedcomputeTask 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.
dispatchcomputeTaskwaitfinishedfailederror
Yeho and YUI chapter
Packages and native interop
Using declarations, package visibility, manifests, C ABI declarations, effects, and target boundaries.
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.
Use using for a dependency you actually call and external only for the smallest intentional package API.
using package.pathexternal thing Name { ... }external Function(...) { ... }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.
usingexternal
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.
Add a manifest when the project needs more than the default entry-file convention or when a feature must be explicitly admitted.
project manifest beside start.yhpackage = "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.
project.mechpackageversionlanguageEditionexperiments
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.
Use C interop at a narrow adapter boundary after confirming the exact target ABI and admitted scalar types.
extern c Name(Type parameter) -> ReturnTypeextern c stdcall Name(...)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.
externccdeclstdcallsysv
Yeho and YUI chapter
YUI apps and surfaces
Create a native YUI project, connect its manifest, and author the first retained application surface.
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.
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.
.\tools\yeho.ps1 new yui <path> <package>.\tools\yeho.ps1 check <path>.\tools\yeho.ps1 run <path>.\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.
newyuicheckrun
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.
Use this frontend block for every authored YUI application, then add only the packages the application actually consumes.
[app] kind = "frontend"[frontend] kind = "yui"entry = "ui/app.yui"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.
project.mechfrontendentrydependencies
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.
Start with the smallest surface and one clear layout container. Add nested layout only when it expresses a real visual or interaction relationship.
surface Name { ... }column Name { ... }row Name { ... }WidgetKind Name { property = value }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.
surfacecolumnrowpanellayout
Yeho and YUI chapter
YUI components and controls
Typed state, commands, properties, slots, reusable components, controls, layouts, and event bindings.
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.
Declare state for interface values and commands for application actions, then connect a control through its value, command, or on-event properties.
state Name { path = Type }commands Name { path = command }onClick = command.pathvalue = state.pathcommands 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.
statecommandscommandonClickonChangeonInputonSubmit
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.
Extract a component when several surfaces share the same UI meaning, or when one interface region deserves its own typed contract.
import "path/component.yui"component Name { ... }property name { type = text required = true }slot Content { required = true }component SettingsSection {
property heading { type = text required = true }
property tone { type = text default = "quiet" }
slot Content { required = true }
}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.
importcomponentpropertyslotrequireddefaultbinding
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.
Choose the widget whose semantic role matches the job. Compose project-specific meaning from public controls instead of adding product vocabulary to the compiler.
textField Name { ... }selectField Name { ... }virtualList Name { ... }dataGrid Name { ... }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.
textFieldtoggleslidermenudialogvirtualListtabledataGridviewport
Yeho and YUI chapter
YUI rendering and access
The custom retained renderer, semantic accessibility tree, inspection path, performance model, and current platform boundary.
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.
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.
state mutation -> dirty ownerdirty owner -> retained fragmentfragment + damage -> custom rendererunchanged tick -> zero lowering and presentation.\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.
retained scenedirty ownerdamagedisplay commandsresources
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.
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.
label = "Accessible name"required = truedisabled = state.pathcommand = action.pathcommands 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.
labeldescriptionrequireddisabledfocusedselectedinvalidloadingempty
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.
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.
yehoc <project> --dump-yuiyehoc <project> --dump-yui-json.\tools\yeho.ps1 inspect <project>.\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.
inspect--dump-yui--dump-yui-jsonWindows x64provider
Yeho and YUI chapter
Tools and inspection
Create, check, run, build, format, test, inspect, package, and expose compiler truth.
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.
Inspect the earliest layer that disagrees with your intent instead of debugging only the final executable.
yehoc <project> --checkyehoc <project> --dump-astyehoc <project> --dump-semayehoc .\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.
--check--check-target--dump-ast--dump-sema--dump-truth--dump-project--dump-native-bridge
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.
Run the narrow command during iteration and the repository verification profile before treating a change as evidence.
.\tools\yeho.ps1 <command> <project>.\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.
formatlinttestinspectpackagewidget
Yeho and YUI chapter
Experiments and boundaries
Opt-in tuples, deprecated spellings, removed syntax, and features Yeho deliberately does not pretend to ship.
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++.
Prefer a named thing when the values have domain meaning. Use tuples only for deliberate compiler research behind the feature gate.
tuple of Type, Typetuple(value, value)deconstruct value into first, secondSplitScore(text name, int score) -> tuple of text, int
{
return tuple(name, score)
}
tuple of text, int pair = SplitScore("Ava", 7)
deconstruct pair into player, scorething PlayerScore
{
text player
int score
}- Requires the tuple-values project gate.
- The fallback is a named thing with fields that preserve meaning.
tupleofdeconstructinto
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.
Return a concrete list in Kyber-ready code. Use yield only in the explicit comparison lane while studying the future generator contract.
yield expressionCollect() -> list of int
{
yield 4
yield 7
}
list of int values = Collect()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.
yield
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.
For Kyber-ready code, collect intended changes separately and apply them after the loop.
plan remove expressionplan removeAt indexplan add valueplan addAt index valuefor score in scores
{
if score < 0
{
plan remove score
}
}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.
planremoveremoveAtaddaddAt
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.
Do not use these in new code. Replace them when touching an older file.
dobox -> thingstring -> textreturns -> ->main.yh -> start.yhthing 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.
doboxstringreturnsmain.yh
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.
Use the simple supported forms shown here. Treat a compiler rejection as a boundary, not an invitation to advertise unfinished 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 APIcount = 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.
genericsslicesinterpolation+=operatormallocfree
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.
Use the replacement that makes ownership and flow explicit. Revisit dedicated syntax only after it earns a compiler, runtime, and verification contract.
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 controltunnel 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.
choicechannelexporteventemitwatchassertpanicfatalfinallyconstthreadendLoops
