stdlib.md

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.