Core Programmer Interface
[Urlan Datatype System]

Data Structures
struct	UBindTarget
	Holds information for binding functions. More...
union	UCell
	A cell holds a single value. More...
struct	UBuffer
	The UBuffer struct holds information about a resource, usually a chuck of memory. More...
struct	UThread
	The UThread struct stores the data specific to a thread of execution. More...
Defines
#define	ur_type(c)   (c)->id.type
	Return UrlanDataType of cell.
#define	ur_setId(c, t)   *((uint32_t*) (c)) = t
	Set type and initialize the other 24 bits of UCellId to zero.
#define	ur_isShared(n)   (n < 0)
	True if buffer number refers to a buffer in the shared environment.
#define	ur_isSliced(c)   ((c)->series.end > -1)
	True if the end member of a series cell is set.
#define	ur_hold(n)   ur_holdBuffer(ut,n)
	Convenience macro for ur_holdBuffer().
#define	ur_release(h)   ur_releaseBuffer(ut,h)
	Convenience macro for ur_releaseBuffer().
#define	ur_buffer(n)   (ut->dataStore.ptr.buf + (n))
	Macro to get buffer known to be in thread dataStore.
#define	ur_bufferE(n)   ur_bufferEnv(ut,n)
	Convenience macro for ur_bufferEnv().
#define	ur_bufferSer(c)   ur_bufferSeries(ut,c)
	Convenience macro for ur_bufferSeries().
#define	ur_bufferSerM(c)   ur_bufferSeriesM(ut,c)
	Convenience macro for ur_bufferSeriesM().
Enumerations
enum	UrlanReturnCode { UR_THROW = 0, UR_OK = 1 }
	These values can be returned by functions to indicate success or failure. More...
enum	UrlanDataType
	Indentifers for the built-in datatypes. More...
enum	UrlanErrorType {   UR_ERR_TYPE, UR_ERR_SCRIPT, UR_ERR_SYNTAX, UR_ERR_ACCESS,   UR_ERR_INTERNAL }
	These descriptive codes are passed to ur_error(). More...
enum	UThreadMethod
	Operations on thread data.
Functions
const char *	ur_atomCStr (UThread *ut, UAtom atom)
	Get name of atom.
UThread *	ur_makeThread (const UThread *ut)
	Create new thread.
int	ur_destroyThread (UThread *ut)
	Remove UThread from environment thread list and free memory.
UThread *	ur_makeEnv (int atomLimit, const UDatatype **dtTable, unsigned int dtCount, unsigned int thrSize, void(*thrMethod)(UThread *, UThreadMethod))
	Allocate UEnv and initial UThread.
void	ur_freeEnv (UThread *ut)
	Free environment and all threads.
void	ur_freezeEnv (UThread *ut)
	Move the startup thread dataStore to the shared environment.
int	ur_datatypeCount (UThread *ut)
	Get number of datatypes installed in the environment.
UAtom	ur_internAtom (UThread *ut, const char *it, const char *end)
	Add a single atom to the shared environment.
UAtom *	ur_internAtoms (UThread *ut, const char *words, UAtom *atoms)
	Add atoms to the shared environment.
void	ur_genBuffers (UThread *ut, int count, UIndex *index)
	Generate new buffers in dataStore.
void	ur_destroyBuffer (UThread *ut, UBuffer *buf)
	Destroy buffer in dataStore.
UIndex	ur_holdBuffer (UThread *ut, UIndex bufN)
	Keeps buffer in thread dataStore from being garbage collected by ur_recycle().
void	ur_releaseBuffer (UThread *ut, UIndex hold)
	Enables garbage collection of dataStore buffer which was held by ur_holdBuffer().
UBuffer *	ur_errorBlock (UThread *ut)
	Get thread error block.
UBuffer *	ur_threadContext (UThread *ut)
	Get thread global context.
UBuffer *	ur_envContext (UThread *ut)
	Get shared global context.
int	ur_error (UThread *ut, int errorType, const char *fmt,...)
	Append error! to the error block.
void	ur_appendTrace (UThread *ut, UIndex blkN, UIndex it)
	Append block position to the UCellError::traceBlk of the error on top of the error stack.
int	ur_isTrue (const UCell *cell)
	Returns: Non-zero if cell is not none! or false.
int	ur_same (UThread *ut, const UCell *a, const UCell *b)
	Returns: Non-zero if values are the same.
int	ur_equal (UThread *ut, const UCell *a, const UCell *b)
	Returns: Non-zero if values are equivalent.
int	ur_equalCase (UThread *ut, const UCell *a, const UCell *b)
	Case-sensitive equality test.
int	ur_compare (UThread *ut, const UCell *a, const UCell *b)
	Returns: 1, 0, or -1, if cell a is greater than, equal to, or less than cell b.
int	ur_compareCase (UThread *ut, const UCell *a, const UCell *b)
	Case-sensitive ordering comparison.
void	ur_toStr (UThread *ut, const UCell *cell, UBuffer *str, int depth)
	Append data representation of cell to a string.
void	ur_toText (UThread *ut, const UCell *cell, UBuffer *str)
	Append textual representation of cell to a string.
const UCell *	ur_wordCell (UThread *ut, const UCell *cell)
	Get word value for read-only operations.
UCell *	ur_wordCellM (UThread *ut, const UCell *cell)
	Get modifiable word value.
int	ur_setWord (UThread *ut, const UCell *word, const UCell *src)
	Set word.
const UBuffer *	ur_bufferEnv (UThread *ut, UIndex n)
	Get buffer from either the thread or shared environment dataStore.
const UBuffer *	ur_bufferSeries (const UThread *ut, const UCell *cell)
	Get series buffer.
UBuffer *	ur_bufferSeriesM (UThread *ut, const UCell *cell)
	Get modifiable series buffer.
void	ur_seriesSlice (const UThread *ut, USeriesIter *si, const UCell *cell)
	Set USeriesIter to series slice.
int	ur_seriesSliceM (UThread *ut, USeriesIterM *si, const UCell *cell)
	Set USeriesIterM to modifiable series slice.
UIndex	ur_tokenize (UThread *ut, const char *it, const char *end, UCell *res)
	Convert a UTF-8 data string into a block.

---

Enumeration Type Documentation

enum UrlanDataType

Indentifers for the built-in datatypes.

These values match the datatype name atom.

enum UrlanErrorType

These descriptive codes are passed to ur_error().

Enumerator:

UR_ERR_TYPE	Invalid argument/parameter datatype.
UR_ERR_SCRIPT	General script evaluation error.
UR_ERR_SYNTAX	Syntax error.
UR_ERR_ACCESS	Problem accessing external resources.
UR_ERR_INTERNAL	Fatal internal problem.

enum UrlanReturnCode

These values can be returned by functions to indicate success or failure.

Enumerator:

UR_THROW	Returned to indicate an evaluation exception occured. This is guaranteed to always be zero.
UR_OK	Returned to indicate successful evaluation/operation. This is guaranteed to always be one.

---

Function Documentation

void ur_appendTrace	(	UThread *	ut,
		UIndex	blkN,
		UIndex	it
	)

Append block position to the UCellError::traceBlk of the error on top of the error stack.

Parameters:

	blkN	Block id.
	it	Position in block blkN.

const char* ur_atomCStr	(	UThread *	ut,
		UAtom	atom
	)

Get name of atom.

Parameters:

atom

Valid atom.

Returns:

Null terminated string.

const UBuffer* ur_bufferEnv	(	UThread *	ut,
		UIndex	n
	)

Get buffer from either the thread or shared environment dataStore.

The macro ur_bufferE() should normally be used to call this function.

Parameters:

n

Buffer identifier.

Returns:

Pointer to buffer n.

const UBuffer* ur_bufferSeries	(	const UThread *	ut,
		const UCell *	cell
	)

Get series buffer.

The macro ur_bufferSer() should normally be used to call this function.

Parameters:

cell

Pointer to valid series or bound word cell.

Returns:

Pointer to buffer referenced by cell->series.buf.

UBuffer* ur_bufferSeriesM	(	UThread *	ut,
		const UCell *	cell
	)

Get modifiable series buffer.

The macro ur_bufferSerM() should normally be used to call this function.

Parameters:

cell

Pointer to valid series or bound word cell.

Returns:

Pointer to buffer referenced by cell->series.buf. If the buffer is in shared storage then an error is generated and zero is returned.

int ur_compareCase	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b
	)

Case-sensitive ordering comparison.

Returns:

1, 0, or -1, if cell a is greater than, equal to, or less than cell b.

int ur_datatypeCount

(

UThread *

ut

)

Get number of datatypes installed in the environment.

Returns:

Number of datatypes.

void ur_destroyBuffer	(	UThread *	ut,
		UBuffer *	buf
	)

Destroy buffer in dataStore.

The buffer must be valid. This function must not be called with a buffer which has not been generated with ur_genBuffers(), has not been initialized, or has already been destroyed.

Parameters:

buf

Pointer to valid buffer.

int ur_destroyThread

(

UThread *

ut

)

Remove UThread from environment thread list and free memory.

If there are no other threads in the environment, then ur_freeEnv() is called.

Parameters:

ut

Thread created with ur_makeThread()

Returns:

Non-zero if ur_freeEnv() is called.

UBuffer* ur_envContext

(

UThread *

ut

)

Get shared global context.

Returns:

Pointer to context, or zero if ur_freezeEnv() has not been called.

int ur_equalCase	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b
	)

Case-sensitive equality test.

Returns:

Non-zero if values are equivalent.

int ur_error	(	UThread *	ut,
		int	errorType,
		const char *	fmt,
			...
	)

Append error! to the error block.

The errorType is only descriptive, it has no real function.

Parameters:

	errorType	UrlanErrorType (UR_ERR_DATATYPE, UR_ERR_SCRIPT, etc.).
	fmt	Error message with printf() style formatting.

Returns:

UR_THROW

See also:

ur_errorBlock

Examples:

calculator.c.

UBuffer* ur_errorBlock

(

UThread *

ut

)

Get thread error block.

Returns:

Pointer to block of errors.

Examples:

calculator.c.

void ur_freeEnv

(

UThread *

ut

)

Free environment and all threads.

Caller must make sure no other threads are running.

Parameters:

ut

UThread created with ur_makeEnv(). It is safe to pass zero.

Examples:

calculator.c.

void ur_freezeEnv

(

UThread *

ut

)

Move the startup thread dataStore to the shared environment.

This may only be called once after ur_makeEnv(), and must be done before a second thread is created.

The thread method UR_THREAD_FREEZE is called before any adjustments are made. After the store has been converted, the method UR_THREAD_INIT will be called on a fresh thread dataStore.

Parameters:

ut

UThread created with ur_makeEnv().

void ur_genBuffers	(	UThread *	ut,
		int	count,
		UIndex *	index
	)

Generate new buffers in dataStore.

This may trigger the garbage collector.

The new buffers are completely unintialized, so the caller must make them valid before the next garbage recycle.

Parameters:

	count	Number of buffers to obtain.
	index	Return array of buffer ids. This must large enough to to hold count indices.

Returns:

The buffer indicies are stored in index.

UIndex ur_holdBuffer	(	UThread *	ut,
		UIndex	bufN
	)

Keeps buffer in thread dataStore from being garbage collected by ur_recycle().

Returns:

Hold id to be used with ur_releaseBuffer().

UAtom ur_internAtom	(	UThread *	ut,
		const char *	it,
		const char *	end
	)

Add a single atom to the shared environment.

Parameters:

	it	Start of word.
	end	End of word.

Returns:

Atom of word.

UAtom* ur_internAtoms	(	UThread *	ut,
		const char *	words,
		UAtom *	atoms
	)

Add atoms to the shared environment.

Parameters:

	words	C string containing words separated by whitespace.
	atoms	Return area for atoms of the words.

Returns:

Pointer marking the end of the entries set in atoms.

Examples:

calculator.c.

UThread* ur_makeEnv	(	int	atomLimit,
		const UDatatype **	dtTable,
		unsigned int	dtCount,
		unsigned int	thrSize,
		void(*)(UThread *, UThreadMethod)	thrMethod
	)

Allocate UEnv and initial UThread.

Parameters:

	atomLimit	Maximum number of atoms. Memory usage is (24 * atomLimit) bytes.
	dtTable	Array of pointers to user defined datatypes. Pass zero if dtCount is zero.
	dtCount	Number of datatypes in dtTable.
	thrSize	Byte size of each thread in the environment. Pass zero if no extra memory is needed.
	thrMethod	Callback function to initialize and cleanup threads. This may be zero.

Returns:

Pointer to initial thread.

Examples:

calculator.c.

UThread* ur_makeThread

(

const UThread *

ut

)

Create new thread.

Parameters:

ut

Existing thread.

Returns:

Pointer to new thread in the same environment as ut.

void ur_seriesSlice	(	const UThread *	ut,
		USeriesIter *	si,
		const UCell *	cell
	)

Set USeriesIter to series slice.

Parameters:

	si	Iterator struct to fill.
	cell	Pointer to a valid series cell.

int ur_seriesSliceM	(	UThread *	ut,
		USeriesIterM *	si,
		const UCell *	cell
	)

Set USeriesIterM to modifiable series slice.

Parameters:

	si	Iterator struct to fill.
	cell	Pointer to a valid series cell.

Returns:

UR_OK/UR_THROW

int ur_setWord	(	UThread *	ut,
		const UCell *	word,
		const UCell *	src
	)

Set word.

This copies src into the cell which the word is bound to.

If the word is unbound or bound to the shared environment then an error is generated and UR_THROW is returned.

Parameters:

	word	Word to set.
	src	Source value to copy.

Returns:

UR_OK/UR_THROW

UBuffer* ur_threadContext

(

UThread *

ut

)

Get thread global context.

Returns:

Pointer to thread global context.

Examples:

calculator.c.

UIndex ur_tokenize	(	UThread *	ut,
		const char *	it,
		const char *	end,
		UCell *	res
	)

Convert a UTF-8 data string into a block.

Note:

Currently, non-ASCII characters are only allowed inside string!/file! types and comments.

Parameters:

	it	Start of string.
	end	End of string.
	res	Cell to initialize as UT_BLOCK if non-zero is returned.

Returns:

Block buffer id. If a syntax error is found, then an error is generated with ur_error() and zero is returned.

Examples:

calculator.c.

void ur_toStr	(	UThread *	ut,
		const UCell *	cell,
		UBuffer *	str,
		int	depth
	)

Append data representation of cell to a string.

Parameters:

str

String to add to.

Examples:

calculator.c.

void ur_toText	(	UThread *	ut,
		const UCell *	cell,
		UBuffer *	str
	)

Append textual representation of cell to a string.

Parameters:

str

String to add to.

const UCell* ur_wordCell	(	UThread *	ut,
		const UCell *	cell
	)

Get word value for read-only operations.

Parameters:

cell

Pointer to word cell.

Returns:

Pointer to value cell. If the word does not reference a valid cell then an error is generated and zero is returned.

Examples:

calculator.c.

UCell* ur_wordCellM	(	UThread *	ut,
		const UCell *	cell
	)

Get modifiable word value.

Parameters:

cell

Pointer to word cell.

Returns:

Pointer to value cell. If the word does not reference a valid cell then an error is generated and zero is returned.

Examples:

calculator.c.

---