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🔗

base64-decode(Str) → Str — Decode a base64 string
base64-encode(Str) → Str — Encode a string to base64
base64-points(Str) → [Int] — Decode a base64 string to code points
base64(Str) → Str — Alias of base64-encode
blank?(Str) → Str — Alias of clojure.string/blank?

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

Remove trailing newlines
chop(Str) → Str — Remove last character
ends?(Str) → B — Alias of clojure.string/ends-with?

True if string ends with suffix
escape(Str {Chr:Str}) → Str — Alias of clojure.string/escape

Escape special characters in a string
index(Str Str) → Int — Alias of clojure.string/index-of

Find index of substring
join([Str]) → Str — Join strings or seqs with ""
join(sep [Str]) → Str — Join strings or seqs with a separator
joins([Str]) → Str — Join strings with " "
lc(Str) → Str — Alias of clojure.string/lower-case

Lowercase a string
lines(Str) → [Str] — Split a string into lines
pretty(Str) → Str — Pretty print a value
replace(X) → X — Alias of clojure.core/replace
replace(Str Rgx Str?) → Str — Alias of clojure.string/replace

Replace all occurrences of regex with new string (default "")
replace1(Str Rgx Str) → Str — Alias of clojure.string/replace-first

Replace first occurrence of regex with new string
rindex(Str Str) → Int — Alias of clojure.string/last-index-of

Find last index of substring
split(Str) → [Str] — Like clojure.string/split

Split on ""
split(Str rgx) → [Str] — Alias of clojure.string/split

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

True if string starts with prefix
substr(Str Int Int?) → Str — 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([Str]) → Str — Join list of strings with newlines, adding a newline at the end
trim(Str) → Str — Alias of clojure.string/trim

Trim whitespace from both ends
triml(Str) → Str — Alias of clojure.string/triml

Trim whitespace from left end
trimr(Str) → Str — Alias of clojure.string/trimr

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

Uppercase a string
uc1(Str) → Str — Alias of clojure.string/capitalize

Uppercase the first character
words(Str) → [Str] — Split a string into words (split on whitespace)

Collection functions🔗

diff(Col Col) → [Str Str Str] — Alias of clojure.data/diff

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

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

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

Works with strings, maps and sequences
omap([X]) → Omap — Create an ordered map
reverse(Col) → Col — Reverse a string, vector or sequence
rng(Int Int) → [Int] — Create a range of numbers or characters, Y is inclusive

If X is greater than Y, the range is descending
slice(Col [Key]) → [X] — Get a sequence of values from the keys

Math functions🔗

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

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

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

Multiplies numbers, strings and sequences
digits(Str) → [Int] — Convert a string of digits to a sequence of numbers
floor(Num) → Num — Alias of CM/floor

Round down to the nearest integer
pow(Num Num+) → Num — Raise a number to a power
sqr(Num) → Num — Square a number
cube(Num) → Num — Cube a number
sqrt(Num) → Num — Square root of a number
sum([Num]) → Num — 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 re-find
!~ — For re-find + not
== — 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 X*) → X — Call a function or value

Function can be a string, symbol or function
die(Msg) — Idiomatic error function
each(Bindings Body) → X — Non-lazy clojure.core/for
eval(Str) → X — Evaluate a string as YS code
exit(RC=0) — Exit the program
if(Cond Then Else) → X — Functional if used in dot chaining
sleep(Secs) → X — Sleep for a number of seconds
value(X) → X — Get var value from var, symbol or string

Often used to convert a string to a function.
when+(Cond Body) → X — Like clojure.core/when

Binds the result of the condition to the _ symbol

Function functions🔗

defn flip(Fn) → X — Flip the arguments of a function

Regex functions🔗

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

I/O functions🔗

err(Str*) → nil — Print to stderr
out(Str*) → nil — Print to stdout

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

Flushes stdout after printing
read(path) → Str — Alias of clojure.core/slurp

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

Flushes stderr after printing
write(path Str) → nil — Alias of clojure.core/spit

Write a string to a file

Shorter named alias functions🔗

a(X) → X — Alias of clojure.core/identity
len(X) → Int — Alias of clojure.core/count

Quoting functions🔗

q(form) → X — Alias of clojure.core/quote
qr(str) → Rgx — Alias of clojure.core/re-pattern
qw(symbols) → [Str] — 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) → B — Convert X to a boolean
to-char(X) → Chr — Convert X to a character
to-float(X) → Flt — Convert X to a float
to-int(X) → Int — Convert X to an integer
to-keyw(X) → Kwd — Convert X to a keyword
to-list(X) → List — Convert X to a list
to-map(X) → Map — Convert X to a map
to-num(X) → Num — Convert X to a number
to-omap(X) → Omap — Convert X to an ordered map
to-set(X) → Set — Convert X to a set
to-str(X) → Str — Convert X to a string
to-type(X) → Str — 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) → Vec — 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*) → List — Convert to a list
M+(X*) → Map — Convert to a map
O+(X*) → Omap — Convert to an ordered map
V+(X*) → Vec — Convert to a vector

Alternate truth functions🔗

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

File system functions🔗

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

Date/Time functions🔗

now() → Instant — Returns java.time.Instant object

Security functions🔗

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

IPC functions🔗

exec(Cmd Str*) → Result — Execute a command
process(Cmd Str*) → Result — Execute a command
sh(Cmd Str*) → Result — Execute a command
shell(Cmd Str*) → Result — Execute a command
shout(Cmd Str*) → Result — Execute a command and return the output

External library functions🔗

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

HTTP functions🔗

curl(URL) → Str — Get a URL and return the body

YAML document result stashing functions🔗

stream() → X — Mapping of document results

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

Atom functions🔗

atom() → Atom — Create an atom with a nil value
atom(X) → Atom — Create an atom with a value X
reset(Atom X) → X — Alias of clojure.core/reset!

Set the value of an atom
swap(Atom Fn Arg*) → X — Alias of clojure.core/swap!

Update the value of an atom

Special functions🔗

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

Acts like clojure.core/comment. Does nothing in YS. Intended for Bash.