core

%#

(% dividend divisor)

Alias for rem. Returns the truncated remainder of dividend / divisor. Result has the same sign as dividend.

Example:

(% 11 2) ; => 1

*#

(*)
(* x)
(* x y)
(* x y z)
(* x y z w)
(* x y z w & more)

Returns the product of all elements in xs. All elements in xs must be numbers. If xs is empty, return 1.

Example:

(* 2 3 4) ; => 24

*'#

(*' & xs)

Auto-promoting variant of *. Integer results are returned as BigInt; floats and rationals pass through unchanged.

Example:

(*' 2 3) ; => 6

**#

(** a x)

Return a to the power of x.

Example:

(** 2 8) ; => 256

*argv*#

Vector of user arguments passed to the script (excludes program name). Use program to get the script path or namespace.

*assert*#

Controls whether assert expands to a runtime check. When logical false at macroexpansion time, assert expands to nil and performs no runtime check, matching Clojure's compile-time *assert* semantics. Defaults to true. To disable globally, set the core binding before compilation via PHP: \Phel::addDefinition("phel\\core", "*assert*", false).

*build-mode*#

*file*#

*file*

Returns the path of the current source file.

Example:

(println *file*) ; => "/path/to/current/file.phel"

*ns*#

*ns*

Returns the namespace in the current scope.

Example:

(println *ns*) ; => "my-app.core"

*program*#

The script path or namespace being executed.

+#

(+)
(+ x)
(+ x y)
(+ x y z)
(+ x y z w)
(+ x y z w & more)

Returns the sum of all elements in xs. All elements xs must be numbers. If xs is empty, return 0.

Example:

(+ 1 2 3) ; => 6

+'#

(+' & xs)

Auto-promoting variant of +. Integer results are returned as BigInt so callers get explicit promotion semantics; floats and rationals pass through unchanged. Equivalent to + for overflow protection (Phel's + already auto-promotes on overflow), kept for .cljc interop.

Example:

(+' 1 2) ; => 3

-#

(-)
(- x)
(- x y)
(- x y z)
(- x y z w)
(- x y z w & more)

Returns the difference of all elements in xs. If xs is empty, return 0. If xs has one element, return the negative value of that element.

Example:

(- 10 3 2) ; => 5
(- 4) ; => -4

-'#

(-' & xs)

Auto-promoting variant of -. Integer results are returned as BigInt; floats and rationals pass through unchanged.

Example:

(-' 5 2) ; => 3

->#

(-> x & forms)

Threads the expr through the forms. Inserts x as the second item in the first form, making a list of it if it is not a list already. If there are more forms, insert the first form as the second item in the second form, etc.

->>#

(->> x & forms)

Threads the expr through the forms. Inserts x as the last item in the first form, making a list of it if it is not a list already. If there are more forms, insert the first form as the last item in the second form, etc.

->closure#

(->closure f)

Converts a Phel function to a PHP Closure. Many PHP libraries (AMPHP, ReactPHP) type-hint \Closure and reject Phel's AbstractFn even though it is callable. This bridges the gap.

Example:

(->closure (fn [x] (* x 2)))

/#

(/)
(/ x)
(/ x y)
(/ x y & more)

Returns the nominator divided by all the denominators. If xs is empty, returns 1. If xs has one value, returns the reciprocal of x.

Integer division with a non-zero remainder returns a Ratio (e.g. (/ 1 2) => 1/2). Use (/ 1.0 2) or (double ...) for float division.

Example:

(/ 1 2) ; => 1/2
(/ 10 2) ; => 5

<#

(< a)
(< a b)
(< a b & more)

Checks if each argument is strictly less than the following argument.

Example:

(< 1 2 3 4) ; => true

<=#

(<= a)
(<= a b)
(<= a b & more)

Checks if each argument is less than or equal to the following argument. Returns a boolean.

Example:

(<= 1 1 2) ; => true

<=>#

(<=> a b)

Alias for the spaceship PHP operator in ascending order. Returns an int. Dispatches on Ratio and BigInt so numeric ordering stays correct for those types.

Example:

(<=> 1 2) ; => -1
(<=> 2 2) ; => 0

=#

(= a)
(= a b)
(= a b & more)

Checks if all values are equal (value equality, not identity).

Example:

(= [1 2 3] [1 2 3]) ; => true

==#

(== a)
(== a b)
(== a b & more)

Numeric equality comparison. Returns true if all arguments have the same numeric value regardless of type (e.g. int vs float); throws on non-numeric arguments. Unlike =, which is value-and-type-strict, == treats 1 and 1.0 as equal, matching Clojure's clojure.core/==.

Example:

(== 1 1.0) ; => true

>#

(> a)
(> a b)
(> a b & more)

Checks if each argument is strictly greater than the following argument.

Example:

(> 4 3 2 1) ; => true

>=#

(>= a)
(>= a b)
(>= a b & more)

Checks if each argument is greater than or equal to the following argument. Returns a boolean.

Example:

(>= 3 3 2) ; => true

>=<#

(>=< a b)

Alias for the spaceship PHP operator in descending order. Returns an int.

Example:

(>=< 1 2) ; => 1

NAN#

Constant for Not a Number (NAN) values.

NaN?#

(NaN? x)

Checks if x is not a number. Alias for nan?, matching Clojure's NaN?.

Example:

(NaN? ##NaN) ; => true

abs#

(abs x)

Returns the absolute value of x. Throws InvalidArgumentException if x is not a number; PHP's permissive abs(null) => 0 / abs("abc") coercions are rejected.

Example:

(abs -5) ; => 5

aclone#

(aclone arr)

Returns a shallow copy of a PHP array. The returned array is a distinct value, mutating the copy via aset does not affect the original, and vice versa. Matches Clojure's aclone for .cljc interop; raises InvalidArgumentException on non-array inputs since Phel's persistent collections are already immutable and don't need cloning.

Example:

(aclone (object-array 3)) ; => <PHP-Array [nil, nil, nil]>

add-tap#

(add-tap f)

Registers f as a tap. Every call to tap> invokes each registered tap with the tapped value. Returns nil.

Example:

(add-tap println)
(tap> 42) ; prints 42

add-watch#

(add-watch variable key f)

Adds a watch function to a variable. The watch fn is called when the variable changes with four arguments: key, ref, old-value, new-value.

Example:

(add-watch my-var :logger (fn [key ref old new] (println old "->" new)))

aget#

(aget arr index)
(aget arr index & indices)

Returns the value at index in a PHP array. With multiple indices, accesses nested arrays: (aget arr i j) is (aget (aget arr i) j). Matches Clojure's aget for .cljc interop.

Example:

(aget (php-indexed-array 10 20 30) 1) ; => 20

alength#

(alength arr)

Returns the number of elements in a PHP array. Matches Clojure's alength for .cljc interop; raises InvalidArgumentException on non-array inputs (use count for collections).

Example:

(alength (int-array 3)) ; => 3

all?#

(all? pred coll)

Returns true if predicate is true for every element in collection, false otherwise.

Example:

(all? even? [2 4 6 8]) ; => true

alter-meta!#

(alter-meta! r f & args)

Replaces the metadata on r with (apply f current-meta args). Works on Var handles (mutates per-var metadata, surviving subsequent def redefinitions) and on atoms (mutates the atom's own meta map). Returns the new metadata map.

Example:

(alter-meta! #'my-var assoc :tag :int)

alter-var-root#

(alter-var-root v f & args)

Replaces the root binding of v with (apply f current-root args). Returns the new root value. v must be a Var; pass an atom and you get a clear error pointing at swap! instead.

Example:

(def counter 0)
(alter-var-root #'counter inc) ; => 1

ancestors#

(ancestors tag)
(ancestors h tag)

Returns the set of all transitive ancestors of tag, or nil. When a hierarchy is provided, consults it; otherwise uses the global hierarchy.

and#

(and & args)

Evaluates expressions left to right, returning the first falsy value or the last value.

Example:

(and true 1 "hello") ; => "hello"

any?#

(any? _)

Returns true given any argument, including nil and false. Mirrors Clojure's clojure.core/any?, useful as a default predicate in spec / validation contexts where every value should be accepted.

Example:

(any? nil) ; => true
(any? 0) ; => true

apply#

(apply f expr*)

Calls the function with the given arguments. The last argument must be a list of values, which are passed as separate arguments, rather than a single list. Apply returns the result of the calling function.

Example:

(apply + [1 2 3]) ; => 6

arity#

(arity f)

Returns the number of required parameters of the function f. For a variadic function this is the number of parameters before &. A multi-arity function compiles to a single variadic dispatch, so it reports 0.

Example:

(arity inc) ; => 1
(arity swap!) ; => 2

array-map#

Constructs a map from the given key/value pairs. If any keys are equal, later values replace earlier ones, as if by repeated assoc. Phel has no distinct array-map type, so the result is the same persistent map as hash-map, array-map exists for .cljc interop with Clojure sources.

Example:

(array-map :a 1 :b 2) ; => {:a 1, :b 2}

as->#

(as-> expr name & forms)

Binds name to expr, evaluates the first form in the lexical context of that binding, then binds name to that result, repeating for each successive form, returning the result of the last form.

Example:

(as-> 1 x (+ x 2) (* x 3)) ; => 9

aset#

(aset arr idx & more)

Sets the value at index in a PHP array to val. Returns val. With additional indices, navigates nested arrays before setting: (aset arr i j val) sets index j in (aget arr i). Matches Clojure's aset for .cljc interop. This is a macro because PHP arrays are value types; a function wrapper would mutate a copy rather than the original.

Example:

(let [a (php-indexed-array 1 2 3)] (aset a 0 42) (aget a 0)) ; => 42

assert#

(assert expr & [message])

Throws an exception if expr is falsy. Optional message string. Used for precondition checking in application code. When *assert* is logical false at macroexpansion time, assert expands to nil and performs no runtime check.

assoc#

(assoc ds key value)
(assoc ds key value & more)

Associates one or more key-value pairs with a collection. Additional key-value pairs beyond the first are applied in order. Throws if an odd number of extra arguments is provided.

Example:

(assoc {:a 1} :b 2) ; => {:a 1, :b 2}
(assoc {:a 1} :b 2 :c 3) ; => {:a 1, :b 2, :c 3}

assoc!#

(assoc! tcoll key value)
(assoc! tcoll key value & more)

Associates one or more key-value pairs with a transient collection, mutating it in place. Works on transient hash-maps and transient vectors. Variadic forms apply each key-value pair in order. A trailing key without a value is associated with nil. Raises InvalidArgumentException when tcoll is not a supported transient collection. Matches Clojure's assoc! semantics.

Example:

(persistent! (assoc! (transient {}) :a 1 :b 2)) ; => {:a 1, :b 2}

assoc-in#

(assoc-in ds [k & ks] v)

Associates a value in a nested data structure at the given path.

Creates intermediate maps if they don't exist.

Example:

(assoc-in {:a {:b 1}} [:a :c] 2) ; => {:a {:b 1, :c 2}}

associative?#

(associative? x)

Returns true if x is an associative data structure, false otherwise.

Associative data structures include vectors, hash maps, structs, and PHP arrays (both indexed and associative), matching Clojure's Associative protocol.

Example:

(associative? [1 2 3]) ; => true

async#

(async & body)

Runs body asynchronously in a new fiber. Returns an Amp\Future.

Captures the caller's dynamic bindings and reinstalls them inside the fiber, so bindings established outside async are visible to body (binding conveyance, as in Clojure's future).

Example:

(async (do-something))

atom#

(atom value & opts)

Creates a new atom with the given value.

Atoms provide a way to manage mutable state. Use reset! to set a new value and swap! to update based on the current value.

Optional :meta and :validator keyword arguments may follow the value in any order. The validator is applied to the initial value when set.

Example:

(def counter (atom 0))
(atom 0 :meta {:tag :counter} :validator number?)

atom?#

(atom? x)

Returns true if the given value is an atom.

Example:

(atom? (atom 1)) ; => true

await#

(await future)

Blocks the current fiber until the Future resolves and returns its value. Accepts either a raw Amp\Future or a Future wrapper.

Example:

(await (async (+ 1 2)))

await-all#

(await-all futures)

Awaits all Futures in the given collection. Returns a vector of results in the same order as the input collection, regardless of which Future resolves first. Accepts a mix of raw Amp\Future and Future wrappers.

Example:

(await-all [(async 1) (async 2)])

await-any#

(await-any futures)

Awaits the first Future to resolve. Returns its value. Accepts a mix of raw Amp\Future and Future wrappers.

Example:

(await-any [(async 1) (async 2)])

bean#

(bean obj)

Returns a Phel map of the public properties of PHP object obj, with keyword keys. Inverse of hydrate for public-property objects.

Example:

(bean (hydrate "My\\Dto" {:id 1})) ; => {:id 1}

bigdec#

(bigdec x)

Coerces x to a Phel\Lang\BigDecimal. Accepts BigDecimal (returned as-is), ints, floats (via the shortest round-trip decimal of the float), BigInt, Ratio (computed via exact decimal division; throws ArithmeticError when the expansion does not terminate, matching (bigdec 1/3)), and numeric strings.

Example:

(bigdec 1.5) ; => 1.5M
(bigdec 1/2) ; => 0.5M
(bigdec "3.14") ; => 3.14M

bigdec?#

(bigdec? x)

Returns true when x is a Phel\Lang\BigDecimal value.

Example:

(bigdec? 1.5M) ; => true

bigint#

(bigint x)

Coerces x to a Phel\Lang\BigInt. Accepts ints, floats (truncated toward zero, rejecting NaN/Inf), numeric strings, and BigInt values.

Example:

(bigint 42) ; => 42
(bigint 1.9) ; => 1
(bigint "123") ; => 123

bigint?#

(bigint? x)

Returns true when x is a Phel\Lang\BigInt value.

Example:

(bigint? (Phel.Lang.BigInt/fromInt 1)) ; => true

biginteger#

(biginteger x)

Alias for bigint. Coerces x to a Phel\Lang\BigInt.

Example:

(biginteger 42) ; => 42

binding#

(binding bindings & body)

Temporarily rebinds dynamic vars while executing body.

Each var in bindings must be tagged ^:dynamic at its def. The rebinding is fiber-local: concurrent fibers observe independent values, and child futures (future, async, future-fiber) inherit the bindings active at their creation.

Throws at runtime if any var in the bindings vector is not :dynamic. To swap a non-dynamic var for the duration of an expression (e.g. mocking in tests), use with-redefs.

bit-and#

(bit-and x y & args)

Bitwise and.

Example:

(bit-and 12 10) ; => 8

bit-and-not#

(bit-and-not x y & args)

Bitwise and with the complement of each subsequent argument: (bit-and-not x y) is x & ~y. Additional arguments are folded in left to right, clearing every bit that is set in any of them.

Example:

(bit-and-not 0xFF 0x0F) ; => 240

bit-clear#

(bit-clear x n)

Returns the integer x with the bit at index n (0-based, least significant first) cleared to 0.

Example:

(bit-clear 7 1) ; => 5

bit-flip#

(bit-flip x n)

Returns the integer x with the bit at index n (0-based, least significant first) toggled.

Example:

(bit-flip 5 1) ; => 7

bit-not#

(bit-not x)

Bitwise complement.

Example:

(bit-not 0) ; => -1

bit-or#

(bit-or x y & args)

Bitwise or.

Example:

(bit-or 12 10) ; => 14

bit-set#

(bit-set x n)

Returns the integer x with the bit at index n (0-based, least significant first) set to 1.

Example:

(bit-set 0 2) ; => 4

bit-shift-left#

(bit-shift-left x n)

Bitwise shift left.

Example:

(bit-shift-left 1 4) ; => 16

bit-shift-right#

(bit-shift-right x n)

Bitwise shift right.

Example:

(bit-shift-right 16 2) ; => 4

bit-test#

(bit-test x n)

Returns true if the bit at index n (0-based, least significant first) of the integer x is set, false otherwise.

Example:

(bit-test 5 0) ; => true

bit-xor#

(bit-xor x y & args)

Bitwise xor.

Example:

(bit-xor 12 10) ; => 6

boolean#

(boolean x)

Coerces x to a boolean. Returns false if x is nil or false, true otherwise.

Example:

(boolean nil) ; => false

boolean?#

(boolean? x)

Returns true if x is a boolean, false otherwise.

Example:

(boolean? true) ; => true
(boolean? nil) ; => false

bound?#

(bound? v)

Returns true when v has a current root binding in the namespace registry. v must be a Var.

Example:

(bound? #'phel.core/map) ; => true

bounded-count#

(bounded-count n coll)

Returns the number of items in coll, but counts at most n when coll is not counted?. If coll is counted? (its size is known in O(1)) the full count is returned, which may exceed n; otherwise the sequence is walked at most n steps.

Example:

(bounded-count 3 [1 2 3 4 5]) ; => 5
(bounded-count 3 (map inc (range 100))) ; => 3

break#

(break)

Pauses execution and opens an interactive debugger sub-REPL with access to the lexical locals in scope. Type (continue) to resume execution.

Example:

(let [x 41] (break)) ; opens the debugger with x in scope

butlast#

(butlast coll)

Returns all but the last item in coll. Returns nil when coll is nil or has fewer than two items.

Example:

(butlast [1 2 3 4]) ; => (1 2 3)
(butlast [0]) ; => nil

byte#

(byte x)

Coerces x to a signed 8-bit integer in the range -128..127. Decimal values are truncated toward zero. Ratio and BigInt values are accepted (truncate toward zero, then range-check). Values outside the range or non-numeric inputs raise InvalidArgumentException. Phel has no dedicated byte type, so the result is a plain PHP int.

Example:

(byte 127) ; => 127
(byte 1.9) ; => 1
(byte -128) ; => -128

canonical-ns#

(canonical-ns ns-str)

Returns the canonical (dot-separated) form of a namespace string. Pass user-supplied namespace strings through this before any registry lookup or write.

Example:

(canonical-ns "phel\core") ; => "phel.core"

case#

(case e & pairs)

Evaluates expression and matches it against constant test values, returning the associated result.

Example:

(case x 1 "one" 2 "two" "other") ; => "one" (when x is 1)

cat#

(cat rf)

A transducer that concatenates the contents of each input into the reduction.

Example:

(transduce cat conj [] [[1 2] [3 4]]) ; => [1 2 3 4]

catch#

(catch exception-type exception-name expr*)

Handle exceptions thrown in a try block by matching on the provided exception type. The caught exception is bound to exception-name while evaluating the expressions.

Example:

(try (throw (new Exception "error")) (catch Exception e (.getMessage e)))

ceil#

(ceil x)

Returns the smallest integer not less than x. Ints and BigInt values are returned unchanged. Ratios collapse via ceiling division. Floats route through PHP's ceil.

Example:

(ceil 1.2) ; => 2.0
(ceil -1.7) ; => -1.0
(ceil 7/3) ; => 3

char#

(char x)

Coerces x to a single-character string representing the given Unicode code point. Accepts a non-negative integer (the code point, converted via mb_chr) or a single-character string, which is returned as-is. Phel has no dedicated char type, character literals such as \A are already single-character strings, so the result is always a plain string. Matches Clojure's char for .cljc interop; raises InvalidArgumentException on negative ints, non-single-character strings, and all other inputs.

Example:

(char 65) ; => "A"
(char 32) ; => " "
(char \A) ; => "A"

char?#

(char? x)

Returns true if x is a single-character string, false otherwise. Phel has no dedicated character type, character literals such as \A are already single-character strings, so char? is true for any string of length 1 (UTF-8 counted). Matches ClojureScript's char? for .cljc interop; Clojure/JVM's char? tests for the distinct Character type, which does not exist here.

Example:

(char? \A) ; => true
(char? "a") ; => true
(char? "ab") ; => false

class#

(class x)

Returns a Phel\Lang\PhpClass for x. With an object argument returns the class of the object. With a string argument resolves the named class or interface FQN. Throws InvalidArgumentException for any other input.

Example:

(class (new stdClass)) ; => stdClass

class-name#

(class-name c)

Returns the FQN string of c (a Phel\Lang\PhpClass). Leading backslashes are not preserved (e.g. \stdClass becomes stdClass).

Example:

(class-name (class "stdClass")) ; => "stdClass"

class?#

(class? x)

Returns true if x is a Phel\Lang\PhpClass value.

Example:

(class? (class (new stdClass))) ; => true

coerce-in#

(coerce-in v min max)

Returns v if it is in the range, or min if v is less than min, or max if v is greater than max.

Example:

(coerce-in 5 0 10) ; => 5
(coerce-in 15 0 10) ; => 10

coll?#

(coll? x)

Returns true if x is a persistent collection, vector, list, hash-map (including sorted-map), struct, set (including sorted-set), or lazy-seq, and false otherwise. Strings, numbers, nil, booleans, keywords, symbols, and plain PHP arrays are not considered collections, matching Clojure's IPersistentCollection membership.

Example:

(coll? [1 2 3]) ; => true
(coll? "abc") ; => false

comment#

(comment &)

Ignores the body of the comment.

comp#

(comp)
(comp outer)
(comp outer inner)
(comp outer inner & fs)

Takes a list of functions and returns a function that is the composition of those functions.

Example:

((comp inc (fn [x] (* x 2))) 3) ; => 7

compact#

(compact coll & values)

Returns a lazy sequence with specified values removed from coll. If no values are specified, removes nil values by default.

Example:

(compact [1 nil 2 nil 3]) ; => (1 2 3)

compare#

(compare x y)

Compares x and y, returning a negative integer, zero, or a positive integer when x is less than, equal to, or greater than y.

nil is less than every non-nil value and equal to itself. Numbers are compared across the numeric tower (int, float, Ratio, BigInt, BigDecimal). Throws InvalidArgumentException when x and y come from mutually incomparable categories (e.g. (compare 1 [])).

Example:

(compare 1 2) ; => -1
(compare :a :a) ; => 0

compare-and-set!#

(compare-and-set! variable old-value new-value)

Atomically sets the value of the atom variable to new-value if and only if its current value is identical (via identical?) to old-value. Returns true when the swap happened, false otherwise.

Example:

(def a (atom 1))
(compare-and-set! a 1 2) ; => true
(compare-and-set! a 1 3) ; => false

compile#

(compile form)

Returns the compiled PHP code string for the given form.

complement#

(complement f)

Returns a function that takes the same arguments as f and returns the opposite truth value.

Example:

((complement even?) 3) ; => true

completing#

(completing f)
(completing f cf)

Takes a reducing function f of 2 args and returns a fn suitable for transduce by adding a 1-arity (completion) that calls cf (default: identity).

Example:

(transduce (filter even?) (completing conj) [] [1 2 3 4]) ; => [2 4]

concat#

(concat)
(concat coll)
(concat coll1 coll2)
(concat coll1 coll2 coll3)
(concat coll1 coll2 coll3 & colls)

Concatenates multiple collections into a lazy sequence.

Example:

(concat [1 2] [3 4]) ; => (1 2 3 4)

cond#

(cond & pairs)

Evaluates test/expression pairs, returning the first matching expression.

Example:

(cond (< x 0) "negative" (> x 0) "positive" "zero") ; => "negative", "positive", or "zero" depending on x

cond->#

(cond-> expr & clauses)

Takes an expression and a set of test/form pairs. Threads expr (via ->) through each form for which the corresponding test expression is true. Note that, unlike cond branching, cond-> threading does not short-circuit after the first true test expression.

Example:

(cond-> 1 true inc false (* 42) true (* 3)) ; => 6

cond->>#

(cond->> expr & clauses)

Takes an expression and a set of test/form pairs. Threads expr (via ->>) through each form for which the corresponding test expression is true. Note that, unlike cond branching, cond->> threading does not short-circuit after the first true test expression.

Example:

(cond->> [1 2 3] true (map inc) false (filter odd?)) ; => (2 3 4)

condp#

(condp pred expr & clauses)

Takes a binary predicate, an expression, and a set of clauses. Each clause takes the form of either: test-expr result-expr test-expr :>> result-fn For each clause, (pred test-expr expr) is evaluated. If it returns logical true, the clause is a match. If a binary clause is a match, result-expr is returned. If a ternary clause with :>> is a match, the result of (pred test-expr expr) is passed to result-fn and the return value is the result. If no clause matches, the default value is returned (if provided), otherwise an exception is thrown.

Example:

(condp = 1 1 "one" 2 "two" "other") ; => "one"

conj#

(conj)
(conj coll)
(conj coll value)
(conj coll value & more)

Returns a new collection with values added. Appends to vectors/sets, prepends to lists.

Example:

(conj [1 2] 3) ; => [1 2 3]

conj!#

(conj!)
(conj! tcoll)
(conj! tcoll value)
(conj! tcoll value & more)

Adds value to the transient collection tcoll, mutating it in place, and returns tcoll. The 'addition' may happen at different 'places' depending on the concrete transient type: transient vectors append at the tail, transient hash-sets add the element (no-op if already present), and transient hash-maps treat value as a [key value] pair (or an associative collection of entries). With zero arguments returns a new empty transient vector. With one argument returns tcoll unchanged. Variadic forms reduce conj! over the remaining values. Raises InvalidArgumentException when tcoll is not a transient collection. Matches Clojure's conj! semantics.

Example:

(persistent (conj! (transient [1 2]) 3)) ; => [1 2 3]

cons#

(cons x coll)

Prepends an element to the beginning of a collection.

Example:

(cons 0 [1 2 3]) ; => [0 1 2 3]

constantly#

(constantly x)

Returns a function that always returns x and ignores any passed arguments.

Example:

((constantly 42) 1 2 3) ; => 42

contains-value?#

(contains-value? coll val)

Returns true if the value is present in the given collection, otherwise returns false.

Example:

(contains-value? {:a 1 :b 2} 2) ; => true

contains?#

(contains? coll key)

Returns true if key is present in collection (checks keys/indices, not values).

Example:

(contains? [10 20 30] 1) ; => true

count#

(count coll)

Counts the number of elements in a sequence. Can be used on everything that implements the PHP Countable interface.

Works with lists, vectors, hash-maps, sets, strings, and PHP arrays. Returns 0 for nil.

Throws for a lazily consumed source that has no size of its own, a transducer pipeline built by eduction, a PHP generator, an iterator. Counting one means draining it, which re-runs the whole pipeline (including its side effects) and still leaves nothing counted behind, so count refuses instead of doing it silently. Realize it first: (count (into [] coll)).

Example:

(count [1 2 3]) ; => 3

counted?#

(counted? coll)

Returns true if coll can report its length in constant time, persistent vectors, lists, hash-maps (including sorted-map), structs, and sets (including sorted-set). Returns false for lazy sequences (counting them requires realizing the whole sequence), strings, numbers, nil, and every other non-counted type. Matches Clojure's counted? semantics, which mirror the clojure.lang.Counted marker interface.

Example:

(counted? [1 2 3]) ; => true
(counted? (range)) ; => false

create-ns#

(create-ns ns-str)

Creates the given namespace if it does not already exist. Returns the namespace name in display form. Existing namespaces are left untouched.

Example:

(create-ns "my-app.tmp") ; => "my-app.tmp"

csv-seq#

(csv-seq filename)
(csv-seq filename options)

Returns a lazy sequence of rows from a CSV file.

Example:

(take 10 (csv-seq "data.csv")) ; => [["col1" "col2"] ["val1" "val2"] ...]

cycle#

(cycle coll)

Returns an infinite lazy sequence that cycles through the elements of collection. Maps are iterated as [key value] pairs.

Example:

(take 7 (cycle [1 2 3])) ; => (1 2 3 1 2 3 1)

dbg#

(dbg)
(dbg expr)

Prints [file:line] form => value to the standard error stream and returns the value unchanged, so it can wrap any subexpression without restructuring code. With no argument prints just [file:line] as a reached-here marker and returns nil.

Example:

(defn area [w h] (* (dbg w) h))
(area 3 4) ; stderr: [src/main.phel:12] w => 3

dbg-write#

(dbg-write message)

Writes message to the standard error stream. Output primitive behind the dbg macro; redefine it with with-redefs to capture debug output in tests.

Example:

(dbg-write "debug line\n")

dec#

(dec x)

Decrements x by one.

Example:

(dec 5) ; => 4

dec'#

(dec' x)

Auto-promoting variant of dec. Integer results are returned as BigInt; floats and rationals pass through unchanged.

Example:

(dec' 1) ; => 0

decimal?#

(decimal? x)

Alias for bigdec?. Returns true when x is a Phel\Lang\BigDecimal.

Example:

(decimal? 1.5M) ; => true

declare#

Declare a global symbol before it is defined.

dedupe#

(dedupe)
(dedupe coll)

Returns a lazy sequence with consecutive duplicate values removed in coll. When called with no args, returns a transducer.

Example:

(dedupe [1 1 2 2 2 3 1 1]) ; => (1 2 3 1)

deep-merge#

(deep-merge)
(deep-merge m)
(deep-merge m1 m2)
(deep-merge m1 m2 & args)

Recursively merges data structures.

Example:

(deep-merge {:a {:x 1}} {:a {:y 2}}) ; => {:a {:x 1, :y 2}}

def#

(def name meta? value)

This special form binds a value to a global symbol.

Example:

(def my-value 42)

def-#

Define a private value that will not be exported.

defenum#

(defenum name & cases)

Defines a native PHP enum. Each case is named by a keyword followed by an optional scalar value (all int or all string); value-less cases produce a pure enum. After the cases, an optional implementations tail (interface symbols with their methods, and a :php block of plain/magic methods) is parsed like defstruct, so an enum can implement interfaces and carry methods. Also defines a Name? predicate.

  (defenum Status :active "active" :inactive "inactive")
  (Status? Status/active) # => true

  (defenum Suit
    :hearts :spades :clubs :diamonds
    Describable
    (describe [this] (.-name this))
    :php
    (label [this] (.-name this)))

defexception#

(defexception name & [parent])

Define a new exception. Optionally pass a parent class to extend (defaults to Exception), so frameworks can catch it by type, e.g. (defexception ProductNotFound RuntimeException). The parent takes any class spelling: bare, dotted (My.Ns.Error), or an alias brought in with :use.

defexception*#

(defexception my-ex)
(defexception my-ex \RuntimeException)

Define a new exception, optionally extending a custom parent class (defaults to \Exception).

Example:

(defexception my-error \RuntimeException)

definterface#

(definterface name & fns)

An interface in Phel defines an abstract set of functions. It is directly mapped to a PHP interface. An interface can be defined by using the definterface macro.

Example:

(definterface name & fns)

definterface*#

(definterface name & fns)

An interface in Phel defines an abstract set of functions. It is directly mapped to a PHP interface. An interface can be defined by using the definterface macro.

Example:

(definterface Greeter (greet [name]))

defmacro#

Define a macro.

defmacro-#

(defmacro- name & fdecl)

Define a private macro that will not be exported.

defmethod#

(defmethod multi-name dispatch-val & fn-tail)

Registers a method implementation for a multimethod.

multi-name is the name of the multimethod defined by defmulti. When extending a multimethod from a different namespace, fully qualify the multi-name (e.g. phel\test/assert-expr) so the methods table is resolved in the multimethod's home namespace. dispatch-val is the value that triggers this method. args and body define the function implementation.

Example:

(defmethod area :circle [{:radius r}] (* 3.14159 r r))

defmulti#

(defmulti name & args)

Defines a multimethod. dispatch-fn is called on the arguments to produce a dispatch value, which is then used to select the appropriate method registered via defmethod.

An optional docstring may be provided between name and dispatch-fn.

If no method matches the dispatch value, the :default method is used (if defined), otherwise an error is thrown.

Example:

(defmulti area "Area of shape." :shape)

defn#

Define a new global function.

defn-#

(defn- name & fdecl)

Define a private function that will not be exported.

defonce#

(defonce name meta? value)

Like def, but only binds the value when name is not already defined in the registry. Useful in REPL workflows where re-evaluating a file should not reset stateful holders (atoms, connections, caches).

Example:

(defonce app-state (atom {}))

defprotocol#

(defprotocol protocol-name & method-specs)

Defines a protocol with the given method signatures. Each method signature is a list of (method-name [args]).

Creates a dispatching function for each method that dispatches on the type of the first argument. Use extend-type to add implementations.

A :default type can be registered via extend-type as a fallback when no specific type implementation is found.

Example:

(defprotocol Stringable (to-string [this]))

defrecord#

(defrecord name fields & impls)

Defines a record type with the given fields, matching Clojure's defrecord.

Expands to a defstruct plus Clojure-style factory functions:

• Name, positional constructor (from defstruct)
• Name?, type predicate (from defstruct)
• ->Name, positional factory, identical to Name
• map->Name, map factory that takes {:field value ...}

An optional tail of protocol/method forms is spliced into an extend-type call, so inline protocol implementations work exactly like Clojure's defrecord body. Only Phel protocols are supported in the inline tail; PHP interface implementations remain on defstruct.

Example:

(defrecord Point [x y] Drawable (draw [this canvas] ...))

defstruct#

(defstruct name keys & implementations)

A Struct is a special kind of Map. It only supports a predefined number of keys and is associated to a global name. The Struct not only defines itself but also a predicate function.

defstruct*#

(defstruct my-struct [a b c])

A Struct is a special kind of Map. It only supports a predefined number of keys and is associated to a global name. The Struct not only defines itself but also a predicate function.

Example:

(defstruct point [x y])

deftype#

(deftype name fields & impls)

Defines a type with the given fields, matching Clojure's deftype syntax.

Expands to a defstruct plus a Clojure-style positional factory:

• Name, positional constructor (from defstruct)
• Name?, type predicate (from defstruct)
• ->Name, positional factory, identical to Name

Unlike defrecord, no map->Name factory is generated.

An optional tail of protocol/method forms is spliced into an extend-type call. Only Phel protocols are supported in the inline tail.

Deviation from Clojure: Phel's deftype shares the map-backed defstruct infrastructure, so instances remain map-like (keys are accessible via get). Clojure's deftype produces a non-map type; if you need that semantic, use native PHP interop.

Example:

(deftype PointT [x y] Drawable (draw [this canvas] ...))

delay#

(delay & body)

Takes a body of expressions and yields a Delay object that will invoke the body only the first time it is forced (via force or deref/@), caching the result.

Example:

(def d (delay (println "computing") 42))

delay?#

(delay? x)

Returns true if x is a Delay.

Example:

(delay? (delay 1)) ; => true

deliver#

(deliver p value)

Delivers value to p if it is still unrealized. Returns p on first delivery, nil if p was already delivered.

Example:

(deliver (promise) 7)

denominator#

(denominator r)

Returns the denominator of r. For rationals the denominator collapses to a PHP int when it fits; integers and BigInt values report 1.

Example:

(denominator 1/2) ; => 2
(denominator 5) ; => 1

deref#

(deref variable & args)

Returns the current value inside an atom or var.

For atoms returns the current cell value; for Var instances returns the current root binding from the namespace registry.

With three arguments, and when variable is a future or promise, blocks for at most timeout-ms milliseconds waiting for it to resolve. If the awaitable has not completed within the timeout, returns timeout-val.

Example:

(deref (atom 42)) ; => 42
(deref #'phel.core/map) ; => <function:map>

derive#

(derive child parent)
(derive h child parent)

Establishes a parent/child relationship between child and parent keywords. With two arguments, mutates the global hierarchy and returns nil. With a hierarchy h, returns a new hierarchy with the relationship added; the original hierarchy is not modified. Throws on cyclic derivation.

Example:

(derive ::square ::shape)

descendants#

(descendants tag)
(descendants h tag)

Returns the set of all descendants of tag, or nil. Only derive-recorded relationships are walked: type inheritance (PHP class hierarchy, protocol extensions) is not surfaced, matching Clojure's contract.

difference#

(difference set & sets)

Difference between multiple sets into a new one.

Example:

(difference (hash-set 1 2 3) (hash-set 2)) ; => #{1 3}

disj#

(disj set)
(disj set k)
(disj set k & ks)

Returns a new set that does not contain the given key(s). Works on hash-sets and sorted-sets. Removing a non-existent key is a no-op. Returns nil when called on nil.

Example:

(disj #{1 2 3} 2) ; => #{1 3}

disj!#

(disj! tcoll)
(disj! tcoll value)
(disj! tcoll value & more)

Removes one or more elements from a transient set, mutating it in place. Raises InvalidArgumentException when tcoll is not a transient set. Matches Clojure's disj! semantics.

Example:

(persistent! (disj! (transient #{1 2 3}) 2)) ; => #{1 3}

display-ns#

(display-ns ns-str)

Returns the display (dot-separated) form of a namespace string. Equivalent to canonical-ns; kept as a separate name so call sites read intent (display vs. canonicalize).

Example:

(display-ns "phel\core") ; => "phel.core"

dissoc#

(dissoc ds)
(dissoc ds k)
(dissoc ds k & ks)

Returns ds without the given keys. With no keys returns ds unchanged.

Example:

(dissoc {:a 1 :b 2} :b) ; => {:a 1}
(dissoc {:a 1 :b 2 :c 3} :a :c) ; => {:b 2}

dissoc!#

(dissoc! tcoll)
(dissoc! tcoll key)
(dissoc! tcoll key & ks)

Dissociates one or more keys from a transient map, mutating it in place. Raises InvalidArgumentException when tcoll is not a transient map. Matches Clojure's dissoc! semantics.

Example:

(persistent! (dissoc! (transient {:a 1 :b 2}) :a)) ; => {:b 2}

dissoc-in#

(dissoc-in ds [k & ks])

Dissociates a value from a nested data structure at the given path.

Example:

(dissoc-in {:a {:b 1 :c 2}} [:a :b]) ; => {:a {:c 2}}

distinct#

(distinct)
(distinct coll)

Returns a lazy sequence with duplicated values removed in coll. When called with no args, returns a transducer.

Example:

(distinct [1 2 1 3 2 4 3]) ; => (1 2 3 4)

distinct?#

(distinct? x & more)

Returns true if no two of the arguments are =. Requires at least one argument.

Example:

(distinct? 1 2 3) ; => true
(distinct? 1 2 1) ; => false

do#

(do expr*)

Evaluates the expressions in order and returns the value of the last expression. If no expression is given, nil is returned.

Example:

(do (println "Hello") (+ 1 2)) ; prints "Hello", returns 3

doall#

(doall coll)

Forces realization of a lazy sequence and returns it as a vector.

Example:

(doall (map println [1 2 3])) ; => [nil nil nil]

dofor#

(dofor head & body)

Repeatedly executes body for side effects with bindings and modifiers as provided by for. Returns nil.

dorun#

(dorun coll)

Forces realization of a lazy sequence for side effects, returns nil.

Example:

(dorun (map println [1 2 3])) ; => nil

doseq#

(doseq seq-exprs & body)

Repeatedly executes body for side effects with Clojure-style bindings. (doseq [x coll] body) runs body once per element of coll. When coll is a map, each iteration sees a [k v] entry pair, so destructuring works just like in Clojure: (doseq [[k v] m] ...). Supports :when, :while, and :let modifiers between bindings.

Example:

(doseq [x [1 2 3]] (println x))
(doseq [[k v] {:a 1 :b 2}] (println k v))

doseq-iterable#

(doseq-iterable coll)

Internal helper used by the doseq macro expansion. Returns a value suitable for Clojure-style iteration: maps are expanded to a sequence of [k v] pair vectors so destructuring binds entries as in Clojure. Every other value is returned unchanged.

dotimes#

(dotimes [binding n] & body)

Evaluates body n times with binding bound to integers from 0 to n-1. Returns nil.

Example:

(dotimes [i 5] (println i))

doto#

(doto x & forms)

Evaluates x then calls all of the methods and functions with the value of x supplied at the front of the given arguments. The forms are evaluated in order. Returns x.

Example:

(deref (doto (atom 0) (reset! 5))) ; => 5

double#

(double x)

Coerces x to a double. In PHP there is no distinction between float and double; both map to the same native PHP float type. Alias for float.

Example:

(double 1) ; => 1.0

double-array#

(double-array size-or-seq)
(double-array size init-val-or-seq)

Creates a PHP array of doubles (same as float-array in PHP). Accepts the same arities and semantics as float-array.

Example:

(double-array 3) ; => <PHP-Array [0.0, 0.0, 0.0]>
(double-array 4 1.5) ; => <PHP-Array [1.5, 1.5, 1.5, 1.5]>

double?#

(double? x)

Returns true if x is a floating-point number, false otherwise. Alias for float?, matching Clojure's double? naming. Since Phel uses PHP floats (IEEE 754 doubles) there is no separate single-precision float type.

Example:

(double? 1.0) ; => true

drop#

(drop n)
(drop n coll)

Drops the first n elements of coll. Returns a lazy sequence. When called with n only, returns a transducer.

Example:

(drop 2 [1 2 3 4 5]) ; => (3 4 5)

drop-last#

(drop-last coll)
(drop-last n coll)

Drops the last n elements of coll. n defaults to 1 when omitted, matching Clojure's (drop-last coll) single-arity form. Returns an empty sequence when coll is nil. Works with any seqable collection including lazy sequences and ranges.

Example:

(drop-last [1 2 3 4 5]) ; => (1 2 3 4)
(drop-last 2 [1 2 3 4 5]) ; => (1 2 3)
(drop-last 5 nil) ; => ()

drop-while#

(drop-while pred)
(drop-while pred coll)

Drops all elements at the front of coll where (pred x) is true. Returns a lazy sequence. When called with pred only, returns a transducer.

Example:

(drop-while #(< % 5) [1 2 3 4 5 6 3 2 1]) ; => (5 6 3 2 1)

eduction#

(eduction & args)

Returns a reducible/iterable applying transducers to coll. The last argument is the source collection; preceding arguments are transducers composed left-to-right. The transformation is re-run on each consumption (no caching), so the result is safe to reduce or iterate multiple times.

Example:

(reduce + (eduction (map inc) (filter odd?) [1 2 3 4])) ; => 8

empty#

(empty coll)

Returns an empty collection of the same category as coll, preserving the original metadata, or nil if coll has no empty equivalent.

Example:

(empty [1 2 3]) ; => []
(empty {:a 1}) ; => {}
(empty (range 10)) ; => ()

empty?#

(empty? x)

Returns true if x would be 0, "" or empty collection, false otherwise. Safe on infinite/lazy sequences: checks the first element instead of counting.

A non-countable iterable (an eduction pipeline, a PHP generator) is answered by pulling a single element, never by counting it.

Example:

(empty? []) ; => true
(empty? [1]) ; => false

eval#

(eval form)

Evaluates a form and return the evaluated results.

Example:

(eval '(+ 1 2)) ; => 3

even?#

(even? x)

Checks if x is even.

Example:

(even? 4) ; => true

every-pred#

(every-pred)
(every-pred p & ps)

Takes a variadic set of predicates and returns a function f that, when called with any number of arguments, returns true if every composing predicate returns a logical true value against every argument, and false otherwise. The returned function short-circuits on the first logical false result: arguments after it are not inspected, and predicates after it are not tried. Predicates are consulted in the order supplied; for a given predicate, arguments are consulted left-to-right. With no arguments the returned function returns true.

Example:

((every-pred even? pos?) 2 4 6) ; => true
((every-pred even? pos?) 2 -4) ; => false

every?#

(every? pred coll)

Returns true if predicate is true for every element in collection, false otherwise. Alias for all?.

Example:

(every? even? [2 4 6 8]) ; => true

ex-cause#

(ex-cause ex)

Returns the cause of an exception, or nil.

Example:

(ex-cause (ex-info "boom" {})) ; => nil

ex-data#

(ex-data ex)

Returns the data map from an ex-info exception, or nil if not an ExceptionInfo.

Example:

(ex-data (ex-info "boom" {:a 1})) ; => {:a 1}

ex-info#

(ex-info msg data)
(ex-info msg data cause)

Creates an exception with a message and a data map. Optionally takes a cause.

Example:

(throw (ex-info "Invalid input" {:field :email}))

ex-message#

(ex-message ex)

Returns the message of an exception.

Example:

(ex-message (ex-info "boom" {})) ; => "boom"

extend-protocol#

(extend-protocol protocol-name & specs)

Convenience macro that extends a single protocol to multiple types. Alternates type-specs and method implementations.

Equivalent to multiple extend-type calls.

Example:

(extend-protocol Describable
  :string (describe [s] s)
  :int (describe [n] (str n)))

extend-type#

(extend-type type-spec & specs)

Extends a type with protocol method implementations.

type-spec can be:

• nil for the nil type
• a type keyword matching what type returns: :string, :int, :float, :boolean, :keyword, :symbol, :vector, :list, :hash-map, :set, :atom, :var, :function, :php/array
• a symbol for struct names (resolved in current namespace)
• a string for explicit PHP class names (cross-namespace structs)

Note: :struct and :php/object cannot be used as type-specs because protocol dispatch resolves these to their specific PHP class names. Use a struct symbol or PHP class name string instead.

Example:

(extend-type :string Stringable (to-string [s] s))

extends?#

(extends? protocol type-key)

Returns true if the given type-key has implementations for all methods of the protocol. type-key should match what protocol-type-key returns.

Example:

(extends? Stringable :string)

extreme#

(extreme order args)

Returns the most extreme value in args based on the binary order function.

Example:

(extreme > [1 5 2]) ; => 5

false?#

(false? x)

Checks if value is exactly false (not just falsy).

Example:

(false? nil) ; => false

ffirst#

(ffirst coll)

Same as (first (first coll)).

Example:

(ffirst [[1 2] [3 4]]) ; => 1

file-seq#

(file-seq path)

Returns a lazy sequence of all files and directories in a directory tree.

Example:

(filter #(php/str_ends_with % ".phel") (file-seq "src/")) ; => ["src/file1.phel" "src/file2.phel" ...]

filter#

(filter pred)
(filter pred coll)
(filter pred coll & more)

Returns a lazy sequence of elements where predicate returns true. When called with pred only, returns a transducer.

Example:

(filter even? [1 2 3 4 5 6]) ; => (2 4 6)

filterv#

(filterv pred coll)

Returns a vector of the items in coll for which (pred item) returns a logical true value. Like filter, but eager and returns a vector rather than a lazy sequence.

Example:

(filterv even? [1 2 3 4 5 6]) ; => [2 4 6]

finally#

(finally expr*)

Evaluate expressions after the try body and all matching catches have completed. The finally block runs regardless of whether an exception was thrown.

Example:

(defn risky-operation [] (throw (new Exception "Error!")))
(defn cleanup [] (println "Cleanup!"))
(try (risky-operation) (catch Exception e nil) (finally (cleanup)))

find#

(find pred-or-coll coll-or-key)

When called with a collection first, returns [key value] when key is present. Otherwise returns the first item in coll where (pred item) evaluates to true.

Example:

(find {:a 1} :a) ; => [:a 1]
(find #(> % 5) [1 2 3 6 7 8]) ; => 6

find-hierarchy-method#

(find-hierarchy-method methods dispatch-val)
(find-hierarchy-method methods dispatch-val prefers-map)

Finds the best matching method for dispatch-val using the global hierarchy. Returns the method function or nil. Used internally by defmulti. When multiple methods match and none is more specific, consults prefers-map (built by prefer-method); if still ambiguous, throws.

find-index#

(find-index pred coll)

Returns the index of the first item in coll where (pred item) evaluates to true.

Example:

(find-index #(> % 5) [1 2 3 6 7 8]) ; => 3

find-ns#

(find-ns ns-str)

Returns the namespace name in display form if it is loaded, or nil if no namespace of that name exists. Accepts dot or backslash separators on input.

Example:

(find-ns "phel.core") ; => "phel.core"

find-var#

(find-var sym)

Returns the Var named by the fully-qualified symbol, or nil if no matching definition exists. Tries the symbol name verbatim first (matching how def stores entries), then falls back to the encoded form (matching how intern stores entries).

Example:

(find-var 'phel.core/map) ; => #'phel.core/map

first#

Returns the first element of a sequence, or nil if empty.

Maps are treated as a sequence of entries: (first {:a 1}) returns a typed MapEntry equal by value to [:a 1]. Strings are treated as sequences of multibyte characters.

A lazily consumed source with no indexed access of its own (an eduction pipeline, a PHP generator, an iterator) is answered by pulling a single element, the same way empty? answers it. count is the one that refuses such a source, because counting means draining it.

Example:

(first [1 2 3]) ; => 1

flatten#

(flatten coll)

Flattens nested sequential structure into a lazy sequence of all leaf values.

Example:

(flatten [[1 2] [3 [4 5]] 6]) ; => (1 2 3 4 5 6)

float#

(float x)

Coerces x to a float. In PHP there is no distinction between float and double; both map to the same native PHP float type. Ratio, BigInt, and BigDecimal values collapse to their float value; everything else delegates to PHP's floatval, so non-numeric strings return 0.0 and nil returns 0.0. Non-numeric objects such as keywords, vectors, or maps raise InvalidArgumentException instead of leaking a raw PHP float-coercion warning.

Example:

(float 1) ; => 1.0
(float 1/2) ; => 0.5

float-array#

(float-array size-or-seq)
(float-array size init-val-or-seq)

Creates a PHP array of floats. Accepts the same arities as int-array; coerces elements to float via floatval and zero-pads with 0.0.

Example:

(float-array 3) ; => <PHP-Array [0.0, 0.0, 0.0]>
(float-array 4 1.5) ; => <PHP-Array [1.5, 1.5, 1.5, 1.5]>

float?#

(float? x)

Returns true if x is float point number, false otherwise.

Example:

(float? 1.0) ; => true
(float? 1) ; => false

floor#

(floor x)

Returns the largest integer not greater than x. Ints and BigInt values are returned unchanged. Ratios collapse via floor division. Floats route through PHP's floor.

Example:

(floor 1.7) ; => 1.0
(floor -1.2) ; => -2.0
(floor 7/3) ; => 2

fn#

(fn [params*] expr*)

Defines a function. A function consists of a list of parameters and a list of expression. The value of the last expression is returned as the result of the function. All other expression are only evaluated for side effects. If no expression is given, the function returns nil.

Example:

(fn [x y] (+ x y))

fn?#

(fn? x)

Returns true if x is a function, false otherwise.

Example:

(fn? inc) ; => true
(fn? 42) ; => false

fnext#

(fnext coll)

Same as (first (next coll)).

Example:

(fnext [1 2 3]) ; => 2

fnil#

(fnil f & defaults)

Returns a function that replaces nil arguments with the provided defaults before calling f. The number of defaults determines how many leading arguments are nil-checked.

Example:

(let [safe-inc (fnil inc 0)] (safe-inc nil)) ; => 1

for#

(for head & body)

List comprehension. The head of the loop is a vector that contains a sequence of bindings modifiers and options. A binding is a sequence of three values binding :verb expr. Where binding is a binding as in let and :verb is one of the following keywords:

• :range loop over a range by using the range function.
• :in loops over all values of a collection (including strings).
• :keys loops over all keys/indexes of a collection.
• :pairs loops over all key-value pairs of a collection.

After each loop binding, additional modifiers can be applied. Modifiers have the form :modifier argument. The following modifiers are supported:

• :while breaks the loop if the expression is falsy.
• :let defines additional bindings.
• :when only evaluates the loop body if the condition is true.

Finally, additional options can be set:

• :reduce [accumulator initial-value] Instead of returning a list, it reduces the values into accumulator. Initially accumulator is bound to initial-value.

Example:

(for [x :in [1 2 3]] (* x 2)) ; => [2 4 6]

force#

(force x)

If x is a Delay, forces it and returns its cached value. Otherwise returns x.

Example:

(force (delay 42)) ; => 42

foreach#

(foreach [value valueExpr] expr*)
(foreach [key value valueExpr] expr*)

The foreach special form can be used to iterate over all kind of PHP datastructures. The return value of foreach is always nil. The loop special form should be preferred of the foreach special form whenever possible.

Example:

(foreach [x [1 2 3]] (println x))

format#

(format fmt & xs)

Returns a formatted string. See PHP's sprintf for more information.

Example:

(format "%d-%s" 1 "a") ; => "1-a"

frequencies#

(frequencies coll)

Returns a map from distinct items in coll to the number of times they appear.

Works with vectors, lists, sets, and strings.

Example:

(frequencies [:a :b :a :c :b :a]) ; => {:a 3, :b 2, :c 1}

full-name#

(full-name x)

Return the namespace and name string of a string, keyword or symbol.

Example:

(full-name :foo/bar) ; => "foo/bar"

future#

(future & body)

Starts evaluating body asynchronously and returns a Future that can be derefed (blocks the current fiber until the value is available) or checked with realized?.

Supports the 3-arg (deref f timeout-ms timeout-val) form for time-bounded blocking, as well as future-cancel, future-cancelled? and future-done? for lifecycle management.

Must be called from inside a fiber context (e.g. the AMPHP event loop or an enclosing async block), because deref resolves via AMPHP's fiber-based await.

Example:

(let [f (future (expensive-computation))] @f)

future-call#

(future-call f)

Invokes f (a zero-arg function) in a new fiber. Returns a PhelFiberFuture you can deref or inspect with future-done? and future-cancel.

Captures the caller's dynamic bindings and reinstalls them inside the fiber before invoking f, so bindings are conveyed the same way as with future/async.

Example:

(future-call (fn [] 42))

future-cancel#

(future-cancel f)

Signals the future's internal cancellation token, causing any pending or subsequent deref call to raise CancelledException (or return the timeout value for the 3-arg form). Due to AMPHP's cooperative fibers, the body keeps running until its next cancellation checkpoint; from the caller's perspective the future behaves as cancelled after this returns.

Example:

(future-cancel (future (expensive-call)))

future-cancelled?#

(future-cancelled? f)

Returns true if future-cancel was called on f, false otherwise.

Example:

(future-cancelled? f)

future-done?#

(future-done? f)

Returns true if the future is in a final state (completed, failed, or cancelled).

Dispatches on type: for a Phel.Fiber.Domain.Future (fiber-backed) it calls isDone; for any other value it falls back to realized?. This lets the same predicate serve both the AMPHP Future wrapper and the cooperative fiber future.

Example:

(future-done? f)

future-fiber#

(future-fiber & body)

Runs body in a new fiber via the cooperative scheduler. Returns a fiber-future that supports deref, realized?, future-done?, and future-cancel. Works at the top level (no enclosing async block required), in contrast to future which requires an AMPHP fiber context.

Example:

@(future-fiber (+ 1 2))

future?#

(future? x)

Returns true if x is a fiber-future (from future-call/future-fiber) or a Future (from the AMPHP-backed future macro).

Example:

(future? (future-call (fn [] 1))) ; => true