Standard library reference

Every function Baa ships with. Module names are sheep-themed; the functions inside them are not: an API you have to remember at 2am is no place for a joke.

The prelude, available without an import
Methods, available on values themselves
wool: Text: formatting, casing, wrapping, bytes.
flock: Collections: grouping, chunking, zipping, building maps.
ram: Arithmetic: rounding, integer division, statistics, constants.
meadow: Time and chance: clocks, calendars, seeded randomness.
pasture: Files and paths: reading, writing, listing, joining.
shepherd: The outside world: arguments, environment, stdin, subprocesses.
lamb: Data: JSON encoding and decoding.
gate: The web: reading a request and writing a reply, over CGI.
barn: Native windows: controls, layout and events. Needs the native runtime.

The prelude#

These names are in scope in every file, with no import. A local declaration may shadow any of them.

Function	Arguments	Description
`len`	1	Length of a string, array, map or range.
`type_of`	1	Type name: "nil", "bool", "number", "string", "array", "map", "range", "function" or "module".
`to_string`	1	Text form of any value.
`inspect`	1	Developer-facing form of any value, with quoted strings.
`to_number`	1	Parse a value as a number, or nil when it is not numeric.
`clone`	1	Deep copy of an array or map. Other values are returned unchanged.
`assert`	1-2	Fail the program when a condition is not truthy.
`assert_eq`	2-3	Fail unless two values are equal, showing both when they are not.
`panic`	1	Stop the program immediately with a message.
`exit`	0-1	Exit the program with a status code (default 0).

Methods#

Methods are looked up on the value itself and are ordinary first-class functions: const shout = "baa".upper then shout() works.

On every value#

Method	Arguments	Description
`to_string`	0	Text form of this value.
`inspect`	0	Developer-facing form, with quotes.
`type_of`	0	Name of this value's type.

On `string`#

Method	Arguments	Description
`length`	0	Number of characters.
`is_empty`	0	True when the string has no characters.
`upper`	0	Uppercase copy.
`lower`	0	Lowercase copy.
`trim`	0	Copy without leading or trailing whitespace.
`trim_start`	0	Copy without leading whitespace.
`trim_end`	0	Copy without trailing whitespace.
`contains`	1	True when the string contains a substring.
`starts_with`	1	True when the string starts with a prefix.
`ends_with`	1	True when the string ends with a suffix.
`index_of`	1	First index of a substring, or -1.
`split`	0-1	Split into an array on a separator.
`lines`	0	Split into an array of lines.
`chars`	0	Array of single-character strings.
`replace`	2	Replace the first occurrence.
`replace_all`	2	Replace every occurrence.
`slice`	1-2	Substring from start (inclusive) to end (exclusive).
`repeat`	1	Repeat the string n times.
`pad_start`	1-2	Pad on the left to a target width.
`pad_end`	1-2	Pad on the right to a target width.
`reverse`	0	Reversed copy.
`to_number`	0	Parse as a number, or nil when it isn't one.

On `array`#

Method	Arguments	Description
`length`	0	Number of items.
`is_empty`	0	True when there are no items.
`push`	1+	Append items; returns the array.
`pop`	0	Remove and return the last item, or nil.
`shift`	0	Remove and return the first item, or nil.
`unshift`	1+	Insert items at the front.
`insert`	2	Insert a value at an index.
`remove`	1	Remove the item at an index and return it.
`clear`	0	Remove every item.
`contains`	1	True when a value is present.
`index_of`	1	First index of a value, or -1.
`first`	0	First item, or nil.
`last`	0	Last item, or nil.
`slice`	1-2	Sub-array from start (inclusive) to end (exclusive).
`concat`	1	New array with another array appended.
`join`	0-1	Join items into a string.
`reverse`	0	Reversed copy.
`map`	1	New array with fn applied to each item.
`filter`	1	New array of items where fn is truthy.
`reduce`	2	Fold the array into a single value.
`for_each`	1	Call fn with each item.
`find`	1	First item where fn is truthy, or nil.
`any`	1	True when fn is truthy for any item.
`all`	1	True when fn is truthy for every item.
`count`	0-1	Count items, optionally matching fn.
`sort`	0-1	Sorted copy; pass fn(a, b) for a custom order.
`unique`	0	Copy with duplicates removed, keeping first occurrences.
`flatten`	0	Concatenate nested arrays one level deep.
`sum`	0	Add every item; all items must be numbers.

On `map`#

Method	Arguments	Description
`length`	0	Number of entries.
`is_empty`	0	True when there are no entries.
`get`	1-2	Value for a key, or a fallback (default nil).
`expect`	1	Value for a key; fails when the key is missing.
`set`	2	Insert or replace a key; returns the map.
`has`	1	True when the key is present.
`remove`	1	Remove a key; returns the removed value or nil.
`clear`	0	Remove every entry.
`keys`	0	Array of keys, in insertion order.
`values`	0	Array of values, in insertion order.
`entries`	0	Array of [key, value] pairs.
`merge`	1	New map with another map's entries layered on top.
`for_each`	1	Call fn with each key and value.

On `range`#

Method	Arguments	Description
`length`	0	How many values the range yields.
`start`	0	First value.
`end`	0	Bound value.
`is_empty`	0	True when the range yields nothing.
`contains`	1	True when a number falls inside the range.
`to_array`	0	Materialise the range as an array.

On `number`#

Method	Arguments	Description
`abs`	0	Absolute value.
`floor`	0	Round down.
`ceil`	0	Round up.
`round`	0	Round to the nearest whole number.
`is_whole`	0	True when the number has no fractional part.
`to_fixed`	1	Text with a fixed number of decimal places.
`clamp`	2	Constrain between a low and high bound.

`wool`#

Text: formatting, casing, wrapping, bytes.

baa

import wool

Function	Arguments	Description
`wool.join`	1–2	Join an array of values into a string.
`wool.concat`	0+	Concatenate every argument as text.
`wool.format`	1+	Fill `%s` placeholders in order: `wool.format("%s of %s", 3, 10)`. `%%` is a literal percent.
`wool.repeat`	2	Repeat a string n times.
`wool.title_case`	1	Capitalise the first letter of each word.
`wool.snake_case`	1	Convert text to snake_case.
`wool.camel_case`	1	Convert text to camelCase.
`wool.kebab_case`	1	Convert text to kebab-case.
`wool.wrap`	2	Wrap text to a maximum line width, breaking on spaces.
`wool.center`	2–3	Centre text within a width.
`wool.escape_html`	1	Escape text so it is safe inside HTML or an attribute.
`wool.safe_url`	1	A URL if its scheme is safe to link to, otherwise nil.
`wool.percent_encode`	1	Percent-encode text for use in a URL.
`wool.percent_decode`	1	Decode percent-encoded text, or nil when it is malformed.
`wool.matches`	2–3	True when a pattern matches anywhere in the text.
`wool.find`	2–3	First match as a map of match, start, end and groups, or nil.
`wool.find_all`	2–3	Every non-overlapping match, as an array of maps.
`wool.substitute`	3–4	Replace every match. `$1` in the replacement is a group.
`wool.split_on`	2–3	Split text on every match of a pattern.
`wool.is_blank`	1	True when a string is empty or only whitespace.
`wool.to_bytes`	1	UTF-8 byte values of a string.
`wool.from_bytes`	1	Build a string from an array of UTF-8 byte values.
`wool.inspect`	1	Developer-facing text for any value.

`flock`#

Collections: grouping, chunking, zipping, building maps.

baa

import flock

Function	Arguments	Description
`flock.of`	0+	Build an array from the arguments.
`flock.repeat`	2	An array with the same value repeated n times.
`flock.zip`	2	Pair up two arrays, stopping at the shorter one.
`flock.chunk`	2	Split an array into chunks of a fixed size.
`flock.group_by`	2	Group items into a map keyed by fn(item).
`flock.partition`	2	Split into [matching, rest] using a predicate.
`flock.sort_by`	2	Sorted copy, ordered by the key fn(item) returns.
`flock.min_by`	2	Item with the smallest fn(item), or nil when empty.
`flock.max_by`	2	Item with the largest fn(item), or nil when empty.
`flock.to_map`	1	Build a map from an array of [key, value] pairs.
`flock.from_keys`	2	Build a map giving every key the same value.
`flock.invert`	1	Swap a map's keys and values.
`flock.range`	1–3	An array of numbers: range(end), range(start, end[, step]).
`flock.to_array`	1	Turn a range, string or map into an array.
`flock.union`	2	Everything in either array, first-seen order, no repeats.
`flock.intersect`	2	Everything in both arrays, in the first array's order.
`flock.difference`	2	Everything in the first array and not the second.
`flock.is_subset`	2	True when every item of the first array is in the second.

`ram`#

Arithmetic: rounding, integer division, statistics, constants.

baa

import ram

Constant	Value
`ram.PI`	`3.141592653589793`
`ram.E`	`2.718281828459045`
`ram.TAU`	`6.283185307179586`
`ram.INF`	`inf`
`ram.NAN`	`nan`
`ram.EPSILON`	`2.220446049250313e-16`
`ram.MAX_SAFE_WHOLE`	`9007199254740991`

Function	Arguments	Description
`ram.abs`	1	Absolute value.
`ram.sign`	1	-1, 0 or 1.
`ram.floor`	1	Round down.
`ram.ceil`	1	Round up.
`ram.trunc`	1	Drop the fractional part.
`ram.round`	1–2	Round to the nearest whole number, or to n decimal places.
`ram.sqrt`	1	Square root.
`ram.pow`	2	Raise to a power.
`ram.exp`	1	e raised to a power.
`ram.log`	1–2	Natural logarithm, or logarithm in a given base.
`ram.sin`	1	Sine, in radians.
`ram.cos`	1	Cosine, in radians.
`ram.tan`	1	Tangent, in radians.
`ram.atan2`	2	Angle of the vector (x, y), in radians.
`ram.hypot`	2	Length of the vector (x, y).
`ram.min`	1+	Smallest of the arguments.
`ram.max`	1+	Largest of the arguments.
`ram.clamp`	3	Constrain a value between low and high.
`ram.lerp`	3	Linear interpolation between a and b.
`ram.idiv`	2	Integer division, rounding toward negative infinity.
`ram.modulo`	2	Remainder that always takes the sign of the divisor.
`ram.gcd`	2	Greatest common divisor of two whole numbers.
`ram.is_nan`	1	True when the value is not a number.
`ram.is_finite`	1	True when the value is a finite number.
`ram.is_whole`	1	True when the value is a whole number.
`ram.sum`	1	Add every number in an array.
`ram.mean`	1	Arithmetic mean of an array, or nil when empty.
`ram.median`	1	Median of an array, or nil when empty.
`ram.to_binary`	1	Binary text for a whole number.
`ram.to_hex`	1	Hexadecimal text for a whole number.
`ram.parse`	1–2	Parse text as a number in a given base (default 10).

`meadow`#

Time and chance: clocks, calendars, seeded randomness.

baa

import meadow

Function	Arguments	Description
`meadow.now`	0	Milliseconds since 1970-01-01 UTC.
`meadow.clock`	0	High-resolution milliseconds, for measuring durations.
`meadow.parts`	0–2	Break a timestamp into calendar parts (UTC, or at an offset).
`meadow.format`	1–2	Format a timestamp as YYYY-MM-DD or with a pattern.
`meadow.iso`	0–2	ISO-8601 text for a timestamp (default: now, UTC).
`meadow.duration`	1	Break a length of time in milliseconds into parts.
`meadow.format_duration`	1	A length of time as `1d 2h 3m 4s`.
`meadow.parse_iso`	1	Parse ISO-8601 text into a timestamp, or nil.
`meadow.random`	0	A random number in [0, 1).
`meadow.random_int`	2	A random whole number between low and high, inclusive.
`meadow.pick`	1	A random item from an array or range, or nil when empty.
`meadow.shuffle`	1	A shuffled copy of an array.
`meadow.sample`	2	n random items from an array, without repeats.

Time zones. Baa carries no zone database, so there is nothing to name a zone with. What it has instead is fixed offsets: meadow.parts(millis, 60) and meadow.iso(millis, 60) read an instant as a clock one hour ahead of UTC would, and the ISO text ends in +01:00 rather than Z. Offsets are whole minutes between -720 and +840, which is the range zones actually use; anything else is BAA311.

This is deliberately not Europe/London: an offset is a fact about an instant, while a zone name is a rule that changes twice a year and needs a database that ships updates. Guessing would be worse than not offering it.

Durations. meadow.duration(millis) breaks a length of time into days, hours, minutes, seconds and milliseconds, with negative saying which way it runs. meadow.format_duration(millis) writes the same thing as 1d 2h 3m 4s, leaving out the units above the largest one that applies.

`pasture`#

Files and paths: reading, writing, listing, joining.

baa

import pasture

Constant	Value
`pasture.SEPARATOR`	the host path separator: `\` on Windows, `/` elsewhere

Function	Arguments	Description
`pasture.read`	1	Read a whole text file as a string.
`pasture.read_lines`	1	Read a text file and split it into lines.
`pasture.write`	2	Write text to a file, replacing anything already there.
`pasture.append`	2	Append text to a file, creating it when missing.
`pasture.write_lines`	2	Write an array of lines to a file.
`pasture.exists`	1	True when a file or directory exists.
`pasture.list`	1	Names inside a directory.
`pasture.make_dir`	1	Create a directory, including any missing parents.
`pasture.info`	1	Size, kind and modification time of a path, or nil.
`pasture.join`	1+	Join path segments with the platform separator.
`pasture.resolve`	1+	Turn path segments into one absolute path.
`pasture.dir_name`	1	The directory part of a path.
`pasture.base_name`	1–2	The final component of a path, optionally without a suffix.
`pasture.extension`	1	The file extension, including the dot.
`pasture.normalise`	1	Collapse `.` and `..` segments.
`pasture.relative_to`	2	The path from one location to another.
`pasture.is_absolute`	1	True when a path is absolute.
`pasture.cwd`	0	The current working directory.
`pasture.walk`	1–2	Every file under a directory, recursively, sorted.
`pasture.glob`	2	Files under a directory whose path matches a glob pattern.
`pasture.matches`	2	True when a path matches a glob pattern.

Glob patterns. pasture.glob and pasture.matches understand three things:

Pattern	Matches
`?`	one character, never a separator
`*`	any run of characters, never crossing a separator
`**`	any run of characters, separators included

Nothing else is special: [, { and the rest match themselves. A pattern that means one thing in bash and another in zsh is worse than one that means itself, and the small set covers what a build script asks for.

Matching is over whole paths, not suffixes, and pasture.glob matches against paths relative to the directory it was given: *.baa matches main.baa and not src/main.baa, and **/*.baa matches both. Either separator works in a pattern, so one pattern reads the same on Windows and elsewhere.

Walking. pasture.walk returns files and not directories, depth-first through names sorted at each level, and stops at 64 levels deep so that a link pointing back up its own tree cannot run forever.

`shepherd`#

The outside world: arguments, environment, stdin, subprocesses.

baa

import shepherd

Constant	Value
`shepherd.PLATFORM`	the host platform: `win32`, `linux`, `darwin`, ...
`shepherd.ARCH`	the host architecture: `x64`, `arm64`, ...

Function	Arguments	Description
`shepherd.args`	0	Arguments passed to the Baa program after `--`.
`shepherd.env`	1–2	An environment variable, or a fallback when it is unset.
`shepherd.env_all`	0	Every environment variable as a map.
`shepherd.write`	1+	Write to stdout without a trailing newline.
`shepherd.write_error`	1+	Write to stderr without a trailing newline.
`shepherd.input`	0–1	Read one line from stdin, or nil at end of input.
`shepherd.read_all`	0	Read all of stdin as a single string.
`shepherd.run`	1–3	Run a program with an explicit argument array. Never uses a shell.
`shepherd.exit`	0–1	Exit with a status code (default 0).

`lamb`#

Data: JSON encoding and decoding.

baa

import lamb

Function	Arguments	Description
`lamb.encode`	1–2	JSON text for a value; pass an indent for pretty output.
`lamb.decode`	1	Parse JSON text into Baa values.
`lamb.try_decode`	1–2	Parse JSON text, or return a fallback (default nil).
`lamb.is_valid`	1	True when a string parses as JSON.

`gate`#

The web: reading a request and writing a reply, over CGI.

baa

import gate

Function	Arguments	Description
`gate.method`	0	The request method, uppercase. Defaults to GET.
`gate.path`	0	The path below the script, or "/".
`gate.query`	0	The query string parsed into a map.
`gate.query_string`	0	The raw, undecoded query string.
`gate.body`	0	The request body as text.
`gate.form`	0	A urlencoded request body parsed into a map.
`gate.header`	1–2	A request header, or a fallback when it is absent.
`gate.headers`	0	Every request header as a map, in Header-Case.
`gate.cookies`	0	The Cookie header parsed into a map.
`gate.status`	1	Set the status code. Must come before the reply starts.
`gate.set_header`	2	Set a response header. Must come before the reply starts.
`gate.text`	1	Reply with plain text.
`gate.html`	1	Reply with HTML, exactly as given. Escape values yourself.
`gate.fill`	1+	Reply with HTML, escaping each value put into a `%s`. The safe way to build a page.
`gate.json`	1	Reply with a value encoded as JSON.
`gate.redirect`	1–2	Reply with a redirect (303 by default).
`gate.escape`	1	Escape a value for HTML. Same as `wool.escape_html`.
`gate.safe_url`	1–2	A URL if its scheme is safe to link to, else a fallback (default "#").
`gate.format`	1+	Build HTML, escaping each value put into a `%s`, without sending it.

`barn`#

Native windows: controls, layout and events. Needs the native runtime.

baa

import barn

Function	Arguments	Description
`barn.window`	0–1	Create a window. Options: title, width, height, padding, spacing.
`barn.row`	1–2	A container that lays its children out left to right.
`barn.column`	1–2	A container that lays its children out top to bottom.
`barn.label`	1–2	Text that cannot be edited.
`barn.button`	1–2	A push button.
`barn.input`	1–2	A single-line text field.
`barn.text_area`	1–2	A multi-line text editor with scrollbars.
`barn.list`	1–2	A list of selectable rows.
`barn.checkbox`	1–2	A checkbox.
`barn.spacer`	1–2	Empty space that takes a share of the layout.
`barn.menu`	2	A menu on the window's menu bar.
`barn.item`	2–3	An entry in a menu. Fires `click`.
`barn.separator`	1	A dividing line in a menu.
`barn.on`	3	Register a handler: "click", "change", "select", "toggle" or "close".
`barn.text`	1	The widget's current text.
`barn.set_text`	2	Replace the widget's text.
`barn.items`	1	A list's rows, as an array of strings.
`barn.set_items`	2	Replace a list's rows.
`barn.selected`	1	The selected row's index, or -1.
`barn.select`	2	Select a row by index.
`barn.checked`	1	Whether a checkbox is ticked.
`barn.set_checked`	2	Tick or untick a checkbox.
`barn.enable`	2	Enable or disable a widget.
`barn.focus`	1	Give a widget keyboard focus.
`barn.title`	2	Set a window's title.
`barn.show`	1	Put a window on screen.
`barn.run`	0	Run the event loop until every window has closed.
`barn.close`	1	Close a window.
`barn.quit`	0	Close every window, ending the event loop.
`barn.alert`	2–3	Show a message box.
`barn.confirm`	2–3	Ask a yes/no question. Returns true for yes.
`barn.open_file`	0–2	Ask for a file to open. Returns a path, or nil if cancelled.
`barn.save_file`	0–2	Ask where to save. Returns a path, or nil if cancelled.
`barn.every`	2	Call a function every n milliseconds. Returns a timer id.
`barn.after`	2	Call a function once, n milliseconds from now. Returns a timer id.
`barn.cancel`	1	Stop a timer, by the id `every` or `after` returned.
`barn.clipboard`	0	The clipboard's text, or nil.
`barn.set_clipboard`	1	Put text on the clipboard.

Missing something? The standard library is deliberately small: see ROADMAP.md for what is planned, and CONTRIBUTING.md for how to add it.

PreviousFAQ NextDiagnostics as JSON

Standard library reference

The prelude#

Methods#

On every value#

On string#

On array#

On map#

On range#

On number#

wool#

flock#

ram#

meadow#

pasture#

shepherd#

lamb#

gate#

barn#