retroforth/doc/book/internals/calling-retro-from-c

68 lines
1.8 KiB
Text
Raw Normal View History

# Calling Retro from C
The C implementation of Retro provides several functions for
interacting with code written in Retro.
## Dictionary
The dictionary is a linked list, with a pointer to the most
recent entry stored in address 2.
You can access the fields for each entry using:
d_link
d_xt
d_class
d_name
Each takes a dictionary header address (the "dictionary token")
and returns a pointer to the Retro address for the desired data.
To find a dictionary token, use `d_lookup`. This takes the address
of the dictionary to search (`memory[2]` in most cases) and the
name of the word to find.
There is also `d_xt_for()` which takes a name and a dictionary
pointer and returns the execution token for the specified word.
## Strings
Like C, Retro uses NUL terminated strings. But, since all
addressing is 32-bit (or 64-bit, depending on your configuration),
some conversion is needed.
To get a C version of a string, use `string_extract()`. This takes
a Retro address and returns a pointer to a C string.
Example:
// Get the name of the most recently defined word
string_extract(d_name(memory[2]));
To push a C string into Retro memory, use `string_inject()`. This
takes a C string and a Retro address.
// Copy a string to the TIB buffer
string_inject("hello", 1024);
## Stack
You can push values to the stack with `stack_push()` and pop them
off with `stack_pop()`.
## Interacting
If you have a word named `hello` that you wish to run:
execute(d_xt_for("hello", memory[2]));
If you want to evaluate a token as if it was typed into a Retro
listener:
string_inject("token", 1024);
stack_push(1024);
execute("interpret", memory[2]);
The `interpret` word handles things like sigils, so this is
needed if you want to run something that needs those.