# Reference docs for non-.arl language topics.
# Includes:
# - R-defined builtins (injected by ArlEngine$initialize_environment)
# - compiler special forms (no object to attach arl_doc to)
#
# Format: Debian Control File (DCF), read by base R's read.dcf().
# Fields: Name, Kind, Vignette, Section, Description, Signature, Examples,
# Assert, Seealso, Note.
# Kind values:
# - builtin (default when omitted)
# - special-form
# Multi-line values use leading whitespace on continuation lines.

Name: quote
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Return expr without evaluating it. The shorthand `'expr` is
  equivalent.
Signature: (quote expr)
Examples:
  (quote (+ 1 2))  ; => (+ 1 2)
  '(a b c)         ; => (a b c)
Assert:
  (assert-equal '(+ 1 2) (quote (+ 1 2)))
  (assert-equal '(a b c) '(a b c))
Seealso: quasiquote, eval

Name: if
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Evaluate then or else based on test truthiness.
Signature: (if test then [else])
Examples:
  (if (> 3 2) "yes" "no") ; => "yes"
  (if #f 1)               ; => #nil
Assert:
  (assert-equal "yes" (if (> 3 2) "yes" "no"))
  (assert-equal #nil (if #f 1))
Seealso: and, or

Name: define
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Bind a name in the current lexical environment.
Signature: (define name value)
Examples:
  (define x 42)
  (define add (lambda (a b) (+ a b)))
Assert:
  (define sf-define-x 42)
  (assert-equal 42 sf-define-x)
  (define sf-add (lambda (a b) (+ a b)))
  (assert-equal 5 (sf-add 2 3))
Seealso: set!, lambda

Name: set!
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Update an existing binding in the current environment chain.
Signature: (set! name value)
Examples:
  (define x 1)
  (set! x (+ x 1)) ; x => 2
Assert:
  (define sf-set-x 1)
  (set! sf-set-x (+ sf-set-x 1))
  (assert-equal 2 sf-set-x)
Seealso: define

Name: lambda
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Create an anonymous function with lexical scope.
Signature: (lambda (params...) body...)
Examples:
  ((lambda (x) (+ x 1)) 41) ; => 42
Assert:
  (assert-equal 42 ((lambda (x) (+ x 1)) 41))
Seealso: define

Name: begin
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Evaluate expressions in sequence and return the final result.
Signature: (begin expr...)
Examples:
  (begin (define x 1) (set! x (+ x 1)) x) ; => 2
Assert:
  (assert-equal 2 (begin (define sf-begin-x 1) (set! sf-begin-x (+ sf-begin-x 1)) sf-begin-x))
Seealso: if

Name: defmacro
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Define a macro that transforms code before evaluation.
Signature: (defmacro name (params...) body...)
Examples:
  (defmacro when (test . body)
    `(if ,test (begin ,@body) #nil))
Assert:
  (defmacro sf-when (test . body)
    `(if ,test (begin ,@body) #nil))
  (assert-equal 3 (sf-when #t (+ 1 2)))
Seealso: macroexpand, macroexpand-1, quasiquote

Name: quasiquote
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Build code/data templates with selective evaluation. The shorthand
  `` `expr `` is equivalent.
Signature: (quasiquote expr)
Examples:
  (define x 10)
  `(a ,x c) ; => (a 10 c)
Assert:
  (define sf-qq-x 10)
  (assert-equal '(a 10 c) `(a ,sf-qq-x c))
Seealso: quote, unquote, unquote-splicing

Name: unquote
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Evaluate expr inside a quasiquote template. Within a template, the
  shorthand `,expr` is equivalent.
Signature: (unquote expr)
Examples:
  (define x 10)
  `(a ,x c) ; => (a 10 c)
Assert:
  (define sf-uq-x 10)
  (assert-equal '(a 10 c) `(a ,sf-uq-x c))
Seealso: quasiquote, unquote-splicing

Name: unquote-splicing
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Splice list elements into a quasiquoted list. Within a quasiquote
  template, the shorthand `,@expr` is equivalent.
Signature: (unquote-splicing expr)
Examples:
  (define xs '(2 3))
  `(1 ,@xs 4) ; => (1 2 3 4)
Assert:
  (define sf-uqs-xs '(2 3))
  (assert-equal '(1 2 3 4) `(1 ,@sf-uqs-xs 4))
Seealso: quasiquote, unquote

Name: and
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Short-circuit logical conjunction.
Signature: (and expr...)
Examples:
  (and #t 1 2) ; => 2
  (and #f (stop "error")) ; => #f (second form not evaluated)
Assert:
  (assert-equal 2 (and #t 1 2))
  (assert-equal #f (and #f (stop "error")))
Seealso: or, if

Name: or
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Short-circuit logical disjunction.
Signature: (or expr...)
Examples:
  (or #f #nil 0 7) ; => 7
  (or #t (stop "error")) ; => #t (second form not evaluated)
Assert:
  (assert-equal 7 (or #f #nil 0 7))
  (assert-equal #t (or #t (stop "error")))
Seealso: and, if

Name: while
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Repeatedly evaluate body while condition remains truthy.
Signature: (while test body...)
Examples:
  (define i 0)
  (while (< i 3) (set! i (+ i 1)))
  i ; => 3
Assert:
  (define sf-while-i 0)
  (while (< sf-while-i 3) (set! sf-while-i (+ sf-while-i 1)))
  (assert-equal 3 sf-while-i)
Seealso: begin

Name: delay
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: Create a promise that delays evaluation of expr until forced.
Signature: (delay expr)
Examples:
  (define p (delay (+ 1 2)))
  (force p) ; => 3
Assert:
  (define sf-delay-p (delay (+ 1 2)))
  (assert-true (promise? sf-delay-p))
  (assert-equal 3 (force sf-delay-p))
Seealso: force, promise?, promise-expr

Name: import
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: 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.
Signature: (import name)
  (import name :refer (sym1 sym2 ...))
  (import name :refer :all)
  (import name :as alias)
  (import name :rename ((old new) ...))
  (import name :reload)
  (import "path/to/file.arl")
Examples:
  (import math)
  (math/inc 5)               ; qualified access
  (import math :refer :all)
  (inc 5)                     ; unqualified access
  (import math :as m)
  (m/inc 5)                   ; aliased qualified access
Seealso: module, load, module-ref

Name: module
Kind: special-form
Vignette: lang-core
Section: Special Forms
Description: 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.
Signature: (module name (export ...) body...)
  (module (export ...) body...)
  (module name (export-all) body...)
  (module name (export-all :re-export) body...)
Examples:
  (module demo
    (export answer)
    (define answer 42))
Assert:
  (module sf-demo
    (export sf-answer)
    (define sf-answer 42))
  (import sf-demo :refer :all)
  (assert-equal 42 sf-answer)
Seealso: import, module?, module-exports, module-name

Name: +
Kind: builtin
Vignette: lang-core
Section: Arithmetic
Description: Variadic addition. With no arguments returns 0 (additive
  identity). With one argument returns it unchanged. With two or more,
  returns their sum left-to-right.
Signature: (+ a ...)
Examples:
  (+)           ; => 0
  (+ 5)         ; => 5
  (+ 1 2 3)     ; => 6
Assert:
  (assert-equal 0 (+))
  (assert-equal 5 (+ 5))
  (assert-equal 6 (+ 1 2 3))
Seealso: -, *, /

Name: *
Kind: builtin
Vignette: lang-core
Section: Arithmetic
Description: Variadic multiplication. With no arguments returns 1
  (multiplicative identity). With one argument returns it unchanged.
  With two or more, returns their product left-to-right.
Signature: (* a ...)
Examples:
  (*)           ; => 1
  (* 5)         ; => 5
  (* 2 3 4)     ; => 24
Assert:
  (assert-equal 1 (*))
  (assert-equal 5 (* 5))
  (assert-equal 24 (* 2 3 4))
Seealso: +, -, /

Name: -
Kind: builtin
Vignette: lang-core
Section: Arithmetic
Description: Variadic subtraction. Requires at least one argument.
  With one argument returns its negation. With two or more, subtracts
  subsequent arguments from the first left-to-right.
Signature: (- a ...)
Examples:
  (- 5)         ; => -5
  (- 10 3)      ; => 7
  (- 10 3 2)    ; => 5
Assert:
  (assert-equal -5 (- 5))
  (assert-equal 7 (- 10 3))
  (assert-equal 5 (- 10 3 2))
Seealso: +, *, /

Name: /
Kind: builtin
Vignette: lang-core
Section: Arithmetic
Description: Variadic division. Requires at least one argument.
  With one argument returns its reciprocal. With two or more, divides
  the first argument by subsequent arguments left-to-right.
Signature: (/ a ...)
Examples:
  (/ 5)         ; => 0.2
  (/ 10 2)      ; => 5
  (/ 100 5 2)   ; => 10
Assert:
  (assert-equal 0.2 (/ 5))
  (assert-equal 5 (/ 10 2))
  (assert-equal 10 (/ 100 5 2))
Seealso: +, -, *

Name: <
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic less-than. With fewer than two arguments returns #t
  (vacuously true). With two or more, checks that each argument is strictly
  less than the next (chained pairwise comparison).
Signature: (< a b ...)
Examples:
  (< 1 2)       ; => #t
  (< 1 2 3)     ; => #t
  (< 1 3 2)     ; => #f
Assert:
  (assert-true (< 1 2))
  (assert-true (< 1 2 3))
  (assert-false (< 1 3 2))
Seealso: <=, >, >=, =

Name: <=
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic less-than-or-equal. With fewer than two arguments
  returns #t. With two or more, checks that each argument is less than or
  equal to the next.
Signature: (<= a b ...)
Examples:
  (<= 1 2)      ; => #t
  (<= 1 1 2)    ; => #t
  (<= 2 1)      ; => #f
Assert:
  (assert-true (<= 1 2))
  (assert-true (<= 1 1 2))
  (assert-false (<= 2 1))
Seealso: <, >, >=, =

Name: >
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic greater-than. With fewer than two arguments returns #t.
  With two or more, checks that each argument is strictly greater than the next.
Signature: (> a b ...)
Examples:
  (> 3 2)       ; => #t
  (> 3 2 1)     ; => #t
  (> 3 1 2)     ; => #f
Assert:
  (assert-true (> 3 2))
  (assert-true (> 3 2 1))
  (assert-false (> 3 1 2))
Seealso: >=, <, <=, =

Name: >=
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic greater-than-or-equal. With fewer than two arguments
  returns #t. With two or more, checks that each argument is greater than or
  equal to the next.
Signature: (>= a b ...)
Examples:
  (>= 3 2)      ; => #t
  (>= 2 2 1)    ; => #t
  (>= 1 2)      ; => #f
Assert:
  (assert-true (>= 3 2))
  (assert-true (>= 2 2 1))
  (assert-false (>= 1 2))
Seealso: >, <, <=, =

Name: =
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic equality comparison (NULL-safe). With fewer than two
  arguments returns #t. With two or more, checks that all adjacent pairs are
  equal. NULL comparisons follow Scheme semantics: (= #nil #nil) is #t,
  (= #nil x) is #f.
Signature: (= a b ...)
Examples:
  (= 1 1)       ; => #t
  (= 1 1 1)     ; => #t
  (= 1 2)       ; => #f
  (= "a" "a")   ; => #t
Assert:
  (assert-true (= 1 1))
  (assert-true (= 1 1 1))
  (assert-false (= 1 2))
  (assert-true (= "a" "a"))
Seealso: ==, !=, <, >
Note: Alias for ==. Both = and == are NULL-safe variadic equality.

Name: ==
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Variadic equality comparison (NULL-safe). Identical to =.
  With fewer than two arguments returns #t. With two or more, checks that
  all adjacent pairs are equal.
Signature: (== a b ...)
Examples:
  (== 1 1)      ; => #t
  (== 1 1 1)    ; => #t
  (== 1 2)      ; => #f
Assert:
  (assert-true (== 1 1))
  (assert-true (== 1 1 1))
  (assert-false (== 1 2))
Seealso: =, !=, <, >

Name: !=
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Inequality comparison (NULL-safe). Returns #t if a and b are
  not equal.
Signature: (!= a b)
Examples:
  (!= 1 2)      ; => #t
  (!= 1 1)      ; => #f
  (!= #nil #nil) ; => #f
Assert:
  (assert-true (!= 1 2))
  (assert-false (!= 1 1))
  (assert-false (!= #nil #nil))
Seealso: =, ==

Name: not
Kind: builtin
Vignette: lang-core
Section: Comparison
Description: Logical negation using Arl truthiness. Returns #t if x is falsy
  (0, #f, or #nil), #f otherwise.
Signature: (not x)
Examples:
  (not #f)      ; => #t
  (not #nil)    ; => #t
  (not 0)       ; => #t
  (not 1)       ; => #f
  (not "hi")    ; => #f
Assert:
  (assert-true (not #f))
  (assert-true (not #nil))
  (assert-true (not 0))
  (assert-false (not 1))
  (assert-false (not "hi"))
Seealso: and, or

Name: pair?
Kind: builtin
Vignette: lang-types
Section: List and Pair Predicates
Description: Return #t if x is a cons cell (dotted pair).
Signature: (pair? x)
Examples:
  (pair? (cons 1 2))        ; => #t (dotted pair)
  (pair? (cons 1 (list 2 3)))  ; => #f (cons onto list returns a list)
  (pair? '(1 2 3))          ; => #f (quoted list, not a cons cell)
  (pair? '())               ; => #f
Assert:
  (assert-true (pair? (cons 1 2)))
  (assert-false (pair? (cons 1 (list 2 3))))
  (assert-false (pair? '(1 2 3)))
  (assert-false (pair? '()))
Seealso: list?, null?, atom?

Name: car
Kind: builtin
Vignette: lang-list-seq
Section: List Operations
Description: Return first element or #nil.
Signature: (car lst)
Examples:
  (car (list 1 2 3))    ; => 1
  (car (list))           ; => #nil
  (car (cons 'a 'b))    ; => a
Assert:
  (assert-equal 1 (car (list 1 2 3)))
  (assert-equal #nil (car (list)))
Seealso: cdr, cons, first

Name: cdr
Kind: builtin
Vignette: lang-list-seq
Section: List Operations
Description: Return list without first element (or cdr of dotted pair).
Signature: (cdr lst)
Examples:
  (cdr (list 1 2 3))    ; => (2 3)
  (cdr (list 1))        ; => ()
  (cdr (cons 'a 'b))    ; => b
Assert:
  (assert-equal (list 2 3) (cdr (list 1 2 3)))
  (assert-equal (list) (cdr (list 1)))
Seealso: car, cons, rest

Name: cons
Kind: builtin
Vignette: lang-list-seq
Section: List Operations
Description: Prepend item to list or call; dotted pair when cdr is not a list.
Signature: (cons item lst)
Examples:
  (cons 1 (list 2 3))   ; => (1 2 3)
  (cons 'a (list 'b))   ; => (a b)
  (cons 'a 'b)          ; => dotted pair (a . b)
Assert:
  (assert-equal (list 1 2 3) (cons 1 (list 2 3)))
  (assert-equal (list 'a 'b) (cons 'a (list 'b)))
Seealso: car, cdr, append

Name: eval
Kind: builtin
Vignette: lang-core
Section: Evaluation
Description: Evaluate a Arl expression in the current environment.
Signature: (eval expr)
Examples:
  (eval '(+ 1 2))           ; => 3
  (eval '(list 1 2 3))      ; => (1 2 3)
Assert:
  (assert-equal 3 (eval '(+ 1 2)))
  (assert-equal (list 1 2 3) (eval '(list 1 2 3)))
Seealso: r-eval, read, macroexpand

Name: read
Kind: builtin
Vignette: lang-core
Section: Evaluation
Description: Parse a string into a Arl expression without evaluating it.
Signature: (read source)
Examples:
  (read "(+ 1 2)")          ; => (+ 1 2) (unevaluated)
  (read "42")               ; => 42
  (read "foo")              ; => foo (symbol)
Assert:
  (assert-equal 42 (read "42"))
  (assert-equal 3 (eval (read "(+ 1 2)")))
Seealso: eval, read-from-string
Note: Returns the first expression from the source string, or #nil if
  the string contains no expressions. Like R's parse(), but returns Arl
  S-expressions.

Name: write
Kind: builtin
Vignette: lang-core
Section: Evaluation
Description: Convert a Arl expression to its string representation.
  The inverse of read.
Signature: (write expr)
Examples:
  (write '(+ 1 2))          ; => "(+ 1 2)"
  (write 42)                ; => "42"
  (write "hello")           ; => "\"hello\""
  (write #t)                ; => "#t"
Assert:
  (assert-equal "42" (write 42))
  (assert-equal "#t" (write #t))
Seealso: read, eval, format-value
Note: Produces output that can be parsed back with read, ensuring the
  round-trip property: (read (write expr)) equals expr for any expression
  produced by read.

Name: help
Kind: builtin
Vignette: lang-core
Section: Documentation
Description: Show help for a topic. Topic may be a symbol or string.
  Use :package to force R help lookup from a specific package.
Signature: (help topic [:package pkg])
Examples:
  (help if)
  (help "sum")
  (help "writeLines" :package "base")
Assert:
  (assert-no-error (help if))
  (assert-no-error (help "sum"))
  (assert-no-error (help "writeLines" :package "base"))
Seealso: doc, macroexpand

Name: load
Kind: builtin
Vignette: lang-core
Section: Evaluation
Description: Load and evaluate an Arl source file in the target environment.
  Defaults to the current environment.
Signature: (load path [env])
Examples:
  (define __load_demo_path (tempfile :fileext ".arl"))
  (writeLines (c "(define __load_demo_value 42)") __load_demo_path)
  (load __load_demo_path)
  __load_demo_value
  (define __load_demo_env (new.env :parent (current-env)))
  (load __load_demo_path __load_demo_env)
  (get "__load_demo_value" __load_demo_env)
  (unlink __load_demo_path)
Assert:
  (define __load_test_path (tempfile :fileext ".arl"))
  (writeLines (c "(define __load_test_value 7)") __load_test_path)
  (load __load_test_path)
  (assert-equal 7 __load_test_value)
  (define __load_test_env (new.env :parent (current-env)))
  (load __load_test_path __load_test_env)
  (assert-equal 7 (get "__load_test_value" __load_test_env))
  (unlink __load_test_path)
Seealso: eval, read, run, current-env

Name: capture
Kind: builtin
Vignette: lang-core
Section: Macro Utilities
Description: Mark a symbol for intentional capture in a macro body,
  overriding hygiene.
Signature: (capture 'sym expr)
Examples:
  (defmacro aif (test then alt)
    `(let ((it ,test))
       (if it ,(capture 'it then) ,(capture 'it alt))))
  (aif (+ 2 3) it 0)          ; => 5
Assert:
  (assert-equal 5 (aif (+ 2 3) it 0))
Seealso: gensym, macroexpand, defmacro
Note: Use capture when writing anaphoric macros or other macros that
  intentionally introduce a binding visible to the caller. Without
  capture, Arl's automatic hygiene renames macro-introduced symbols to
  prevent accidental capture.

Name: gensym
Kind: builtin
Vignette: lang-core
Section: Macro Utilities
Description: Generate a unique uninterned symbol, useful for writing
  hygienic macros.
Signature: (gensym [prefix])
Examples:
  (gensym)                  ; => G1 (unique symbol)
  (gensym "tmp")            ; => tmp2 (unique with prefix)
Assert:
  (assert-true (symbol? (gensym)))
  (assert-true (symbol? (gensym "tmp")))
Seealso: macroexpand, macroexpand-1
Note: Each call returns a fresh symbol guaranteed not to conflict with
  user-defined names. The optional prefix defaults to "G".

Name: macro?
Kind: builtin
Vignette: lang-core
Section: Macro Utilities
Description: Return #t if the symbol names a currently-defined macro.
Signature: (macro? sym)
Examples:
  (defmacro my-mac (x) x)
  (macro? 'my-mac)          ; => #t
  (macro? 'car)             ; => #f
Assert:
  (assert-true (macro? 'my-mac))
  (assert-false (macro? 'car))

Name: macroexpand
Kind: builtin
Vignette: lang-core
Section: Macro Utilities
Description: Recursively expand all macros in expr until no macro calls
  remain.
Signature: (macroexpand expr)
Examples:
  (defmacro my-when (test body)
    `(if ,test ,body #nil))
  (macroexpand '(my-when #t 42))  ; => (if #t 42 #nil)
Assert:
  (assert-equal '(if #t 42 #nil) (macroexpand '(my-when #t 42)))
Seealso: macroexpand-1, macro?, gensym
Note: Also available as `macroexpand-all` (alias).

Name: promise?
Kind: builtin
Vignette: lang-core
Section: Promises (Lazy Evaluation)
Description: Return #t if x is a promise (created with `delay`).
Signature: (promise? x)
Examples:
  (define p (delay (+ 1 2)))
  (promise? p)              ; => #t
  (promise? 42)             ; => #f
Assert:
  (define __p (delay (+ 1 2)))
  (assert-true (promise? __p))
  (assert-false (promise? 42))
Seealso: force, promise-expr

Name: force
Kind: builtin
Vignette: lang-core
Section: Promises (Lazy Evaluation)
Description: Force a promise, evaluating its delayed expression and
  returning the result. If x is not a promise, returns x unchanged.
Signature: (force x)
Examples:
  (define p (delay (+ 1 2)))
  (force p)                 ; => 3
  (force 42)                ; => 42 (non-promise passed through)
Assert:
  (define __fp (delay (+ 10 20)))
  (assert-equal 30 (force __fp))
  (assert-equal 42 (force 42))
Seealso: promise?, promise-expr, delay

Name: promise-expr
Kind: builtin
Vignette: lang-core
Section: Promises (Lazy Evaluation)
Description: Extract the unevaluated expression from a promise.
Signature: (promise-expr p)
Examples:
  (define p (delay (+ 1 2)))
  (promise-expr p)          ; => (+ 1 2)
Assert:
  (define __pe (delay (+ 1 2)))
  (assert-equal '(+ 1 2) (promise-expr __pe))
Seealso: promise?, force, delay
Note: Signals an error if p is not a promise.

Name: r-eval
Kind: builtin
Vignette: lang-core
Section: Evaluation
Description: Evaluate an R expression directly via R's eval(), bypassing
  Arl's compiler.
Signature: (r-eval expr)
Examples:
  (r-eval (quote (seq_len 5)))  ; => c(1, 2, 3, 4, 5)
Assert:
  (assert-equal (c 1 2 3 4 5) (r-eval (quote (seq_len 5))))
Seealso: eval, r-call
Note: Useful for evaluating raw R calls that use R control flow (for,
  while) or other constructs that Arl normally overrides.

Name: toplevel-env
Kind: builtin
Vignette: lang-core
Section: Environment Introspection
Description: Return the top-level engine environment where user definitions
  and standard library exports live. This is the environment used by
  eval_text and the REPL. Note that builtins-env sits between this
  environment and R's baseenv() in the parent chain.
Signature: (toplevel-env)
Examples:
  (environment? (toplevel-env))  ; => #t
Assert:
  (assert-true (environment? (toplevel-env)))
Seealso: current-env, builtins-env

Name: builtins-env
Kind: builtin
Vignette: lang-core
Section: Environment Introspection
Description: Return the builtins environment that sits between the
  top-level engine environment and R's baseenv(). Contains core
  operators (=, +, *, <, etc.), module/macro registries, and
  environment commands. Module environments parent to this
  environment rather than to toplevel-env, which enforces that
  modules must explicitly import stdlib functions.
Signature: (builtins-env)
Examples:
  (environment? (builtins-env))  ; => #t
Assert:
  (assert-true (environment? (builtins-env)))
Seealso: toplevel-env, current-env

Name: current-env
Kind: builtin
Vignette: lang-core
Section: Environment Introspection
Description: Return the current Arl evaluation environment.
Signature: (current-env)
Examples:
  (environment? (current-env))  ; => #t
Assert:
  (assert-true (environment? (current-env)))
Seealso: toplevel-env, builtins-env

Name: doc!
Kind: builtin
Vignette: lang-core
Section: Documentation
Description: Attach documentation fields to a function. With a single
  string argument, sets the description (backward compatible). With keyword
  arguments, sets specific fields and merges with existing documentation.
Signature: (doc! fn "docstring") or (doc! fn :description "..." :examples "...")
Noeval: yes
Examples:
  (doc! my-fn "Doubles the input.")
  (doc! my-fn :examples "(my-fn 3) ; => 6")
  (doc! my-fn :description "Doubles." :note "Fast path.")
Assert:
  (define __doc-test-fn (lambda (x) (* x 2)))
  (doc! __doc-test-fn "Doubles the input.")
  (assert-equal "Doubles the input." (doc __doc-test-fn))
  (doc! __doc-test-fn :examples "(my-fn 3) ; => 6")
  (assert-equal "(my-fn 3) ; => 6" (doc __doc-test-fn "examples"))
Seealso: doc, help

Name: doc
Kind: builtin
Vignette: lang-core
Section: Documentation
Description: Retrieve documentation from a function. With no field argument,
  returns the description. Pass a field name string to get a specific field,
  or "all" to get the full documentation list.
Signature: (doc fn) or (doc fn "field")
Noeval: yes
Examples:
  (doc my-fn)              ; => "Doubles the input."
  (doc my-fn "examples")   ; => "(my-fn 3) ; => 6"
  (doc my-fn "all")        ; => named list of all fields
Assert:
  (define __doc-get-fn (lambda (x) (+ x 1)))
  (doc! __doc-get-fn "Increments input.")
  (assert-equal "Increments input." (doc __doc-get-fn))
  (doc! __doc-get-fn :note "Simple function.")
  (assert-equal "Simple function." (doc __doc-get-fn "note"))
Seealso: doc!, help

Name: module-ref
Kind: builtin
Vignette: lang-core
Section: Module Introspection
Description: Look up a symbol in a module or namespace. This is the
  desugared form of qualified access: `mod/sym` parses as
  `(module-ref mod sym)`.
Signature: (module-ref mod sym)
Examples:
  (import math)
  (module-ref math inc)  ; same as math/inc
Assert:
  (module __mr-mod (export __mr-x) (define __mr-x 99))
  (import __mr-mod)
  (assert-equal 99 (module-ref __mr-mod __mr-x))
Seealso: import, module?, module-exports

Name: module?
Kind: builtin
Vignette: lang-core
Section: Module Introspection
Description: Return #t if x is a module environment (registered in the
  module registry).
Signature: (module? x)
Examples:
  (import math)
  (module? math)  ; => #t
  (module? 42)    ; => #f
Assert:
  (module __mp-mod (export __mp-a) (define __mp-a 1))
  (import __mp-mod)
  (assert-true (module? __mp-mod))
  (assert-false (module? 42))
Seealso: namespace?, module-exports, module-name

Name: namespace?
Kind: builtin
Vignette: lang-core
Section: Module Introspection
Description: Return #t if x is a namespace node (created by importing a
  hierarchical module name like `a/b`).
Signature: (namespace? x)
Examples:
  (namespace? 42)      ; => #f
  (namespace? "hello") ; => #f
Assert:
  (assert-false (namespace? 42))
  (assert-false (namespace? "hello"))
Seealso: module?, module-ref

Name: module-exports
Kind: builtin
Vignette: lang-core
Section: Module Introspection
Description: Return the list of exported symbol names from a module.
Signature: (module-exports mod)
Examples:
  (import math)
  (module-exports math)  ; => list of exported names
Assert:
  (module __me-mod (export __me-x __me-y) (define __me-x 1) (define __me-y 2))
  (import __me-mod)
  (define __me-exports (module-exports __me-mod))
  (assert-true (list? __me-exports))
Seealso: module?, module-name, module-ref

Name: module-name
Kind: builtin
Vignette: lang-core
Section: Module Introspection
Description: Return the canonical name string of a module.
Signature: (module-name mod)
Examples:
  (import math)
  (module-name math)  ; => "math"
Assert:
  (module __mn-mod (export __mn-a) (define __mn-a 1))
  (import __mn-mod)
  (assert-equal "__mn-mod" (module-name __mn-mod))
Seealso: module?, module-exports
