Meow Programming Language - Cat-themed Functional Language that Transpiles to Go on Meow Programming Language

Contributing to the Meow Programming Language

Mon, 01 Jan 0001 00:00:00 +0000

Thank you for your interest in contributing to the Meow Programming Language! This guide covers everything you need to know to get started.

Development Environment Setup

Prerequisites

Go 1.26+ — required (see go.mod)
stringer — for code generation of token type names

# Install stringer
go install golang.org/x/tools/cmd/stringer@latest

Clone and Build

git clone https://github.com/135yshr/meow.git
cd meow
go build ./cmd/meow

Run Tests

go test ./...

Build and Run

# Build the compiler
go build ./cmd/meow

# Run a .nyan program
go run ./cmd/meow run examples/hello.nyan

# Show transpiled Go code
go run ./cmd/meow transpile examples/hello.nyan

# Run tests
go test ./...

# Run tests verbose
go test ./... -v

# Static analysis
go vet ./...

# Update golden files (required when changing compiler output)
go test ./compiler/ -update

# Regenerate stringer output (after changing token types)
go generate ./...

Project Structure

flowchart LR
 subgraph meow[" meow/ "]
 direction TB
 subgraph cmd["cmd/meow/ — CLI entry point"]
 cmd_main["main.go"]
 end
 subgraph compiler["compiler/ — Pipeline orchestration + E2E tests"]
 comp_go["compiler.go"]
 comp_test["compiler_test.go"]
 end
 subgraph pkg["pkg/"]
 token["token/ — Token types, keywords, positions<br/>token.go, tokentype_string.go"]
 lexer["lexer/ — iter.Seq-based tokenizer<br/>lexer.go, lexer_test.go"]
 ast["ast/ — AST node definitions<br/>ast.go, types.go, walk.go"]
 parser["parser/ — Pratt parser (iter.Pull)<br/>parser.go, parser_test.go"]
 checker["checker/ — Type checker<br/>checker.go"]
 types["types/ — Type system definitions<br/>types.go"]
 codegen["codegen/ — AST → Go source generation<br/>codegen.go, codegen_test.go"]
 formatter["formatter/ — Code formatter<br/>formatter.go"]
 linter["linter/ — Code linter<br/>linter.go"]
 mutation["mutation/ — Mutation testing<br/>mutation.go"]
 end
 subgraph runtime["runtime/"]
 meowrt["meowrt/ — Core runtime: Value, operators, builtins<br/>value.go, operators.go, builtins.go, list.go"]
 file["file/ — File I/O (snoop, stalk)<br/>file.go"]
 http["http/ — HTTP client (pounce, toss, knead, swat, prowl)<br/>http.go"]
 testing["testing/ — Test framework (judge, expect, refuse, run)<br/>testing.go"]
 coverage["coverage/ — Statement coverage tracking<br/>coverage.go"]
 end
 examples["examples/ — Sample .nyan programs"]
 testdata["testdata/ — Golden file tests (.nyan + .golden)"]
 docs["docs/ — Documentation"]
 end

Adding a New Keyword

Add the token in pkg/token/token.go:

Meow Programming Language Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

A summary of features and changes in each Meow Programming Language release, organized from newest to oldest.

From v0.20.0 onwards each release also gets its own post, with runnable .nyan examples and upgrade notes. See the blog index for the full list.

Kitty (Struct) Types — PR #26

User-defined composite types with typed fields.

kitty Cat {
 name: string
 age: int
}

nyan nyantyu = Cat("Nyantyu", 3)
nya(nyantyu.name) # => Nyantyu

What’s new:

Meow Programming Language Specification: Syntax, Types, Functions, and Pattern Matching

Mon, 01 Jan 0001 00:00:00 +0000

This document defines the syntax and semantics of the Meow Programming Language.

Meow is a cat-themed programming language that transpiles to Go. Source files use the .nyan extension and are encoded in UTF-8.

Notation

This specification uses Extended Backus-Naur Form (EBNF) for grammar productions:

Production = name "=" Expression "." .
Expression = Term { "|" Term } .
Term = Factor { Factor } .
Factor = name | literal | "(" Expression ")" | "[" Expression "]" | "{" Expression "}" .

[ ... ] denotes optional (0 or 1).
{ ... } denotes repetition (0 or more).
" ... " denotes terminal symbols.

Source Code Representation

Source code is UTF-8 encoded text in .nyan files. Newlines serve as statement terminators (semicolons are not used); the one exception is a line beginning with |=|, which continues the expression on the line above — see Pipe Expression. The compiler processes a single .nyan file at a time.

Meow Programming Language Tutorial: Learn .nyan Syntax from Hello World

Mon, 01 Jan 0001 00:00:00 +0000

A step-by-step guide to learning the Meow Programming Language. Each section builds on the previous one and includes runnable .nyan examples.

Prerequisites

Go 1.26+ installed
Meow compiler installed (see Installation)

Verify your installation:

meow version

1. Hello, World!

Create a file called hello.nyan:

nya("Hello, World!")

Run it:

meow run hello.nyan

Output:

Hello, World!

nya is Meow’s print function. It prints its arguments separated by spaces, followed by a newline.

You can also build a native binary:

Effective Meow Programming Language: Idiomatic Patterns and Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Idiomatic patterns and conventions for writing clean, consistent code in the Meow Programming Language.

Placeholder Names

Every language has its go-to stand-in names — the world at large reaches for foo, bar, and baz. In Meow, we have our own cast of characters:

Name	Role
Nyantyu	The first cat on the scene — your default placeholder
Tyako	The second — shows up when one name isn’t enough
Tyomusuke	The third — for when the gang’s all here

Use them in examples, tests, and documentation whenever you need throwaway names. Keeping these consistent makes .nyan code feel at home everywhere in the project.

Meow Programming Language Standard Library

Mon, 01 Jan 0001 00:00:00 +0000

This document describes all built-in functions and standard library packages available in the Meow Programming Language.

Built-in Functions (no `nab` required)

These functions are available globally in every .nyan program.

`nya(args...)`

Print values to standard output, separated by spaces, followed by a newline.

nya("Hello", "World") # => Hello World
nya(42) # => 42
nya([1, 2, 3]) # => [1, 2, 3]

Returns catnap.

`hiss(args...)`

Raise an error by panicking. Arguments are joined with spaces and prefixed with "Hiss! ".

Meow Programming Language Quick Reference

Mon, 01 Jan 0001 00:00:00 +0000

A complete reference of all keywords, operators, and syntax in the Meow Programming Language.

Keywords

Meow	Meaning	Example
`nyan`	Variable declaration	`nyan x = 42`
`meow`	Function definition	`meow add(a int, b int) int { bring a + b }`
`bring`	Return a value	`bring x + 1`
`sniff`	Conditional branch (if)	`sniff (x > 0) { ... }`
`scratch`	Else branch	`} scratch { ... }`
`purr`	Loop (count, range, list, or condition)	`purr i (10) { ... }`, `purr (ready) { ... }`
`bolt`	Leave the loop	`sniff (found) { bolt }`
`slink`	On to the next turn	`sniff (empty) { slink }`
`paw`	Lambda (anonymous function)	`paw(x int) { x * 2 }`
`nya`	Print values	`nya("Hello!")`
`lick`	Transform each element in a list (map)	`lick(nums, paw(x) { x * 2 })`
`picky`	Select elements matching a condition (filter)	`picky(nums, paw(x) { x > 0 })`
`curl`	Combine a list into a single value (reduce)	`curl(nums, 0, paw(a, x) { a + x })`
`peek`	Branch based on a value (pattern match)	`peek(v) { 0 => "zero", _ => "other" }`
`hiss`	Raise an error	`hiss("something went wrong")`
`gag`	Catch errors (try/recover)	`gag(paw() { risky() })`
`is_furball`	Check if a value is an error	`is_furball(result)`
`nab`	Import standard library package	`nab "http"`
`flaunt`	Export (reserved)	—
`yarn`	True (boolean literal)	`nyan ok = yarn`
`hairball`	False (boolean literal)	`nyan ng = hairball`
`catnap`	Nil (represents no value)	`nyan nothing = catnap`
`kitty`	Struct (composite type) definition	`kitty Cat { name: string }`
`breed`	Type alias (transparent)	`breed Nickname = string`
`collar`	Newtype (nominal wrapper)	`collar UserId = int`
`pose`	Interface definition	`pose Showable { meow show() string }`
`groom`	Add methods to a type	`groom Cat { meow show() string { ... } }`
`self`	Instance reference in methods	`self.name`
`trill`	Pure-function modifier (opt-in purity check)	`trill meow add(a int, b int) int { bring a + b }`

Type Keywords

Meow supports gradual static typing. Type keywords annotate variables, function parameters, and return values.

Meow Programming Language vs Go: Side-by-Side Reference

Mon, 01 Jan 0001 00:00:00 +0000

A side-by-side reference for Go developers learning the Meow Programming Language. Meow transpiles to Go, so many concepts map directly.

Syntax Comparison

Concept	Go	Meow
Variable	`var x int = 42`	`nyan x int = 42`
Short variable	`x := 42`	`nyan x = 42`
Function	`func add(a, b int) int`	`meow add(a, b int) int`
Return	`return x`	`bring x`
If	`if x > 0 { }`	`sniff (x > 0) { }`
Else	`} else { }`	`} scratch { }`
Else if	`} else if x == 0 {`	`} scratch sniff (x == 0) {`
For (counting)	`for i := 0; i < n; i++`	`purr i (n)`
For (inclusive)	`for i := a; i <= b; i++`	`purr i (a..b)`
Lambda	`func(x int) int { return x*2 }`	`paw(x int) { x * 2 }`
Print	`fmt.Println(x)`	`nya(x)`
True	`true`	`yarn`
False	`false`	`hairball`
Nil	`nil`	`catnap`
Struct	`type Cat struct { ... }`	`kitty Cat { ... }`
Import	`import "net/http"`	`nab "http"`
Error	`errors.New("msg")`	`hiss("msg")`
Panic	`panic("msg")`	`hiss("msg")`
Recover	`defer func() { recover() }()`	`gag(paw() { ... })`

Detailed Examples

Variable Declaration

Go:

Meow Programming Language Compiler Internals

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the internal architecture of the Meow Programming Language compiler for contributors who want to understand or modify the compilation pipeline.

Pipeline Overview

flowchart TD
 src[".nyan source"]
 lexer["Lexer<br/>pkg/lexer"]
 parser["Parser<br/>pkg/parser"]
 checker["Checker<br/>pkg/checker"]
 codegen["Codegen<br/>pkg/codegen"]
 gobuild["go build"]
 bin(["binary"])
 interp["Interpreter<br/>pkg/interpreter"]
 output(["output"])

 src --> lexer
 lexer -- "iter.Seq[Token]" --> parser
 parser -- "AST" --> checker
 checker -- "TypeInfo" --> codegen
 checker -- "TypeInfo" --> interp
 codegen -- "Go source" --> gobuild
 gobuild --> bin
 interp -- "direct execution" --> output

There are two execution paths from the AST:

Meow Programming Language v0.21.4: The Documentation Says What the Language Does

Thu, 20 Aug 2026 15:05:06 +0000

Released 2026-08-20. No compiler behaviour changed in this one. What changed is that the documentation now describes the language that v0.17.0 through v0.21.3 actually built, and a test keeps it that way.

What the reference did not say

The reference had never learned about nab go at all — its import section ended at the list of Meow’s own packages. Reaching a Go package by import path, naming it with tag, and pinning a version with @ are all documented now, and every example was run rather than written from memory:

Meow Programming Language v0.21.3: Purity Judged by the Declaration a Name Reaches

Thu, 20 Aug 2026 08:23:16 +0000

Released 2026-08-20. A trill function is pure: it must not call a non-pure one. Until this release, the guard judged that by name alone, so a trill body could not call a pure local of its own where an impure top-level function happened to share the name.

meow helper(x int) int {
 nya("side effect")
 bring x + 1
}

trill meow adds(n int) int {
 nyan helper = paw(x) { bring x + 1 }
 bring helper(n)
}

Hiss! pure function adds must not call non-pure function helper, nya~

The local has nothing to do with the top-level helper, but the purity check looked the name up in the table of top-level functions and never asked whether it still reached that declaration here.

Meow Programming Language v0.21.2: A Call Goes to the Declaration the Name Reaches

Thu, 20 Aug 2026 05:27:36 +0000

Released 2026-08-20. v0.21.1 settled what a name read rather than called reaches. Calling through the same name did not follow — it went to the top-level function of that name, in both halves of the compiler.

meow greet(who string) string { bring "hi " + who }

meow rename() string {
 nyan greet = paw(a, b) { bring a + "/" + b }
 bring greet("x", "y")
}

The checker looked the name up in its table of top-level functions before it looked in scope, so the call was checked against the wrong signature and refused outright:

Meow Programming Language v0.21.1: A Top-Level Function Named Rather Than Called

Thu, 20 Aug 2026 03:36:22 +0000

Released 2026-08-20. v0.21.0 made a member readable as a value. A plain top-level function was still not one, and saying so leaked Go’s own complaint:

meow greet(who string) string { bring "hi " + who }
nya(greet)

cannot use greet (value of type func(who string) string) as meowrt.Value value
in argument to meow.Nya: func(who string) string does not implement meowrt.Value

Not a Hiss!, and not something a Meow program could act on. It was not only nya — no top-level function could be used as a value at all, so the plainest functional idiom did not work:

Meow Programming Language v0.21.0: A Member Read as Well as Called

Wed, 19 Aug 2026 22:47:43 +0000

Released 2026-08-19. Reading a member without calling it used to come apart — codegen emitted an unchecked assertion, so a program ended with a Go panic rather than a furball:

nyan swap = strings.new_replacer("cat", "nyan")
nyan speak = swap.replace

interface conversion: meowrt.Value is *meowrt.Opaque, not *meowrt.Kitty

A member read is now a value

A field is what it holds. A method — one groomed on, or one belonging to something from Go — is that method bound to what it was reached through, which is a function like any other:

Meow Programming Language v0.20.0: A Value Read Out of Go Remembers Where It Came From

Wed, 19 Aug 2026 22:03:28 +0000

Released 2026-08-19. nab go lets a .nyan program reach a Go package with no wrapper written for it. In v0.20.0 the value that comes back stops forgetting what it is.

Reading a Go value was what made it unusable

The rule ran backwards: the more of a Go type Meow could read, the less of it was left to use. A *url.URL was read into a basket, and once it was a basket the methods of the URL were gone.

Meow Programming Language vs MeowLang and Other Cat-themed Languages

Mon, 01 Jan 0001 00:00:00 +0000

If you searched for “Meow language” or “MeowLang” and landed here, this page explains what the Meow Programming Language is, and how it relates to other projects that share a similar cat-themed name.

What is the Meow Programming Language?

The Meow Programming Language is a cat-themed functional programming language that transpiles .nyan source files into Go source code, which is then compiled to a native binary using the standard Go toolchain.

Sitemap - Meow Programming Language

Mon, 01 Jan 0001 00:00:00 +0000

Browse every page of the Meow Programming Language website. If you cannot find a page through navigation, this directory lists everything that is published.

Meow Programming Language - Cat-themed Functional Language that Transpiles to Go on Meow Programming Language

Contributing to the Meow Programming Language

Development Environment Setup

Prerequisites

Clone and Build

Run Tests

Build and Run

Project Structure

Adding a New Keyword

Meow Programming Language Release Notes

Kitty (Struct) Types — PR #26

Meow Programming Language Specification: Syntax, Types, Functions, and Pattern Matching

Notation

Source Code Representation

Meow Programming Language Tutorial: Learn .nyan Syntax from Hello World

Prerequisites

1. Hello, World!

Effective Meow Programming Language: Idiomatic Patterns and Conventions

Placeholder Names

Meow Programming Language Standard Library

Built-in Functions (no nab required)

nya(args...)

hiss(args...)

Meow Programming Language Quick Reference

Keywords

Type Keywords

Meow Programming Language vs Go: Side-by-Side Reference

Syntax Comparison

Detailed Examples

Variable Declaration

Meow Programming Language Compiler Internals

Pipeline Overview

Meow Programming Language v0.21.4: The Documentation Says What the Language Does

What the reference did not say

Meow Programming Language v0.21.3: Purity Judged by the Declaration a Name Reaches

Meow Programming Language v0.21.2: A Call Goes to the Declaration the Name Reaches

Meow Programming Language v0.21.1: A Top-Level Function Named Rather Than Called

Meow Programming Language v0.21.0: A Member Read as Well as Called

A member read is now a value

Meow Programming Language v0.20.0: A Value Read Out of Go Remembers Where It Came From

Reading a Go value was what made it unusable

Meow Programming Language vs MeowLang and Other Cat-themed Languages

What is the Meow Programming Language?

Sitemap - Meow Programming Language

Built-in Functions (no `nab` required)

`nya(args...)`

`hiss(args...)`