Converting between C and uLisp
This article summarises how to convert values between C variables of different types and the corresponding uLisp objects.
Integers
C to uLisp
The built-in function number() takes an int argument and returns a uLisp integer object.
For example, here's the definition of the uLisp function (millis) which returns the value of the Arduino function millis():
object *fn_millis (object *args, object *env) {
(void) args, (void) env;
return number(millis());
}
uLisp to C
The built-in function integer() takes a uLisp object and returns a C int. It causes an error if the parameter isn't a uLisp integer.
For example, here's the definition of the uLisp function (delay n) which takes one integer parameter and calls the Arduino function delay(n). It returns n:
object *fn_delay (object *args, object *env) {
(void) env;
object *arg1 = first(args);
delay(integer(arg1));
return arg1;
}
Floats
C to uLisp
On 32-bit platforms the built-in function makefloat() takes a float argument and returns a uLisp floating-point object.
uLisp to C
On 32-bit platforms the built-in function fromfloat() takes a uLisp object and returns a C float. It causes an error if the parameter isn't a uLisp floating-point number.
For example, you could define a uLisp function radians that converted a floating-point object from degrees to radians as follows:
object *fn_radians (object *args, object *env) {
(void) env;
object* arg = first(args);
return makefloat(fromfloat(arg) * 3.14159 / 180.0);
}
Characters
C to uLisp
The built-in function character() takes a char argument and returns a uLisp character object.
For example, here's the definition of the Lisp function code-char which takes a uLisp integer object and converts it to a uLisp character object:
object *fn_codechar (object *args, object *env) {
(void) env;
return character(integer(first(args)));
}
uLisp to C
The built-in function fromchar() takes a uLisp object and returns a C integer. It causes an error if the parameter isn't a uLisp character object.
For example, here's the definition of the Lisp function char-code which takes a uLisp character object and converts it to a uLisp integer object:
object *fn_charcode (object *args, object *env) {
(void) env;
return number(fromchar(first(args)));
}
Strings
C to uLisp
The function lispstring() will take a C char* string and return a uLisp string object. This function is currently only provided in the ESP version of uLisp, as it is needed for the Wi-Fi extensions, but you can add it from the following definition:
object *lispstring (char *s) {
object *obj = myalloc();
obj->type = STRING;
char ch = *s++;
object *head = NULL;
int chars = 0;
while (ch) {
if (ch == '\\') ch = *s++;
buildstring(ch, &chars, &head);
ch = *s++;
}
obj->cdr = head;
return obj;
}
For example, here's the definition of the uLisp Wi-Fi extension function (wifi-localip) which returns the local ip address as a uLisp string:
object *fn_wifilocalip (object *args, object *env) {
(void) args, (void) env;
return lispstring((char*)WiFi.localIP().toString().c_str());
}
uLisp to C
The function cstring() takes a uLisp string, a buffer, and the buffer length, and returns the buffer containing the uLisp string converted to a C string. This function is already provided in the ESP version of uLisp:
char *cstring (object *form, char *buffer, int buflen) {
int index = 0;
form = cdr(form);
while (form != NULL) {
int chars = form->integer;
for (int i=(sizeof(int)-1)*8; i>=0; i=i-8) {
char ch = chars>>i & 0xFF;
if (ch) {
if (index >= buflen-1) error(PSTR("no room for string"));
buffer[index++] = ch;
}
}
form = car(form);
}
buffer[index] = '\0';
return buffer;
}
This function assumes that you've already checked that the uLisp object is a string. If necessary do this first using the stringp() macro.
A second function cstringbuf() is provided in the ESP version of uLisp which is simpler to use when you only need to buffer one string at a time because it uses uLisp's built-in buffer for the string:
char *cstringbuf (object *arg) {
cstring(arg, SymbolTop, SYMBOLTABLESIZE-(SymbolTop-SymbolTable));
return SymbolTop;
}
The built-in buffer lives at the top of the symbol table and is guaranteed to have a minimum size of BUFFERSIZE, by default 34 characters.
Lists
This section explains how to convert between a uLisp list and multiple C values such as in variables, a struct, or an array.
C to uLisp
As an example of converting multiple values between C and Lisp, here's an example of a C routine to read the x and y values from an analogue joystick connected to the analogue inputs A0 and A1. It uses pointers to pass out the values x and y from the joystick:
void Joystick (int *x, int *y) {
*x = analogRead(A0);
*y = analogRead(A1);
}
We will convert this to a uLisp function (joystick) which returns the x and y values as a list of two integers:
> (joystick) (512 250)
I usually find it useful to draw a diagram of the Lisp structure I want to construct:
The '4' label identifies an integer object. Here's the definition of the joystick function:
object *fn_joystick (object *args, object *env) {
(void) args, (void) env;
int x, y;
Joystick(&x, &y);
object *result = cons(number(x), cons(number(y), NULL));
return result;
}
uLisp to C
To transfer multiple values from uLisp to C one way is to write a function that takes a list argument. Here's a function servo that takes a list of two values and writes them to analogue outputs:
object *fn_servo (object *args, object *env) {
(void) args, (void) env;
object *arg1 = first(args);
if (arg1 == NULL || cdr(arg1) == NULL) error(PSTR("argument is not a list of two items"));
pinMode(5, OUTPUT); pinMode(6, OUTPUT);
analogWrite(5, integer(first(arg1)));
analogWrite(6, integer(second(arg1)));
return arg1;
}
The tests in the if statement check that the subsequent calls to first() and second() will access valid memory addresses; otherwise on some platforms such as the ESP32 an exception will be caused if you call the function with a list of fewer than two items.
To test the function you could write, for example:
> (servo '(255 255)) (255 255)