[![seqlings](https://img.shields.io/crates/v/seqlings.svg?label=seqlings)](https://crates.io/crates/seqlings)

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

    "Look out! Broken programs below!"

Interactive exercises for learning [Seq](https://git.navicore.tech/navicore/patch-seq), a stack-based programming language.

Inspired by [Rustlings](https://github.com/rust-lang/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](https://git.navicore.tech/navicore/patch-seq#installation) for setup details.

## Quick Start

```bash
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.

```seq
# 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:**
```seq
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:
```seq
[ dup i.* ]     # A quotation (not executed yet)
5 [ dup i.* ] call   # Execute it: result is 25
```

**Lists** are created from strings:
```seq
"apple banana cherry" " " string.split   # Creates a 3-element list
[ string.to-upper ] list.map             # Transform each element
```

**Unions** define algebraic data types:
```seq
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](https://git.navicore.tech/navicore/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**
```bash
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**
```bash
seqlings completions bash > ~/.local/share/bash-completion/completions/seqlings
```

**fish**
```bash
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:

```bash
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
