Skip to content

ACMEScript-functions.md

Latest commit

 

History

History
2559 lines (1524 loc) · 72.9 KB

ACMEScript-functions.md

File metadata and controls

2559 lines (1524 loc) · 72.9 KB

← README
← ACMEScript

ACMEScript - Functions & Variables

The following built-in functions and variables are provided by the ACMEScript interpreter.

Type Function Description
Basic . Return a string of concatenated symbols
argv Get script arguments
assert Assert a condition
base64-encode Base64-encode a string
car Return the first element from a list
case Conditional execution depending on an input value
cdr Return a list with elements from a list, except the first element
cons Construct a new list
datetime Return a timestamp
defun Define a function
dec Decrement a variable
dolist Loop over a list
dotimes Loop over a numeric value
eval Evaluate and execute a quoted list
evaluate-inline Enable and disable inline string evaluation
get-json-attribute Get a JSON attribute from a JSON structure
has-json-attribute Determine the existence of a JSON attribute in a JSON structure
if Conditional execution
in Determine whether a symbol is contained in a list, or a string in another string
inc Increment a variable
index-of Determine the position of a value in a list, or string in another string
is-defined Test whether a symbol has been defined
json-to-string Convert a JSON structure to a string
jsonify Escape characters that would otherwise break a JSON structure
lambda Define a nameless function
length Returns length of a string or a list
let* Handles multiple variable assignments sequentially
list Returns a list from its arguments
log Print symbols to the log console (log-level debug)
log-error Print symbols to the log console (log-level warning)
lower Returns a lower case copy of a string
match Determines whether a string matches a regex
nl Returns a newline character
nth Returns the n-th element from a list, or the n-th character from a string
print Print symbols to the console
progn Evaluate and execute symbols and lists
quit Ends the running script and returns a result
quit-with-error Ends the running script with an error status and returns a result
quote Return a quoted version of an s-expression
random Generate a random number
return Early return from a function or while loop
round Return a round number
set-json-attribute Set a JSON attribute in a JSON structure to a new value
setq Assigns a value to a variable
sleep Sleep during script exection
slice Returns the slice of a list or string
sp Returns a space character
string-to-json Convert a string to a JSON structure
to-number Converts a string to a number
to-string Returns a string representation of a symbol
to-symbol Converts a string to a symbol
upper Returns an upper case copy of a string
url-encode URL-encode a string
while Evaluate an s-expression in a loop
Operations Comparison Operations List of supported comparison operations
Logical Operations List of supported logical operations
Mathematical Operations List of supported mathematical operations
CSE clear-console Clear the console screen
cse-attribute-info Return information about one or more matching attributes
cse-status Return the CSE's current status
get-config Retrieve a CSE's configuration setting
get-loglevel Retrieve the CSE's current log level
get-storage Retrieve a value from the CSE's internal script-data storage
has-config Determine the existence of a CSE's configuration setting
has-storage Determine the existence of a key/value in the CSE's internal script-data storage
log-divider Add a line to the DEBUG log
print-json Print a JSON structure to the console
put-storage Store a symbol in the CSE's internal script-data storage
removes-storage Removes a key/value pair from the CSE's internal script-data storage
reset-cse Initiate a CSE reset
run-script Removes a key/value pair from the CSE's internal script-data storage
runs-in-ipython Determine whether the CSE runs in an iPython environment
schedule-next-script Schedule the nest running script and its arguments
set-config Set a CSE's configuation setting
set-console-logging Switch on or off console logging
oneM2M create-resource Send a oneM2M CREATE request
delete-resource Send a oneM2M DELETE request
import-raw Directly create a resource in the CSE's resource tree
query-resource Evaluate an advanced query on a oneM2M resource
retrieve-resource Send a oneM2M RETRIEVE request
send-notification Send a oneM2M NOTIFY request
update-resource Send a oneM2M UPDATE request
Text UI open-web-browser Open a web page in the default browser
set-category-description Set the description for a whole category of scripts
runs-in-tui Determine whether the CSE runs in Text UI mode
tui-notify Display a desktop-like notification
tui-refresh-resources Force a refresh of the Text UI's resource tree
tui-visual-bell Shortly flashes the script's entry in the text UI's scripts list
Network http Send http requests
ping-tcp-service Check the availability of a network service via TCP
Variables argc Get number of arguments
event.data For event handlers: An event's payload data
event.type For event handlers: An event's event type
notification.originator For notification handlers: A notification's originator
notification.resource For notification handlers: A notification's body
notification.uri For notification handlers: A notification's target URI
tui.autorun Set if autorun from the text UI
tui.theme Set to the current text UI theme

ASFunctions.as

In addition more functions are provided in the file ASFunctions.as. These functions can be included and made available in own scripts with the include-script function.

Basic Functions

.

(. [<symbol>]+)

Concatenate and return the stringified versions of the symbol arguments.

Note, that this function will not add spaces between the symbols. One can use the nl and sp functions to add newlines and spaces.

See also: nl, sp, to-string

Example:

(. "Time:" sp (datetime))  ;; Returns "Time: 20230308T231049.934630"

top

argv

(argv [<n:integer>]*)

Evaluates to the n-th argument of the script . The index starts a 0, where the 0-th argument is the name of the script. If the argv function is called without an argument or stand-alone then a string including the name of the function and the arguments is returned.

The number of arguments available is stored in the variable argc.

See also: argc

Example:

;; Print the script name
(print "The name of the script is:" (argv 0))

;; Print the first argument
(print "The first argument is:" (argv 1))

;; Print script name and all arguments
(print "All arguments:" argv)

top

assert

(assert <boolean>)

The assert function terminates the script if its argument evaluates to false.

Example:

(assert (== (get-configuration "cse.type") 
            "IN"))  ;; Terminates when the setting is different from "IN"

top

base64-encode

(base64-encode <string>)

This function encodes a string as base64s.

See also: url-encode

Example:

(base64-encode "Hello, World")  ;; Returns "SGVsbG8sIFdvcmxk"

top

car

(car <list>)

The car function returns the first symbol from a list. It doesn't change the original list.

Note, that a list needs to be quoted when used directly.

See also: cdr, nth

Example:

(car '(1 2 3))  ;; Returns 1

top

case

(case <key:string> (<condition> <s-expression>)*)

The case function implements the functionality of a switch...case statement in other programming languages.

The key s-expression is evaluated and its value taken for the following comparisons. After this expression a number of lists may be given.

Each of these list contains two symbols that are handled in order: The first symbol evaluates to a value that is compared to the result of the key s-expression. If there is a match then the second s-expression is evaluated, and then the comparisons are stopped and the case function returns.

The special symbol otherwise for a condition s-expression always matches and can be used as a default or fallback case .

Example:

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

top

cdr

(cdr <list>)

The cdr function returns a list with all symbols from a list except the first symbol. It doesn't change the original list.

Note, that a list needs to be quoted when used directly.

See also: car, nth

Example:

(cdr '(1 2 3))  ;; Returns (2 3)

top

cons

(cons <symbol> <list>)

The cons function adds a new symbol to the front of a list and returns it. It doesn't change the original list.

Note, that a list needs to be quoted when used directly.

Example:

(cons 1 2)	          ;; Returns (1 2)
(cons 1 '(2 3))	      ;; Returns (1 2 3)
(cons '(1 2) '(3 4))  ;; Returns ((1 2) 3 4)

top

datetime

(datetime [<format:string>])

The datetime function returns the current date and time. As a default, if not argument is provided, the function returns an ISO8901 timestamp. An optional format string can be provided. With this format string one can define the format for the output based on the format defined by Python's strftime() function.

All timestamps are UTC-based.

Example:

(datetime)          ;; Returns a timestamp, e.g. 20230302T221625.771604
(datetime "%H:%M")  ;; Returns, for example, "22:16"

top

defun

(defun <function name> <parameter list> <function body>)

The defun function defines a new function.

The first argument to this function is a string and specifies the new function's name. A function definition overrides already user-defined or built-in functions with the same name.

The second argument is a symbol list with argument names for the function. Arguments act as function-local variables that can be used in the function body.

The third argument is an s-expression that is evaluated as the function body.

The result of a function is the result of the expression that is evaluated last in a function evaluation.

See also: lambda, return

Examples:

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

;; Fibonacci
(defun fib (n)          ;; Define the function
    (if (< n 2)
        n
        (+ (fib (- n 1)) 
           (fib (- n 2)))
    ))
(fib 10)                ;; Returns 55

top

dec

(dec <variable> [<value:number>])

The dec function decrements a provided variable. The default for the increment is 1, but can be given as an optional second argument. If this argument is provided then the variable is decremented by this value. The value can be an integer or a float.

The function returns the variable's new value.

See also: inc

Example:

(setq a 1)   ;; Set variable "a" to 1
(dec a)      ;; Decrement variable "a" by 1
(dec a 2.5)  ;; Decrement variable "a" by 2.5

top

dolist

(dolist (<loop variable> <list:list or quoted list> [<result variable>]) (<s-expression>+))

The dolist function loops over a list.
The first arguments is a list that contains a loop variable, a list to iterate over, and an optional result variable. The second argument is a list that contains one or more s-expressions that are executed in the loop.

If the result variable is specified then the loop returns the value of that variable, otherwise nil.

See also: dotimes, while

Example:

(dolist (i '(1 2 3 4 5 6 7 8 9 10))
	(print i))                   ;; print 1..10

(setq result 0)
(dolist (i '(1 2 3 4 5 6 7 8 9 10) result)
	(setq result (+ result i)))  ;; sum 1..10
(print result)                   ;; 55

top

dotimes

(dotimes (<loop variable> <count:number> [<result variable>]) (<s-expression>+))

The dotimes function provides a simple numeric loop functionality.
The first arguments is a list that contains a loop variable that starts at 0, the loop count (which must be a non-negative number), and an optional result variable. The second argument is a list that contains one or more s-expressions that are executed in the loop.

If the result variable is specified then the loop returns the value of that variable, otherwise nil.

See also: dolist, while

Example:

(dotimes (i 10)
	(print i))                   ;; print 0..9

(setq result 0)
(dotimes (i 10 result)
	(setq result (+ result i)))  ;; sum 0..9
(print result)                   ;; 45

top

eval

(eval <quoted list>)

The eval function evaluates and executes a quoted list or symbol.

See also: parse-string, progn, to-symbol

Example:

(eval '(print "Hello, World"))  ;; Prints "Hello, World"

top

evaluate-inline

(evaluate-inline <boolean>)

With this function one can disable or enable the evaluation of s-expressions in strings.

Example:

(evaluate-inline false)  ;; Disables inline evaluation
(print "1 + 2 = [(+ 1 2)]")  ;; Prints "1 + 2 = [(+ 1 2)]"

top

get-json-attribute

(get-json-attribute <JSON> <key:string>)

The get-json-attribute function retrieves an attribute from a JSON structure via a key path. This key may be a structured path to access elements deeper down in the JSON structure. There are the following extra elements to access more complex structures:

  • It is possible to address a specific element in a list. This is done be specifying the element as {n}.
  • If an element is specified as {} then all elements in that list are returned in a list.
  • If an element is specified as {*} and is targeting a dictionary then a single unknown key is skipped in the path. This can be used to skip, for example, unknown first elements in a structure. This is similar but not the same as {0} that works on lists.

See also: has-json-attribute, set-json-attribute

Examples:

(get-json-attribute { "a" : { "b" : "c" }} "a/b" )     ;; Returns "c"
(get-json-attribute { "a" : [ "b", "c" ]} "a/{0}" )    ;; Returns "b"
(get-json-attribute { "a" : [ "b", "c" ]} "a/{}" )     ;; Returns ( "b" "c" )
(get-json-attribute { "a" : [ "b", "c" ]} "{*}/{0}" )  ;; Returns "b"

top

has-json-attribute

(has-json-attribute <JSON> <key:string>)

The has-json-attribute function determines whether an attribute exists in a JSON structure for a key path. This key may be a structured path to access elements deeper down in the JSON structure. See get-json-attribute for further details on how to access JSON attributes.

See also: get-json-attribute, set-json-attribute

Examples:

(has-json-attribute { "a" : { "b" : "c" }} "a/b" )  ;; Returns true
(has-json-attribute { "a" : { "b" : "c" }} "a/c" )  ;; Returns false

top

if

(if <boolean expression> <s-expression> [<s-expression>])

The if function works like an “if-then-else” statement in other programing languages. The first argument is a boolean expression. If it evaluates to true then the second argument is executed. If it evaluates to false then the third (optional) argument is executed, if present.

The boolean expression can be any s-expression that evaluates to a boolean value or nil, or a list or a string. nil values, empty lists, or zero-length strings evaluate to false, or to true otherwise.

Example:

(if (< 1 2)           ;; Evaluates to "true"
    (print "true")    ;; This expression is executed
    (print "false"))  ;; This expression is not executed

top

in

(in <symbol or list> <list or string>)

The in function determines whether a symbol or list is contained in a list, or whether a string is contained in another string. The function returns true if this is the case, or false otherwise.

See also: index-of

Example:

(in "Hello" "Hello, World")  ;; Returns true
(in "Bye" "Hello, World")    ;; Returns false
(in 1 '(1 2 3))              ;; Returns true
(in '(1 2) '((1 2) (3 4)))   ;; Increment variable "a" by 2.5

top

inc

(inc <variable symbol> [<value:number>])

The inc function increments a provided variable. The default for the increment is 1, but can be given as an optional second argument. If this argument is provided then the variable is incremented by this value. The value can be an integer or a float.

The function returns the variable's new value.

See also: dec

Example:

(setq a 1)   ;; Set variable "a" to 1
(inc a)      ;; Increment variable "a" by 1
(inc a 2.5)  ;; Increment variable "a" by 2.5

top

index-of

(index-of <value> <list or string>)

The index-of function determines the index of a value in a list, or the index of a string in another string. If the second argument is a string then the first argument must be a string as well. The index is 0-based.

The function returns the index as a number, or nil if the value could not be found.

See also: in, nth

Example:

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

top

is-defined

(is-defined <symbol>)

The is-defined function tests whether a symbol (ie. a variable, built-in or defined function) is defined.

Example:

(setq a 1)       ;; Define variable "a"
(is-defined 'a)  ;; Evaluates to "true".
(is-defined 'b)  ;; Evaluates to "false"

Note:

Most of the time the symbol argument needs to be quoted, otherwise the symbol is evaluated first and the function will not work as expected.

top

json-to-string

(json-to-string <JSON>)

The json-to-string function returns a JSON structure in a string.

See also: string-to-json, to-number, to-string

Example:

(json-to-string { "a" : { "b" : "c" }})  ;; Returns "{\"a\": {\"b\": \"c\"}}"

top

jsonify

(jsonify <string>)

The jsonify function returns a string where characters are escaped that would otherwise break a JSON structure.

See also: string-to-json, to-number, to-string

Example:

(jsonify (jsonify "Hello,
World"))  ;; Returns "Hello\nworld"

top

lambda

(lambda <parameter list> <function body>)

The lambda function defines a new nameless function.

It is similar to the defun function, but the difference is that functions defined as lambda functions cannot be called by name. They need to be used directly, assigned to a variable, or passed, for example, in a function call.

The first argument is a symbol list with argument names for the lambda function. Arguments act as function-local variables that can be used in the function body.

The second argument is an s-expression that is evaluated as the function body.

The result of a lambda function is the result of the expression that is evaluated last in a function evaluation.

See also: defun, return

Examples:

;; Immediate use
((lambda (x) (* x x)) 5)       ;; Returns 25

;; Assign a lambda function to a variable
(setq y (lambda (x) (* x x)))  ;; Define and assign lambda function
(y)                            ;; Returns ( ( x ) ( * x x ) )
((y) 5)                        ;; Returns 25

top

length

(length <string or list>)

The length function returns the length of a string or the number of elements in a list.

Example:

(length "Hello, World")  ;; Returns 12
(length '(1 2 3))        ;; Returns 3

top

let*

(let* [( <variable> <s-expression> )]+)

The let* function let one assigns values to variables in multiple steps.

Each assignment consists, like the setq function, of an implicit quoted list with a variable symbol and an s-expression, but differently from the setq function, the let* function handles multiple assignments. The assignments are handled sequentially.

Note: The let function (without the star), where assignments are handled in parallel is yet not supported.

See also: setq

Example:

(let* (a 1)         ;; Assigns 1 to a
      (a (+ a 1)))  ;; Assigns a + 1 = 2 to a
(let* (b 2) (c 3))  ;; Assigns 2 to b and 3 to c

top

list

(list <symbol>+)

The list function returns a list that contains all the symbol arguments.

See also: cons

Example:

(list 1 2 3)  ;; Returns ( 1 2 3 )

top

log

(log <s-expression>*)

The log function prints symbols to the logging console with a debug log-level. Usually these symbols are strings or numbers, but representations of other data types are supported as well.

The function always returns nil.

See also: log-error, print

Example:

(log "Hello, World")  ;; Prints "Hello, World" to the log

top

log-error

(log <s-expression>*)

The log-error function prints symbols to the logging console with an warning log-level. Usually these symbols are strings or numbers, but representations of other data types are supported as well.

The function always returns nil.

See also: log, print

Example:

(log-error "Hello, World")  ;; Prints "Hello, World" to the warning log

top

lower

(lower <string>)

The lower function returns a lower case copy of the input string.

See also: upper

Example:

(lower "Hello, World")  ;; Returns "hello, world"

top

match

(match <string> <regex:string>)

The match function determines whether a string matches a regular expression regex.

Note: The default implementation supports a simplified regex operator set:

  • ? : any single character
  • * : zero or more characters
  • + : one or more characters
  • \ : Escape an expression operator

Example:

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

top

nl

(nl)

The nl function returns a newline character.

See also: print, sp

Example:

(. "Hello," nl "World")  ;; Returns "Hello,\nWorld"

top

nth

(nth <index:number> <list or string>)

The nth function returns the n-th element from a list, or the nth character from a string.

The index is 0-based.

See also: car, cdr, index-of

Example:

(nth 2 '(1 2 3))        ;; Returns 3
(nth 2 "Hello, World")  ;; Returns "l"

top

parse-string

(parse-string <string with an <s-expression>)

The parse-string function parses a string that contains an s-expression and returns the result as an executable s-expression for further evaluation, e.g. with the eval function.

See also: eval, to-symbol

Example:

(eval (parse-string "(print \"hello, world\")")) ;; Prints "hello, world"

top

print

(print <s-expression>*)

The print function prints symbols to the console. Usually these symbols are strings or numbers, but representations of other data types are supported as well.

The function always returns nil.

See also: log, log-error

Example:

(print "Hello, World")  ;; Prints "Hello, World"

top

progn

(progn <s-expression>+)

The progn function evaluates all provided symbols or lists, and returns the result of the last evaluation. All other results are ignored.

This function is implicitly used internally when used to evaluate s-expressions.

See also: eval

Example:

(progn (print "Hello, World") 1)  ;; Prints "Hello, World" and returns 1

top

quit

(quit [<symbol>])

The quit function ends the execution of the current script without an 0 error code.

If a symbol is provided for the optional argument its value is taken as the result of the script. Otherwise, nil is returned.

See also: quit-with-error

Example:

(quit)             ;; Returns nil
(quit "a result")  ;; Returns "a result"

top

quit-with-error

(quit-with-error [<symbol>])

The quit-with-error function ends the execution of the current script with an -1 error code.

If a symbol is provided for the optional argument its value is taken as the result of the script. Otherwise, nil is returned.

See also: quit

Example:

(quit-with-error)             ;; Returns nil
(quit-with-error "a result")  ;; Returns "a result"

top

quote

(quote <symbol or list>)

The quote function returns a quoted version of the argument. It can be used to get a quoted version of an s-expression or symbol that is the result of another function.

Example:

(setq i 0)       ;; Set loop variable
(while (< i 10)  ;; Loop 10 times
    ((print i)   ;; Print to the console
	(inc i)))    ;; Increment loop variable

top

random

(random [<end:number> or <start:number> <end:number>])

The random function generates a random float number in the given range.

The default for the range, when no argument is given, is [0.0, 1.0]. If one number argument is given then this indicates a range of [0.0, <end number>]. If two number arguments are given then this indicates a range of [<start number>, <end number>].

Example:

(random)         ;; Returns, for example, 0.748786
(random 10)      ;; Returns, for example, 4.976338
(random 10 20)   ;; returns, for example, 12.73221

top

return

(return [<s-expression>])

The return function stops the evaluation of a function or while loop and returns the evaluation to the caller. The function may return a symbol, or nil.

See also: defun, while

Example:

(if (< 1 2)      ;; Evaluates to "true"
    (return 23)  ;; Return the number 23

top

round

(round <value:number> [<precission:number>])

The round function rounds a number to precision digits after the decimal point. The default is 0, meaning to round to nearest integer.

Example:

(round 3.1415926)    ;; Returns 3
(round 3.1415926 2)  ;; Returns 3.14

top

set-json-attribute

(set-json-attribute <JSON> <key:string> <value)

The set-json-attribute function sets an attribute in a JSON structure via a key path to the new value. This key may be a structured path to access elements deeper down in the JSON structure. See get-json-attribute for further details on how to access JSON attributes.

The function doesn't change the original JSON structure, but returns an updated structure.

See also: get-json-attribute, has-json-attribute

Example:

(set-json-attribute { "a" : { "b" : "c" }} "a/b" "e")  ;; Returns {"a": {"b": "e"}}

top

setq

(setq <variable> <s-expression)

The setq function assigns a value to a variable.

See also: let*

Example:

(setq a "Hello, World")  ;; Returns "Hello, World" and sets the variable "a"

top

sleep

(sleep <number>)

The sleep function adds a delay to the script execution. The evaluation stops for a number of seconds. The delay could be provided as an integer or float number.

If the script execution timeouts during a sleep, the function is interrupted and all subsequent s-expressions are not evaluated.

The function returns the delay.

Example:

(sleep 1.5)  ;; Sleep for 1.5 seconds

top

slice

(slice <start:number> <end:number> <list or string>)

The slice function returns the slice of a list or a string.

The behavior is the same as slicing in Python, except that both start and end must be provided. The first argument is the start (including) of the slice, the second is the end (excluding) of the slice. The fourth argument is the list or string to slice.

Example:

(slice 1 2 '(1 2 3))     ;; Returns (2)
(slice 0 -1 "abcde")     ;; Returns "abcd"
(slice -1 99 "abcde")    ;; Returns "e"
(slice 99 100 '(1 2 3))  ;; Returns ()

top

sp

(sp)

The sp function returns a space character.

See also: print, nl

Example:

(. "Hello," sp "World")  ;; Returns "Hello, World"

top

string-to-json

(string-to-json <string>)

The string-to-json function converts a string to a JSON structure and returns it. The string must contain a valid parseable JSON structure.

See also: json-to-string, to-number, jsonify

Example:

(string-to-json "{ \"a\" : { \"b\" : \"c\" }}")  ;; Returns {"a": {"b": "c"}}

top

to-number

(to-number <symbol>)

The to-number function converts a string that contains a number to a number symbol and returns it.

See also: json-to-string, to-string

Example:

(to-string '(1 2))  ;; Returns "[1, 2]"

top

to-string

(to-string <symbol>)

The to-string function converts a symbol of any of the built-in types to a string representation and returns it.

See also: json-to-string, to-number

Example:

(to-string '(1 2))  ;; Returns "[1, 2]"

top

to-symbol

(to-symbol <string>)

The to-symbol function converts a string to a symbol and returns it. The resulting symbol has the name and value of the input string, but is itself not a string.

See also: eval, from-string, parse-string

Example:

(to-symbol "a-symbol")  ;; Returns the symbol 'a-symbol'

top

upper

(upper <string>)

The upper function returns an upper case copy of the input string.

See also: lower

Example:

(upper "Hello, World")  ;; Returns "HELLO, WORLD"

top

url-encode

(url-encode <string>)

The url-encode function encodes a string so that may be safely used as part of a URL.

See also: base64-encode

Example:

(url-encode "Hello, World")  ;; Returns "Hello%2C+World"

top

while

(while <boolean guard> <body s-expression> )

The while function implements a loop functionality.

A while loop continues to run when the first guard s-expression evaluates to true. Then the body s-expression is evaluated. After this the guard is evaluated again and the the loops continues or the while function returns.

The boolean guard can be any s-expression that evaluates to a boolean value or nil, or a list or a string. nil values, empty lists, or zero-length strings evaluate to false, or to true otherwise.

The while function returns the result of the last evaluated s-expression in the body.

See also: doloop, dotime, return

Example:

(setq i 0)       ;; Set loop variable
(while (< i 10)  ;; Loop 10 times
    ((print i)   ;; Print to the console
	(inc i)))    ;; Increment loop variable

top

Operations

Comparison Operations

The following comparison operations are supported by ACMEScript. They are used like any other function, and return a boolean value.

Example:

(if (< 1 2)           ;; Evaluates to "true"
    (print "true")    ;; This expression is executed
    (print "false"))  ;; This expression is not executed

Note that the first operant in comparison operations may be a list or a quoted list. Only if the second operant is not a list, too, then the comparison operation is repeated for every member in the first operant's list. The comparison operation evaluates to true if any of these comparisons returns true.

Example:

(== '(1 2 3) 2)  ;; Evaluates to "true"
operation Description Example
== Equal to (== a b) ;; equal to: a == b
!=, <> Not equal to (!= a b) ;; equal to: a != b
< Smaller than (< a b) ;; equal to: a < b
<= Smaller or equal than (<= a b) ;; equal to: a <= b
> Greater than (> a b) ;; equal to: a > b
>= Greater or equal than (>= a b) ;; equal to: a >= b

top

Logical Operations

The following logical operations are supported by ACMEScript. They are used like any other function, and return a boolean value.

Examples:

(or (< 1 2) (>= 4 3) (== 1 1))   ;; Returns true
(and (or true false) (not true)) ;; Returns false

Note that the first operant in logical operations may be a list or quoted list. Only if the second operant is not a list, too, then the logical operation is repeated for every member in the first operant's list. The logical operation evaluates to true if any of these operations returns true.

Example:

(and '(false false true) true)  ;; Evaluates to "true"
(and '(false false false) true)  ;; Evaluates to "false"
operation Description Example
or, | logical or of two or more boolean expressions (or a b) ;; a or b
and, & logical *and *of two or more boolean expressions (and a b c) ;; a and b and c
not, ! logical negation or one boolean expression (not true) ;; false

top

Mathematical Operations

The following mathematical operations are supported by ACMEScript. They are used like any other function, and return a number value.

Example:

(* 6 7)        ;; Returns 42
(* (+ 3 3) 7)  ;; Return 42
operation Description Example
+ Add two or more numbers (+ 1 2 3) ;; Returns 6
- Subtract two or more numbers (- 10 1 2 3) ;; Returns 4
* Multiply two or more numbers (* 6 7) ;; Returns 42
/ Divide two or more numbers (/ 23 5) ;; Returns 4.6
** Calculates the power of two or more numbers (** 2 3 4) ;; Returns 4096
% Calculates to modulo of two or more numbers (% 100 21 13) ;; Returns 3

top

CSE Functions

The following functions provide support to access certain CSE functionalities, configurations, and other runtime aspects.

clear-console

(clear-console)

The clear-console function clears the console screen.

Example:

(clear-console)  ;; Clears the console screen

top

cse-attribute-info

(cse-attribute-info <name:str>)

Return a list of CSE attribute infos for the attribute `name``. The search is done over the short and long names of the attributes applying a fuzzy search when searching the long names.

The function returns a quoted list where each entry is another quoted list with the following symbols:

  • attribute short name
  • attribute long name
  • attribute type

Example:

(cse-attribute-info "acop") ;; Returns ( ( "acop" "accessControlOperations" "nonNegInteger" ) )

top

cse-status

(cse-status)

The cse-status function returns the CSE's current running status as an upper-case string.

Possible return values are:

  • STARTING
  • RUNNING
  • STOPPING
  • STOPPED
  • RESETTING

Example:

(cse-status)  ;; Returns "RUNNING"

top

get-config

(get-config <key:string>)

The get-config function retrieves a setting from the CSE's internal configuration. The key is a configuration name as defined in the configuration documentation.

See also: has-config, set-config

Examples:

(get-config "cse.type")    ;; Returns, for example, 1
(get-config "cse.cseID")   ;; Returns, for example, "/id-in"

top

get-loglevel

(get-loglevel)

The get-loglevel function retrieves a the CSE's current log level setting. The return value will be one of the following strings:

  • "DEBUG"
  • "INFO"
  • "WARNING"
  • "ERROR"
  • "OFF"

Example:

(get-loglevel)  ;; Return, for example, INFO

top

get-storage

(get-storage <key:string>)

The get-storage function retrieves a value from the CSE's internal script-data storage. The key is a unique name of the value.

See also: has-storage, put-storage, remove-storage

Examples:

(get-storage "aStorageID" "aKey")  ;; Retrieves the value for "aKey" from "aStorageID"

top

has-config

(has-config <key:string>)

The has-config function determines whether a setting from the CSE's internal configuration exists. The key is a configuration name as defined in the configuration documentation.

See also: get-config, set-config

Examples:

(has-config "cse.cseID")     ;; Returns true
(has-config "cse.unknown")   ;; Returns false

top

has-storage

(has-storage <key:string>)

The has-storage function determines whether a value has been stored under the given key in the CSE's internal script-data storage.

See also: get-storage, put-storage, remove-storage

Examples:

(has-storage "aStorageID" "aKey")       ;; Tests whether the key "aKey" exists in "aStorageID"

top

include-script

(include-script <script name:string> [<argument:any>]*)

The include-script function runs another ACMEScript script by its script name in its own context. Differently to the run-script function variables, function definitions etc from the script execution are available in the calling script after the script finished.

The function returns the result of the finished script.

See also: run-script. schedule-next-script

Example:

(include-script "functions" "an argument")  ;; Run the script "functions"

top

log-divider

(log-divider [<message:string>])

The log-divider function inserts a divider line in the CSE's DEBUG log. It can help to easily identify the different sections when working with many requests. An optional (short) message can be provided in the argument.

Examples:

(log-divider)                 ;; Add a divider
(log-divider "Hello, World")  ;; Add a divider with a centered message

top

print-json

(print-json <JSON>)

The print-json function prints a JSON structure with syntax highlighting to the console.

Example:

(print-json { "m2m:cnt" : { "rn": "myCnt" }})  ;; Print the JSON structure

top

put-storage

(put-storage <storageID:string> <key:string> <value:symbol>)

The put-storage function inserts or updates a value in the CSE's internal script-data storage with the storage ID storageID. The key is a unique name of the value.

See also: get-storage, has-storage, remove-storage

Examples:

(put-storage "aStorageID" "aKey" "Hello, World")  ;; Inserts or updates the key "aKey" in "aStorageID"

top

remove-storage

(remove-storage <key:string>) (remove-storage <storageID:string> <key:string>)

With 2 parameters the remove-storage function removes a key/value pair from the CSE's internal script-data storage with the storage ID storageID. The key is a unique name of the value.

With only 1 parameter the remove-storage function removes all key/value pairs from the CSE's internal script-data storage with the storage ID storageID.

See also: get-storage, has-storage, put-storage

Examples:

(remove-storage "aStorageID" "aKey")  ;; Removes the key and value from storageID
(remove-storage "aStorageID")         ;; Removes all keys and value from storageID

top

reset-cse

(reset-cse)

The reset-cse function initiates a CSE reset.

The script execution does continue after the CSE finished the reset.

Example:

(reset-cse)  ;; Resets the CSE

top

run-script

(run-script <script name:string> [<argument:any>]*)

The run-script function runs another ACMEScript script by its script name in its own scope. Variables, function definitions etc from the script execution are not available in the calling script.

The function returns the result of the finished script.

See also: include-script, schedule-next-script

Example:

(setq result (run-script "aScript" "an argument"))  ;; Run the script "aScript" and assign the result

top

runs-in-ipython

(runs-in-ipython)

The runs-in-ipython function determines whether the CSE currently runs in an IPython environment, such as Jupyter Notebooks.

Examples:

(runs-in-ipython)  ;; Returns true if the CSE runs in an iPython environment

top

schedule-next-script

(schedule-next-script <scriptName:string> <argument:any>*)

The schedule-next-script function schedules the next script that is run after the current script finished.

This is different from include-script and run-script in so far that the context of the current running script is finished and may be called again. This means that a script can schedule itself, which would not be possible otherwise because scripts can only be run one at a time.

See also: include-script, run-script

Examples:

(schedule-next-script "scriptName" "anArgument")  ;; Schedule a script with an argument

top

set-config

(set-config <key:string> <value:any>)

The set-config function updates a setting from the CSE's internal configuration. The key is a configuration name as defined in the configuration documentation.

It is only possible to update an existing setting, but not to create a new one. The value type must be equivalent to the setting's type.

See also: get-config, has-config

Examples:

(set-config "cse.checkExpirationsInterval" 1.5)  ;; Set the configuration to 1.5

top

set-console-logging

(set-console-logging <boolean>)

The set-console-logging function enables or disables console logging. It does not turn on or off logging in general. Printing to the console is not affected.

Example:

(set-console-logging false)  ;; Switch off console logging

top

oneM2M Functions

The following functions provide support for the oneM2M request operations.

create-resource

(create-resource <originator:string> <resource-id:string> <resource:JSON> [request arguments:JSON])

The create-resource function sends a oneM2M CREATE request to a target resource.

The function has the following arguments:

  • originator of the request

  • The target resource-id

  • The resource JSON structure

  • Optional: A JSON structure with additional request arguments

The function will provide defaults for the required request arguments (e.g. rvi, rid). These can be overwritten if necessary by setting them in the request arguments argument.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content

See also: delete-resource, import-raw, retrieve-resource, send-notification, update-resource

Examples:

(create-resource "CAdmin" "cse-in"  { "m2m:cnt" : { "rn": "myCnt" }})  
;; Returns ( 2001 { "m2m:cnt" ... } )
(create-resource "CAdmin" "cse-in"  { "m2m:cnt" : { }} { "rvi": "3"})  ;; Provide requestVersionIndicator
;; Returns ( 2001 { "m2m:cnt" ... } )

top

delete-resource

(delete-resource <originator:string> <resource-id:string> [request arguments:JSON])

The delete-resource function sends a oneM2M DELETE request to a target resource.

The function has the following arguments:

  • originator of the request
  • The target resource-id
  • Optional: A JSON structure with additional request arguments

The function will provide defaults for the required request arguments (e.g. rvi, rid). These can be overwritten if necessary by setting them in the request arguments argument.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content (usually nil if successful)

See also: create-resource, retrieve-resource, send-notification, update-resource

Examples:

(delete-resource "CAdmin" "cse-in/myCnt")  
;; Returns ( 2002 { "m2m:cnt" ... } )
(delete-resource "CAdmin" "cse-in/myCnt" { "rvi": "3"})  ;; Provide requestVersionIndicator
;; Returns ( 2002 { "m2m:cnt" ... } )

top

import-raw

(import-raw <originator:string> <resource:JSON>)

The import-raw function creates a resource in the CSE without using the normal procedures when handling a CREATE request. The resource is added to the resource tree without much validation.

This function is primarily used when importing initial resources, and when restoring resources during the startup of the CSE.

resource is a valid oneM2M resource. All necessary attributes must be present in that resource, including the parentID ( pi ) attribute that determines the location in the resource tree.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content (usually nil if successful)

Example:

;; Add an AE resource under the CSEBase
(import-raw 
    "CmyAE"                                      ;; Originator
    { "m2m:ae": {
        "ri":  "CmyAE",
        "rn":  "CmyAE",
        "pi":  "${ (get-config \"cse.ri\") }",  ;; Get the CSE's resource ID from the configuration
        "rr":  true,
        "api": "NmyAppId",
        "aei": "CmyAE",
        "csz": [ "application/json", "application/cbor" ]
    }})

top

query-resource

(query-resource <query:quoted s-expression> <resource:JSON>)

The query-resource function evaluates a query for the attributes in the resource structure.

The function has the following arguments:

  • query to evaluate. This query must be quoted and follows oneM2M's advanced query specification. the unknown symbols in the query are replaced by the resource's attribute values during the evaluation. Only a limited set boolean and comparison operators are allowed in the query.
  • A oneM2M resource as a JSON structure.

The function returns a boolean indicating the query result.

See also: get-json-attribute

Examples:

;; Returns true
(query-resource 
	'(& (> x 100) (== rn "cnt1234"))
	{ "m2m:cnt": {
		"rn": "cnt1234",
	  	"x": 123
	}})

top

retrieve-resource

(retrieve-resource <originator:string> <resource-id:string> [request arguments:JSON])

The retrieve-resource function sends a oneM2M RETRIEVE request to a target resource.

The function has the following arguments:

  • originator of the request
  • The target resource-id
  • Optional: A JSON structure with additional request arguments

The function will provide defaults for the required request arguments (e.g. rvi, rid). These can be overwritten if necessary by setting them in the request arguments argument.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content (usually the target resource if successful)

See also: create-resource, delete-resource, send-notification, update-resource

Examples:

(retrieve-resource "CAdmin" "cse-in/myCnt")  
;; Returns ( 2000 { "m2m:cnt" ... } )
(retrieve-resource "CAdmin" "cse-in/myCnt" { "rvi": "3"})  ;; Provide requestVersionIndicator
;; Returns ( 2000 { "m2m:cnt" ... } )

top

send-notification

(send-notification <originator:string> <resource-id:string> <notification:JSON> [request arguments:JSON])

The send-notification function sends a oneM2M NOTIFY request to a target resource.

The function has the following arguments:

  • originator of the request

  • The target resource-id

  • The notification JSON structure

  • Optional: A JSON structure with additional request arguments

The function will provide defaults for the required request arguments (e.g. rvi, rid). These can be overwritten if necessary by setting them in the request arguments argument.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content

See also: create-resource, delete-resource, retrieve-resource, update-resource,

Example:

(send-notification "CAdmin" "cse-in/myAE"  { "m2m:sgn" : { ... }})  ;; Returns notification result

top

update-resource

(update-resource <originator:string> <resource-id:string> <resource:JSON> [request arguments:JSON])

The update-resource function sends a oneM2M UPDATE request to a target resource.

The function has the following arguments:

  • originator of the request

  • The target resource-id

  • The resource JSON structure

  • Optional: A JSON structure with additional request arguments

The function will provide defaults for the required request arguments (e.g. rvi, rid). These can be overwritten if necessary by setting them in the request arguments argument.

The function returns a list:

(<response status:number> <resource:JSON>)

  • response status is the oneM2M Response Status Code (RSC) for the request

  • resource is the response content

See also: create-resource, delete-resource, retrieve-resource, send-notification,

Examples:

(update-resource "CAdmin" "cse-in"  { "m2m:cnt" : { "mni": 10 }})  
;; Returns ( 2004 { "m2m:cnt" ... } )
(update-resource "CAdmin" "cse-in"  { "m2m:cnt" : { "mni": 10 }} { "rvi": "3"})  
;; Provide requestVersionIndicator
;; Returns ( 2004 { "m2m:cnt" ... } )

top

Text UI

open-web-browser

(open-web-browser <url:string>)

The open-web-browser function opens a web browser with the given URL.

Examples:

;; Opens the web browser with the URL "http://www.onem2m.org"
(open-web-browser "http://www.onem2m.org")

top

set-category-description

(set-category-description <category:string> <description:string>)

The set-category-description function sets the description for a whole category in the CSE's Text UI.

The description may contain Markdown formatting.

Examples:

;; Sets the description for the category "myCategory"
(set-category-description "myCategory" "My category description")

top

runs-in-tui

(runs-in-tui)

The runs-in-tui function determines whether the CSE currently runs in Text UI mode.

Examples:

(runs-in-tui)  ;; Returns true if the CSE runs in Text UI mode

top

tui-notify

(tui-notify <message:str> [<title:str>] [<severity>:str>] [<timeout:float>])

Show a desktop-like notification in the TUI.

This function is only available in TUI mode. It has the following arguments:

  • message: The message to show.
  • title: (Optional) The title of the notification.
  • severity: (Optional) The severity of the notification. This can be one of the following values:
    • information (the default)
    • warning
    • error
  • timeout: (Optional) The timeout in seconds after which the notification will disappear again. If not specified, the notification will disappear after 3 seconds.

If one of the optional arguments needs to be left out, a nil symbol must be used instead. The function returns NIL.

Examples:

(tui-notify "a message")                ;; Displays "a message" in an information notification for 3 seconds
(tui-notify "a message" "a title")      ;; Displays "a message" with title "a title in an information notification for 3 seconds
(tui-notify "a message")                ;; Displays "a message" in an information notification for 3 seconds
(tui-notify "a message" nil "warning")  ;; Displays "a message" in a warning notification, no title
(tui-notify "a message" nil nil 10)     ;; Displays "a message" in an information notification, no title, for 3 seconds

top

tui-refresh-resources

(tui-refresh-resources)

The tui-refresh-resources function refreshes the resources in the CSE's Text UI.

Examples:

(tui-refresh-resources)  ;; refreshes the resource tree

top

tui-visual-bell

(tui-visual-bell)

The tui-visual-bell function shortly flashes the script's entry in the scripts' list/tree.

Examples:

(tui-visual-bell)  ;; Flashes the script's name

top

Network

http

(http <operation:quoted symbol> <url:string> [<headers:JSON or nil>] [<body:string or JSON>])

The http function sends an http request to an http server.

The function has the following arguments:

  • operation of the request. This is one of the following supported quoted symbols: get, post, put, delete, patch

  • The target server's url. This is a string with a valid URL.

  • Optional: A JSON structure of header fields. Each header field is a JSON attribute with the name of the header field and its value. If the optional body argument is present then this argument must be present as well, ie. with at least an empty JSON structure or the nil symbol.

  • Optional: The http request's body, which could be a string or a JSON structure.

The function returns a list:

(<http status:number> <response body:JSON> <response headers:list of header fields)

  • http status is the htttp status code for the request

  • response body is the response content

  • response headers is a list of header fields. The format of these header fields is the same as in the request above.

Examples:

;; Retrieve a web page
(http 'get "https://www.onem2m.org")

;; Send a oneM2M CREATE request manually
(http 'post "http://localhost:8080/cse-in"   ;; Operation and URL
	  { "X-M2M-RI":"1234",                   ;; Header fields
        "X-M2M-RVI": "4",
        "X-M2M-Origin": "CAdmin",
		"Content-type": "application/json;ty=3" }
      { "m2m:cnt": {                         ;; Body
          "rn": "myCnt"}})

top

ping-tcp-service

(ping-tcp-server <hostname:string> <port:number> [<timeout:number>])

The ping-tcp-servicefunction tests the availability and reachability of a TCP-based network service.

It has the following arguments:

  • The hostname of the target service. This can be a hostname or an IP address.
  • The port of the target service. This is a number.
  • Optional: The request timeout in seconds. The default is 5 seconds.

The function returns a boolean value.

Examples:

(ping-tcp-service "localhost" 8080 2)  
;; Returns true if the service is reachable. Timeout after 2 seconds.

top

Variables

argc

argc

Evaluates to the number of elements in argv. A script called with no arguments still has argc set to 1, because the name of the script is always the first element in argv.

See also: argv

Example:

(if (> argc 2)
    ((log-error "Wrong number of arguments")
     (quit-with-error)))

top

event.data

event.data

Evaluates to the payload data of an event. This could be, for example, the string representation in case of an onKey event.

Note: This variable is only set when the script was invoked by an event.

See also: event.type

Example:

(if (== event.type "onKey")     ;; If the event is "onKey"
    (print "Key:" event.data))  ;; Print the pressed key

top

event.type

event.type

Evaluates to the type of an event. This could be, for example, "onKey" in case of an onKey event.

Note: This variable is only set when the script was invoked by an event.

See also: event.data

Example:

(if (== event.type "onKey")     ;; If the event is "onKey"
    (print "Key:" event.data))  ;; Print the pressed key

top

notification.originator

The notification.originator variable is set when a script is called to process a notification request.

It contains the notification's originator.

Example:

(print notification.originator)

top

notification.resource

The notification.resource variable is set when a script is called to process a notification request.

It contains the notification's JSON body.

Example:

(print notification.resource)

top

notification.uri

The notification.uri variable is set when a script is called to process a notification request.

It contains the notification's target URI.

Example:

(print notification.uri)

top

tui.autorun

tui.autorun

Evaluates to true if the script was started as an "autorun" script. This is the case when the @tuiAutoRun meta tag is set in a script.

See also: @tuiAutoRun

Note: This variable is only set when the script is run from the text UI.

Example:

(if (is-defined 'tui.autorun)     ;; If the variable is defined
	(if (== tui.autorun true)     ;; If the script is an autorun script
        (print "Autorun: True")))  ;; Print a message

top

tui.theme

tui.theme

Evaluates to the state of the current theme of the text UI. This can be either light or dark.

Example:

(print "Theme: " tui.theme)  ;; Print the theme name

top

← ACMEScript
← README