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. Qualified libraries such as ys::str and ys::math must be loaded with use before using their full names or aliases.

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.

ERROR: Failed in function mdys-stdlib:
java.lang.ClassCastException: java.lang.Character cannot be cast to java.util.Map$Entry
 for:
```mdys:stdlib
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 CS/blank? |
    True if string is nil, empty or only whitespace
  chomp(Str) Str: Alias of CS/trim-newline |
    Remove trailing newlines
  chop(Str) Str: Remove last character
  ends?(Str) B: Alias of CS/ends-with? |
    True if string ends with suffix
  escape(Str {Chr:Str}) Str: Alias of CS/escape |
    Escape special characters in a string
  index(Str Str) Int: Alias of CS/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 CS/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 CC/replace
  replace(Str Rgx Str?) Str: Alias of CS/replace |
    Replace all occurrences of regex with new string (default "")
  replace1(Str Rgx Str) Str: Alias of CS/replace-first |
    Replace first occurrence of regex with new string
  rindex(Str Str) Int: Alias of CS/last-index-of |
    Find last index of substring
  split(Str) [Str]: Like CS/split |
    Split on `""`
  split(Str rgx) [Str]: Alias of CS/split |
    Split a string by a regex
  starts?(Str Str) Str: Alias of CS/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 CS/trim |
    Trim whitespace from both ends
  triml(Str) Str: Alias of CS/triml |
    Trim whitespace from left end
  trimr(Str) Str: Alias of CS/trimr |
    Trim whitespace from right end
  uc(Str) Str: Alias of CS/upper-case |
    Uppercase a string
  uc1(Str) Str: Alias of CS/capitalize |
    Uppercase the first character
  words(Str) [Str]: Split a string into words (split on whitespace)

- https://clojuredocs.org/quickref#strings-characters

Collection functions:
- diff(Col Col) [Str Str Str]: Alias of CD/diff |
    Return the difference of two collections
  flat(Vec) Vec: Like CC/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

- https://clojuredocs.org/quickref#collections

Math functions:
- add(Num*) Num: Alias of CC/+
  sub(Num+) Num: Alias of CC/-
  mul(Num*) Num: Alias of CC/*
  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

- https://clojure.github.io/clojure/clojure.math-api.html

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 CC/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 CC/when |
    Binds the result of the condition to the `_` symbol

- https://clojuredocs.org/quickref#flow-control

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

- https://clojuredocs.org/quickref#regular-expressions

I/O functions:
  err(Str*) nil: Print to stderr without a newline
  out(Str*) nil: Print to stdout|
    Flushes stdout after printing
  pp(X) nil: Pretty print a value through ys::pprint
  print(Str*) nil: Print to stdout without newline|
    Flushes stdout after printing
  read(Path) Str: Read a file through ys::fs
  readline(Reader?) Str?: Read one line through ys::io|
    With no argument, reads from IN
  say(Str*) nil: Print to stdout with newline
  warn(Str*) nil: Print to stderr with newline|
    Flushes stderr after printing
  write(Path Str) nil: Write a file through ys::fs

Shorter named alias functions:
  a(X) X: Alias of CC/identity
  len(X) Int: Alias of CC/count

Quoting functions:
  q(form) X: Alias of CC/quote
  qr(str) Rgx: Alias of CC/re-pattern
  qw(symbols) [Str]: Turn symbols into a vector of strings

Named function for infix operators:
  eq: Alias of CC/=
  ne: Alias of CC/not=
  gt: Alias of CC/>
  ge: Alias of CC/>=
  lt: Alias of CC/<
  le: Alias of CC/<=

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 the explicit [FS Library](ys-fs.md)

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: |
  See the explicit [Process Library](ys-ipc.md)

External library functions:
  use-pod(pod-name version) nil: Load an external library pod

HTTP functions: |
  See the explicit [HTTP Library](ys-http.md)

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 CC/reset! |
    Set the value of an atom
  swap(Atom Fn Arg*) X: Alias of CC/swap! |
    Update the value of an atom


Special functions:
  source(X*) nil: Run a YS file as a Bash script|
    Acts like CC/comment. Does nothing in YS. Intended for Bash.
```

See Also

• The ys::std source code 
• The clojure::core source code