acme.helpers.interpreter.Interpreter

Execute a symbol list.

This function is used internally by the interpreter.

Return True if all of the arguments are True. The arguments can be a list of symbols. The type of all arguments must be Bool.

(any true false) -> false
(any true true) -> true
(any '(false false)) -> false
(any '(true true)) -> true

Return True if any of the arguments is True. The arguments can be a list of symbols. The type of all arguments must be Bool.

(any true false) -> true
(any false false) -> false
(any '(false false)) -> false
(any '(false true)) -> true

With the argv function one can access the individual arguments of a script.

• Without an index argument this function returns the whole argument list, including the script name.
• If the index is 0 then only the script name is returned.
• Otherwise the nth argument is returned, starting with 1.

(argv) -> The script name and all arguments
(argv 3) -> The third script arguments

Assert a condition. If it fails an exception is raised and script execution interrupted.

(assert (< x 4))

Base64-decode a string.

(base64-decode "SGVsbG8gV29ybGQ=") -> "Hello, World"

Base64-encode a string.

(base64-encode "Hello, World") -> SGVsbG8gV29ybGQ=

Execute a block of expressions.

;; Prints "Hello" and "World". The result is "World".
(block aSymbol
        (print "Hello")
        (print "World"))


;; Prints only "Hello". The result is 42.
(block aSymbol
        (print "Hello")
        (return-from aSymbol 42)
        (print "World"))

Just set and return a boolean value.

(true)

Get the first symbol of a list without changing the list.

(car (1 2 3)) -> 1

The case function implements multiple test-action clauses. It evaluates a symbol and compares the result against multiple action lists based on the evaluation of that symbol.

The special symbol otherwise is the default case if no other action list matches the symbol.

(case aSymbol
        ( 1 (print "Result: 1"))
        ( 2 (print "Result: 2"))
        (otherwise (print "Result: something else")))

The CDR of a list is the rest of the list without the first symbol. The original list is not changed.

(cdr '(1 2 3)) -> (2 3)

Concat symbols together.

Though this function is mainly for concatenation strings, all types are supported. No space is added between the symbols, but the special symbol sp can be used to add a space character.

(. "Hello" sp "world")

The cons function creates a new list out of a first element (the car) and a second element (the cdr).

It can be seens as the reverse of a car and a cdr function calls.

(cons "a" "b") -> ("a" "b")
(cons "a" ("b" "c")) -> ("a" "b" "c")
(cons ("a" "b") "c") -> (("a" "b") "c")

This function returns the the current time (UTC-based) in the specified format.

This function has an optional format paramater that is the same as the Python's strftime* function. The default is %Y%m%dT%H%M%S.%f, which evaluates to an ISO8901 timestamp.

(datetime) -> 20220107T221625.771604
(datetime "%H:%M") -> 13:31

This function defines a new function.

A new function may have zero, one or multiple arguments. The result of the last executed expression in the function determines the function's result.

(defun hello (name) (print (. "hello" sp name))) ;; define the function
(hello "Arthur") ;; call the function

This function executes a code block for each element in a list.

The first argument is a list that contains the loop variable symbol and the list to loop over. An optional third argument is the result variable for the loop. The second argument is the code block to execute.

(dolist (i (1 2 3)) (print i))
(dolist (i (1 2 3) result) (setq (+ result i))

This function executes a code block a number of times.

The first argument is a list that contains the loop counter symbol and the loop limit. An optional third argument is the result variable for the loop. The second argument is the code block to execute.

(dotimes (i 10) (print i))
(dotimes (i 10 result) (setq result i))

End script execution with an error. The optional argument will be assigned as the result of the script (pcontext.result).

(quit-with-error "Some error")

Evaluate a list as a function call.

(eval '(print "Hello, world"))

Enable or disable inline string evaluation.

(evaluate-inline false) ;; Disable inline evaluation

Filter a list based on a condition.

(filter (lambda (x) (< x 3)) (1 2 3 4 5)) -> (1 2)

This function defines an alias for a symbol.

An alias is a new symbol that points to an existing symbol. Aliased symbols can be aliases themselves.

The symbols must be quoted.

If the second symbold is not provided, then the alias is removed.

(fset 'aSymbol 'anotherSymbol)

Retrieve an attribute from a JSON structure via a key path.

(get-json-attribute { "a" : { "b" : "c" }} "a/b" ) -> "c"

Check whether an attribute exists in a JSON structure for a key path.

(has-json-attribute { "a" : { "b" : "c" }} "a/b" ) -> true

Check whether an expression evaluates to true and then execute a symbol or list. Otherwise a second, optional symbol or list is executed.

(if (< 1 2)
        (print "true")
        (print "false") )

Check whether a symbol is contained in a list, or a string is contained in another string.

(in "Hello" "Hello, World") -> true
(in a (b c)) -> false

Increment or decrement a variable by an optional value.

The default is 1.

(setq a 1)
(inc a 2) -> 3
(dec a) -> 2

Determine the index of a symbol or string in a list or string.

If the second argument is a string, then the first argument must also be a string.

(index-of 1 '(1 2 3)) -> 0
(index-of "a" '("b", "c", "d")) -> nil
(index-of "b" "abc") -> 1

Check whether a symbol, function, or variable is defined.

(setq a 1)
(is-defined a) -> true
(is-defined b) -> false

Escape a string for use in a JSON structure. Newlines and quotes are escaped.

(jsonify "Hello,
World") -> "Hello\nWorld"

Convert a JSON structure to a string.

(json-to-string { "a": 1 }) -> "{ "a": 1 }"

Define a nameless lambda function.

((lambda (x) (* x x)) 5) -> 25
(setq y (lambda (x) (* x x)))
((y) 5) -> 25

Get the length of a symbol or list.

(length "Hello, World") -> 11
(length (a b)) -> 2

Perform multipe assignments in sequence (let* function).

(let* (a 1)
          (a (+ a 1))) -> a = 2

Create a list out of the arguments

(list 1 2 3) -> (1 2 3)

Print a message to the debug or to the error log. Either the internal or a provided log function is used.

(log "Hello, World")

Convert a string to upper or lower case.

(upper "Hello, World") -> "HELLO, WORLD"
(lower "Hello, World") -> "hello, world

Apply a function to each element of a list or multiple lists, accumulating the result.

(map (lambda (x y) (+ x y)) '(1 2 3) '(4 6 7)) -> (5 8 10)

Apply a regular expression to a string and return whether it matches.

(match "aa" "a?") -> true
(match "aa" "b*") -> false

Get the minimum or maximum value of a list of numbers, strings or orher comparables.

(min (1 2 3)) -> 1
(min 1 2) -> 1
(max (1 2 3)) -> 3
(max 1 2) -> 2

Boolean not operation.

(not true) -> false

Get the nth element from a list, or the nth character from a string. The index is 0-based.

(nth 2 '(1 2 3)) -> 3
(nth 2 "Hello, World") -> "l"

Process various boolean and mathematical operations.

The supported operations are:

• "<": smaller
• "<=": smaller or equal
• ">": greater
• ">=": greater or equal
• "==": equal
• "!=": unequal
• "or": boolean or
• "|": boolean or
• "and": boolean and
• "&": boolean and
• "!": boolean not
• "+": Addition
• "-": Substraction
• "*": Multiplication
• "/": Division
• "//": Division, rounding down and returning an integer number
• "**": Power
• "%": Modulo

The mathematical operations may have more then two arguments.

(+ 1 2) -> 3
(+ 1 2 3) -> 6
(< 1 2) -> true

Parse a string as executable code and return it for evaluation.

(eval (parse-string "(print "hello, world")")) -> prints "hello, world"

Print the arguments to the console.

The function return the resulting string as a symbol.

(print "Hello, World")

Evaluate one or multiple symbols in a list. This is the explicite function that many

(progn (print "Hello, World"))

End script execution. The optional argument will be assigned as the result of the script in the PContext.result attribute.

(quit "some result") -> "some result"

Convert a symbol into a quotable version.

(quote (a b c)) -> '(a b c)

Generate a random float number in the given range. The default for the range is [0.0, 1.0]. If one argument is given then this indicates a range of [0.0, arg].

(random 1) -> 0.3
(random 2 3) -> 2.87

Apply a function to each element of a list or multiple lists, accumulating the result.

(reduce (lambda (x y) (+ x y)) '(1 2 3 4 5)) -> 15
(reduce '+ '(1 2 3 4 5) 10) -> 25

Remove an attribute from a JSON structure via its key path.

One may remove multiple attributes at once by providing multiple key paths.

(remove-json-attribute { "a" : { "b" : "c" }} "a/b") -> { "a" : {} }

Return from a function call or break from while loop.

While returning it is possible to pass a return value.

(return "some result") -> "some result"

Return from a named block.

(block "aBlock" 1 (return-from "aBlock" 2) 3) -> 2

Reverse a list or string.

(reverse '(1 2 3)) -> (3 2 1)

Return a number rounded to optional ndigits precision after the decimal point.

If ndigits, the second parameter, is omitted, it returns the nearest integer.

(round 1.6) -> 2
(round 1.678 2) -> 1.67

Set an attribute of a JSON structure via its key path.

One may set multiple values at one by providing a list of (key/values).

(set-json-attribute { "a" : { "b" : "c" }} "a/b" "d") -> { "a" : { "b" : "d" }
(set-json-attribute { "a" : { "b" : "c" }} '('("a/b" "d") '("a/c" "e"))) -> { "a" : { "b" : "d", "c" : "e"}

Set a variable. The second symbol is automatically quoted, so it is taken as the variable name.

(setq a "Hello, World") -> "Hello, World"

Sleep for a number of seconds.

This function can be interrupted when the script's state is set to any other state than running.

(sleep 2.5)

Return a slice of a string or list.

The behaviour is the same as slicing in Python, except that both start and end must be provided.

The first argument is the beginning of the slice, the second is the end (exlcuding) of the slice. The fourth argument is the list or string to slice.

(slice 1 2 '(1 2 3)) -> (2)
(slice 0 -1 "abcde") -> "abcd"
(slice 99 100 '(1 2 3)) -> ()

Convert a string that contains a JSON structure to a JSON dictionary.

(string-to-json "{ "a": "b"")

Convert a string to a number.

(string-to-number "1") -> 1

Convert any symbol to its string representation.

(to-string aSymbol) -> "[1, 2, 3]"

Convert a string to a symbol.

(to-symbol "aSymbol") -> aSymbol

Execute a cleanup form after the main form has been executed or in case of an error.

Currently only programmatic flow interrupts are supported to trigger the cleanup form: assert, quit, quit-with-error, return, return-from.

(unwind-protect
        (print "main form")
        (print "cleanup form"))

URL-Encode a string.

(url-encode "Hello, World") -> "Hello+World"

Provide a while loop functionality.

(setq i 0)
(while (< i 10)
        ((print i)
                (inc i)))

Zip lists together.

(zip '(1 2 3) '(4 5 6)) -> ((1 4) (2 5) (3 6))

Return the current time, but relative to UTC.

Return the current time's timestamp, but relative to UTC.