Dynamic

This module contains dynamic functions which are used in the Carp repl and during compilation. They are not available in compiled code. Read more about dynamic functions in the Language Guide.

*

command

Dynamic

multiplies its two arguments.

Example Usage:

(* 2 3) ; => 6

+

command

Dynamic

adds its two arguments.

Example Usage:

(+ 1 2) ; => 3

-

command

Dynamic

subtracts its second argument from its first.

Example Usage:

(- 1 2) ; => -1

/

command

Dynamic

divides its first argument by its second.

Example Usage:

(/ 4 2) ; => 2

/=

dynamic

Dynamic

                        (/= a b)
                    

<

command

Dynamic

checks whether its first argument is less than its second.

Example Usage:

(< 1 2) ; => true

=

command

Dynamic

compares its arguments for equality.

Example Usage:

(= 1 2) ; => false

>

command

Dynamic

checks whether its first argument is greater than its second.

Example Usage:

(> 1 2) ; => false

Debug

module

Module

List

module

Module

Map

module

Module

Pair

module

Module

Random

module

Module

all-but-last

command

Dynamic

gets all elements except for the last one of a list or array.

Example Usage:

(all-but-last '(1 2 3)) ; => '(1 2)

all?

dynamic

Dynamic

                        (all? f xs)
                    

Checks whether all of the elements in xs conform to the predicate function f.

(all? (fn [x] (< 1 x)) '(2 3 4))
=> true
(all? (fn [x] (< 1 x)) '(-1 0 1))
=> false

any?

dynamic

Dynamic

                        (any? f xs)
                    

Checks whether any of the elements in xs conforms to the predicate function f.

(any? (fn [x] (= 'a x)) '(a b c))
=> true
(any? (fn [x] (= 'a x)) '(e f g))
=> false

append

command

Dynamic

appends two lists or arrays.

Example Usage:

(append '(1 2) '(3 4)) ; => '(1 2 3 4)

apply

dynamic

Dynamic

                        (apply f argument-list)
                    

Applies the function f to the provided argument list, passing each value in the list as an argument to the function.

array

command

Dynamic

creates an array from a collection of elements.

Example Usage:

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

array?

dynamic

Dynamic

                        (array? s)
                    

build

command

Dynamic

builds the current code to an executable. Optionally takes a boolean that, when true, silences the output.

Example Usage:

(build)

c

command

Dynamic

prints the C code emitted for a binding.

Example Usage:

(c '(+ 2 3)) ; => int _3 = Int__PLUS_(2, 3);

caaaar

dynamic

Dynamic

                        (caaaar pair)
                    

caaadr

dynamic

Dynamic

                        (caaadr pair)
                    

caaar

dynamic

Dynamic

                        (caaar pair)
                    

caadar

dynamic

Dynamic

                        (caadar pair)
                    

caaddr

dynamic

Dynamic

                        (caaddr pair)
                    

caadr

dynamic

Dynamic

                        (caadr pair)
                    

caar

dynamic

Dynamic

                        (caar pair)
                    

cadaar

dynamic

Dynamic

                        (cadaar pair)
                    

cadadr

dynamic

Dynamic

                        (cadadr pair)
                    

cadar

dynamic

Dynamic

                        (cadar pair)
                    

caddar

dynamic

Dynamic

                        (caddar pair)
                    

cadddr

dynamic

Dynamic

                        (cadddr pair)
                    

caddr

dynamic

Dynamic

                        (caddr pair)
                    

cadr

dynamic

Dynamic

                        (cadr pair)
                    

car

command

Dynamic

gets the head of a list or array.

Example Usage:

(car '(1 2 3)) ; => 1

cat

command

Dynamic

spits out the generated C code.

Example Usage:

(cat)

cdaaar

dynamic

Dynamic

                        (cdaaar pair)
                    

cdaadr

dynamic

Dynamic

                        (cdaadr pair)
                    

cdaar

dynamic

Dynamic

                        (cdaar pair)
                    

cdadar

dynamic

Dynamic

                        (cdadar pair)
                    

cdaddr

dynamic

Dynamic

                        (cdaddr pair)
                    

cdadr

dynamic

Dynamic

                        (cdadr pair)
                    

cdar

dynamic

Dynamic

                        (cdar pair)
                    

cddaar

dynamic

Dynamic

                        (cddaar pair)
                    

cddadr

dynamic

Dynamic

                        (cddadr pair)
                    

cddar

dynamic

Dynamic

                        (cddar pair)
                    

cdddar

dynamic

Dynamic

                        (cdddar pair)
                    

cddddr

dynamic

Dynamic

                        (cddddr pair)
                    

cdddr

dynamic

Dynamic

                        (cdddr pair)
                    

cddr

dynamic

Dynamic

                        (cddr pair)
                    

cdr

command

Dynamic

gets the tail of a list or array.

Example Usage:

(cdr '(1 2 3)) ; => '(2 3)

collect-into

dynamic

Dynamic

                        (collect-into xs f)
                    

Transforms a dynamic data literal into another, preserving order

column

primitive

Dynamic

returns the column a symbol was defined on.

Example Usage:

(column mysymbol)

compose

dynamic

Dynamic

                        (compose f g)
                    

Returns the composition of two functions f and g for functions of any arity; concretely, returns a function accepting the correct number of arguments for g, applies g to those arguments, then applies f to the result.

If you only need to compose functions that take a single argument (unary arity) see comp. Comp also generates the form that corresponds to the composition, compose contrarily evaluates 'eagerly' and returns a computed symbol.

;; a silly composition
((compose empty take) 3 [1 2 3 4 5])
;; => []

(String.join (collect-into ((compose reverse map) Symbol.str '(p r a c)) array))
;; => 'carp'

;; comp for comparison
((comp (curry + 1) (curry + 2)) 4)
;; => (+ 1 (+ 2 4))

cons

command

Dynamic

adds an element to the front of an array or list

Example Usage:

(cons 1 '(2 3)) ; => '(1 2 3)

cons-last

command

Dynamic

adds an element to the back of an array or list

Example Usage:

(cons-last 3 '(1 2)) ; => '(1 2 3)

curry

dynamic

Dynamic

                        (curry f x)
                    

Returns a curried function accepting a single argument, that applies f to x and then to the following argument.

(map (curry Symbol.prefix 'Foo) '(bar baz))
=> (Foo.bar Foo.baz)

curry*

dynamic

Dynamic

                        (curry* f :rest args)
                    

Curry functions of any arity.

(map (curry* Dynamic.zip + '(1 2 3)) '((4 5) (6)))
=> (((+ 1 4) (+ 2 5)) ((+ 1 6)))

((curry* Dynamic.zip cons '(1 2 3)) '((4 5) (6)))
=> ((cons 1 (4 5)) (cons (2 (6))))

(defndynamic add-em-up [x y z] (+ (+ x y) z))
(map (curry* add-em-up 1 2) '(1 2 3))
=> (4 5 6)

cxr

dynamic

Dynamic

                        (cxr x pair)
                    

takes a specification of a traversal in a (head) and d (tail) symbols and a list pair to traverse.

Example:

(cxr '(1 a 1 d) '(1 2 3)) ; => 2

(cxr '(1 a 1 d 1 a 4 d) '(1 2 3 4 (5 6 7))) ; => 6

dec

dynamic

Dynamic

                        (dec x)
                    

decrements a number.

defdynamic

primitive

Dynamic

defines a new dynamic value, i.e. a value available at compile time.

Example Usage:

(defdynamic name value)

defined?

primitive

Dynamic

checks whether a symbol is defined.

Example Usage:

(defined? mysymbol)

definterface

primitive

Dynamic

defines a new interface (which could be a function or symbol).

Example Usage:

(definterface mysymbol MyType)

defmacro

primitive

Dynamic

defines a new macro.

Example Usage:

(defmacro name [args :rest restargs] body)

defmodule

primitive

Dynamic

defines a new module in which expressions are defined.

Example Usage:

(defmodule MyModule <expressions>)

defndynamic

primitive

Dynamic

defines a new dynamic function, i.e. a function available at compile time.

Example Usage:

(defndynamic name [args] body)

deftemplate

primitive

Dynamic

defines a new C template.

Example Usage:

(deftemplate symbol Type declString defString)

deftuple

macro

Macro

                        (deftuple name :rest props)
                    

defines a tuple type.

For example:

; is the definition of Pair in the stdlib
(deftuple Pair a b)

deftype

primitive

Dynamic

defines a new sumtype or struct.

Example Usage:

(deftype Name <members>)

dynamic-type

command

Dynamic

Gets the dynamic type as a string.

Example Usage:

(dynamic-type '()) ; => "list"

empty

dynamic

Dynamic

                        (empty xs)
                    

Returns the empty form of xs.

(empty '(1 2 3 4))
=> ()
(empty '[1 2 3 4])
=> []

empty?

dynamic

Dynamic

                        (empty? xs)
                    

Returns true if the provided data literal is empty, false otherwise.

env

command

Dynamic

lists all current bindings.

Example Usage:

(env)

eval

primitive

Dynamic

evaluates a list.

Example Usage:

(eval mycode)

even?

dynamic

Dynamic

                        (even? n)
                    

checks whether the number n is even.

expand

command

Dynamic

expands a macro and prints the result.

Example Usage:

(expand '(when true 1)) ; => (if true 1 ())

expand-compiled

command

Dynamic

expands and desugars the code.

Example Usage:

(expand-compiled '(+ 2 3)) ; => (Int.+ 2 3)

file

primitive

Dynamic

returns the file a symbol was defined in.

Example Usage:

(file mysymbol)

filter

dynamic

Dynamic

                        (filter p xs)
                    

Returns a list containing only the elements of xs that satisify predicate p.

(filter (fn [x] (= 'a x)) '(a b a b a b a b))
=> (a a a a)

flatten

dynamic

Dynamic

                        (flatten l)
                    

Flattens a list recursively.

(flatten '(1 2 (3 (4))))
=> '(1 2 3 4)

flip

dynamic

Dynamic

                        (flip f)
                    

Flips the arguments of a function f.

((flip Symbol.prefix) 'Bar 'Foo)
=> (Foo.Bar)

get-env

command

Dynamic

gets an environment variable. The result will be () if it isn’t set.

Example Usage:

(read-file "CARP_DIR")

hash

command

Dynamic

calculates the hash associated with a value.

Example Usage:

(hash '('my 'value)) ; => 3175346968842793108

help

primitive

Dynamic

prints help.

Example Usage:

(help)

host-arch

command

Dynamic

prints the host architecture (as returned by the Haskell function System.Info.arch).

Example Usage:

(host-arch)

host-bit-width

command

Dynamic

gets the bit width of the host platform.

Example Usage:

(host-bit-width) ; => your host machine’s bit width, e.g. 32 or 64

host-os

command

Dynamic

prints the host operating system (as returned by the Haskell function System.Info.os).

Example Usage:

(host-os)

imod

dynamic

Dynamic

                        (imod x y)
                    

implements modulo on integers, and is much faster than `mod.

implements

primitive

Dynamic

designates a function as an implementation of an interface.

Example Usage:

(implements zero Maybe.zero)

inc

dynamic

Dynamic

                        (inc x)
                    

increments a number.

info

primitive

Dynamic

prints all information associated with a symbol.

Example Usage:

(info mysymbol)

kind

primitive

Dynamic

prints the kind of a symbol.

Example Usage:

(kind mysymbol)

last

command

Dynamic

gets the last element of a list or array.

Example Usage:

(last '(1 2 3)) ; => 3

length

command

Dynamic

returns the length of the argument (must be an array, string or list).

Example Usage:

(length '(1 2 3)) ; => 3

line

primitive

Dynamic

returns the line a symbol was defined on.

Example Usage:

(line mysymbol)

list

command

Dynamic

creates an array from a collection of elements.

Example Usage:

(list 1 2 3) ; => (1 2 3)

list?

dynamic

Dynamic

                        (list? s)
                    

load

command

Dynamic

loads a file into the current environment.

Example Usage:

(load "myfile.carp")
(load "myrepo@version" "myfile")

load-once

command

Dynamic

loads a file and prevents it from being reloaded (see reload).

Example Usage:

(load-once "myfile.carp")
(load "myrepo@version" "myfile")

macro-error

command

Dynamic

logs an error and errors out of a macro.

Example Usage:

(macro-error "this is wrong")

macro-log

command

Dynamic

logs a message in a macro.

Example Usage:

(macro-log "this will be printed at compile time")

managed?

primitive

Dynamic

checks whether a type is managed by Carp by checking whether delete was implemented for it. For an explanation of memory management, you can reference this document.

Example Usage:

(register-type Unmanaged "void*")
(managed? Unmanaged) ; => false

map

dynamic

Dynamic

                        (map f xs)
                    

Applies a function f to each element in the list or array xs and returns a list dynamic data literal containing the result of the function applications.

'(map symbol? '(a b c))
=> (true true true)
'(map (curry + 1) '(1 2 3))
=> (2 3 4)

members

primitive

Dynamic

returns the members of a type as an array.

Example Usage:

(members MyType)

meta

primitive

Dynamic

gets the value under "mykey" in the meta map associated with a symbol. It returns () if the key isn’t found.

Example Usage:

(meta mysymbol "mykey")

meta-set!

primitive

Dynamic

sets a new key and value pair on the meta map associated with a symbol.

Example Usage:

(meta-set! mysymbol "mykey" "myval")

mod

dynamic

Dynamic

                        (mod x y)
                    

implements modulo, is slower than modulo specialized on integers imod.

n-times

dynamic

Dynamic

                        (n-times n f)
                    

make a list by executing f n times.

neg

dynamic

Dynamic

                        (neg x)
                    

negates a number.

nil

defdynamic

Dynamic

is the value nil, i.e. the empty list.

nil?

dynamic

Dynamic

                        (nil? value)
                    

checks whether a value is nil, i.e. the empty list.

not

command

Dynamic

negates its boolean argument.

Example Usage:

(not false) ; => true

nthcar

dynamic

Dynamic

                        (nthcar n pair)
                    

takes the nth head or car of the list pair.

nthcdr

dynamic

Dynamic

                        (nthcdr n pair)
                    

takes the nth tail or cdr of the list pair.

number?

dynamic

Dynamic

                        (number? s)
                    

odd?

dynamic

Dynamic

                        (odd? n)
                    

checks whether the number n is odd.

parse

command

Dynamic

parses a string into an expression

Example Usage:

(parse "(+ 1 2)") ; => (+ 1 2)

postwalk

dynamic

Dynamic

                        (postwalk f form)
                    

Performs a depth-first, post-order traversal of form and calls f on each subform, collecting the result.

Example:

; note: this could be achieved using `walk-replace` as well
(postwalk (fn [x]
            (cond
              (= x '+) '*
              (= x '-) '/
              x))
          '(+ 1 (- 2 3))) ; => (* 1 (/ 2 3))

prewalk

dynamic

Dynamic

                        (prewalk f form)
                    

behaves like postwalk, but does pre-order traversal.

Example:

(prewalk (fn [x] (if (number? x) (* x 4) x)) '(+ 1 (- 2 3))) ; => (+ 4 (- 8 12))

proc?

dynamic

Dynamic

                        (proc? x)
                    

checks whether x is callable.

project

command

Dynamic

prints the current project state.

Example Usage:

(project)

quit

command

Dynamic

quits the program.

Example Usage:

(quit)

quote

primitive

Dynamic

quotes any value.

Example Usage:

(quote x) ; where x is an actual symbol

quoted

dynamic

Dynamic

                        (quoted x)
                    

read-file

command

Dynamic

reads a file into a string.

Example Usage:

(read-file "myfile.txt")

reduce

dynamic

Dynamic

                        (reduce f x xs)
                    

Reduces or 'folds' a data literal, such as a list or array, into a single value through successive applications of f.

register

primitive

Dynamic

registers a new function. This is used to define C functions and other symbols that will be available at link time.

Example Usage:

(register name <signature> <optional: override>)

register-type

primitive

Dynamic

registers a new type from C.

Example Usage:

(register-type Name <optional: c-name> <optional: members>)

relative-include

command

Dynamic

adds a relative include, i.e. a C include with quotes. It also prepends the current directory.

Example Usage:

(relative-include "myheader.h")

reload

command

Dynamic

reloads all currently loaded files that weren’t marked as only loading once (see load and load-once).

Example Usage:

(reload)

reverse

dynamic

Dynamic

                        (reverse xs)
                    

Reverses the order of elements in an array or list.

(reverse [1 2 3 4])
=> [4 3 2 1]

round

command

Dynamic

rounds its numeric argument.

Example Usage:

(round 2.4) ; => 2

run

command

Dynamic

runs the built executable.

Example Usage:

(run)

run-exe-with-args

command

Dynamic

runs an executable with arguments.

Example Usage:

(run-exe-with-args "path-to-executable" 1 2 3)

run-with-args

command

Dynamic

runs the built executable with arguments.

Example Usage:

(run-with-args 1 2 3)

s-expr

command

Dynamic

returns the s-expression associated with a binding. When the binding is a type, the deftype form is returned instead of the type's module by default. Pass an optional bool argument to explicitly request the module for a type instead of its definition form. If the bool is true, the module for the type will be returned. Returns an error when no definition is found for the binding.

Example Usage:

(s-expr foo), (s-expr foo true)

save-docs-ex

command

Dynamic

takes two arrays, one with paths to modules (as symbols), and one with filenames (as strings). The filenames are used to emit global symbols in those files into a 'Global' module.

Example Usage:

(save-docs-internal '(ModuleA ModuleB) '("globals.carp"))

set-env

command

Dynamic

sets an environment variable.

Example Usage:

(set-env "CARP_WAS_HERE" "true")

sort

dynamic

Dynamic

                        (sort l compare)
                    

Sorts a list using the provided predicate. It is not a stable sort. Example:

(sort '(1 3 4 2 5 4) <) ; => (1 2 3 4 4 5)
(sort '(1 3 4 2 5 4) >) ; => (5 4 4 3 2 1)
(sort '("one" "two---" "three" "four") (fn [a b] (< (String.length a) (String.length b)))) ; => ("one" "four" "three" "two---")

str

command

Dynamic

stringifies its arguments.

Example Usage:

(str 1 " " 2 " " 3) ; => "1 2 3"

string?

dynamic

Dynamic

                        (string? s)
                    

structured-info

primitive

Dynamic

gets all information associated with a symbol as a list of the form (type|(), info|(), metadata).

Example Usage:

(structured-info mysymbol)

symbol?

dynamic

Dynamic

                        (symbol? s)
                    

system-include

command

Dynamic

adds a system include, i.e. a C #include with angle brackets (<>).

Example Usage:

(system-include "stdint.h")

take

dynamic

Dynamic

                        (take n xs)
                    

Returns a list containing the first n elements of a list.

(take 3 '(1 2 3 4 5))
=> (1 2 3)

type

primitive

Dynamic

prints the type of a symbol.

Example Usage:

(type mysymbol)

unreduce

dynamic

Dynamic

                        (unreduce f x lim acc)
                    

Applies f to a starting value x, then generates a sequence of values by successively applying f to the result lim-1 times. Collects results in the structure given by acc.

(unreduce (curry + 1) 0 10 (list))
=> (1 2 3 4 5 6 7 8 9 10)

use

primitive

Dynamic

uses a module, i.e. imports the symbols inside that module into the current module.

Example Usage:

(use MyModule)

walk

dynamic

Dynamic

                        (walk inner outer form)
                    

traverses form, an arbitrary data structure, using the functions inner and outer. It will apply inner to each element of form, building up a data structure of the same type, then applies outer to the result. It recognizes arrays and lists. Other data structures will just be passed to outer.

Example:

(walk car reverse [[1 2] [3 4] [5 6]]) ; => [5 3 1]

walk-replace

dynamic

Dynamic

                        (walk-replace pairs form)
                    

Performs a depth-first, pre-order traversal of form and finds a matching replacement for each subform in the replacement pairs pairs, if applicable, collecting the result.

Example:

(walk-replace '((+ *) (- /)) '(+ 1 (- 2 3))) ; => (* 1 (/ 2 3))

write-file

command

Dynamic

writes a string to a file.

Example Usage:

(write-file "myfile" "hello there!")

zip

dynamic

Dynamic

                        (zip f :rest forms)
                    

Returns the form that results from applying a function f to each of the values supplied in forms. If the members of a single form are exhuasted, the result of the applications thus far is returned, and any remaining members in the other forms are ignored.

(zip + '(1 2 3) '(4 5 6))
=> ((+ 1 4) (+ 2 5) (+ 3 6))

It's important to note that zip operates on forms, and that the form returned by zip may not be evaluable by itself. For instance, to actually transform the result in the example above into something Carp can evaluate, we need to wrap each member of the list in a do:

(append (list 'do) (zip + '(1 2 3) '(4 5 6)))
=> (do (+ 1 4) (+ 2 5) (+ 3 6))
(eval (append (list 'do) (zip + '(1 2 3) '(4 5 6))))
=> 9 ;; do returns the value of the last form in its body