Working with Salam

Salam is a compiled, statically typed language whose keywords exist in English and Persian. Its rules differ from mainstream languages in ways that are not guessable, so verify with tools rather than assuming.

Always do this

1. Look the construct up. salam_docs answers "how is X written in Salam" from the full reference (loops, lambdas, structs, generics, error handling, Persian) and explains an error code such as E085.
2. Never guess a stdlib API. salam_stdlib_search finds a function by what it does across every package; salam_stdlib_symbols shows one package's types, fields, methods and functions with exact signatures. Inventing function names is the most common cause of invalid Salam.
3. Check after every edit. salam_check type-checks without codegen and returns each diagnostic with its source line, the compiler's help and a hint for syntax borrowed from other languages. Fix the first error first.
4. Look at working code. salam_find_examples searches the shipped test corpus for a real, compiling usage, with surrounding lines.

If those tools are not available, the same information is in std/ (the standard library is ordinary Salam source) and tests/.

The three rules that break builds most often

until means while. until i < n: loops while i < n. It is not a do-while and not "loop until true". Getting it backwards gives a loop that never runs or never ends.

Top-level order is enforced:

package → import → include → extern: → globals → types → private funcs / export: → pub funcs

Once the first pub func appears, only pub funcs may follow (E088). extern: holds body-less C declarations only; Salam functions that C must call by their plain name go in an export: block, which ranks with the private funcs. Put every private helper above the public section. Globals must precede all functions and types (E084/E085), types must precede all functions (E087), imports come directly after package (E083) and before every include (E108).

Unused things are errors, not warnings: unused import E082, unused variable E059, unused function E066. Remove them; a _ prefix is only for a parameter whose signature is fixed, such as a callback.

switch and match are not interchangeable. switch/ترابرد is a fallthrough statement with bare labels (no case/default) - break stops the fallthrough, no exhaustiveness check, and it rejects a Variant subject outright. match is an exhaustive, no-fallthrough expression for enum/Variant dispatch. Use switch for C-style fallthrough or range/relational labels (90 to 100:, >= 60:); use match when every case must be handled.

Quick syntax

package main

import str

func _helper(a: int): int:
    ret a * 2
end

pub func Double(a: int): int: ret _helper(a) end

func main:
    x := 21                    // immutable, inferred
    mut total := 0             // mutable
    total = Double(x)
    println str.FromInt(total)
    ret 0                      // main's return value is the exit code (0 when omitted)
end

• No typed declarations (x: int = 1 is a parse error): use :=, cast with as.
• Never call os.Exit in main (E109, it skips defers); ret <code> instead.
• Lambdas capture by value and must not declare a return type.
• &: marks a by-reference parameter.
• Built-in str methods are only: len concat substr find/search/indexOf trim lower upper repeat split to_int to_float. Everything else is in str.
• Vector {} as Vector<str>, v.get(i) to read an element, v.ref(i) for its address.
• enum E: A, B, C end - on one line the comma between members is required (member names can contain spaces); one member per line also works.

Traps that fail silently

• Check the compiler version with salam version. There is no --version flag; salam --version fails with unknown command '--version'.
• salam js stores i64/u64/size/usize as JS numbers: 64-bit math is exact up to 2^53, but larger results or intermediates are rounded.
• Source files are keyed by filename, not package: two files named io.salam in one program, or your own shell.salam next to import os.shell, are rejected with "package name ... is claimed by two different files". Keep every filename unique.
• switch falls through like C: an arm without break (or ret) runs the next arm too, including else:.
• A side-effect-free endless loop can be deleted by clang on the C backend, so the program segfaults instead of spinning; give a busy-wait a real effect.

Multilingual source

Keywords exist in both languages (salam_keywords returns the table). Declarations carry aliases:

@en "Trim"
@fa "پیرایش"
pub func Trim(s: str): str: ret s.trim() end

The language is detected from the keywords; --lang=fa forces Persian.

Persian source

Persian Salam has the same grammar and rules with Persian spellings. The entry function is ریشه, blocks end with پایان, and ، works as a comma. The most used words:

English	Persian	English	Persian
func / ret	تابع / برگشت	if / else	اگر / وگرنه
until (while)	تا	repeat ... to ... in	تکرار ... تا ... در
each / by	هر	match / switch	همخوان / ترابرد
mut / const	ناپایا / پایا	struct / enum	ساختار / جداشمار
pub / this	همگانی / این	as	برگردان
import / include	واردسازی / فراخوانی	println / print	سرچاپ / چاپ
and / or / not	و / یا / وارونه	true / false / null	درست / نادرست / پوچ
int / f64 / str / bool	صحیح / اعشار۶۴ / رشته / منطقی	Vector / HashMap	وکتور / نگاشت

Persian-only traps: enum patterns in همخوان are bare member names; ترابرد labels each end with پایان; و is reserved; اعشار is f32; the decimal point is . not ٫; std functions must use their Persian @fa names (an English name is an error in a Persian file); spawn, join, dyn, len and sizeof stay English.

The root SKILL.md Part II has the complete tables, and the Persian course at https://www.salamlang.ir/learn/ teaches the whole language with runnable examples; point Persian-speaking users there.

Full reference: docs/ai/AGENTS.md, or the salam://guide/agents.md resource.