---
title: "Language Reference"
output: arl::arl_html_vignette
pkgdown:
  as_is: true
vignette: >
  %\VignetteIndexEntry{Language Reference}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- AUTO-GENERATED from inst/arl/ source files. Do not edit manually. -->
<!-- Regenerate with: make lang-docs -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
arl::register_knitr_engine()
```

*Examples on this page may reference functions from other stdlib modules
without showing explicit `(import ...)` statements. In the REPL or your
own code, you will need to import non-prelude modules before using their
exports — see [Importing modules](#importing-modules).*

## Special forms

**Special forms** are expressions with evaluation rules that differ from normal
function calls -- for example, `if` does not evaluate all its arguments, and
`define` binds a name rather than passing it as a value. They are handled
directly by the compiler and cannot be redefined or passed as values.

- [`quote`](lang-core.html#quote) -- Return expr without evaluating it. The shorthand `'expr` is
equivalent.
- [`if`](lang-core.html#if) -- Evaluate then or else based on test truthiness.
- [`define`](lang-core.html#define) -- Bind a name in the current lexical environment.
- [`set!`](lang-core.html#set-bang) -- Update an existing binding in the current environment chain.
- [`lambda`](lang-core.html#lambda) -- Create an anonymous function with lexical scope.
- [`begin`](lang-core.html#begin) -- Evaluate expressions in sequence and return the final result.
- [`defmacro`](lang-core.html#defmacro) -- Define a macro that transforms code before evaluation.
- [`quasiquote`](lang-core.html#quasiquote) -- Build code/data templates with selective evaluation. The shorthand
`` `expr `` is equivalent.
- [`unquote`](lang-core.html#unquote) -- Evaluate expr inside a quasiquote template. Within a template, the
shorthand `,expr` is equivalent.
- [`unquote-splicing`](lang-core.html#unquote-splicing) -- Splice list elements into a quasiquoted list. Within a quasiquote
template, the shorthand `,@expr` is equivalent.
- [`and`](lang-core.html#and) -- Short-circuit logical conjunction.
- [`or`](lang-core.html#or) -- Short-circuit logical disjunction.
- [`while`](lang-core.html#while) -- Repeatedly evaluate body while condition remains truthy.
- [`delay`](lang-core.html#delay) -- Create a promise that delays evaluation of expr until forced.
- [`import`](lang-core.html#import) -- Load a module and bind it as a first-class value. By default,
`(import name)` binds the module environment to the symbol `name` for
qualified access via `name/sym`. Use `:refer` to bring specific exports
(or all exports) into scope unqualified. Use `:as` to alias the module
binding.
- [`module`](lang-core.html#module) -- Define a module with explicit exports. A named module registers
itself in the module registry. A nameless module derives its name from the
source file. `export-all` exports all non-private definitions; add
`:re-export` to also re-export imported symbols.

Anything not in this list is a function or macro, whether
[built-in](#built-in-functions), [standard library](#standard-library),
user-defined, or inherited from R. Unlike special forms, these are ordinary
values and can be passed around, stored in variables, and so on.

## Built-in functions

Certain **built-in functions** are implemented in R ([`R/engine.R`](https://github.com/wwbrannon/arl/blob/main/R/engine.R)) rather than in Arl source modules. These are
low-level primitives that need direct access to engine internals — cons-cell
operations, the macro expander, the evaluator, promise handling, and
documentation helpers. They are always available, even when the stdlib modules
are not loaded (`Engine$new(load_prelude = FALSE)`).

| Category | Functions |
|----------|-----------|
| Arithmetic | [`+`](lang-core.html#plus), [`*`](lang-core.html#star), [`-`](lang-core.html#minus), [`/`](lang-core.html#div) |
| Comparison | [`<`](lang-core.html#lt), [`<=`](lang-core.html#lte), [`>`](lang-core.html#gt), [`>=`](lang-core.html#gte), [`=`](lang-core.html#num-eq), [`==`](lang-core.html#num-eq-eq), [`!=`](lang-core.html#bang-eq), [`not`](lang-core.html#not) |
| List and Pair Predicates | [`pair?`](lang-types.html#pair-p) |
| List Operations | [`car`](lang-list-seq.html#car), [`cdr`](lang-list-seq.html#cdr), [`cons`](lang-list-seq.html#cons) |
| Evaluation | [`eval`](lang-core.html#eval), [`read`](lang-core.html#read), [`write`](lang-core.html#write), [`load`](lang-core.html#load), [`r-eval`](lang-core.html#r-eval) |
| Documentation | [`help`](lang-core.html#help), [`doc!`](lang-core.html#doc-bang), [`doc`](lang-core.html#doc) |
| Macro Utilities | [`capture`](lang-core.html#capture), [`gensym`](lang-core.html#gensym), [`macro?`](lang-core.html#macro-p), [`macroexpand`](lang-core.html#macroexpand) |
| Promises (Lazy Evaluation) | [`promise?`](lang-core.html#promise-p), [`force`](lang-core.html#force), [`promise-expr`](lang-core.html#promise-expr) |
| Environment Introspection | [`toplevel-env`](lang-core.html#toplevel-env), [`builtins-env`](lang-core.html#builtins-env), [`current-env`](lang-core.html#current-env) |
| Module Introspection | [`module-ref`](lang-core.html#module-ref), [`module?`](lang-core.html#module-p), [`namespace?`](lang-core.html#namespace-p), [`module-exports`](lang-core.html#module-exports), [`module-name`](lang-core.html#module-name) |

These builtins are documented alongside the stdlib functions they relate to
in the individual reference pages below.

## Inherited R functions

Because Arl compiles to R and its environment chain ultimately parents to
R's `baseenv()`, every function in base R is available in Arl without any
import or special syntax. This is not just interop glue — many common
operations you will use day-to-day come directly from R rather than from Arl's
own builtins or stdlib.

### What "inherited" means

When you write `(max 1 2 3)` in Arl, the compiler emits an R call to `max()`.
There is no Arl wrapper — R's own `max` function runs directly. The same is
true for hundreds of base R functions. They work because R's `baseenv()` sits
at the bottom of the environment chain, so any name not shadowed by an Arl
builtin, stdlib export, or user definition resolves to R's version.

### Examples of commonly used inherited functions

Here are some examples of base R functions that are used routinely in Arl
code and are **not** redefined — R's own implementations run directly:

| Category | Examples |
|----------|----------|
| Math | `max`, `min`, `sum`, `prod` |
| Vectors | `c`, `length`, `seq`, `seq_len`, `seq_along`, `rep`, `rev`, `unique`, `which` |
| Predicates | `is.null`, `is.na`, `is.numeric`, `is.character`, `is.logical`, `is.function`, `is.list`, `is.environment` |
| Coercion | `as.numeric`, `as.character`, `as.logical`, `as.integer`, `as.double`, `as.list` |
| Strings | `paste`, `paste0`, `sprintf`, `nchar`, `substr`, `sub`, `gsub`, `grepl`, `toupper`, `tolower`, `trimws`, `strsplit` |
| Data structures | `list`, `vector`, `matrix`, `data.frame`, `names`, `attr`, `attributes` |
| Accessors | `$`, `[`, `[[`, `@` |
| Apply family | `lapply`, `sapply`, `vapply`, `mapply`, `tapply`, `do.call` |
| I/O | `cat`, `message`, `warning`, `stop`, `readLines`, `writeLines`, `readRDS`, `saveRDS` |
| Environment | `environment`, `new.env`, `parent.env`, `exists`, `assign`, `ls`, `rm` |

This is far from exhaustive — any function in R's base package works in
Arl the same way.

### When Arl shadows R

Arl intentionally redefines some R names with its own versions. The most
important are the **operators**:

- **Arithmetic** (`+`, `-`, `*`, `/`): Arl's versions are variadic, so
  `(+ 1 2 3 4)` works. R's `+` is binary.
- **Comparison** (`<`, `<=`, `>`, `>=`): Arl's versions chain, so
  `(< 1 2 3)` means "1 < 2 and 2 < 3". R's `<` compares two vectors.
- **Equality** (`=`, `==`, `!=`): Arl's versions are NULL-safe and variadic.
  R's `=` is assignment, not comparison.
- **Logical** (`!`): Arl uses `not` and the special forms `and`/`or`.
- **Control flow** (`if`, `while`, `for`): These are Arl special forms or
  macros with Lisp-style syntax.

The stdlib also shadows some base R function names with Lisp-flavored
versions:

- **Math wrappers** (`abs`, `sqrt`, `exp`, `log`, `floor`, `ceiling`,
  `round`): Arl's versions are thin wrappers that add documentation and
  integrate with the help system; behavior is the same.
- **List operations** (`append`, `sort`, `reverse`): Arl's versions work on
  both R lists and cons-cell pair lists, with Lisp-style semantics.
- **I/O and display** (`print`, `format`, `system`): Arl's versions add
  Lisp-style formatting or Arl-specific behavior.
- **Other** (`get`, `identity`, `subset`, `transform`, `try`): Arl provides
  its own implementations of these with Arl-specific semantics.

When you need R's original, use the `base::` namespace prefix:

```{arl, eval=FALSE}
(base::sort (c 3 1 2))      ; R's vector sort, not Arl's list sort
(base::identity (list 1 2))  ; R's identity, not Arl's
```

### Beyond base: R's default packages

Arl's environment chain parents to R's `baseenv()`, **not** to
`.GlobalEnv`. But R's default packages — `stats`, `utils`, `grDevices`,
`graphics`, `datasets`, and `methods` — are also attached at engine
startup. Their exports are copied into a chain of environments between
`builtins_env` and `baseenv()`, mirroring how R itself structures its
search path.

This means functions like `median`, `head`, `lm`, `plot`, `rgb`, and
data like `iris` and `mtcars` work without any prefix:

```{arl, eval=FALSE}
(median (c 1 2 3 4 5))
(head mtcars 3)
(lm (~ mpg cyl) :data mtcars)
```

The set of attached packages is controlled by R's `defaultPackages`
option (see `?options`). Users can customize it by setting the
`R_DEFAULT_PACKAGES` environment variable before starting R — for
example, `R_DEFAULT_PACKAGES=""` disables all default packages, leaving
only `baseenv()`.

For packages **not** in the default set, use the `::` prefix:

```{arl, eval=FALSE}
(jsonlite::fromJSON "{\"a\": 1}")
(httr::GET "https://example.com")
```

See [R Interop and Data Workflows](r-interop.html) for more on calling R
functions, using keyword arguments, formulas, and `r-eval`.

## Standard library

In addition to built-in functions, Arl has a **standard library** written in
Arl (`inst/arl/*.arl`). These stdlib modules provide various features: list
operations, math, strings, control flow, and everything else. Modules are
loaded in dependency order (each module declares its dependencies with `(import
...)` and is loaded after the modules it imports).

For the full, per-function reference, see the individual stdlib reference
pages:

- [Standard Library: Core, R Interop, and Testing](lang-core.html)
- [Standard Library: Types, Equality, and Conversions](lang-types.html)
- [Standard Library: Control Flow and Macros](lang-control.html)
- [Standard Library: Lists and Sequences](lang-list-seq.html)
- [Standard Library: Strings, Display, and I/O](lang-strings-io.html)
- [Standard Library: Collections and Data Structures](lang-collections.html)
- [Standard Library: Higher-Order Functions](lang-functional.html)
- [Standard Library: Math and Numeric Functions](lang-math.html)

## Importing modules

Prelude modules are loaded automatically by `Engine$new()`. Non-prelude
modules (like `math`, `looping`, `sort`, `strings`, `dict`, `set`, `io`,
etc.) require explicit `(import ...)`. The `import` form is also needed
inside your own modules (where you start with an empty scope) and when
working with a bare engine (`Engine$new(load_prelude = FALSE)`):

```{arl, eval=FALSE}
; Import non-prelude modules
(import math)      ; inc/dec/abs/min/max/floor/ceiling/round/square/...
(import looping)   ; do-list/loop/recur/until
(import sort)      ; sort/sort-by
(import strings)   ; str/string-join/string-split/...
```

From R, you can create an engine with the stdlib already loaded:

```r
engine <- Engine$new()                   # prelude loaded
bare <- Engine$new(load_prelude=FALSE)    # builtins only
```


## [Core, R Interop, and Testing](lang-core.html)

Evaluation, macro utilities, R interop helpers, and assertions.

[`license`](lang-core.html#license), [`error`](lang-core.html#error),
[`warn`](lang-core.html#warn), [`identity`](lang-core.html#identity),
[`values`](lang-core.html#values), [`values?`](lang-core.html#values-p),
[`call-with-values`](lang-core.html#call-with-values),
[`funcall`](lang-core.html#funcall), [`r-call`](lang-core.html#r-call),
[`get`](lang-core.html#get),
[`unbind-variable`](lang-core.html#unbind-variable),
[`run`](lang-core.html#run), [`macroexpand-1`](lang-core.html#macroexpand-1),
[`macroexpand-all`](lang-core.html#macroexpand-all),
[`suppressWarnings`](lang-core.html#suppresswarnings),
[`suppressMessages`](lang-core.html#suppressmessages),
[`with`](lang-core.html#with), [`within`](lang-core.html#within),
[`subset`](lang-core.html#subset), [`transform`](lang-core.html#transform),
[`substitute`](lang-core.html#substitute), [`assert`](lang-core.html#assert),
[`assert-equal`](lang-core.html#assert-equal),
[`assert-true`](lang-core.html#assert-true),
[`assert-false`](lang-core.html#assert-false),
[`assert-eq`](lang-core.html#assert-eq),
[`assert-error`](lang-core.html#assert-error),
[`assert-no-error`](lang-core.html#assert-no-error),
[`+`](lang-core.html#plus), [`*`](lang-core.html#star),
[`-`](lang-core.html#minus), [`/`](lang-core.html#div),
[`<`](lang-core.html#lt), [`<=`](lang-core.html#lte), [`>`](lang-core.html#gt),
[`>=`](lang-core.html#gte), [`=`](lang-core.html#num-eq),
[`==`](lang-core.html#num-eq-eq), [`!=`](lang-core.html#bang-eq),
[`not`](lang-core.html#not), [`eval`](lang-core.html#eval),
[`read`](lang-core.html#read), [`write`](lang-core.html#write),
[`help`](lang-core.html#help), [`load`](lang-core.html#load),
[`capture`](lang-core.html#capture), [`gensym`](lang-core.html#gensym),
[`macro?`](lang-core.html#macro-p),
[`macroexpand`](lang-core.html#macroexpand),
[`promise?`](lang-core.html#promise-p), [`force`](lang-core.html#force),
[`promise-expr`](lang-core.html#promise-expr),
[`r-eval`](lang-core.html#r-eval),
[`toplevel-env`](lang-core.html#toplevel-env),
[`builtins-env`](lang-core.html#builtins-env),
[`current-env`](lang-core.html#current-env), [`doc!`](lang-core.html#doc-bang),
[`doc`](lang-core.html#doc), [`module-ref`](lang-core.html#module-ref),
[`module?`](lang-core.html#module-p),
[`namespace?`](lang-core.html#namespace-p),
[`module-exports`](lang-core.html#module-exports),
[`module-name`](lang-core.html#module-name)

Modules: [`core.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/core.arl), [`r-interop.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/r-interop.arl), [`assert.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/assert.arl), and builtins

## [Types, Equality, and Conversions](lang-types.html)

Type predicates, numeric type hierarchy, structural and identity equality, S3-style dispatch, and type conversions.

[`list?`](lang-types.html#list-p),
[`list-or-pair?`](lang-types.html#list-or-pair-p),
[`null?`](lang-types.html#null-p), [`nil?`](lang-types.html#nil-p),
[`symbol?`](lang-types.html#symbol-p), [`keyword?`](lang-types.html#keyword-p),
[`number?`](lang-types.html#number-p), [`string?`](lang-types.html#string-p),
[`vector?`](lang-types.html#vector-p), [`true?`](lang-types.html#true-p),
[`false?`](lang-types.html#false-p), [`boolean?`](lang-types.html#boolean-p),
[`fn?`](lang-types.html#fn-p), [`callable?`](lang-types.html#callable-p),
[`procedure?`](lang-types.html#procedure-p),
[`environment?`](lang-types.html#environment-p),
[`is-refclass?`](lang-types.html#is-refclass-p),
[`atom?`](lang-types.html#atom-p), [`empty?`](lang-types.html#empty-p),
[`type-of`](lang-types.html#type-of), [`real?`](lang-types.html#real-p),
[`complex?`](lang-types.html#complex-p),
[`rational?`](lang-types.html#rational-p), [`exact?`](lang-types.html#exact-p),
[`inexact?`](lang-types.html#inexact-p),
[`integer?`](lang-types.html#integer-p),
[`natural?`](lang-types.html#natural-p), [`finite?`](lang-types.html#finite-p),
[`infinite?`](lang-types.html#infinite-p), [`nan?`](lang-types.html#nan-p),
[`even?`](lang-types.html#even-p), [`odd?`](lang-types.html#odd-p),
[`zero?`](lang-types.html#zero-p), [`positive?`](lang-types.html#positive-p),
[`negative?`](lang-types.html#negative-p),
[`non-negative?`](lang-types.html#non-negative-p),
[`non-positive?`](lang-types.html#non-positive-p),
[`identical?`](lang-types.html#identical-p), [`eq?`](lang-types.html#eq-p),
[`eqv?`](lang-types.html#eqv-p), [`equal?`](lang-types.html#equal-p),
[`equal?.default`](lang-types.html#equal-p-default),
[`equal?.environment`](lang-types.html#equal-p-environment),
[`equal?.list`](lang-types.html#equal-p-list),
[`env-equal?`](lang-types.html#env-equal-p),
[`list-equal?`](lang-types.html#list-equal-p),
[`s3-type`](lang-types.html#s3-type),
[`check-s3-type-match`](lang-types.html#check-s3-type-match),
[`use-method`](lang-types.html#use-method),
[`set-method!`](lang-types.html#set-method-bang),
[`symbol->string`](lang-types.html#symbol-to-string),
[`string->symbol`](lang-types.html#string-to-symbol),
[`->symbol`](lang-types.html#to-symbol),
[`->number`](lang-types.html#to-number), [`->list`](lang-types.html#to-list),
[`->vector`](lang-types.html#to-vector),
[`->integer`](lang-types.html#to-integer),
[`->double`](lang-types.html#to-double),
[`->complex`](lang-types.html#to-complex),
[`exact->inexact`](lang-types.html#exact-to-inexact),
[`inexact->exact`](lang-types.html#inexact-to-exact),
[`pair?`](lang-types.html#pair-p)

Modules: [`types.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/types.arl), [`equality.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/equality.arl), [`conversions.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/conversions.arl), and builtins

## [Control Flow and Macros](lang-control.html)

Conditionals, binding forms, looping, threading macros, continuations, and error handling.

[`when`](lang-control.html#when), [`unless`](lang-control.html#unless),
[`cond`](lang-control.html#cond), [`case`](lang-control.html#case),
[`try`](lang-control.html#try), [`try-catch`](lang-control.html#try-catch),
[`call-cc`](lang-control.html#call-cc),
[`call-with-current-continuation`](lang-control.html#call-with-current-continuation),
[`pattern-symbols`](lang-control.html#pattern-symbols),
[`destructuring-bind`](lang-control.html#destructuring-bind),
[`let`](lang-control.html#let), [`let*`](lang-control.html#let-star),
[`letrec`](lang-control.html#letrec), [`when-let`](lang-control.html#when-let),
[`if-let`](lang-control.html#if-let), [`until`](lang-control.html#until),
[`do-list`](lang-control.html#do-list), [`loop`](lang-control.html#loop),
[`recur`](lang-control.html#recur), [`->`](lang-control.html#thread-first),
[`->>`](lang-control.html#thread-last), [`as->`](lang-control.html#as-to),
[`some->`](lang-control.html#some-to),
[`some->>`](lang-control.html#some-to-gt),
[`cond->`](lang-control.html#cond-to),
[`cond->>`](lang-control.html#cond-to-gt)

Modules: [`control.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/control.arl), [`binding.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/binding.arl), [`looping.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/looping.arl), [`threading.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/threading.arl)

## [Lists and Sequences](lang-list-seq.html)

List construction, accessors, association lists, sequence helpers, and sorting.

[`call`](lang-list-seq.html#call), [`caar`](lang-list-seq.html#caar),
[`cadr`](lang-list-seq.html#cadr), [`cdar`](lang-list-seq.html#cdar),
[`cddr`](lang-list-seq.html#cddr), [`caaar`](lang-list-seq.html#caaar),
[`caadr`](lang-list-seq.html#caadr), [`cadar`](lang-list-seq.html#cadar),
[`caddr`](lang-list-seq.html#caddr), [`cdaar`](lang-list-seq.html#cdaar),
[`cdadr`](lang-list-seq.html#cdadr), [`cddar`](lang-list-seq.html#cddar),
[`cdddr`](lang-list-seq.html#cdddr), [`cadddr`](lang-list-seq.html#cadddr),
[`cddddr`](lang-list-seq.html#cddddr), [`list*`](lang-list-seq.html#list-star),
[`append`](lang-list-seq.html#append), [`reverse`](lang-list-seq.html#reverse),
[`first`](lang-list-seq.html#first), [`second`](lang-list-seq.html#second),
[`third`](lang-list-seq.html#third), [`fourth`](lang-list-seq.html#fourth),
[`rest`](lang-list-seq.html#rest), [`last`](lang-list-seq.html#last),
[`nth`](lang-list-seq.html#nth), [`assoc`](lang-list-seq.html#assoc),
[`assoc-by-equal?`](lang-list-seq.html#assoc-by-equal-p),
[`assoc-by-identical?`](lang-list-seq.html#assoc-by-identical-p),
[`assoc-by-==`](lang-list-seq.html#assoc-by-eq-eq),
[`assq`](lang-list-seq.html#assq), [`assv`](lang-list-seq.html#assv),
[`rassoc`](lang-list-seq.html#rassoc),
[`rassoc-by-equal?`](lang-list-seq.html#rassoc-by-equal-p),
[`range`](lang-list-seq.html#range), [`iota`](lang-list-seq.html#iota),
[`make-list`](lang-list-seq.html#make-list),
[`list-ref`](lang-list-seq.html#list-ref),
[`list-tail`](lang-list-seq.html#list-tail), [`take`](lang-list-seq.html#take),
[`drop`](lang-list-seq.html#drop),
[`take-while`](lang-list-seq.html#take-while),
[`drop-while`](lang-list-seq.html#drop-while),
[`partition`](lang-list-seq.html#partition),
[`flatten`](lang-list-seq.html#flatten),
[`repeatedly`](lang-list-seq.html#repeatedly),
[`repeat`](lang-list-seq.html#repeat), [`zip`](lang-list-seq.html#zip),
[`member`](lang-list-seq.html#member),
[`contains?`](lang-list-seq.html#contains-p),
[`length=`](lang-list-seq.html#length-eq),
[`length>`](lang-list-seq.html#length-gt),
[`length<`](lang-list-seq.html#length-lt), [`find`](lang-list-seq.html#find),
[`distinct`](lang-list-seq.html#distinct),
[`split-at`](lang-list-seq.html#split-at),
[`split-with`](lang-list-seq.html#split-with),
[`interpose`](lang-list-seq.html#interpose),
[`partition-by`](lang-list-seq.html#partition-by),
[`list-sort`](lang-list-seq.html#list-sort),
[`sort-by`](lang-list-seq.html#sort-by),
[`merge-sorted`](lang-list-seq.html#merge-sorted),
[`stable-sort`](lang-list-seq.html#stable-sort),
[`car`](lang-list-seq.html#car), [`cdr`](lang-list-seq.html#cdr),
[`cons`](lang-list-seq.html#cons)

Modules: [`list.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/list.arl), [`sequences.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/sequences.arl), [`sort.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/sort.arl), and builtins

## [Strings, Display, and I/O](lang-strings-io.html)

String manipulation, file and console I/O, environment access, and display formatting.

[`string-join`](lang-strings-io.html#string-join),
[`string-split`](lang-strings-io.html#string-split),
[`trim`](lang-strings-io.html#trim),
[`string-format`](lang-strings-io.html#string-format),
[`string-contains?`](lang-strings-io.html#string-contains-p),
[`string-match?`](lang-strings-io.html#string-match-p),
[`string-find`](lang-strings-io.html#string-find),
[`string-replace`](lang-strings-io.html#string-replace),
[`string-replace-all`](lang-strings-io.html#string-replace-all),
[`string-append`](lang-strings-io.html#string-append),
[`->string`](lang-strings-io.html#to-string),
[`char-at`](lang-strings-io.html#char-at),
[`string-ref`](lang-strings-io.html#string-ref),
[`string-slice`](lang-strings-io.html#string-slice),
[`string-length`](lang-strings-io.html#string-length),
[`string-upcase`](lang-strings-io.html#string-upcase),
[`string-downcase`](lang-strings-io.html#string-downcase),
[`string-titlecase`](lang-strings-io.html#string-titlecase),
[`string<?`](lang-strings-io.html#string-lt-p),
[`string>?`](lang-strings-io.html#string-gt-p),
[`string=?`](lang-strings-io.html#string-eq-p),
[`string<=?`](lang-strings-io.html#string-lte-p),
[`string>=?`](lang-strings-io.html#string-gte-p),
[`string->list`](lang-strings-io.html#string-to-list),
[`list->string`](lang-strings-io.html#list-to-string),
[`number->string`](lang-strings-io.html#number-to-string),
[`string->number`](lang-strings-io.html#string-to-number),
[`string-prefix?`](lang-strings-io.html#string-prefix-p),
[`string-suffix?`](lang-strings-io.html#string-suffix-p),
[`string-empty?`](lang-strings-io.html#string-empty-p),
[`string-repeat`](lang-strings-io.html#string-repeat),
[`read-line`](lang-strings-io.html#read-line),
[`read-file`](lang-strings-io.html#read-file),
[`read-lines`](lang-strings-io.html#read-lines),
[`write-file`](lang-strings-io.html#write-file),
[`write-lines`](lang-strings-io.html#write-lines),
[`append-file`](lang-strings-io.html#append-file),
[`file-exists?`](lang-strings-io.html#file-exists-p),
[`newline`](lang-strings-io.html#newline),
[`read-from-string`](lang-strings-io.html#read-from-string),
[`write-string`](lang-strings-io.html#write-string),
[`file-size`](lang-strings-io.html#file-size),
[`file-modified-time`](lang-strings-io.html#file-modified-time),
[`file-delete`](lang-strings-io.html#file-delete),
[`directory-exists?`](lang-strings-io.html#directory-exists-p),
[`directory-list`](lang-strings-io.html#directory-list),
[`directory-delete`](lang-strings-io.html#directory-delete),
[`getenv`](lang-strings-io.html#getenv),
[`setenv`](lang-strings-io.html#setenv),
[`system-output`](lang-strings-io.html#system-output),
[`exit`](lang-strings-io.html#exit),
[`format-value`](lang-strings-io.html#format-value),
[`display`](lang-strings-io.html#display),
[`println`](lang-strings-io.html#println),
[`string-concat`](lang-strings-io.html#string-concat),
[`trace`](lang-strings-io.html#trace)

Modules: [`strings.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/strings.arl), [`io.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/io.arl), [`display.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/display.arl)

## [Collections and Data Structures](lang-collections.html)

Dictionaries, sets, and struct definitions for structured data.

[`dict`](lang-collections.html#dict), [`hash`](lang-collections.html#hash),
[`dict?`](lang-collections.html#dict-p),
[`dict-get`](lang-collections.html#dict-get),
[`dict-set`](lang-collections.html#dict-set),
[`dict-remove`](lang-collections.html#dict-remove),
[`dict-keys`](lang-collections.html#dict-keys),
[`dict-values`](lang-collections.html#dict-values),
[`dict-has?`](lang-collections.html#dict-has-p),
[`dict-merge`](lang-collections.html#dict-merge),
[`dict-update`](lang-collections.html#dict-update),
[`dict-map`](lang-collections.html#dict-map),
[`dict-filter`](lang-collections.html#dict-filter),
[`dict-for-each`](lang-collections.html#dict-for-each),
[`dict->alist`](lang-collections.html#dict-to-alist),
[`alist->dict`](lang-collections.html#alist-to-dict),
[`set`](lang-collections.html#set), [`set?`](lang-collections.html#set-p),
[`set-add`](lang-collections.html#set-add),
[`set-remove`](lang-collections.html#set-remove),
[`set-contains?`](lang-collections.html#set-contains-p),
[`set-union`](lang-collections.html#set-union),
[`set-intersection`](lang-collections.html#set-intersection),
[`set-difference`](lang-collections.html#set-difference),
[`set->list`](lang-collections.html#set-to-list),
[`list->set`](lang-collections.html#list-to-set),
[`set-size`](lang-collections.html#set-size),
[`set-map`](lang-collections.html#set-map),
[`set-filter`](lang-collections.html#set-filter),
[`defstruct`](lang-collections.html#defstruct)

Modules: [`dict.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/dict.arl), [`set.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/set.arl), [`struct.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/struct.arl)

## [Higher-Order Functions](lang-functional.html)

Mapping, filtering, folding, function composition, and logical combinators.

[`map`](lang-functional.html#map), [`mapcat`](lang-functional.html#mapcat),
[`filter`](lang-functional.html#filter),
[`remove`](lang-functional.html#remove),
[`reduce`](lang-functional.html#reduce), [`foldl`](lang-functional.html#foldl),
[`foldr`](lang-functional.html#foldr),
[`every?`](lang-functional.html#every-p), [`any?`](lang-functional.html#any-p),
[`complement`](lang-functional.html#complement),
[`compose`](lang-functional.html#compose),
[`partial`](lang-functional.html#partial),
[`curry`](lang-functional.html#curry), [`juxt`](lang-functional.html#juxt),
[`constantly`](lang-functional.html#constantly),
[`iterate`](lang-functional.html#iterate),
[`iterate-until`](lang-functional.html#iterate-until),
[`memoize`](lang-functional.html#memoize),
[`for-each`](lang-functional.html#for-each),
[`count`](lang-functional.html#count),
[`map-indexed`](lang-functional.html#map-indexed),
[`group-by`](lang-functional.html#group-by),
[`frequencies`](lang-functional.html#frequencies), [`not`](lang-core.html#not),
[`xor`](lang-functional.html#xor)

Modules: [`functional.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/functional.arl), [`logic.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/logic.arl)

## [Math and Numeric Functions](lang-math.html)

Arithmetic, comparison, rounding, trigonometry, number theory, and complex number utilities.

[`%`](lang-math.html#percent), [`inc`](lang-math.html#inc),
[`dec`](lang-math.html#dec), [`clamp`](lang-math.html#clamp),
[`within?`](lang-math.html#within-p), [`signum`](lang-math.html#signum),
[`expt`](lang-math.html#expt), [`quotient`](lang-math.html#quotient),
[`remainder`](lang-math.html#remainder), [`modulo`](lang-math.html#modulo),
[`gcd`](lang-math.html#gcd), [`lcm`](lang-math.html#lcm),
[`make-rectangular`](lang-math.html#make-rectangular),
[`make-polar`](lang-math.html#make-polar),
[`real-part`](lang-math.html#real-part),
[`imag-part`](lang-math.html#imag-part),
[`magnitude`](lang-math.html#magnitude), [`angle`](lang-math.html#angle)

Modules: [`math.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/math.arl)

## Source files

Built-in functions are defined in
[`R/engine.R`](https://github.com/wwbrannon/arl/blob/main/R/engine.R). The
Arl stdlib modules are organized by topic in
[`inst/arl/`](https://github.com/wwbrannon/arl/tree/main/inst/arl) (each file
defines a module). The engine loads these modules in dependency order when
initializing.

- [`core.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/core.arl)
- [`list.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/list.arl)
- [`types.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/types.arl) (type predicates, numeric type hierarchy)
- [`logic.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/logic.arl) (logical operations)
- [`conversions.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/conversions.arl) (type conversions)
- [`equality.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/equality.arl) (equality and S3 dispatch)
- [`control.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/control.arl)
- [`functional.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/functional.arl)
- [`sequences.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/sequences.arl)
- [`sort.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/sort.arl)
- [`struct.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/struct.arl)
- [`threading.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/threading.arl)
- [`binding.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/binding.arl)
- [`looping.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/looping.arl)
- [`dict.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/dict.arl)
- [`math.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/math.arl)
- [`set.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/set.arl)
- [`strings.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/strings.arl)
- [`display.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/display.arl)
- [`io.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/io.arl)
- [`assert.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/assert.arl)
- [`r-interop.arl`](https://github.com/wwbrannon/arl/blob/main/inst/arl/r-interop.arl)

If you're looking for implementation details, these files are the source of
truth for the stdlib definitions.