grayscale

README

The Grayscale Programming Language

---

---

Why Grayscale?

• Readable syntax — for_each, as_long_as(alias is while), if/or/otherwise(alias is else), when/is, in/not_in(alias is !in), or_return, ensure, bit_and/bit_or/bit_xor, etc.
• Versatility through simplicity — Scripts, microservices, CLI tools, or projects where you want to learn systems programming fundamentals
• A compiler that for the programmer — Clear error messages, a built-in formatter, live reloading, and built-in language and stdlib docs via gray man. When questions arise, Grayscale provides the answers.
• Safe by default — Automatic Scope-Based Arena Management for memory, bounds-checked arrays, overflow-checked math, nil protection, NO pointer arithmetic. The guardrails are on unless you explicitly take them off with the @mem stdlib module

---

The Standard Library

@arrays · @strings · @maps · @math · @time · @random · @json · @io · @os @http · @server · @crypto · @encoding · @uuid · @bytes · @binary · @sqlite @regex · @csv · @net · @threads · @sync · @channels · @mem · @atomic · @fmt · @strconv

---

Install

Binary download (recommended)

Download the latest release for your platform from the Releases page. No dependencies required.

Build from source

Requires Go 1.23+ and a C compiler (gcc or clang).

git clone https://github.com/grayscale-lang/grayscale.git
cd grayscale
make build
make install

Note: Grayscale currently supports macOS and Linux only.

---

Commands

Command	Description	Example
gray <file>	Compile and run	gray main.gray
gray build <file> -o <name>	Compile to a distributable binary	gray build main.gray -o myapp
gray build <file> --emit-c	Emit generated C source to a file (no binary)	gray build main.gray --emit-c
gray check <file>	Type check without compiling	gray check main.gray
gray watch <file>	Watch for changes, re-run on save	gray watch main.gray
gray fmt <path>	Format .gray source files in place	gray fmt . or gray fmt ./...
gray fmt --check <path>	Check formatting without modifying files (CI gate)	gray fmt --check ./...
gray doc <file>	Generate docs from #doc attributes	gray doc main.gray
gray new <name>	Scaffold a new project	gray new myproject
gray report	Print system info for bug reports	gray report
gray update	Update to the latest stable version	gray update
gray update --pre	Update to the latest pre-release (alpha/beta)	gray update --pre
gray install <version>	Install a specific version by semver	gray install x.y.z
gray version	Show version info	gray version
gray man	Show help for the man command	gray man
gray man <module>	Show info about a stdlib module	gray man strings
gray man <function>	Show info about a stdlib function	gray man to_upper
gray man <struct>	Show info about a stdlib struct type	gray man HttpRequest

---

Updating

gray update              # latest stable
gray update --pre        # latest pre-release Note: The latest pre-release may be very out of date
gray install x.y.z       # pin to an exact version

gray update checks for new versions, shows the changelog, and upgrades both the gray CLI and the compiler. Pass --pre to pick up the latest alpha, beta, or rc. Use gray install <version> to install an exact version by semver — downgrades and pre-release tags (e.g. 3.0.0-beta.2) are supported.

---

Learn More

• Language standard
• Contributing guide

Tooling

• The Grayscale Language Server Protocol

---

Status

Grayscale is in active development. The language is usable for personal projects and dev tools. Breaking changes may occur frequently.

---

License

MIT License - Copyright (c) 2025-Present Marshall A Burns

See LICENSE for details.

---

Contributors

Thank you to everyone who has contributed to Grayscale!