Built-ins

Name Description Signature
.s Print the stack at the current location. (--)
.b Print paths to all known binaries. (--)
.def Print available definitions at the current location. (--)
.env Write all environment variables to stderr in sorted order. (--)
dup Duplicate the top stack item. (a -- a a)
swap Swap the top two stack items. (a b -- b a)
drop Drop the top stack item. (a -- )
over Copy the second element to the top of the stack. (a b -- a b a)
pick Copy the nth element to the top of the stack. Example: (a b c int pick -- a b c [a | b | c]). (... int -- ...)
rot Rotate the top three items. (a b c -- b c a)
-rot Rotate the top three items in the opposite direction. (a b c -- c a b)
nip Remove the second item. (a b -- b)
w Write a string to stdout. (str -- )
wl Write a string to stdout and add a newline. (str -- )
we Write a string to stderr. (str -- )
wle Write a string to stderr and add a newline. (str -- )
len Return the length of a string or list. ([a] -- int), (str -- int)
args Push the argument list (without argv[0]) onto the stack. (-- [str])
glob Run filepath.Glob against the string or literal on the stack and return the matches as a list. (str -- [str])
/ Divide numbers or join paths. (numeric numeric -- numeric), (path path -- path)
x Interpret or execute a quotation. (quote -- )
toFloat Convert a numeric value to a float. (numeric -- Maybe[float])
toInt Convert a numeric value to an int. (numeric -- Maybe[int])
exit Exit the current script with the provided exit code. (int -- )
read Read a line from stdin. Leaves the line and a success flag. (-- str bool)
stdin Read stdin into a string. (-- str)
:: Read stdin and split into lines (shorthand for stdin lines). (-- [str])
foldl Left fold a list with an initial value and quotation. (quote initial list -- result)
wt Whitespace table; split stdin by lines and whitespace. (-- [[str]])
tt Tab table; split stdin by lines and tabs. (-- [[str]])
ttFile Tab table from a file; split file contents by lines and tabs. (str -- [[str]])
uw Shorthand for unlines w. ([str] -- )
tuw Shorthand for (tjoin) map uw. ([[str]] -- )
runtime Get the current OS runtime (GOOS). (-- str)
hostname Get the current hostname, or unknown on failure. (-- str)
parseCsv Parse CSV input (path or string) into a list of rows. (path|str -- [[str]])
parseJson Parse JSON input (path or string) into mshell objects. (path|str -- list|dict|numeric|str|bool)
seq Generate a list of integers starting from 0 (exclusive end). (int -- [int])
binPaths List every known executable and its resolved path. (-- [[str]])
versionSortCmp Comparison function for version-aware sorting. (str str -- int)
urlEncode URL encode a string or dictionary of parameters. (str|dict -- str)
type Return the type name of the top stack item. (a -- str)
sleep Sleep a float number of seconds. (numeric -- )

File and Directory

Name Description Signature
toPath Convert a string to a path. (str -- path)
absPath Convert a string or path to an absolute path. (str|path -- path)
isDir Test whether a path is a directory. (path -- bool)
isFile Test whether a path is a file. (path -- bool)
hardLink Create a hard link. (existingSourcePath newTargetPath -- )
tempFile Create a temporary file and push its path. (-- str)
tempDir Return the OS-specific temporary directory via os.TempDir (for example, $TMPDIR on Unix or %TMP% on Windows). (-- str)
rm Remove a file; fails on IO errors. (str -- )
rmf Remove a file; ignore IO errors. (str -- )
cp Copy a file or directory. (str:source str:dest -- )
mv Move a file or directory. (str:source str:dest -- )
readFile Read a file into a string. (str -- str)
readFileBytes Read a file into binary data. (str -- binary)
readTsvFile Read a TSV file into a list of rows. (str -- [[str]])
cd Change the current working directory. (str -- )
pwd Return the current working directory. (-- str)
writeFile Write a UTF-8 string to a file (overwrites existing). (str content str file -- )
appendFile Append a UTF-8 string to a file. (str content str file -- )
fileSize Return the file size in bytes as a Maybe. (str -- Maybe[int])
lsDir List all items in a directory with full paths. (str -- [str])
sha256sum Compute the SHA256 checksum of a file. (path -- str)
md5 Compute the MD5 checksum of a file or string. (path|str -- str)
files List files in the current directory (non-recursive). (str -- [str])
dirs List directories in the current directory (non-recursive). (str -- [str])
isCmd Check whether a command can be found in PATH. (str -- bool)
removeWindowsVolumePrefix Remove the volume prefix from a Windows path. (str -- str)

Math

Name Description Signature
abs Absolute value. (numeric -- numeric)
inc Increment an integer. (int -- int)
max2 Maximum of two values. (numeric numeric -- numeric)
max Maximum value of a list. ([numeric] -- numeric)
transpose Transpose a list of lists. ([[a]] -- [[a]])
min2 Minimum of two values. (numeric numeric -- numeric)
min Minimum value of a list. ([numeric] -- numeric)
mod Remainder after division. (numeric numeric -- numeric)
round Round to the nearest integer (half away from zero). (numeric -- int)

Strings

Name Description Signature
str Convert a value to its string representation. (a -- str)
findReplace Find and replace substrings. (str str str -- str)
lines Split a string into a list of lines. (str -- [str])
split Split a string by the provided delimiter. (str str -- [str])
wsplit Split a string into fields by runs of whitespace. (str -- [str])
join Join a list of strings with a delimiter. ([str] str -- str)
in Check whether a substring exists. (str str -- bool)
index Index of the first occurrence of a substring. Returns Maybe[int]. (str str -- Maybe[int])
tab Push a tab character. (-- str)
tsplit Split a string into fields by tabs. (str -- [str])
trim Trim whitespace from both ends of a string. (str -- str)
trimStart Trim whitespace from the start of a string. (str -- str)
trimEnd Trim whitespace from the end of a string. (str -- str)
startsWith Check whether a string starts with a prefix. (str str -- bool)
endsWith Check whether a string ends with a suffix. (str str -- bool)
lower Convert a string to lowercase. (str -- str)
upper Convert a string to uppercase. (str -- str)
toFixed Convert a number to a fixed-width decimal string. (numeric int -- str)
countSubStr Count occurrences of a substring. (str str -- int)
take Take the first n characters from a string. (str int -- str)
utf8Str Decode UTF-8 bytes into a string. (binary -- str)
utf8Bytes Encode a string as UTF-8 bytes. (str -- binary)

Lists

Name Description Signature
append Append an item to a list. ([a] a -- [a])
map Map a quotation over a list. ([a] (a -- b) -- [b])
each Execute a quotation for each element. ([a] (a -- ) -- )
eachWhile Iterate until a quotation leaves false on the stack. ([a] (a -- bool) -- )
del Delete an element from a list. (list index -- list), (index list -- list)
extend Extend a list with the contents of another list in place. (list list -- list)
insert Insert an element into a list at an index. (list element index -- list)
setAt Replace an element at an index. (list element index -- list)
nth Return the nth element (0-based). ([a] int -- a)
reverse Reverse a list. (list -- list)
sum Sum numeric values in a list. ([numeric] -- numeric)
filter Filter a list by a predicate quotation. ([a] (a -- bool) -- [a])
any Return true if any element satisfies the predicate. ([a] (a -- bool) -- bool)
all Return true if all elements satisfy the predicate. ([a] (a -- bool) -- bool)
skip Skip the first n elements. (list int -- list)
sort Sort a list by string conversion using sort.Strings. (list -- list)
sortV Version-sort a list (like sort -V). (list -- list)
uniq Remove duplicate elements. ([a] -- [a])
zip Zip two lists using a combining quotation. Result length matches the shorter input. ([a] [b] (a b -- c) -- [c])
concat Flatten a list of lists one level. ([[a]] -- [a])
cartesian Cartesian product of two lists. ([a] [a] -- [[a]])
groupBy Group items into a dictionary using a key quotation. The quotation receives each item and must return a string key; the resulting dictionary maps each key to the list of items that produced it. ([a] (a -- str) -- dict)
listToDict Transform a list into a dictionary using key and value selectors. ([a] (a -- b) (a -- c) -- {b: c})
take Return the first n elements of a list. ([a] int -- [a])
pop Pop the final element off a list. Returns none when the list is empty and leaves the (possibly shortened) list on the stack. ([a] -- [a] Maybe[a])
sortByCmp Sort a list using a custom comparison quotation that returns -1, 0, or 1. ([a] (a a -- int) -- [a])

Dictionaries

Name Description Signature
get Get a value by key. Returns none when missing. (dict str -- Maybe[a])
getDef Get a value by key, returning a default when missing. (dict str a -- a)
set Set a dictionary value by key. (dict str a -- dict)
setd Set a dictionary value by key and drop the dictionary. (dict str a -- )
keys Return sorted dictionary keys. (dict -- [str])
values Return dictionary values sorted by key. (dict -- [str])
keyValues Return key/value pairs as a list of two-element lists. (dict -- [[str a]])
in Test whether a key exists. (dict str -- bool)

Dates

Name Description Signature
toDt Parse a string into a date/time (Maybe result). (str -- Maybe[date])
date Push the current local date/time. (-- date)
year Get the year component. (date -- int)
month Get the month (1-12). (date -- int)
day Get the day of the month (1-31). (date -- int)
hour Get the hour (0-23). (date -- int)
minute Get the minute (0-59). (date -- int)
dateFmt Format a date using a Go layout string (reference). (date str -- str)
isoDateFmt Format a date as ISO 8601 (YYYY-MM-DD). (date -- str)
isWeekend Return true when the date falls on a weekend. (date -- bool)
isWeekday Return true when the date falls on a weekday. (date -- bool)
dow Return the day-of-week (0=Sunday). (date -- int)
toUnixTime Convert a date to Unix time. (date -- int)
fromUnixTime Create a date from a Unix time integer. (int -- date)
addDays Add days to a date. (date numeric -- date)
utcToCst Convert a UTC datetime to US Central Time. (date -- date)

Regular Expressions

All regular expression functions use the Go regular expression syntax. See Regexp.Expand for replacement details.

Name Description Signature
reMatch Test whether a string matches a regular expression. (str re -- bool)
reFindAll Return all matches for a regular expression. (str re -- [[str]])
reFindAllIndex Return start/end offsets (including capture groups) for all matches. (str re -- [[int]])
reReplace Replace all matches with the provided replacement string. (str:orig re str:replacement -- str)

Paths

Name Description Signature
dirname Return the directory portion of a path. (path -- path)
basename Return the base name (file name) of a path. (path -- path)
ext Return the extension (including the dot). (path -- path)
stem Return the path without the final extension. (path -- path)

Shell Utilities

Name Description Signature
mkdir Create a directory. (str -- )
mkdirp Create a directory and any required parents. (str -- )

Maybe

Name Description Signature
isNone Check whether a Maybe value is none. (Maybe[a] -- bool)
just Wrap a value in a Maybe. (a -- Maybe[a])
none Create a none value. (-- Maybe[a])
? Unwrap a Maybe, failing if it is none. (Maybe[a] -- a)
maybe Unwrap a Maybe, providing a default value. (Maybe[a] a -- a)
bind Monadic bind for chaining Maybe-returning functions. (Maybe[a] (a -- Maybe[b]) -- Maybe[b])
map Map a function over a Maybe value. (Maybe[a] (a -- b) -- Maybe[b])

HTML

Name Description Signature
parseHtml Parse HTML from a string or file into node dictionaries with tag, attr, children, and text. (str|path -- dict)
htmlDescendents Return all descendant nodes (including the root) from a parsed HTML node. (dict -- [dict])
findByTag Find all nodes with the given tag name. (dict str -- [dict])

HTTP Requests

Name Description Signature
httpGet Make an HTTP GET request.

Request dictionary keys:

  • url: full URL including query parameters.
  • headers: dictionary of request headers.

The result is a Maybe; it is none when the request fails entirely (for example, a timeout). When successful it wraps a response dictionary with:

  • status: integer status code.
  • reason: status line (for example "200 OK").
  • headers: dictionary of response headers.
  • body: binary response body.
 (dict -- Maybe[dict])
httpPost Make an HTTP POST request. Accepts the same request dictionary keys as httpGet, optionally a body string, and returns none on transport failures. (dict -- Maybe[dict])