Yo

English | 简体中文

Work in Progress :) Not Ready!

https://shd101wyy.github.io/Yo

LLM-friendly to write, human-friendly to read.

A multi-paradigm, general-purpose, compiled programming language. Yo aims to be Simple and Fast (around 0% - 15% slower than C).

The name Yo comes from the Chinese word 柚 (yòu), meaning pomelo, a large citrus fruit similar to grapefruit. It's my daughter's nickname.

Meet Youyou (柚柚), the Yo panda. Rust has Ferris the crab; Yo has Youyou, a panda hugging a halved pomelo. The logo is the same pomelo: the white pith between its three segments draws a Y, and the round rind around it is the o.

📖 My Story with Programming Languages — the journey from Java at 16 to building Yo.

• Features
• Installation
  • Install script (recommended)
• Quick Start
• Prelude
• Standard Library
• Code examples
  • Hello World
  • Example Projects
• Contributing
• Editor Support
• Version Management
• AI Agent Skills
  • Using in your own project
• License

Features

For the design of the language, please refer to DESIGN.md.

Below is a non-exhaustive list of features that Yo supports:

• First-class types.
• Compile-time evaluation.
• Homoiconicity and metaprogramming (Yo syntax is inspired by the Lisp S expression. Simple syntax rule, Human & AI friendly).
• Closure.
• Algebraic Effects and Handlers (One-shot delimited continuation. Tail-Resumptive. Effect handlers with return/unwind, by Evidence Passing).
• Async/await (Builtin Io effect. Stackless coroutine & Cooperative multi-tasking. Lazy Futures, multi-await, single-threaded concurrency via state machine transformation).
• FFI — c_include(...) / extern(...) evaluate to module values: bind, select, rename, or glob their members; a bare declaration is the glob; no shadowing.
• Memory safety by default — user code can't write UB (no raw pointers, no FFI, no inline assembly) without an explicit pragma(Pragma.AllowUnsafe); opt-in. inout(name) for in-place mutation; yo unsafe-report for auditing the unsafe surface.
• Explicit allocators — Zig-style placement beside reference counting: with_allocator(arena.allocator(), f) puts every object and container buffer f creates in an arena, RC still decides when each dies, and Arena.deinit panics instead of freeing under a live block.
• ref(struct(...)) and ref(enum(...)) types with Non-atomic Reference Counting and Thread-Local Cycle Collection.
• Compile-time Reference Counting with Ownership and Lifetime Analysis.
• Thread-per-core parallelism model (see PARALLELISM.md).
• Formal verification — contracts (requires/ensures/decreases), refinement types (refine(T, p)), and ghost/quantifier specs prove at compile time against a pinned Z3 (yo verify): counter-examples at refuted obligations, cache telemetry, --strict gating, JSON reports, and LSP contract hover.
• Declarative build system inspired by Zig and Nix (yo build, yo init, WASM targets).
• C interop.
• etc.

Installation

Install script (recommended)

Installs a native prebuilt compiler.

# macOS / Linux
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh

# Windows (PowerShell)
> irm https://shd101wyy.github.io/Yo/install.ps1 | iex

This installs to <prefix>/lib/yo/<tag> and links <prefix>/bin/yo, with the prefix defaulting to $HOME/.local. Useful options:

Option	Meaning
-v, --version=<tag>	install a specific release (default: latest)
-p, --prefix=<dir>	install prefix — /usr/local for system-wide (uses sudo)
--from-source	build from the published single-file yo.c
-cc, --c-compiler=<cc>	C compiler for the source build (implies --from-source)
-cflags, --c-flags=<f>	extra C flags for the source build (implies --from-source)
-u, --uninstall	uninstall instead of install
--dry-run	show what would happen, change nothing

# a specific release, system-wide
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh -s -- --version=v0.2.4 --prefix=/usr/local

# build from source with your own toolchain
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh -s -- -cc=gcc -cflags='-march=native'

Platforms without a prebuilt bundle — pass --from-source. The installer downloads the release's single-file yo.c and compiles it with your own C compiler, so it links against your own libc and loader. This is the answer on NixOS, where the prebuilt binary's hardcoded ELF interpreter (/lib64/ld-linux-x86-64.so.2) does not exist.

Note: --from-source needs a release that publishes the single-file yo.c. Releases up to and including v0.2.4 predate that artifact, so the option only works on releases made after it. The installer says so explicitly rather than failing obscurely.

Memory: building Yo itself, whether --from-source or yo build in a checkout, fits on an 8 GB machine with a v0.2.43 or later compiler. A full build of the compiler peaks at about 4.3 GiB (measured on Linux, C compiler included), and CI builds it inside an 8 GB no-swap limit on every change. Older releases needed about 10 GB. Compiling your own programs needs far less.

The installer puts the yo command on your PATH. Run yo --help to see the available commands.

Yo transpiles to C, so a C compiler is required to produce machine code. The install script above sets one up for you — these guides are for configuring the toolchain by hand, or for diagnosing a failed install.

• Linux
• macOS
• Windows

Targeting WebAssembly needs Emscripten as well — WASM setup.

Quick Start

$ yo init my-project        # Scaffold a new project
$ cd my-project
$ yo build run              # Build and run
Hello, world!

yo init generates a project with a manifest, a build file, source, and tests — plus the bundled agent skill files and AGENTS.md so AI coding agents pick up version-matched Yo knowledge (skip with yo init --no-skills):

my-project/
├── yo.toml               # Package manifest: name, modules, dependencies (edited by yo add)
├── build.yo              # Build configuration
├── src/
│   ├── main.yo           # Entry point
│   └── lib.yo            # Library module
├── tests/
│   ├── main.test.yo      # Unit tests for the executable
│   └── lib.test.yo       # Unit tests for the library
├── spec/
│   ├── README.md         # The claims wall: laws live here, proofs in the code
│   └── example.yo        # A seed law (`yo verify ./spec --strict` proves it)
├── .agents/skills/       # Agent skill files (AGENTS.md lists them)
├── AGENTS.md             # Guidance for AI coding agents
├── .gitignore
└── README.md

src/main.yo:

{ println } :: import("std/fmt");

main :: (fn() -> unit)({
  println("Hello, world!");
});

export(main);

Common build commands:

$ yo build                  # Build all artifacts
$ yo build run              # Build and run the executable
$ yo build test             # Run tests
$ yo build --list-steps     # List available build steps
$ yo build doc              # Generate HTML documentation
$ yo fmt                    # Format Yo source files
$ yo fmt --check            # Check formatting without writing changes

Prelude

Every Yo file automatically imports std/prelude.yo, which provides the core types, traits, and builtins available without any explicit import:

• Primitive types: bool, i8–i64, u8–u64, f32, f64, isize, usize, str
• C-compatible types: int, uint, short, long, longlong, char, etc.
• Core traits: Eq, Ord, Add, Sub, Mul, Div, Iterator, IntoIterator, TryFrom, TryInto, Dispose, Send, Acyclic, etc.
• Metaprogramming: Type, Expr, ExprList, Var
• Async: Io, FutureState, JoinHandle
• Utilities: assert, unsafe, try, for, not, arc, Rc, rc
• etc.

Standard Library

Still In Design

Yo ships with a comprehensive standard library covering strings, collections, file I/O, networking, encoding, regex, crypto, and more. For the full module reference, see the Standard Library Documentation.

You can generate documentation for your own project with yo doc:

$ yo doc ./src -o docs --title "My Project"

Or add a documentation step to your build.yo — see yo doc --help for details.

Code examples

Check the ./tests and ./std folders for more code examples.

Hello World

// main.yo
{ println } :: import("std/fmt");

main :: (fn() -> unit)({
  println("Hello, world!");
});

export(main);

// $ yo compile main.yo --optimize 2 -o main
// $ ./main

Example Projects

Project	Description
raylib_yo	Comprehensive raylib bindings — 35 struct types, 535 functions, 227 constants
tetris_yo | Online Demo	Classic Tetris game built with raylib_yo, demonstrating Yo's build system and C interop
http_server_demo_yo	Simple HTTP/1.1 server — async I/O, algebraic effects, TCP networking, request parsing & routing
markdown_it_yo	Direct port of the popular JavaScript markdown parser markdown-it to Yo, showcasing string processing and performance
markdown_yo | Online Demo	High-performance markdown-to-HTML converter — 5-7× faster than markdown-it (native), 2-6× faster (WASM at ≥1 MB). Try it in the browser
yo_http_benchmark	HTTP throughput benchmark — Yo vs Bun vs Deno vs Node.js vs Go, using wrk load testing

Contributing

The compiler is written in Yo and builds itself. See CONTRIBUTING.md for the dev environment, the build loop, and how to run the test suites — LLM-assisted contributions included.

Editor Support

• A VS Code extension is available here, providing syntax highlighting and a language client for .yo files.

  The language server is the yo binary itself (yo lsp, stdio): diagnostics, hover, completion, go-to-definition, document symbols, find references, rename, signature help, folding and formatting, all served by the Yo evaluator. The extension starts it when a yo binary is on PATH (or at yo.binPath); any other LSP-capable editor can spawn yo lsp directly. See docs/en-US/LSP.md for setup and the feature list.

• Vim / Neovim: a minimal syntax file and a usage README are available in vscode-extension/syntaxes/. See vscode-extension/syntaxes/README.md for installation steps, ftdetect examples and home-manager snippets.

Version Management

Yo supports per-project version pinning via a .yo-version file (similar to .nvmrc or .python-version):

# Pin your project to a specific Yo version
yo version pin 0.1.12

# Show current and pinned version
yo version

# Install, list, and clean cached versions
yo version install 0.1.13
yo version list
yo version clean

When a .yo-version file exists, the yo CLI automatically dispatches to the pinned version — downloading and caching the matching native release bundle on first use.

See docs/en-US/VERSION_MANAGEMENT.md for full documentation.

AI Agent Skills

This repository ships a set of agent skill files that teach AI agents how to write Yo programs. The skills are portable — you can copy the .github/skills/ directory into any Yo project and agents will be able to use them there too.

Skill	Description
yo-syntax	Core language syntax: curly braces, cond/match, structs, enums, operators, modules
yo-core-patterns	Everyday patterns: types, generics, traits, error handling, collections, iterators
yo-async-effects	Async/await, algebraic effects, Exception, Io, spawning tasks
yo-project-workflow	yo CLI commands, build.yo project files, dependency management

Using in your own project

yo init installs the skills automatically (along with an AGENTS.md that lists them). For a project created another way, use the yo CLI:

yo skills install

This copies all skill files into every agent config directory found in the current project (.github, .agents, .claude, .opencode, .openai, .cursor). If none exist, .agents/skills/ is created automatically.

You can also copy them manually:

cp -r .github/skills /path/to/your-yo-project/.github/
# or .agents, .claude, etc depending on your agent platform

Then in any AI agent session, invoke a skill by name (e.g. @yo-syntax) to give the agent contextual knowledge about the Yo language.

CLI output language

CLI help texts and user-facing messages are bilingual (English + 简体中文): yo --lang zh-CN --help or export YO_LANG=zh-CN switches the CLI to Simplified Chinese. English is the default.

License

Apache License 2.0 with LLVM Exceptions