YS Standard Library

YS has over 1000 functions that are always available to your YS programs without needing to explicitly import (use) any libraries. Over 800 of these can be used without a namespace prefix like str/ or math/.

Most of these functions are from the Clojure standard library ⧉, but YS also has the ys::std standard library that provides additional functions.

This document describes the ys::std functions and how to use them. It also links to related functions in the Clojure core library.

Note

In a few cases, the YS standard library replaces some Clojure functions with a version more suited to YS. In those cases, the original Clojure function is still available in the ys::clj namespace.

String functions🔗

blank?(S) — Alias of clojure.string/blank? ⧉

True if string is nil, empty or only whitespace
chomp(S) — Alias of clojure.string/trim-newline ⧉

Remove trailing newlines
chop(S) — Remove last character
ends?(S) — Alias of clojure.string/ends-with? ⧉

True if string ends with suffix
escape(S char-map) — Alias of clojure.string/escape ⧉

Escape special characters in a string
index(S sub) — Alias of clojure.string/index-of ⧉

Find index of substring
join(*X) — Join strings or seqs with ""
join(sep *X) — Join strings or seqs with a separator
joins(*X) — Join strings with " "
lc(S) — Alias of clojure.string/lower-case ⧉

Lowercase a string
lines(S) — Split a string into lines
pretty(X) — Pretty print a value
replace(X) — Alias of clojure.core/replace ⧉
replace(S old) — Like clojure.string/replace ⧉

Replace all occurrences of old with ""
replace(S old new) — Alias of clojure.string/replace ⧉

Replace all occurrences of old with new
replace1(S old new) — Alias of clojure.string/replace-first ⧉

Replace first occurrence of old with new
rindex(S sub) — Alias of clojure.string/last-index-of ⧉

Find last index of substring
split(S) — Like clojure.string/split ⧉

Split on ""
split(S rgx) — Alias of clojure.string/split ⧉

Split a string by a regex
starts?(S) — Alias of clojure.string/starts-with? ⧉

True if string starts with prefix
substr(S off len?) — Substring function with Perl semantics

Offset is 0-based, negative offset counts from end; Optional length is from offset and defaults to end of string; Negative length counts from end of string
text(*S) — Join list of strings with newlines, adding a newline at the end
trim(S) — Alias of clojure.string/trim ⧉

Trim whitespace from both ends
triml(S) — Alias of clojure.string/triml ⧉

Trim whitespace from left end
trimr(S) — Alias of clojure.string/trimr ⧉

Trim whitespace from right end
uc(S) — Alias of clojure.string/upper-case ⧉

Uppercase a string
uc1(S) — Alias of clojure.string/capitalize ⧉

Uppercase the first character
words(S) — Split a string into words (split on whitespace)

Collection functions🔗

diff(C1 C2) — Alias of clojure.data/diff ⧉

Return the difference of two collections
flat(V) — Like clojure.core/flatten ⧉

Only flattens one level
get+(C K) — Get a string, keyword or symbol from a map or sequence
grep(FN C) — Filter a collection by a predicate function
has?(C) — Returns a partial function closed over C
has?(C X) — True if collection has X

Works with strings, maps and sequences
in?(C) — Returns a partial function closed over C
in?(X C) — True if X is in collection

Works with strings, maps and sequences
omap(*X) — Create an ordered map
reverse(C) — Reverse a string, vector or sequence
rng(X Y) — Create a range of numbers or characters, Y is inclusive

If X is greater than Y, the range is descending
.. — Infix rng operator
slice(C *K) — Get a sequence of values from the keys

Math functions🔗

add(*N) — Alias of clojure.core/+ ⧉
sub(*N) — Alias of clojure.core/- ⧉
mul(*N) — Alias of clojure.core/* ⧉
div(*N) — Division function that returns a float if needed
add+(*X) — Polymorphic addition function

Adds numbers, strings, chars, sequences, maps, sets and functions
sub+(*X) — Polymorphic subtraction function

Subtracts numbers, strings, chars, sequences, maps and sets
mul+(*X) — Polymorphic multiplication function

Multiplies numbers, strings and sequences
digits(S) — Convert a string of digits to a sequence of numbers
floor(X) — Alias of CM/floor

Round down to the nearest integer
pow(N *N) — Raise a number to a power
** — Infix pow operator - right associative
sqr(X) — Square a number
cube(X) — Cube a number
sqrt(X) — Square root of a number
sum(nums) — Sum a sequence of numbers

Infix operators🔗

. — For chaining functions (foo.bar.baz())
: — This foo:bar is same as foo.bar()
+ — For add+
- — For sub+
* — For mul+
/ — For div
** — For pow
.. — For rng
== — For eq
!= — For ne
> — For gt
>= — For ge
< — For lt
<= — For le
&& — For and
|| — For or
&&& — For and?
||| — For or?

Chaining short forms🔗

value.# — Short for value.count()
value.$ — Short for value.last()
value.++ — Short for value.inc()
value.-- — Short for value.dec()
value.? — Short for value.truey?()
value.! — Short for value.falsey?()
value.?? — Short for value.boolean()
value.!! — Short for value.not()
value.@ — Short for `value.deref()
value.>>> — Short for value.DBG()

Print value/data to stderr and return the value unchanged

Control functions🔗

call(FN *args) — Call a function or value

Function FN can be a string, symbol or function
die(msg) — Idiomatic error function
each(bindings *body) — Non-lazy clojure.core/for ⧉
eval(S) — Evaluate a string as YS code
exit(rc=0) — Exit the program
if(cond then else) — Functional if used in dot chaining
sleep(secs) — Sleep for a number of seconds
value(X) — Get var value from var, symbol or string

Often used to convert a string to a function.
when+(cond *body) — Like clojure.core/when ⧉

Binds the result of the condition to the _ symbol

Function functions🔗

defn flip(FN) — Flip the arguments of a function

Regex functions🔗

=~ — Infix re-find operator
!~ — Infix re-find complement operator

I/O functions🔗

err(*S) — Print to stderr
out(*S) — Print to stdout

Flushes stdout after printing
pp(X) — Pretty print a value
print(*S) — Print to stdout without newline

Flushes stdout after printing
read(F) — Alias of clojure.core/slurp ⧉

Read a file into a string
say(*S) — Print to stdout with newline
warn(*S) — Print to stderr with newline

Flushes stderr after printing
write(F S) — Alias of clojure.core/spit ⧉

Write a string to a file

Shorter named alias functions🔗

a — Alias of clojure.core/identity ⧉
len — Alias of clojure.core/count ⧉

Quoting functions🔗

q(form) — Alias of clojure.core/quote ⧉
qr(str) — Alias of clojure.core/re-pattern ⧉
qw(symbols) — Turn symbols into a vector of strings

Named function for infix operators🔗

eq — Alias of clojure.core/= ⧉
ne — Alias of clojure.core/not= ⧉
gt — Alias of clojure.core/> ⧉
ge — Alias of clojure.core/>= ⧉
lt — Alias of clojure.core/< ⧉
le — Alias of clojure.core/<= ⧉

Common type conversion functions🔗

to-bool(X) — Convert X to a boolean
to-char(X) — Convert X to a character
to-float(X) — Convert X to a float
to-int(X) — Convert X to an integer
to-keyw(X) — Convert X to a keyword
to-list(X) — Convert X to a list
to-map(X) — Convert X to a map
to-num(X) — Convert X to a number
to-omap(X) — Convert X to an ordered map
to-set(X) — Convert X to a set
to-str(X) — Convert X to a string
to-type(X) — Convert X to a string name of its type:

"atom", "bool", "char", "class", "float", "fun", "int", "keyw", "list", "map", "nil", "num", "rgx", "seq", "set", "str", "sym", "var", "vec"
to-vec(X) — Convert X to a vector

Single character casting functions🔗

B(X) — Convert to a boolean
C(X) — Convert to a character
D(X) — Deref an atom
F(X) — Convert to a float
I(X) — Convert to an integer
K(X) — Convert to a keyword
L(X) — Convert to a list
M(X) — Convert to a map
N(X) — Convert to a number
O(X) — Convert to an ordered map
S(X) — Convert to a set
T(X) — Convert to a type name string
V(X) — Convert to a vector
L+(*X) — Convert to a list
M+(*X) — Convert to a map
O+(*X) — Convert to an ordered map
V+(*X) — Convert to a vector

Alternate truth functions🔗

falsey?(X) — True if X is falsey - 0, nil, false, empty
F?(X) — Short for falsey?
truey?(X) — True if X is not falsey
T?(X) — Short for truey?
or?(X *X) — Return first truey value or nil
and?(X *X) — Return last truey value or nil
||| — or? operator
&&& — and? operator

File system functions🔗

fs-d(path) — True if path is a directory
fs-e(path) — True if path exists
fs-f(path) — True if path is a regular file
fs-l(path) — True if path is a symbolic link
fs-r(path) — True if path is readable
fs-s(path) — True if path is not empty
fs-w(path) — True if path is writable
fs-x(path) — True if path is executable
fs-z(path) — True if path is empty
fs-abs(path) — Get the absolute path
fs-abs?(path) — True if path is absolute
fs-basename(path *ext) — Get the file name of a path, without extension
fs-dirname(path) — Get the directory name of a path
fs-filename(path) — Get the file name of a path
fs-glob(path) — Glob a path
fs-ls(dir) — List a directory
fs-mtime(file) — Get the modification time of a file
fs-rel(path) — Get the relative path
fs-rel?(path) — True if path is relative
fs-which(name) — Find the path of an executable

Date/Time functions🔗

now() — Returns java.time.Instant object

Security functions🔗

md5(S) — Calculate the MD5 hash of a string
sha1(S) — Calculate the SHA-1 hash of a string
sha256(S) — Calculate the SHA-256 hash of a string

IPC functions🔗

exec(cmd *S) — Execute a command
process(cmd *S) — Execute a command
sh(cmd *S) — Execute a command
shell(cmd *S) — Execute a command
shout(cmd *S) — Execute a command and return the output

External library functions🔗

use-pod(pod-name version) — Load an external library pod

HTTP functions🔗

curl(url) — Get a URL and return the body

YAML document result stashing functions🔗

stream() — Mapping of document results

The symbol _ at the top level compiles to (stream)

Special functions🔗

source(*) — Run a YS file as a Bash script