Ale is a Lisp Environment

Ale Assembler

Wed, 21 Aug 2024 18:10:19 +0200

Ale is a dialect of Lisp which means that it’s infinitely extensible out of the box. Hygienic macros and syntax quoting make this possible. But what if you really, really need to start making deep changes? Like at the compiler level? Well, I’ve designed that to be a relatively straight-forward process as well!

From the Ale REPL, type the word if (no parens) and you’ll see something like this:

{:instance "0x51a160" :type special}

This is the string representation of Ale’s if special form. Other forms will present themselves differently. For example, lazy-seq has a type of “macro”, while first is a lambda and has a type of “procedure”. But what’s this “special” stuff?

Go and Ale

Fri, 12 Feb 2021 07:20:10 +0200

Ale is designed to be hosted within a Go process. And while it’s not particularly difficult to embed or even extend Ale, getting data structures from Go into Ale (and vice versa) has historically been a high-friction activity. There’s a reason for this and it all comes down to equality.

Equality in Ale ≠ Equality in Go

Ale employs what’s called “structural equality.” This means that for any value, even if it’s not the same instance of a value, Ale will dive into its content to check whether or not it contains the same stuff. For example:

Ale Language Design

Fri, 08 May 2020 13:08:12 +0200

Ale is a Lisp dialect that takes syntactic cues from both Scheme and Clojure.

Where Scheme treats parentheses and square brackets as being one in the same. Ale treats them the way that Clojure does – meaning parentheses are used to delimit lists, while square brackets are used to delimit vectors. Ale takes advantage of this by incorporating the syntactic difference into its language design, a move that (hopefully) improves consistency and readability.

Metaprogramming Ale

Sun, 16 Jun 2019 09:15:11 +0200

When I first saw Lisp code, my immediate reaction was “Wow, that’s a lot of parentheses!” I then backed up from the computer, turned around, walked away, and didn’t look at it again for years. I had convinced myself that any language that doesn’t have rich grammatical productions and super clean syntax couldn’t possibly be of any value. But that’s because I was young and stupid.

I remained stupid until my mid 40s. And then something happened. Although I had been designing and developing languages for about a decade at that point, I had never studied language design at a theoretical level. So when I finally did, I was blown away. Lambda calculus, why had I never heard of it!? Prolog, it’s like magic! I’d been missing out!

Tail Call Optimization

Fri, 17 May 2019 10:17:02 +0200

Functional programming languages introduce a different set of compilation problems than do imperative languages. They’re simpler in many ways, but when it comes to accommodating the functional style of problem solving, the compiler author has a duty to the programmer that cannot be ignored.

So where my Clojure people at? Fire up the Leiningen REPL, type the following code into it, and then tell me what happens. Don’t worry, I’ll wait. ¹

(defn to-zero [x]
  (cond
    (> x 1000) (to-zero (- x 1))
    (> x 0)    (to-zero (- x 1))
    :else      0))

(to-zero 9999)

If you said it spits out something like the following, then you’d be right:

Extending Ale

Wed, 17 Apr 2019 08:10:19 +0200

Embedding Ale

Tue, 09 Apr 2019 08:19:19 +0200

Ale is designed to be hosted within a Go process, but with a catch – each environment you create is isolated from the others, meaning namespace modifications are not shared. So what could have been as simple as calling eval.String("(+ 1 2 3)") suddenly becomes a few lines of code more complicated.

I should explain why this is.

Namespaces and Their Environments

Namespaces are where you put your stuff. They manage bindings from names to values. Bindings are immutable after being defined, though a binding can be declared before being defined, which I’ll explain later.

An Ale Introduction

Sat, 06 Apr 2019 12:19:22 +0200

They say you’re not a great JavaScript programmer until you’ve written your own framework – hence all of the half-assed attempts. Similarly you can’t really say you understand programming language design until you’ve implemented your own Lisp. So here we are.

But why Lisp? The answer is straight-forward. Because even though over sixty years have come and gone since Lisp was first introduced, no language beats it for simplicity and power. None! And I dare you to prove me wrong. John McCarthy, may he rest in peace, designed a language that is as close to perfection as a human can hope to achieve.

:

Mon, 01 Jan 0001 00:00:00 +0000

Looks up method from target using get, then calls the resulting value as a procedure with any remaining arguments. It expands to a normal get followed by a call.

An Example

(: {:inc (lambda (x) (+ x 1))} :inc 41)

This example returns 42.

addition (+)

Mon, 01 Jan 0001 00:00:00 +0000

Calculates the sum of a set of numbers.

An Example

(+ 9 10 23)       ;; returns 42
(+ 50 12.6 34.8)  ;; returns 97.4
(+)               ;; returns 0

and

Mon, 01 Jan 0001 00:00:00 +0000

Evaluates forms from left to right. As soon as one evaluates to false, will return that value. Otherwise, it will proceed to evaluate the next form.

An Example

(and (+ 1 2 3)
     false
     "not returned")

Will return #f (false), never evaluating “not returned”, whereas:

(and (+ 1 2 3)
     true
     "returned")

Will return the string “returned”.

append

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new sequence with value appended to the end of seq. The target must satisfy appendable?.

An Example

(append [1 2 3] 4)

This example returns [1 2 3 4].

apply

Mon, 01 Jan 0001 00:00:00 +0000

Evaluates the provided sequence and applies the provided function to its values and any explicitly included arguments.

An Example

(define x '(1 2 3))
(apply + x)

This example will return 6.

asm

Mon, 01 Jan 0001 00:00:00 +0000

Provides direct access to Ale’s assembler syntax. This form is primarily used by the core library and low-level code that needs explicit control over VM instructions.

An Example

(asm
  const 99)

This example emits code that returns the literal value 99.

assoc

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new mapper sequence wherein the specified key/value pairs are associated. If a key already exists, the value replaces the one previously stored; otherwise the pair is added to the sequence.

An Example

(define robert {:name "Bob" :age 45})
(assoc robert (:age . 46))

This example returns a copy of robert wherein the value associated with :age has been replaced by the number 46. The original sequence is unaffected.

atom?

Mon, 01 Jan 0001 00:00:00 +0000

A form is considered to be atomic if it cannot be further evaluated and would otherwise evaluate to itself.

An Example

(atom? '() :hello "there")

This example will return #t (true) because each value is atomic.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be atomic.

(!atom? '(+ 1 2 3) [4 5 6])

This example will return #t (true) because compound types such as lists and vectors are not considered to be atomic.

begin

Mon, 01 Jan 0001 00:00:00 +0000

Evaluate each form in turn, returning the final evaluation as its result.

An Example

(begin
  (println "hello")
  "returned")

branching helpers

Mon, 01 Jan 0001 00:00:00 +0000

These macros build on if to cover common control-flow patterns. case compares a value using eq, and a clause test may be either a single value or a list of values. if-let binds a value and tests whether it is truthy. when-let is the body-only form of if-let. If no case clause matches, it raises an error.

An Example

(if-let [x (get {:name "ale"} :title false)]
  (str "hello " x)
  "missing")

bytes

Mon, 01 Jan 0001 00:00:00 +0000

Creates a byte sequence from numeric values. Byte sequences also have reader syntax using #b[...].

An Example

(bytes 65 66 67)

This example returns the byte sequence representing ABC.

bytes?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to byte sequences, this function returns #t (true). Otherwise it returns #f (false).

An Example

(bytes? (bytes 65 66) #b[1 2 3])

car

Mon, 01 Jan 0001 00:00:00 +0000

This function will return the first element of the specified pair or sequence, or the empty list if the sequence is empty.

An Example

(define x '(99 64 32 48))
(car x)  ;; will return 99

(define y (100 . 200))
(car y)  ;; will return 100

car/cdr accessors

Mon, 01 Jan 0001 00:00:00 +0000

These are compound sequence accessors that combine multiple car and cdr operations. The name of each function describes which operations to perform from right to left. a represents car, which gets the first element. d represents cdr, which gets the rest of the list.

Examples

Given a nested list structure:

(define x '((1 2) (3 4)))
(caar x)  ; gets car of (car x) -> 1
(cadr x)  ; gets car of (cdr x) -> (3 4)
(cdar x)  ; gets cdr of (car x) -> (2)
(cddr x)  ; gets cdr of (cdr x) -> ()

;; More deeply nested examples
(define y '((1 2) ((3 4) 5)))
(cadar y)  ; car of (cdr of (car y)) -> 2
(caadr y)  ; car of (car of (cdr y)) -> (3 4)

The functions can access up to 4 levels deep in a nested list structure. Reading from right to left helps understand the access pattern - for example, caddr means “get the first element (car) of the rest of the rest (cddr) of the list”.

cdr

Mon, 01 Jan 0001 00:00:00 +0000

This function will return the portion of a pair or sequence that excludes its first element. For sequences, this will be the remainder of the sequence. For cons pairs, this will be the cdr portion.

An Example

(define x '(99 64 32 48))
(cdr x)  ;; will return (64, 32, 48)

(define y (100 . 200))
(cdr y)  ;; will return 200

chan

Mon, 01 Jan 0001 00:00:00 +0000

A channel is a data structure used to generate a lazy sequence of values. The result is a hash-map consisting of an emit function, a close function, and a sequence. Depending on the size of the channel’s buffer, retrieving an element from the sequence may block, waiting for the next value to be emitted or for the channel to be closed. Emitting a value to a channel will also block until the buffer is flushed as a result of iterating over the sequence.

comp

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new function based on chained invocation of the provided functions, from left to right. The first composed function can accept multiple arguments, while any subsequent functions are applied with the result of the previous.

An Example

(define mul2Add5 (comp (partial \* 2) (partial + 5)))
(mul2Add5 10)

This example will return 25 as though (+ 5 (\* 2 10)) were called.

concat

Mon, 01 Jan 0001 00:00:00 +0000

Creates a lazy sequence whose content is the result of concatenating the elements of each provided sequence. To immediately materialize a complete concatenated sequence, use the concat! function.

An Example

(seq->list (concat [1 2 3] '(4 5 6)))

This will return the list (1 2 3 4 5 6)

cond

Mon, 01 Jan 0001 00:00:00 +0000

For each pred-then clause, the predicate will be evaluated, and if it is truthy (not false), the then form is evaluated and returned, otherwise the next clause is processed.

An Example

(define x 99)

(cond
  [(< x 50)  "was less than 50"    ]
  [(> x 100) "was greater than 100"]
  [:else     "was in between"      ])

In this case, “was in between” will be returned. The reason that this works is that the :else keyword, like all keywords, evaluates to truthy.

conditional thread first (cond->)

Mon, 01 Jan 0001 00:00:00 +0000

Like ->, but each form is paired with a test condition. The form is only applied if the test evaluates to true. Each test is evaluated with the current threaded value in scope.

An Example

(cond-> 10
        [true   (+ 5)]   ; Always applies: 10 + 5 = 15
        [(> 12) (\* 2)]   ; Applies if > 12: 15 \* 2 = 30
        [(< 25) (/ 3)]   ; Doesn't apply (30 is not < 25)
        [true   (- 1)])  ; Always applies: 30 - 1 = 29

Another Example

(cond-> {}
        [empty?            (assoc (:name . "John"))]
        [!empty?           (assoc (:size . "non-empty"))]
        [(contains? :name) (assoc (:greeting . "Hello"))]
        [object?           (assoc (:type . "object"))])

conditional thread last (cond->>)

Mon, 01 Jan 0001 00:00:00 +0000

Like ->>, but each form is paired with a test condition. The form is only applied if the test evaluates to true. Each test is evaluated with the current threaded value in scope.

An Example

(cond->> [1 2 3 4 5]
         [seq?    (map (lambda (x) (\* x 2)))]  ; doubles: [2 4 6 8 10]
         [!empty? (filter even?)]              ; keeps evens: [2 4 6 8 10]
         [(> 2)   (take 3)]                    ; takes first 3: [2 4 6]
         [false   (concat [0])])               ; skipped

Another Example

(cond->> [1 2 3]
         [seq?   (filter even?)]  ; predicate true, filters to [2]
         [empty? (concat [4 5])]  ; predicate false, skips concat
         [true   (take 1)])       ; takes first element

conj

Mon, 01 Jan 0001 00:00:00 +0000

Adds elements to a conjoinable sequence. This behavior will differ depending on the concrete type. A list will prepend, a vector will append, while an object makes no guarantees about ordering.

An Example

(conj [1 2 3 4] 5 6 7 8)

Will return the vector [1 2 3 4 5 6 7 8].

cons

Mon, 01 Jan 0001 00:00:00 +0000

When cdr is an ordered sequence, such as a list or vector, the result is a new list or vector with the car value prepended to the original. With an unordered sequence, such as an object array, there is no guarantee regarding position. If cdr is not a sequence, then a new cons cell will be constructed.

The name cons is a vestige of when Lisp implementations constructed new lists or cells by pairing a car (contents of the address part of register) with a cdr (contents of the decrement part of register).

contains?

Mon, 01 Jan 0001 00:00:00 +0000

Returns #t if coll can resolve key, otherwise #f. This works with mapped lookup types such as objects and sets.

An Example

(contains? #{:name :age} :name)

This example returns #t.

core literals

Mon, 01 Jan 0001 00:00:00 +0000

These names are predefined literal values. true and false are Ale’s boolean values. null is the empty list or null value. +inf, -inf, and nan are special floating-point values.

An Example

[true false null +inf -inf nan]

counted?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a valid sequence than can report its length without counting, then this function will return #t (true). The first non-counted sequence will result in the function returning #f (false).

An Example

(counted? '(1 2 3 4) [5 6 7 8])

This example will return #t (true).

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be valid counted sequences.

current-time

Mon, 01 Jan 0001 00:00:00 +0000

Returns the system’s current time, measured in nanoseconds since January 1, 1970 UTC.

An Example

(current-time)  ;; returns 1554720691499809478

declare

Mon, 01 Jan 0001 00:00:00 +0000

Forward declares bindings. This means that the names will be known in the current namespace, but not yet assigned. This can be useful when two functions refer to one another.

The private variant makes the binding private to the current namespace.

An Example

(declare is-odd-number)

(define (is-even-number n)
  (cond [(= n 0) true]
        [:else   (is-odd-number (- n 1))]))

(define (is-odd-number n)
  (cond [(= n 0) false]
        [:else   (is-even-number (- n 1))]))

define

Mon, 01 Jan 0001 00:00:00 +0000

Binds a value to a global name. All bindings are immutable and result in an error being raised if an attempt is made to re-bind them. This behavior is different from most Lisps, as they will generally fail silently in such cases.

An Example

(define x
  (map
    (lambda (y) (\* y 2))
    seq1 seq2 seq3))

This example will create a lazy map where each element of the three provided sequences is doubled upon request. It will then bind that lazy map to the name x.

define-lambda

Mon, 01 Jan 0001 00:00:00 +0000

Bind a function by name to the current namespace.

An Example

(define-lambda (fib i)
  (cond
    [(= i 0) 0]
    [(= i 1) 1]
    [(= i 2) 1]
    [:else   (+ (fib (- i 2)) (fib (- i 1)))]))

This example performs recursion with no tail call optimization, and no memoization. For a more performant and stack-friendly fibonacci sequence generation example, see the documentation of lazy-seq.

define-macro

Mon, 01 Jan 0001 00:00:00 +0000

Binds a macro to a global name. The reader expands a macro to alter the source code’s data representation before it is evaluated.

An Example

(define-macro (cond . clauses)
  (when (seq clauses)
    (if (= 1 (length clauses))
      (clauses 0)
      (list 'ale/if
        (clauses 0) (clauses 1)
        (cons 'cond (rest (rest clauses)))))))

delay

Mon, 01 Jan 0001 00:00:00 +0000

delay returns a promise that evaluates its body the first time it is forced. That result is cached, so later calls return immediately. force resolves one promise layer, or returns non-promises unchanged. force! keeps forcing until the result is no longer a promise. delay-force delays a computation whose result should be forced once before being cached.

An Example

(define p (delay
            (println "hello once")
            "hello"))
(force p) ;; prints "hello once"
(force p)

The first invocation of p will print “hello once” to the console, and also return the string “hello”. Subsequent invocations of p will only return “hello”.

dissoc

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new mapper sequence wherein the associations identified by the provided keys are removed. If the keys don’t exist, the original sequence is returned.

An Example

(define robert {:name "Bob" :age 45})
(dissoc robert :age)

This example returns a copy of robert from which the :age association has been removed. The original sequence is unaffected.

division (/)

Mon, 01 Jan 0001 00:00:00 +0000

Calculates the collective quotient of a set of numbers.

An Example

(/ 10 3)      ;; returns 10/3
(/ 10 3.0)    ;; returns 3.3333333333333335
(/ 20 2.0 4)  ;; returns 2.5

drop

Mon, 01 Jan 0001 00:00:00 +0000

Return a lazy sequence that excludes the first count elements of the provided sequence. If the source sequence is shorter than the requested count, an empty list will be returned.

An Example

(define x '(1 2 3 4))
(define y [5 6 7 8])
(drop 3 (concat x y))

This example will return the lazy sequence (4 5 6 7 8).

empty?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to empty sequences, then this function will return #t (true). The first evaluation that is not an empty sequence will result in the function returning #f (false).

An Example

(empty? '(1 2 3 4) [] {})

This example will return #f (false) because the first form is a list with four elements.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be nil.

equal to (=)

Mon, 01 Jan 0001 00:00:00 +0000

eval

Mon, 01 Jan 0001 00:00:00 +0000

false?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to false (#f), then this function will return #t (true). The first non-false will result in the function returning #f (false).

An Example

(false? (< 3 2) (> 5 10))

This example will return #t (true) because all the equalities result in #f (false).

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be true. This is equivalent to the true? predicate.

filter

Mon, 01 Jan 0001 00:00:00 +0000

Creates a lazy sequence whose content is the result of applying the provided function to the elements of the provided sequence. If the result of the application is truthy (not false), then the value will be included in the resulting sequence.

An Example

(filter (lambda (x) (< x 3)) [1 2 3 4])

This will return the lazy sequence (1 2)

fold-left

Mon, 01 Jan 0001 00:00:00 +0000

Iterates over a sequence, reducing its elements to a single resulting value. The function provided must take two arguments. The first and second sequence elements encountered are the initial values applied to that function. Thereafter, the result of the previous calculation is used as the first argument, while the next element is used as the second argument.

An Example

(fold-left + 5 (range 1 11))

This will return the value 60.

fold-right

Mon, 01 Jan 0001 00:00:00 +0000

These forms reduce a sequence from right to left. fold-right uses reverse, while fold-right! uses reverse! and can therefore work with non-reversible sequences by materializing them first. foldr is an alias for fold-right.

An Example

(fold-right cons '() [1 2 3])

for

Mon, 01 Jan 0001 00:00:00 +0000

for builds a lazy sequence by iterating over one or more bindings. for-each evaluates the same comprehension for side effects and returns the final result.

An Example

(for ([x [1 2]]
      [y [10 20]])
  (+ x y))

This example lazily yields 11, 21, 12, and 22.

future

Mon, 01 Jan 0001 00:00:00 +0000

Returns a promise whose expressions are immediately evaluated in another thread of execution.

An Example

(define fut (future
  (seq->vector (generate
    (emit "red")
    (emit "orange")
    (emit "yellow")))))

(fut)

This example produces a promise called fut that converts the results of an asynchronous block into a vector. The (fut) call will block until the future returns a value.

generate

Mon, 01 Jan 0001 00:00:00 +0000

Evaluate the specified forms in a separate thread of execution. Returns a sequence that will iterate over any of the values that are emitted. Values are emitted using a locally scoped function of the form (emit value). The forms are executed as a co-routine, meaning that a call to emit will block until the corresponding element is resolved by a consumer of the sequence.

An Example

(define colors (generate
  (emit "red")
  (emit "orange")
  (emit "yellow")))

(seq->vector colors)

This example will bind the lazy sequence returned by the call to generate to the name colors. The seq->vector call will block until that variable is fully consumed, and then return the vector [“red” “orange” “yellow”].

gensym

Mon, 01 Jan 0001 00:00:00 +0000

If an unqualified symbol is provided, that symbol will be used to clarify the uniquely generated symbol. This function provides the underlying behavior for hash-tailed symbols in syntax-highlighting macros.

An Example

(let [s (gensym 'var)]
  (list 'ale/let [s "hello"] s))

;; is equivalent to
``(let [var# "hello"] var#)

This example will return “hello”.

get

Mon, 01 Jan 0001 00:00:00 +0000

Returns the value within a sequence that is associated with the specified key. If the key does not exist within the sequence, then either the default value is returned, or an error is raised.

An Example

(define robert {:name "Bob" :age 45})
(get robert :address "wrong")

This example returns “wrong” because the object doesn’t contain an :address property.

go

Mon, 01 Jan 0001 00:00:00 +0000

The provided forms will be evaluated in a separate thread of execution. Any resulting value of the block will be discarded.

An Example

(define ch (chan))
(go (: ch :emit "hello")
    (: ch :close))
(str (first (ch :seq)) " world!")

greater or equal (>=)

Mon, 01 Jan 0001 00:00:00 +0000

greater-than (>)

Mon, 01 Jan 0001 00:00:00 +0000

identical (eq)

Mon, 01 Jan 0001 00:00:00 +0000

Return #f (false) as soon as it encounters a form that is not identical to the first. Otherwise, will return #t (true).

An Example

(define h "hello")
(eq "hello" h)

Like most predicates, this function can also be negated by prepending the ! character. In this case, #t (true) will be returned if not all forms are equal.

if

Mon, 01 Jan 0001 00:00:00 +0000

If the evaluated predicate is truthy (not #f (false) or the empty list), the then form is evaluated and returned, otherwise the else form, if any, will be evaluated and returned.

An Example

(define x '(1 2 3 4 5 6 7 8))

(if (> (length x) 3)
    "x is big"
    "x is small")

If the symbol unless is used instead of if, then the logical branching will be inverted.

inc / dec

Mon, 01 Jan 0001 00:00:00 +0000

inc adds 1 to a numeric value and dec subtracts 1.

An Example

(inc 41) ; => 42
(dec 42) ; => 41

index-of

Mon, 01 Jan 0001 00:00:00 +0000

Returns the zero-based index of the first matching value in a sequence. If no value matches, returns #f.

An Example

(index-of [4 8 15 16] 15)

This example returns 2.

indexed?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a valid sequence that can be accessed by index, then this function will return #t (true). The first non-indexed sequence will result in the function returning #f (false).

An Example

(indexed? '(1 2 3 4) [5 6 7 8])

This example will return #t (true).

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be valid indexed sequences.

juxt

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new function that represents the juxtaposition of the provided functions. This function returns a vector containing the result of applying each provided function to the juxtaposed function’s arguments.

An Example

(define juxt-math (juxt * + - /))
(juxt-math 32 10)

This example will return [320 42 22 16/5] as though [(* 32 10) (+ 32 10) (- 32 10) (/ 32 10)] were called.

keyword?

Mon, 01 Jan 0001 00:00:00 +0000

A form is considered to be a keyword if it is a symbol with a colon (":") prefix. Keywords are often used as unique identifiers and are typically used to access values in objects or define objects keys.

An Example

(keyword? :keyword1 :keyword2 :keyword3)

This example will return #t (true) because each provided form is a keyword.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be keywords.

label

Mon, 01 Jan 0001 00:00:00 +0000

Wraps a form with a stable name, primarily to support recursive procedure definitions and clearer generated values.

An Example

(label fact
  (lambda (n)
    (if (zero? n) 1 (* n (fact (dec n))))))

lambda

Mon, 01 Jan 0001 00:00:00 +0000

Creates a lambda function that may be passed around in a first-class manner.

An Example

(define double
  (let [mul 2]
    (lambda (x) (\* x mul))))

(seq->vector
  (map double '(1 2 3 4 5 6)))

This example will return the vector [2 4 6 8 10 12].

Lambdas produce a closure that copies the bindings that have been referenced from the surrounding scope.

last

Mon, 01 Jan 0001 00:00:00 +0000

This function will return the last element of the specified sequence, or the empty list if the sequence is empty. If the sequence is lazily computed, asynchronous, or otherwise incapable of returning a count, this function will raise an error.

To perform a brute-force scan of the sequence, use the last! function, keeping in mind that last! may never return a result.

An Example

(define x '(99 64 32 48))
(last x)

This example will return 48.

lazy

Mon, 01 Jan 0001 00:00:00 +0000

Like delay, but if the first forced result is a promise, it will continue to be forced until a non-promise result is capable of being returned.

An Example

(define p (lazy
            (println "hello once")
            (delay
              (println "hello twice")
              "hello")))
(force p) ;; prints "hello once / hello twice"
(force p)

The first invocation of p will print “hello once” followed by “hello twice” to the console, also returning the string “hello”. Subsequent invocations of p will only return “hello”.

lazy-seq

Mon, 01 Jan 0001 00:00:00 +0000

An Example:

(define (fib-seq)
  (let [fib (lambda-rec fib (a b)
              (lazy-seq (cons a (fib b (+ a b)))))]
    (fib 0 1)))

(for-each [x (take 300 (fib-seq))]
  (println x))

This example prints the first 300 fibonacci numbers.

length

Mon, 01 Jan 0001 00:00:00 +0000

The length function will return the number of elements in a sequence.

If the sequence is lazily computed, asynchronous, or otherwise incapable of returning a count, this function will raise an error. To perform a brute-force count of a sequence, use the length! function, keeping in mind that it may never return a result.

An Example

(length '(1 2 3 4))

This example will return 4.

less or equal (<=)

Mon, 01 Jan 0001 00:00:00 +0000

less-than (<)

Mon, 01 Jan 0001 00:00:00 +0000

let

Mon, 01 Jan 0001 00:00:00 +0000

Create a new local scope, evaluate the provided expressions, and then bind the resulting values to their respective names. The body is evaluated within that scope and returns the result of its final form.

The binding forms differ in how names can see one another. let performs bindings in parallel. let* performs bindings sequentially. let-rec allows recursive and mutually recursive references.

An Example

(let ([x '(1 2 3 4)]
      [y [5 6 7 8] ])
  (concat x y))

This example will create a list called x and a vector called y and return the lazy concatenation of those sequences. Note that the two names do not exist outside the let form.

let thread (let->)

Mon, 01 Jan 0001 00:00:00 +0000

A threaded let binding that threads the bound value through each form by name. Each form receives the current value of the binding and the result becomes the new value of the binding.

An Example

(let-> [x 10]
       (+ x 5)
       (\* x 2)
       (/ x 2))

Another Example

(let-> [user {}]
       (assoc user (:name . "John"))
       (assoc user (:age . 25))
       (assoc user (:status . "active")))

letfn

Mon, 01 Jan 0001 00:00:00 +0000

Creates a local scope containing named recursive function bindings. It is useful when several local procedures need to reference one another.

An Example

(letfn [(lambda-rec even? (n) (if (zero? n) true (odd? (dec n))))
        (lambda-rec odd?  (n) (if (zero? n) false (even? (dec n))))]
  (even? 10))

list

Mon, 01 Jan 0001 00:00:00 +0000

Create a new list whose elements are the evaluated forms provided, or return the empty list if no forms are provided.

An Example

(define x "hello")
(define y "there")
(list x y)

list?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a list, then this function will return #t (true). The first non-list will result in the function returning #f (false).

An Example

(list? '(1 2 3 4) [5 6 7 8])

This example will return #f (false) because the second form is a vector.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be lists.

macro

Mon, 01 Jan 0001 00:00:00 +0000

Converts a procedure into a macro value. The procedure receives the unevaluated input forms and returns expanded code. In most user code, define-macro is the more convenient interface.

An Example

(define twice
  (macro (lambda (form) `(+ ,form ,form))))

macro expansion

Mon, 01 Jan 0001 00:00:00 +0000

macroexpand-1 expands a single macro layer. macroexpand expands repeatedly until the form is no longer a macro call.

An Example

(macroexpand-1 '(when true 42))

map

Mon, 01 Jan 0001 00:00:00 +0000

Creates a lazy sequence whose elements are the result of applying the provided function to the sequence elements. If more than one sequence is provided, their elements are retrieved in parallel to supply additional arguments to the mapped function. Mapping will terminate as soon as any sequence is exhausted.

An Example

(map (lambda (x) (\* x 2)) [1 2 3 4])

This will return the lazy sequence (2 4 6 8). The following example performs mapping in parallel.

mapped?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to mapped values, then this function will return #t (true). A mapped value supports keyed lookup through functions like get and contains?.

An Example

(mapped? {:name "bill"} #{:name :age} [1 2 3])

This example will return #f (false) because the third form is a vector.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be mapped.

mapper?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to mapper values, then this function will return #t (true). A mapper supports keyed lookup and association operations such as assoc and dissoc.

An Example

(mapper? {:name "bill"} #{:name :age} [1 2 3])

This example will return #f (false) because sets and vectors are not mappers.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be mappers.

multiplication (*)

Mon, 01 Jan 0001 00:00:00 +0000

Calculates the product of a set of numbers.

An Example

(\* 9 10 23)       ;; returns 2070
(\* 50 12.6 34.8)  ;; returns 21924
(\*)               ;; returns 1

namespaces

Mon, 01 Jan 0001 00:00:00 +0000

These forms work with Ale namespaces. define-namespace creates and populates a namespace. import brings public names from another namespace into scope, either all at once or through explicit names and aliases. declared returns the names declared in the current or specified namespace.

An Example

(define-namespace demo
  (define answer 42))
(import demo answer)

not

Mon, 01 Jan 0001 00:00:00 +0000

Return #f (false) if the provided form is truthy, otherwise will return #t (true).

An Example

(not "hello")

This will return the boolean #f (false) because the value “hello” is truthy.

not equal to (!=)

Mon, 01 Jan 0001 00:00:00 +0000

nth

Mon, 01 Jan 0001 00:00:00 +0000

Returns the value that can be found at the specified index of its sequence. If the index is out of the bounds of the sequence, then either the default value is returned or an error is raised. Keep in mind that indexes are zero-based.

If the sequence is lazily computed, asynchronous, or otherwise incapable of indexed lookup, this function will raise an error. To perform a brute-force lookup, use the nth! function, keeping in mind that it may never return a result.

null?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to null (empty list), then this function will return #t (true). The first non-null will result in the function returning #f (false).

An Example

(null? '(1 2 3 4) '())

This example will return #f (false) because the first form is a list.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be null.

object

Mon, 01 Jan 0001 00:00:00 +0000

Create a new object (hash-map) based on the provided key-value pairs, or return an empty object if no forms are provided. This function is no different from the object literal syntax except that it can be treated in a first-class fashion.

An object can be iterated over as a sequence. The resulting sequence is guaranteed to have no duplicated keys, but is not guaranteed to return in any particular order.

object?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to an object (hash-map), then this function will return #t (true). The first non-object will result in the function returning #f (false).

An Example

(object? {:name "bill"} {:name "peggy"} [1 2 3])

This example will return #f (false) because the third form is a vector.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be objects.

or

Mon, 01 Jan 0001 00:00:00 +0000

Evaluate forms from left to right. As soon as one evaluates to a truthy value, will return that value. Otherwise, it will proceed to evaluate the next form.

An Example

(or (+ 1 2 3)
    false
    "not returned")

Will return 6, never evaluating false (false) and "not returned", whereas:

(or false
    '()
    "returned")

Will return the string “returned”.

partial

Mon, 01 Jan 0001 00:00:00 +0000

Returns a new function whose initial arguments are pre-bound to those provided. When that function is invoked, any provided arguments will simply be appended to the pre-bound arguments before calling the original function.

An Example

(define plus10 (partial + 4 6))
(plus10 9)

This example will return 19 as though (+ 4 6 9) were called.

partition

Mon, 01 Jan 0001 00:00:00 +0000

Partition a sequence into groups of count elements, incrementing by the number of elements defined in step (or count if step is not provided).

An Example

(seq->list (partition 2 3 [1 2 3 4 5 6 7 8 9 10]))

This example will return ((1 2) (4 5) (7 8) (10)).

predicates

Mon, 01 Jan 0001 00:00:00 +0000

These predicates test values for specific types or properties. Each predicate has a corresponding negated version prefixed with “!”. For example, number? tests if a value is a number, while !number? tests if it is not a number.

Examples

;; Type checking
(number? 42)     ; -> #t
(boolean? true)  ; -> #t
(symbol? 'abc)   ; -> #t
(procedure? +)   ; -> #t

;; Value properties
(nan? (/ 0.0 0))  ; -> #t
(inf? +inf)       ; -> #t
(-inf? -inf)      ; -> #t
(even? 2)         ; -> #t
(odd? 3)          ; -> #t

;; Sequences
(pair? '(1 . 2))         ; -> #t
(appendable? [1 2 3])    ; -> #t ; vectors are appendable
(reversible? [1 2 3])    ; -> #t ; vectors can be reversed
(!appendable? '(1 2 3))  ; -> #t ; lists are not appendable

;; Symbols
(local? 'x)         ; -> #t ; for non-qualified symbols
(qualified? 'ns/x)  ; -> #t ; for namespace-qualified symbols

;; Special forms and macros
(special? lambda)  ; -> #t  ; lambda is a special form
(macro? when)      ; -> #t  ; when is a macro

;; Promise state
(define p (delay (+ 1 2)))
(resolved? p)  ; -> #f  ; not yet computed
(force p)
(resolved? p)  ; -> #t  ; now computed

Note that each negated predicate (!predicate?) returns the opposite of its corresponding positive predicate. For example, (!even? 3) is equivalent to (not (even? 3)).

printing

Mon, 01 Jan 0001 00:00:00 +0000

These functions print space-separated values to *out*. print and println use the regular string conversion. pr and prn use reader-oriented output via str!. println and prn append a trailing newline.

An Example

(println "hello" 42)
(prn {:name "ale"})

promise?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a promise, then this function will return #t (true). The first non-promise will result in the function returning #f (false).

An Example

(define p1 (delay "one"))
(define p2 (delay "two"))
(promise? p1 p2 [1 2 3])

This example will return #f (false) because the third form is a vector.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be promises.

quote

Mon, 01 Jan 0001 00:00:00 +0000

Meaning that lists and symbols will not be evaluated. This macro is effectively the same as prepending an expression with an apostrophe (’).

An Example

(quote (1 2 3 4))

This will return the literal list rather than trying to apply the number 1, as if it were a function. It is synonymous with the expression '(1 2 3 4).

raise

Mon, 01 Jan 0001 00:00:00 +0000

Converts its arguments to a string and raises the resulting value as an error.

An Example

(raise "unexpected value: " 42)

range

Mon, 01 Jan 0001 00:00:00 +0000

Creates a lazy sequence that presents the numbers from min (inclusive) to max (exclusive), by increment. All parameters are optional. min defaults to 0, max defaults to *pos-inf*, and step defaults to 1. If only one argument is provided, it is treated as max.

An Example

(seq->vector (take 5 (range 10 inf 5)))

Will return the vector [10 15 20 25 30].

read

Mon, 01 Jan 0001 00:00:00 +0000

recover

Mon, 01 Jan 0001 00:00:00 +0000

Invokes the zero-argument procedure body. If evaluation raises or panics, the runtime normalizes the error and passes the resulting Ale value to the single-argument procedure rescue. This is the procedural building block used by higher-level error macros such as try.

An Example

(recover
  (thunk (raise "boom"))
  (lambda (err) (str "caught: " err)))

reduce

Mon, 01 Jan 0001 00:00:00 +0000

Iterates over a set of sequence, reducing their elements to a single resulting value. The function provided must take two arguments. The first and second sequence elements encountered are the initial values applied to that function. Thereafter, the result of the previous calculation is used as the first argument, while the next element is used as the second argument.

An Example

(reduce + 5 (range 1 11))

This will return the value 60.

remainder (mod)

Mon, 01 Jan 0001 00:00:00 +0000

Takes a set of numbers and calculates the collective remainder of dividing each by the next.

An Example

(mod 10 3)      ;; returns 1
(mod 20 7.0 4)  ;; returns 2.0

reverse

Mon, 01 Jan 0001 00:00:00 +0000

reverse requires a reversible sequence. reverse! will reverse reversible sequences directly, and otherwise materialize the sequence before reversing it.

An Example

(reverse [1 2 3 4])

This example returns [4 3 2 1].

seq

Mon, 01 Jan 0001 00:00:00 +0000

Attempt to convert the provided form to a sequence if it isn’t already. If the form cannot be converted, or if the resulting sequence is empty, the empty list will be returned.

An Example

(when-let [s (seq "hello")]
  (seq->vector (map (lambda (x) (str x "-")) s)))

This example will return [“h-” “e-” “l-” “l-” “o-”].

seq->list

Mon, 01 Jan 0001 00:00:00 +0000

Concatenate a set of sequences into a list. Unlike the standard concat function, which is lazily computed, the result of this function will be materialized immediately.

An Example

(define x [1 2 3 4])
(define y
  (map (lambda (x) (+ x 4))
  '(1 2 3 4)))
(seq->list x y)

seq->object

Mon, 01 Jan 0001 00:00:00 +0000

Concatenate a set of sequences into an object (hash-map). Unlike the standard concat function, which is lazily computed, the result of this function will be materialized immediately.

An Example

(define x [:name "ale" :age 0.3])
(define y '(:weight "light"))
(seq->object x y)

seq->set

Mon, 01 Jan 0001 00:00:00 +0000

Concatenates one or more sequences into a set. Duplicate values collapse to a single member.

An Example

(seq->set [1 2] '(2 3))

This example returns #{1 2 3}.

seq->vector

Mon, 01 Jan 0001 00:00:00 +0000

Concatenate a set of sequences into a vector. Unlike the standard concat function, which is lazily computed, the result of this function will be materialized immediately.

An Example

(define x
  (map (lambda (x) (\* x 2))
  '(1 2 3 4)))
(seq->vector '(1 2 3 4) x)

seq!

Mon, 01 Jan 0001 00:00:00 +0000

Returns value when it can act as a non-empty sequence. If value is a sequence but empty, returns #f. If value cannot act as a sequence at all, an error is raised.

seq?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a valid sequence, then this function will return #t (true). The first non-sequence will result in the function returning #f (false).

An Example

(seq? '(1 2 3 4) [5 6 7 8])

This example will return #t (true).

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be valid sequences.

sequence combinators

Mon, 01 Jan 0001 00:00:00 +0000

These helpers build or transform sequences. zip groups aligned values into lists and stops when the shortest input ends. mapcat maps, then lazily concatenates the mapped results. cartesian-product produces every combination across the provided sequences. map! eagerly maps into a list. take-while lazily consumes values while a predicate stays true.

set

Mon, 01 Jan 0001 00:00:00 +0000

Creates a persistent set containing unique values. Set literals can also be written with #{...} reader syntax.

An Example

(set 1 2 2 3)

This example returns #{1 2 3}.

set?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to sets, this function returns #t (true). Otherwise it returns #f (false).

An Example

(set? #{1 2 3} (set 4 5 6))

some first (some->)

Mon, 01 Jan 0001 00:00:00 +0000

Like ->, but returns the empty list as soon as any form evaluates as such.

some last (some->>)

Mon, 01 Jan 0001 00:00:00 +0000

Like ->>, but returns the empty list as soon as any form evaluates as such.

spawn

Mon, 01 Jan 0001 00:00:00 +0000

Starts an actor-like process whose function receives a mailbox sequence. The returned value is a sender procedure that can emit messages into that mailbox. The default mailbox size is 16. If a monitor procedure is provided, it is used to handle raised values from the actor body.

An Example

(define send
  (spawn (lambda (mailbox) (first mailbox))))

special

Mon, 01 Jan 0001 00:00:00 +0000

Constructs a compiler special form directly from parameter cases and assembler instructions. This is the low-level mechanism used to define forms such as if, and is mainly useful for core language implementation work rather than regular user code.

str

Mon, 01 Jan 0001 00:00:00 +0000

Creates a new string from the stringified values of the provided forms.

An Example

(str "hello" [1 2 3 4])

This example will return the string “hello[1 2 3 4]”.

Reader Strings

Alternatively, one can use the str! function to produce a stringified version that may be able to be read by the Ale reader.

(str! "hello" [1 2 3 4])

This example will return the string ""hello" [1 2 3 4]".

str?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to string, then this function will return #t (true). The first non-string will result in the function returning #f (false).

An Example

(string? '(1 2 3 4) "hello")

This example will return #f (false) because the first form is a list.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be strings.

subtraction (-)

Mon, 01 Jan 0001 00:00:00 +0000

Takes a set of numbers and calculates their collective difference.

An Example

(- 50 35 6)  ;; returns 9
(- 12 3.5)   ;; returns 8.5
(- 6)        ;; returns -6

sym

Mon, 01 Jan 0001 00:00:00 +0000

Convert the provided string into a symbol. Both qualified and local symbols are accepted.

An Example

(define hello-sym (sym "hello"))
(eq hello-sym 'hello)

This example will return #t (true).

syntax-quote

Mon, 01 Jan 0001 00:00:00 +0000

Quotes a form while resolving symbols hygienically. Within a syntax-quoted form, unquote and unquote-splicing can inject evaluated values.

An Example

(let [x 99]
  `(list ,x))

take

Mon, 01 Jan 0001 00:00:00 +0000

Return a lazy sequence of either count or fewer elements from the beginning of the provided sequence. If the source sequence is shorter than the requested count, the resulting sequence will be truncated.

An Example

(define x '(1 2 3 4))
(define y [5 6 7 8])
(take 6 (concat x y))

This example will return the lazy sequence (1 2 3 4 5 6).

thread first (->)

Mon, 01 Jan 0001 00:00:00 +0000

Evaluates expr and threads it through the supplied forms as their first argument. Any form that is not already a function call will be converted into one before threading.

An Example

(-> 0 (+ 10) (\* 2) (/ 5))

Will expand to (/ (\* (+ 0 10) 2) 5) and return 4.

thread last (->>)

Mon, 01 Jan 0001 00:00:00 +0000

Evaluates expr and threads it through the supplied forms as their last argument. Any form that is not already a function call will be converted into one before threading.

An Example

(->> 0 (+ 10) (\* 2) (/ 5.0))

Will expand to (/ 5.0 (\* 2 (+ 10 0))) and return 0.25.

time

Mon, 01 Jan 0001 00:00:00 +0000

Evaluates the provided forms, prints the elapsed duration to standard output, and returns the value of the final form. Durations under 1000 are printed in nanoseconds; longer durations are printed in milliseconds.

An Example

(time (+ 1 2 3))

true?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to true (#t), then this function will return #t (true). The first non-true will result in the function returning #f (false).

An Example

(true? (> 3 2) (< 5 10) (and #t #f))

This example will return #f (false) because the last form evaluates to #f.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be true. This is equivalent to the false? predicate.

try/catch

Mon, 01 Jan 0001 00:00:00 +0000

Evaluate the provided forms, immediately short-circuiting if an error is raised, at which point control is passed into the first catch clause whose predicate evaluates to #t (true). If a finally clause is defined, control will be passed into it after a successful evaluation of the provided forms or after a catch clause is evaluated.

catch-clause is defined as (catch [name predicate] form*)

finally-clause is defined as (finally form*)

An Example

(try
  (raise "hello!")
  (println "won't reach me")
  (catch [n inf?] (println "won't match me"))
  (catch [s str?] (println "was a string ->" s))
  (finally (println "done")))

This will print the following to the console.

type helpers

Mon, 01 Jan 0001 00:00:00 +0000

These helpers work with Ale types. assert-type returns value when it matches type, otherwise it raises. is-a looks up the predicate for a builtin type keyword and applies it to value.

An Example

(assert-type :number 42)
(is-a :string "hello")

utility helpers

Mon, 01 Jan 0001 00:00:00 +0000

These are small utility forms used throughout Ale programs. identity returns its argument unchanged. constantly returns a function that always yields the same value. no-op ignores its arguments and returns null. thunk wraps forms in a zero-argument function.

vector

Mon, 01 Jan 0001 00:00:00 +0000

Create a new vector whose elements are the evaluated forms provided. This function is no different from the vector literal syntax except that it can be treated in a first-class fashion.

An Example

(define x "hello")
(define y "there")
(vector x y)

vector?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to a vector, then this function will return #t (true). The first non-vector will result in the function returning #f (false).

An Example

(vector? '(1 2 3 4) [5 6 7 8])

This example will return #f (false) because the first form is a list.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be vectors.

when

Mon, 01 Jan 0001 00:00:00 +0000

If the evaluated predicate is truthy (not #f (false) or the empty list), the forms are evaluated. Will evaluate each form in turn, returning the final evaluation as its result.

An Example

(define x '(1 2 3 4 5 6 7 8))

(when (> (length x) 3)
  (println "x is big")
  (length x))

If the symbol when-not is used instead of when, then the predicate is evaluated and the block will be evaluated only if the result is not truthy

with-open

Mon, 01 Jan 0001 00:00:00 +0000

Binds one or more values and ensures their :close procedures are called after the body finishes, even if an error is raised. If a bound value does not expose a callable :close, cleanup for that binding becomes a no-op.

An Example

(with-open [r (:some-resource factory)]
  (: r :read))

zero?

Mon, 01 Jan 0001 00:00:00 +0000

If all forms evaluate to zero (0, 0.0, or 0/x), then this function will return #t (true). The first non-zero will result in the function returning #f (false).

An Example

(zero? (- 3 2 1) 0 0/1 (/ 3 3))

This example will return #f (false) because the last form evaluates to 1.

Like most predicates, this function can also be negated by prepending the ! character. This means that all the provided forms must not be zero.