`ys::std` — The 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 External link , 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🔗

See FS Library

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(Opts? Cmd Str*) → Result — Execute a command
process(Opts? Cmd Str*) → Result — Execute a command
sh(Opts? Cmd Str*) → Result — Execute a command
shell(Opts? Cmd Str*) → Result — Execute a command
sh-out(Opts? Cmd Str*) → Result — Execute a command and return the output
bash(Opts? Cmd Str*) → Result — Command wrapped with bash -c '...'
bash-out(Opts? Cmd Str*) → Result — Run bash and return output

Opts is an optional mapping that supports the following options:

:in - stdin for command
:out - file to redirect stdout to
:err - file to redirect stderr to
:dir - working directory
:env - environment variables to use

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.

ys::std — The YS Standard Library🔗