Harsh

A quick reference to everything you write daily, spelled in Harsh — as of Harsh 0.2.0. It does not teach: The Harsh Programming Language does, and reading it is not optional. Keep this page beside it. Every example on this page is transpiled by check.sh, so none of it can fall behind the language.

Basics

The rule behind every call: arguments follow the function, one atom each; anything that is not an atom — an operator, a prefix -, & or * — goes in parentheses. f$ calls with no arguments.

Operators and precedence

Tightest first: atoms (f$, v[i], ( … )), application f a b, the chain <-, ?, the prefix operators, Rust's operators in Rust's order, the pipes, assignment. Two traps: f -1 is a subtraction, and *p <- x dereferences the field x, not p.

Strings and characters

Numbers

Collections

Comprehensions

Control flow

Blocks over several lines are what you will write most:

fn classify (n: i32) -> &'static str:
    if n < 0:
        "negative"
    else if n == 0:
        "zero"
    else:
        "positive"

fn count_new (words: &[&str]) -> usize:
    let mut seen = std.collections.HashSet.new$
    for w in words:
        seen <- insert w
        ()
    seen <- len$

Pattern matching

More than two arms go one per line, no commas:

fn describe (n: i32) -> String:
    match n\
        0 => String.from "zero"
        1 | 2 | 3 => String.from "a few"
        4..=9 => String.from "several"
        x if x < 0 => format! "negative {x}"
        _ => String.from "many"

Functions and closures

A body of several statements goes beneath its header; so may any body, for room:

fn double n: i32 -> i32:
    n * 2

fn apply<F: Fn (i32) -> i32> (f: F) (x: i32) -> i32:
    f x

fn adder n: i32 -> impl Fn (i32) -> i32:
    move |x| x + n

fn print_all<T: std.fmt.Debug> (items: &[T]):
    for i in items:
        println! "{:?}" i

Structs and enums

Declarations take no mark; their fields or variants go beneath, and a literal with more than two fields goes one field per line:

#[derive Debug Clone]
struct Point
    x: f64
    y: f64

enum Shape
    Circle f64
    Rect
        w: f64
        h: f64
    Empty

fn origin_config$ -> Config:
    Config\
        name = String.from "origin"
        verbose = true
        retries = 3

struct Config
    name: String
    verbose: bool
    retries: u32

Methods and traits

use std.fmt

struct Circle
    r: f64

impl Circle
    fn new r: f64 -> Self:
        Self\ r
    fn area (&self) -> f64:
        3.14159 * self <- r * self <- r
    fn grow (&mut self) (by: f64):
        self <- r += by

trait Describe
    fn describe (&self) -> String
    fn shout (&self) -> String:
        self <- describe$ <- to_uppercase$

impl Describe for Circle
    fn describe (&self) -> String:
        format! "a circle of radius {}" (self <- r)

impl fmt.Display for Circle
    fn fmt (&self) (f: &mut fmt.Formatter) -> fmt.Result:
        write! f "Circle({})" (self <- r)

Ownership and borrowing

Errors

A custom error type:

use std.fmt

#[derive Debug]
enum AppError
    NotFound String
    Invalid u32

impl fmt.Display for AppError
    fn fmt (&self) (f: &mut fmt.Formatter) -> fmt.Result:
        match self\
            AppError.NotFound name => write! f "{name} not found"
            AppError.Invalid code => write! f "invalid code {code}"

impl std.error.Error for AppError {}

Iterators

A chain of three steps or more goes vertical:

fn evens_squared (v: &[i32]) -> Vec<i32>:
    v
        <- iter$
        <- filter (|x| *x % 2 == 0)
        <- map (|x| x * x)
        <- collect$

Modules and imports

Testing

fn add (a: i32) (b: i32) -> i32:
    a + b

#[cfg test]
mod tests
    use super.*

    #[test]
    fn adds_two_numbers$:
        assert_eq! (add 2 3) 5

    #[test]
    #[should_panic]
    fn index_out_of_range$:
        let v = vec! 1 2 3
        v[99]
        ()

Concurrency and async

A thread whose body spans lines, inside a loop; the () after the body says the loop body is worth nothing:

fn spawn_all$:
    let (tx, rx) = std.sync.mpsc.channel$
    for id in 0..3:
        let tx = tx <- clone$
        std.thread.spawn move ||:
            tx <- send (id * id) <- unwrap$
        ()
    drop tx
    for n in rx: println! "{n}"

Linear algebra

Add hrs_std to the project once: hrs add hrs_std.

solve and inv stop the program on a singular matrix, as Julia does; try_solve and try_inv return Err (LinAlgError.Singular) instead.

Macros

Harsh's own macros, written ~, are expanded by hrs and are gone from the Rust. A macro's own language — an rsx! tree, view! markup, select! arms — goes in braces as Rust, with Harsh in holes @: … :@. The Book's chapter 23 teaches writing both kinds.

The hrs tool

Three ways to use Harsh

• #1: hrs new mylib, hrs build, hrs test; used by path today, in the user's Hrs.toml: mylib = { path = "../mylib" }, Harsh macros included. Harsh's registry is still to come.
• #2: hrs new, hrs build, then hrs -c publish: the Rust in export/. A Harsh crate it uses is named by its own export/ and its version: hrs -c publish that one first. Harsh macros unfold before the Rust is written, so the published crate has none.
• #3: cargo new; each .hrs file beside the .rs it produces, with hrs src/parser.hrs src/lexer.hrs (files given together see each other's functions); commit the .rs, put hrs --check src/*.hrs in CI, then cargo publish.

Layout style

hrs fmt applies the countable rules; the rest is judgment:

• A chain of three steps or more goes vertical, every <- under the first.
• A literal of three fields or more goes one field per line, no commas.
• An if with three branches or more goes on several lines.
• A literal inside a literal on one line is parenthesised: Dog\ inner = (Animal\ name = n), good = true.
• An inline if c: a else: b is left as written; too long, write a block if with each value beneath its branch.
• A match with more than two arms goes one arm per line.
• A call made long by a long argument goes vertical, one argument per line.
• No semicolons: a block that discards its last value ends with a line ().

Naming

As in Rust: snake_case for functions, variables and modules; CamelCase for types and traits; SCREAMING_SNAKE_CASE for constants and statics. Harsh files end in .hrs.

Where to read more

• The Harsh Programming Language — the Book; read it all.
• Harsh by Example — one runnable page per feature.
• Harsh Design Patterns and The Harshonomicon — the companions.
• The language guide — every rule, with its Rust beside it.