_ _
 ___  ___  __| | (_)_ __   __ _ ___
/ __|/ _ \/ _` | | | '_ \ / _` / __|
\__ \  __/ (_| | | | | | | (_| \__ \
|___/\___|\__, |_|_|_| |_|\__, |___/
             |_|          |___/

"Look out! Broken programs below!"

Interactive exercises for learning Seq, a stack-based programming language.

Inspired by Rustlings, Seqlings guides you through Seq's concepts with hands-on exercises that you complete in your editor.

Prerequisites

You need the Seq compiler (seqc) installed and available in your PATH.

See the patch-seq installation instructions for setup details.

Quick Start

git clone https://git.navicore.tech/navicore/seqlings
cd seqlings
cargo run

This starts watch mode - Seqlings monitors your exercise files and provides instant feedback as you edit them.

Starting over: If you want to reset all exercises to their original state, run git checkout . from the seqlings directory.

How It Works

1. Seqlings shows you the current exercise
2. Open the exercise file in your editor
3. Read the instructions and fix/complete the code
4. Delete the # I AM NOT DONE marker when finished
5. Seqlings automatically verifies and advances to the next exercise

Commands

Command	Description
seqlings	Start watch mode (default)
seqlings list	Show all exercises with completion status
seqlings hint	Get a hint for the current exercise
seqlings hint <name>	Get a hint for a specific exercise
seqlings verify	Check all exercises at once
seqlings next	Skip to the next exercise
seqlings reset	Reset current exercise to original state
seqlings reset <name>	Reset a specific exercise

Curriculum

The exercises cover Seq from basics to advanced topics:

Section	Topics
00-intro	Hello world, comments, numbers
01-stack-basics	push, dup, drop, swap, over, rot
02-stack-advanced	nip, tuck, 2dup, pick, roll
03-arithmetic	i.add, i.subtract, i.multiply, i.divide
04-floats	Float literals and f.* operations
05-comparison	=, <, >, <=, >=, <>
06-boolean	and, or, not
07-conditionals	if/then/else
08-words	Defining words (functions)
09-recursion	Recursive patterns, TCO
10-quotations	Higher-order programming with [ ]
11-types	Type system basics
12-type-conversions	int->string, string->int, etc.
13-strings	String operations
14-variants	Union types and pattern matching
15-lists	list.map, list.filter, list.fold
16-maps	Key-value dictionaries
19-io	Console I/O
20-files	File operations
21-args	Command-line arguments
22-os	Environment and system info
23-time	Timestamps and timing
24-channels	CSP-style concurrency
25-spawn	Green threads (strands)
26-tcp	Network programming
27-std-imath	Integer math stdlib
28-std-fmath	Float math stdlib
29-weave	Generator patterns with strands
30-encoding	Base64, Hex encoding/decoding
31-regex	Regular expressions
32-compression	Gzip and Zstd compression
33-crypto	SHA-256, HMAC, AES-GCM, Ed25519
34-http-client	HTTP requests and JSON APIs

Seq Language Basics

Seq is a stack-based, concatenative language. Values go on a stack, and words (functions) consume and produce stack values.

# Push values onto the stack
10 20

# i.+ pops two values, pushes their sum
i.+          # Stack: ( 30 )

# Define a word (function)
: square ( Int -- Int )
    dup i.*
;

# Use it
5 square       # Stack: ( 25 )

Key Concepts

Stack manipulation:

dup      # ( a -- a a )       Duplicate top
drop     # ( a -- )           Discard top
swap     # ( a b -- b a )     Exchange top two
over     # ( a b -- a b a )   Copy second to top
rot      # ( a b c -- b c a ) Rotate third to top

Quotations are deferred code blocks:

[ dup i.* ]     # A quotation (not executed yet)
5 [ dup i.* ] call   # Execute it: result is 25

Lists are created from strings:

"apple banana cherry" " " string.split   # Creates a 3-element list
[ string.to-upper ] list.map             # Transform each element

Unions define algebraic data types:

union Option { Some { value: Int }, None }

42 Make-Some      # Create a Some variant
Make-None         # Create a None variant

# Pattern match
my-option match
    Some { >value } -> value
    None -> 0
end

Tips

• Read the comments - Each exercise explains the concept
• Use seqlings hint - When stuck, get a hint
• Check solutions/ - Reference solutions are available
• Experiment - Try variations in the REPL (seqc repl)

Contributing

Found a bug or want to improve an exercise? PRs welcome!

If you find gaps in the Seq language itself, please open issues at patch-seq.

Shell Completions

Seqlings can print a completion script for your shell. Redirect it to a file your shell picks up on startup.

zsh

mkdir -p ~/.zfunc
seqlings completions zsh > ~/.zfunc/_seqlings
# Make sure ~/.zfunc is on your fpath. Add to ~/.zshrc if it isn't:
#   fpath=(~/.zfunc $fpath)
#   autoload -U compinit && compinit

bash

seqlings completions bash > ~/.local/share/bash-completion/completions/seqlings

fish

seqlings completions fish > ~/.config/fish/completions/seqlings.fish

PowerShell and Elvish are also supported — pass powershell or elvish to seqlings completions.

Restart your shell after installing and seqlings <TAB> will complete subcommands and flags.

Documentation

Build locally with just docs (serve) or just build-docs (one-shot). The site pulls content from docs/ plus a generated copy of README.md.

CI

Run the full CI check locally before pushing:

just ci

This runs fmt-check, lint (clippy with -D warnings), test, and a release build — the same commands GitHub Actions runs. The Rust toolchain is pinned in rust-toolchain.toml so local and CI agree exactly.

License

MIT