Soplang 3 Language Reference

This reference targets Soplang 3.6.0. Prefer the canonical names in new programs; supported earlier spellings are listed under Compatibility spellings.

This page covers the core syntax and collection API. The full language reference also covers the 3.6 file, network, task, web, and data APIs.

The terminology review records current names, source evidence, and naming decisions. This reference uses implemented canonical spellings; compatibility names are listed below. The collection design record explains shared operation contracts.

Variable Declaration Keywords

Control Flow Keywords

kale is contextual. After an haddii branch, kale (condition) { ... } adds another conditional branch, while kale { ... } is the fallback. Inside dooro, kale { ... } supplies the default case. Existing names such as hawl kale(x) and calls such as kale(1) remain valid; a conditional branch header must be followed by {.

abn da = 21
haddii (da < 18) {
  qor("Ilmo")
} kale (da < 60) {
  qor("Qof weyn")
} kale {
  qor("Waayeel")
}

Function Keywords

Special Values

maran is the canonical null literal. null remains accepted as a compatibility spelling. An empty string, list, or object is a value of its own type, distinct from maran.

Data Types

abn uses signed 64-bit integers. jajab uses 64-bit binary floating-point values; it does not provide exact decimal arithmetic. qoraal is a string, teed is a mutable list, and walax stores string keys and values.

door, madoor, and abn are Soplang short identifiers. The terminology review relates them to doorsoome, madoorsoome, and abyoone, respectively; these explanations do not establish a historical abbreviation or SLS approval.

Operators

Note: Soplang supports the use of comparison operators directly in expressions without requiring additional parentheses. For example, door x = a > b is valid syntax to store the result of a comparison in a variable.

Built-in Functions

daji() rounds toward negative infinity and kor() toward positive infinity. duub() rounds to the nearest integer, with halfway values rounded away from zero. xidid() computes only a square root, not an arbitrary root.

xul() returns a floating-point number in [0, 1). xul(a, b) returns a floating-point number in [a, b). xul(teed) returns one item and reports an error for an empty list.

Note: abn, qoraal, bool, teed, and walax are used both as static type keywords (see Variable Declaration Keywords / Data Types above) and as built-in conversion/constructor functions here. The meaning depends on context: e.g. abn age = 25 declares a typed variable, while abn("5") converts a string to a number.

baaxad (Range)

baaxad() is a built-in function that creates a list of integers.

Unlike a lazy range iterator, it creates a list containing all the requested integers. The stop bound is excluded.

Usage:

// baaxad(stop): from 0 through stop - 1
qor(baaxad(5))  // [0, 1, 2, 3, 4]

// baaxad(start, stop): from start through stop - 1
qor(baaxad(2, 6))  // [2, 3, 4, 5]

// baaxad(start, stop, step): stop is excluded; increment by step
qor(baaxad(1, 10, 2))  // [1, 3, 5, 7, 9]

baaxad accepts integers only. A zero step reports an error that can be caught with tijaabi and qabo.

Shared collection operations

Lists and objects share dherer, leeyahay, hel, dhig, saar, nadiifi, and nuqul where applicable. Strings share dherer, leeyahay, and hel; strings remain immutable.

• hel(position, default?) reads a list item or Unicode character; hel(key, default?) reads an object value. Missing entries return the supplied default or maran. A present maran value is returned unchanged. Defaults are evaluated normally even when an entry exists.
• List and string positions must be integers and may be negative. Object keys must be strings. Invalid argument types report catchable errors.
• dhig(index, value) replaces an existing list item; dhig(key, value) inserts or replaces an object entry. Both mutate and return the receiver. An invalid list position reports an error before mutation; use geli for insertion.
• List saar() removes the last item; saar(index) removes an indexed item. Both return the removed value and reject empty or out-of-range removals. Object saar(key) returns the removed value or maran for a missing key.
• nadiifi() mutates and returns the receiver. nuqul() returns a shallow copy.

door tirooyin = [10, 20, 30]
door qof = { magac: "Ayaan", da: 25 }
qor(tirooyin.hel(-1))
qor(qof.dherer())
tirooyin.dhig(0, 15)
qof.dhig("da", 26)
qor(tirooyin.saar())
qor(qof.saar("da"))

Slicing, endpoints, counting, and search

Lists and strings accept jar(), jar(start), or jar(start, end). Bounds must be integers. The default start is zero and the default end is the length; negative bounds count from the end. Bounds are clamped to the collection. The start is included and the end excluded. Equal or reversed normalized bounds produce an empty result. Slicing leaves the receiver unchanged; list slices are shallow copies. String positions count Unicode characters.

hore()/dambe() return the first/last item or character, or maran when empty. List tiri(value) counts matching values using the same equality rules as list membership and search, including structural collection equality and distinct integer/float values. String tiri(sub) counts non-overlapping matches and rejects an empty substring.

Search has one compatibility exception: missing list raadi/muuji results are maran, while string raadi/raadi_dambe results are -1. A successful search returns an integer position, including zero. Test misses explicitly rather than relying on the truthiness of a search result.

List Methods

midee(teed) returns a concatenated copy without mutating either input. geli(item) always appends one item, including a nested list. nuqul() and jar() also return new lists. saar() and saar(index) return the removed value. Methods that otherwise mutate a list return the original list after changing it. Nested lists and objects remain shared when copied.

hore() and dambe() return the first and last list items without modifying the list. Strings use the same names for Unicode characters. Both return maran for an empty receiver. Objects have no built-in positional first/last methods.

raadi(item) returns the first matching index or maran when no item matches. ururi(func, bilow) is a general left fold: its callback receives the accumulated value and the next item. It can multiply values, construct text, or perform other accumulation; its behavior is not restricted to summation.

Map, filter, fold, every, and some validate callbacks even on empty lists. Each iterates a shallow snapshot, allowing callbacks to modify the original list without changing the remaining iteration sequence. Callback errors stop the operation and propagate to qabo. dhammaan and qaar stop at the first decisive result; on an empty list they return run and been, respectively.

Object Methods

Objects also support computed bracket access: obj["name"] and obj["name"] = "Ali". Object nuqul() is shallow: nested lists and objects remain shared. tir(key) returns the object, whereas saar(key) returns the removed value or maran.

Object key, value, and pair lists follow sorted-key order. midee returns a new shallow object; the right input wins overlapping keys. Neither input is mutated.

String Methods

String positions and bracket indexes count characters rather than UTF-8 bytes. jar() and bracket indexing accept negative positions from the end. Missing indexes return maran; raadi() returns -1 when it finds no match. Calls with the wrong number of arguments report an error that can be caught with tijaabi and qabo.

weynee (Uppercase)

Usage:

door q = "soplang"
door natiijo = q.weynee()
qor(natiijo)  // SOPLANG

yaree (Lowercase)

Usage:

door q = "SOPLANG"
door natiijo = q.yaree()
qor(natiijo)  // soplang

masax (Trim Whitespace)

Usage:

door q = "  soplang  "
door natiijo = q.masax()
qor(natiijo)  // soplang

raadi (Find Substring)

Usage:

door q = "soplang programming"
door natiijo = q.raadi("pro")
qor(natiijo)  // 8

beddel (Replace All)

Usage:

door q = "abaaba"
door natiijo = q.beddel("a", "x", maran)
qor(natiijo)  // xbxxbx

masax() trims both ends; masax("hore") trims only leading whitespace and masax("dambe") only trailing whitespace. raadi(sub) and raadi(sub, "hore") search from the beginning; raadi(sub, "dambe") returns the last match. Unsupported direction values report catchable errors.

beddel(old, new) replaces the first occurrence. A third nonnegative integer limits replacements; zero leaves the text unchanged. Passing maran as the third argument replaces all occurrences. Empty search text matches character boundaries. xiriiri(list) joins the string representations of values, including non-string values. weynee and yaree use Unicode case conversion. kuceli requires a nonnegative integer count and is accepted after a dot without changing the numeric loop syntax.

Object-Oriented Programming (OOP)

Class example:

qaab Xayawaan {
  hawl cod() {
      celi "xayawaan"
  }
}

qaab Bisad dhaxal Xayawaan {
  hawl dhis(magac) {
      nafta.magac = magac
  }
  hawl salaam() {
      qor("Salaan, " + nafta.magac)
  }
}

door bisad = cusub Bisad("Mia")
Bisad b = cusub Bisad("Mia")
bisad.salaam()
qor(bisad.magac)

Notes:

• Class bodies may contain only hawl (method) definitions.
• nafta is injected automatically as the first parameter of every class method.
• Instance fields are stored as object properties; read them with obj.field.
• Method lookup walks the inheritance chain (child overrides parent).

Modules and error handling

Import example:

hawl laba() { celi 2 }
hawl afar() { celi 4 }

keen "_math_lib.sop"
qor(laba() + afar())   // 6

Imported files are resolved relative to the current file's directory. Top-level definitions (functions, variables, classes) from the imported file become available in the importing program.

Try/catch example:

tijaabi {
  qor(1 / 0)
} qabo (khalad) {
  qor("Qabtay: " + khalad)
}

Runtime errors inside the tijaabi block are caught; the first qabo variable receives the message. An optional second variable receives a structured error. tuur raises an error, and dhammee runs on exit. See error handling.

Compatibility spellings

tijaabi is contextual: it starts a try block only before {. Existing variables, functions, and properties named tijaabi remain valid. qabo is unchanged.

Automatic construction searches the nearest class first, preferring its dhis over its dhaw, then walks to its parent. Explicit constructor calls, including waalid.dhis() and waalid.dhaw(), prefer the requested spelling in each class and fall back to the other spelling before moving to the next ancestor. If a class defines both, both methods remain explicitly callable.

Legacy object tir(key) remains supported and returns the receiver; it is not a direct alias of saar(key), which returns the removed value. Existing kudar overloads also preserve their mutation and copying behavior.

List kudar(value) retains its original type-dependent behavior: scalar values append in place, while a list argument produces a concatenated copy. Prefer geli(value) for adding exactly one item, including a nested list, and midee for combining collections.

Global updates

Functions, methods, and callbacks share the current value of a global variable with top-level code. Global variables take precedence over built-in names, matching local shadowing. Replacing a scalar, list, object, or callable is visible on the next read. Function parameters and local declarations still shadow globals; closure captures of enclosing local variables retain their existing snapshot semantics.

Top-level numeric loop indexes are published to globals and can be read or updated by functions during the loop. The increment uses the current index, including any update from the body. The final index remains available after the loop; jooji preserves the index at the break.

Typed global writes inside functions enforce the same type and class checks as top-level writes. Rejected assignments preserve the previous global value. An accepted integral float is converted to abn for an integer annotation, and an accepted integer is converted to jajab for a floating-point annotation, keeping the representation consistent with native arithmetic. Fractional floats are rejected for abn annotations; use abn(value) for explicit truncation.