REBOL 3 Concepts: Extensions: Host/Extension API

Updated for A104 on 31-Aug-2010

Describes the functions of reb-lib, the REBOL API (both the DLL and extension library.)

Editor note: This document is auto-generated and changes should not be made within this wiki.

WARNING: PRELIMINARY Documentation

This API is under development and subject to change. Various functions may be moved, removed, renamed, enhanced, etc.

Also note: the formatting of this document will be enhanced in future revisions.

Contents

Concept

The REBOL API provides common API functions needed by the Host-Kit and also by REBOL extension modules. This interface is commonly referred to as "reb-lib".

There are two methods of linking to this code:

• Direct calls as you would use functions within any DLL.
• Indirect calls through a set of macros (that use a structure pointer to the library.)

Functions

RL_Version

Function:	void RL_Version(REBYTE vers[])
Summary:	Obtain current REBOL interpreter version information.
Returns:	A byte array containing version, revision, update, and more.
Arguments:	vers - a byte array to hold the version info. First byte is length, followed by version, revision, update, system, variation.
Notes:	This function can be called before any other initialization to determine version compatiblity with the caller.

RL_Init

Function:	int RL_Init(REBARGS rargs, void lib)
Summary:	Initialize the REBOL interpreter.
Returns:	Zero on success, otherwise an error indicating that the host library is not compatible with this release.
Arguments:	rargs - REBOL command line args and options structure. See the host-args.c module for details. lib - the host lib (OS_ functions) to be used by REBOL. See host-lib.c for details.
Notes:	This function will allocate and initialize all memory structures used by the REBOL interpreter. This is an extensive process that takes time.

RL_Start

Function:	int RL_Start(int reserved)
Summary:	Evaluate the default boot function.
Returns:	Zero on success, otherwise indicates an error occurred.
Arguments:	reserved - must be set to zero
Notes:	This function should be called after the host has added any custom code or extensions. Note that before this function is called, security and startup options have not been initialized. The primary content of the boot is in mezz-intrinsics.r in system/intrinsic/begin function.

RL_Reset

Function:	void RL_Reset()
Summary:	Reset REBOL (not implemented)
Returns:	nothing
Arguments:	none
Notes:	Intended to reset the REBOL interpreter.

RL_Extend

Function:	void RL_Extend(REBYTE source, RXICAL call)
Summary:	Appends embedded extension to system/catalog/boot-exts.
Returns:	A pointer to the REBOL library (see reb-lib.h).
Arguments:	source - A pointer to a UTF-8 (or ASCII) string that provides extension module header, function definitions, and other related functions and data. call - A pointer to the extension's command dispatcher.
Notes:	This function simply adds the embedded extension to the boot-exts list. All other processing and initialization happens later during startup. Each embedded extension is queried and init using LOAD-EXTENSION system native. See extensions: embedded extensions

RL_Escape

Function:	void RL_Escape(REBINT reserved)
Summary:	Signal that code ecaluation needs to be interrupted.
Returns:	nothing
Arguments:	reserved - must be set to zero.
Notes:	This function set's a signal that is checked during evaluation and will cause the interpreter to begin processing an escape trap. Note that control must be passed back to REBOL for the signal to be recognized and handled.

RL_Do_String

Function:	int RL_Do_String(REBYTE text, REBCNT flags, RXIARG result)
Summary:	Load a string and evaluate the resulting block.
Returns:	The datatype of the result.
Arguments:	text - A null terminated UTF-8 (or ASCII) string to transcode into a block and evaluate. flags - set to zero for now result - value returned from evaluation.

RL_Do_Binary

Function:	int RL_Do_Binary(REBYTE bin, REBINT length, REBCNT flags, REBCNT key, RXIARG result)
Summary:	Evaluate an encoded binary script such as compressed text.
Returns:	The datatype of the result or zero if error in the encoding.
Arguments:	bin - by default, a REBOL compressed UTF-8 (or ASCII) script. length - the length of the data. flags - special flags (set to zero at this time). key - encoding, encryption, or signature key. result - value returned from evaluation.
Notes:	As of A104, only compressed scripts are supported, however, rebin, cloaked, signed, and encrypted formats will be supported.

RL_Do_Block

Function:	int RL_Do_Block(REBSER blk, REBCNT flags, RXIARG result)
Summary:	Evaluate a block. (not implemented)
Returns:	The datatype of the result or zero if error in the encoding.
Arguments:	blk - A pointer to the block series flags - set to zero for now result - value returned from evaluation
Notes:	Not implemented. Contact Carl on R3 Chat if you think you could use it for something.

RL_Do_Commands

Function:	void RL_Do_Commands(REBSER blk, REBCNT flags, REBCEC context)
Summary:	Evaluate a block of extension commands at high speed.
Returns:	Nothing
Arguments:	blk - a pointer to the block series flags - set to zero for now context - command evaluation context struct or zero if not used.
Notes:	For command blocks only, not for other blocks. The context allows passing to each command a struct that is used for back-referencing your environment data or for tracking the evaluation block and its index.

RL_Print

Function:	void RL_Print(REBYTE fmt, ...)
Summary:	Low level print of formatted data to the console.
Returns:	nothing
Arguments:	fmt - A format string similar but not identical to printf. Special options are available. ... - Values to be formatted.
Notes:	This function is low level and handles only a few C datatypes at this time.

RL_Print_TOS

Function:	void RL_Print_TOS(REBCNT flags, REBYTE marker)
Summary:	Print top REBOL stack value to the console. (pending changes)
Returns:	Nothing
Arguments:	flags - special flags (set to zero at this time). marker - placed at beginning of line to indicate output.
Notes:	This function is used for the main console evaluation input loop to print the results of evaluation from stack. The REBOL data stack is an abstract structure that can change between releases. This function allows the host to print the result of processed functions. Note that what is printed is actually TOS+1. Marker is usually "==" to show output. The system/options/result-types determine which values are automatically printed.

RL_Event

Function:	int RL_Event(REBEVT evt)
Summary:	Appends an application event (e.g. GUI) to the event port.
Returns:	Returns TRUE if queued, or FALSE if event queue is full.
Arguments:	evt - A properly initialized event structure. The contents of this structure are copied as part of the function, allowing use of locals.
Notes:	Sets a signal to get REBOL attention for WAIT and awake. To avoid environment problems, this function only appends to the event queue (no auto-expand). So if the queue is full

RL_Make_Block

Function:	void RL_Make_Block(u32 size)
Summary:	Allocate a new block.
Returns:	A pointer to a block series.
Arguments:	size - the length of the block. The system will add one extra for the end-of-block marker.
Notes:	Blocks are allocated with REBOL's internal memory manager. Internal structures may change, so NO assumptions should be made! Blocks are automatically garbage collected if there are no references to them from REBOL code (C code does nothing.) However, you can lock blocks to prevent deallocation. (?? default)

RL_Make_String

Function:	void RL_Make_String(u32 size, int unicode)
Summary:	Allocate a new string.
Returns:	A pointer to a string series.
Arguments:	size - the length of the string. The system will add one extra for a null terminator (not strictly required, but good for C.) unicode - set FALSE for ASCII/Latin1 strings, set TRUE for Unicode.
Notes:	Strings can be REBYTE or REBCHR sized (depends on R3 config.) Strings are allocated with REBOL's internal memory manager. Internal structures may change, so NO assumptions should be made! Strings are automatically garbage collected if there are no references to them from REBOL code (C code does nothing.) However, you can lock strings to prevent deallocation. (?? default)

RL_Make_Image

Function:	void RL_Make_Image(u32 width, u32 height)
Summary:	Allocate a new image of the given size.
Returns:	A pointer to an image series.
Arguments:	width - the width of the image in pixels height - the height of the image in lines
Notes:	Images are allocated with REBOL's internal memory manager. Image are automatically garbage collected if there are no references to them from REBOL code (C code does nothing.)

RL_Protect_GC

Function:	void RL_Protect_GC(REBSER series, u32 flags)
Summary:	Protect memory from garbage collection.
Returns:	nothing
Arguments:	series - a series to protect (block, string, image, ...) flags - set to 1 to protect, 0 to unprotect
Notes:	You should only use this function when absolutely necessary, because it bypasses garbage collection for the specified series. Meaning: if you protect a series, it will never be freed. Also, you only need this function if you allocate several series such as strings, blocks, images, etc. within the same command and you don't store those references somewhere where the GC can find them, such as in an existing block or object (variable).

RL_Get_String

Function:	int RL_Get_String(REBSER series, u32 index, void str)
Summary:	Obtain a pointer into a string (bytes or unicode).
Returns:	The length and type of string. When len > 0, string is unicode. When len < 0, string is bytes.
Arguments:	series - string series pointer index - index from beginning (zero-based) str - pointer to first character
Notes:	If the len is less than zero, then the string is optimized to codepoints (chars) 255 or less for ASCII and LATIN-1 charsets. Strings are allowed to move in memory. Therefore, you will want to make a copy of the string if needed.

RL_Map_Word

Function:	u32 RL_Map_Word(REBYTE string)
Summary:	Given a word as a string, return its global word identifier.
Returns:	The word identifier that matches the string.
Arguments:	string - a valid word as a UTF-8 encoded string.
Notes:	Word identifiers are persistent, and you can use them anytime. If the word is new (not found in master symbol table) it will be added and the new word identifier is returned.

RL_Map_Words

Function:	u32 RL_Map_Words(REBSER series)
Summary:	Given a block of word values, return an array of word ids.
Returns:	An array of global word identifiers (integers). The [0] value is the size.
Arguments:	series - block of words as values (from REBOL blocks, not strings.)
Notes:	Word identifiers are persistent, and you can use them anytime. The block can include any kind of word, including set-words, lit-words, etc. If the input block contains non-words, they will be skipped. The array is allocated with OS_MAKE and you can OS_FREE it any time.

RL_Word_String

Function:	REBYTE RL_Word_String(u32 word)
Summary:	Return a string related to a given global word identifier.
Returns:	A copy of the word string, null terminated.
Arguments:	word - a global word identifier
Notes:	The result is a null terminated copy of the name for your own use. The string is always UTF-8 encoded (chars > 127 are encoded.) In this API, word identifiers are always canonical. Therefore, the returned string may have different spelling/casing than expected. The string is allocated with OS_MAKE and you can OS_FREE it any time.

RL_Find_Word

Function:	u32 RL_Find_Word(u32 words, u32 word)
Summary:	Given an array of word ids, return the index of the given word.
Returns:	The index of the given word or zero.
Arguments:	words - a word array like that returned from MAP_WORDS (first element is size) word - a word id
Notes:	The first element of the word array is the length of the array.

RL_Series

Function:	int RL_Series(REBSER series, REBCNT what)
Summary:	Get series information.
Returns:	Returns information related to a series.
Arguments:	series - any series pointer (string or block) what - indicates what information to return (see RXI_SER enum)
Notes:	Invalid what arg nums will return zero.

RL_Get_Char

Function:	int RL_Get_Char(REBSER series, u32 index)
Summary:	Get a character from byte or unicode string.
Returns:	A Unicode character point from string. If index is at or past the tail, a -1 is returned.
Arguments:	series - string series pointer index - zero based index of character
Notes:	This function works for byte and unicoded strings. The maximum size of a Unicode char is determined by R3 build options. The default is 16 bits.

RL_Set_Char

Function:	u32 RL_Set_Char(REBSER series, u32 index, u32 chr)
Summary:	Set a character into a byte or unicode string.
Returns:	The index passed as an argument.
Arguments:	series - string series pointer index - where to store the character. If past the tail, the string will be auto-expanded by one and the char will be appended.

RL_Get_Value

Function:	int RL_Get_Value(REBSER series, u32 index, RXIARG result)
Summary:	Get a value from a block.
Returns:	Datatype of value or zero if index is past tail.
Arguments:	series - block series pointer index - global word identifier (integer) result - set to the value of the field

RL_Set_Value

Function:	int RL_Set_Value(REBSER series, u32 index, RXIARG val, int type)
Summary:	Set a value in a block.
Returns:	TRUE if index past end and value was appended to tail of block.
Arguments:	series - block series pointer index - global word identifier (integer) val - new value for field type - datatype of value

RL_Words_Of_Object

Function:	u32 RL_Words_Of_Object(REBSER obj)
Summary:	Returns information about the object.
Returns:	Returns an array of words used as fields of the object.
Arguments:	obj - object pointer (e.g. from RXA_OBJECT)
Notes:	Returns a word array similar to MAP_WORDS(). The array is allocated with OS_MAKE. You can OS_FREE it any time.

RL_Get_Field

Function:	int RL_Get_Field(REBSER obj, u32 word, RXIARG result)
Summary:	Get a field value (context variable) of an object.
Returns:	Datatype of value or zero if word is not found in the object.
Arguments:	obj - object pointer (e.g. from RXA_OBJECT) word - global word identifier (integer) result - gets set to the value of the field

RL_Set_Field

Function:	int RL_Set_Field(REBSER obj, u32 word, RXIARG val, int type)
Summary:	Set a field (context variable) of an object.
Returns:	The type arg, or zero if word not found in object or if field is protected.
Arguments:	obj - object pointer (e.g. from RXA_OBJECT) word - global word identifier (integer) val - new value for field type - datatype of value

RL_Callback

Function:	int RL_Callback(RXICBI cbi)
Summary:	Evaluate a REBOL callback function, either synchronous or asynchronous.
Returns:	Sync callback: type of the result; async callback: true if queued
Arguments:	cbi - callback information including special option flags, object pointer (where function is located), function name as global word identifier (within above object), argument list passed to callback (see notes below), and result value.
Notes:	The flag value will determine the type of callback. It can be either synchronous, where the code will re-enter the interpreter environment and call the specified function, or asynchronous where an EVT_CALLBACK event is queued, and the callback will be evaluated later when events are processed within the interpreter's environment. For asynchronous callbacks, the cbi and the args array must be managed because the data isn't processed until the callback event is handled. Therefore, these cannot be allocated locally on the C stack; they should be dynamic (or global if so desired.) See extensions: callback functions