urlan.h File Reference

The Urlan programmer interface. More...

#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	UCellId
	Basic type identification. More...
struct	UCellNumber
	UCell structure for number types. More...
struct	UCellCoord
	UCell structure for coord type. More...
struct	UCellWord
	UCell structure for word types. More...
struct	UCellSeries
	UCell structure for series types. 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...
struct	UBindTarget
	Holds information for binding functions. More...
struct	UDatatype
	The UDatatype struct holds methods for a specific class of data. More...
struct	USeriesType
	The USeriesType struct holds extra methods for series datatypes. More...
Defines
#define	ur_strFree   ur_arrFree
	A string is a simple array.
#define	ur_blkFree   ur_arrFree
	A block is a simple array.
#define	ur_ctxCell(c, n)   ((c)->ptr.cell + n)
	Get pointer of UCell in context by index.
#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().
#define	ur_cstr(strC, bin)   ur_cstring(ur_bufferSer(strC), bin, strC->series.it, strC->series.end)
	Make null terminated UTF-8 string in binary buffer.
Enumerations
enum	UrlanDataType
	Indentifers for the built-in datatypes. More...
enum	UrlanReturnCode { UR_THROW = 0, UR_OK = 1 }
	These values can be returned by functions to indicate success or failure. 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.
enum	UrlanRecyclePhase { UR_RECYCLE_MARK, UR_RECYCLE_SWEEP }
Functions
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 *)
	Free environment and all threads.
void	ur_freezeEnv (UThread *)
	Move the startup thread dataStore to the shared environment.
UThread *	ur_makeThread (const UThread *)
	Create new thread.
int	ur_destroyThread (UThread *)
	Remove UThread from environment thread list and free memory.
int	ur_datatypeCount (UThread *)
	Get number of datatypes installed in the environment.
UAtom	ur_internAtom (UThread *, const char *it, const char *end)
	Add a single atom to the shared environment.
UAtom *	ur_internAtoms (UThread *, const char *words, UAtom *atoms)
	Add atoms to the shared environment.
const char *	ur_atomCStr (UThread *, UAtom atom)
	Get name of atom.
void	ur_atomsSort (UAtomEntry *entries, int low, int high)
	Perform quicksort on UAtomEntry table.
int	ur_atomsSearch (const UAtomEntry *entries, int count, UAtom atom)
	Find an atom in a UAtomEntry table using a binary search.
void	ur_genBuffers (UThread *, int count, UIndex *index)
	Generate new buffers in dataStore.
void	ur_destroyBuffer (UThread *, UBuffer *)
	Destroy buffer in dataStore.
UIndex	ur_holdBuffer (UThread *, UIndex bufN)
	Keeps buffer in thread dataStore from being garbage collected by ur_recycle().
void	ur_releaseBuffer (UThread *, UIndex hold)
	Enables garbage collection of dataStore buffer which was held by ur_holdBuffer().
void	ur_recycle (UThread *)
	Perform garbage collection on thread dataStore.
int	ur_markBuffer (UThread *, UIndex bufN)
	Makes sure the buffer is marked as used.
int	ur_error (UThread *, int errorType, const char *fmt,...)
	Append error! to the error block.
UBuffer *	ur_errorBlock (UThread *)
	Get thread error block.
UBuffer *	ur_threadContext (UThread *)
	Get thread global context.
UBuffer *	ur_envContext (UThread *)
	Get shared global context.
void	ur_appendTrace (UThread *, UIndex blkN, UIndex it)
	Append block position to the UCellError::traceBlk of the error on top of the error stack.
UIndex	ur_tokenize (UThread *, const char *it, const char *end, UCell *res)
	Convert a UTF-8 data string into a block.
int	ur_serialize (UThread *, UIndex blkN, UCell *res)
	Serialize block.
void	ur_toStr (UThread *, const UCell *cell, UBuffer *str, int depth)
	Append data representation of cell to a string.
void	ur_toText (UThread *, const UCell *cell, UBuffer *str)
	Append textual representation of cell to a string.
const UCell *	ur_wordCell (UThread *, const UCell *cell)
	Get word value for read-only operations.
UCell *	ur_wordCellM (UThread *, const UCell *cell)
	Get modifiable word value.
int	ur_setWord (UThread *, const UCell *wordCell, const UCell *src)
	Set word.
const UBuffer *	ur_bufferEnv (UThread *, UIndex n)
	Get buffer from either the thread or shared environment dataStore.
const UBuffer *	ur_bufferSeries (const UThread *, const UCell *cell)
	Get series buffer.
UBuffer *	ur_bufferSeriesM (UThread *, const UCell *cell)
	Get modifiable series buffer.
void	ur_seriesSlice (const UThread *, USeriesIter *si, const UCell *cell)
	Set USeriesIter to series slice.
int	ur_seriesSliceM (UThread *, USeriesIterM *si, const UCell *cell)
	Set USeriesIterM to modifiable series slice.
void	ur_bind (UThread *, UBuffer *blk, const UBuffer *ctx, int bindType)
	Bind block to context.
void	ur_bindCells (UThread *, UCell *it, UCell *end, const UBindTarget *bt)
	Bind an array of cells to a target.
void	ur_infuse (UThread *, UCell *it, UCell *end, const UBuffer *ctx)
	Replace words in cells with their values from a context.
int	ur_isTrue (const UCell *cell)
	Returns: Non-zero if cell is not none! or false.
int	ur_same (UThread *, const UCell *a, const UCell *b)
	Returns: Non-zero if values are the same.
int	ur_equal (UThread *, const UCell *a, const UCell *b)
	Returns: Non-zero if values are equivalent.
int	ur_equalCase (UThread *, const UCell *a, const UCell *b)
	Case-sensitive equality test.
int	ur_compare (UThread *, 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 *, const UCell *a, const UCell *b)
	Case-sensitive ordering comparison.
void	ur_makeDatatype (UCell *cell, int type)
	Initialize cell to be a UT_DATATYPE value of the given type.
int	ur_isDatatype (const UCell *cell, const UCell *datatype)
	Test if cell is of a certain datatype.
void	ur_datatypeAddType (UCell *cell, int type)
	Add type to multi-type UT_DATATYPE cell.
int	ur_charLowercase (int c)
	Convert UCS2 character to lowercase.
int	ur_charUppercase (int c)
	Convert UCS2 character to uppercase.
UIndex	ur_makeBinary (UThread *, int size)
	Generate and initialize a single binary buffer.
UBuffer *	ur_makeBinaryCell (UThread *, int size, UCell *cell)
	Generate a single binary and set cell to reference it.
void	ur_binInit (UBuffer *, int size)
	Initialize buffer to type UT_BINARY.
void	ur_binReserve (UBuffer *, int size)
	Allocates enough memory to hold size bytes.
void	ur_binExpand (UBuffer *, int index, int count)
	Create space in the binary for count bytes starting at index.
void	ur_binErase (UBuffer *, int start, int count)
	Remove bytes from the binary.
void	ur_binAppendData (UBuffer *, const uint8_t *data, int len)
	Append data to binary buffer.
void	ur_binAppendArray (UBuffer *, const USeriesIter *si)
	Append array slice to binary buffer.
const char *	ur_binAppendBase (UBuffer *buf, const char *it, const char *end, enum UrlanBinaryEncoding enc)
	Append encoded ASCII string to binary buffer.
void	ur_binFree (UBuffer *)
	Free binary data.
void	ur_binSlice (UThread *, UBinaryIter *, const UCell *cell)
	Set UBinaryIter to binary slice.
int	ur_binSliceM (UThread *, UBinaryIterM *, const UCell *cell)
	Set UBinaryIterM to binary slice.
void	ur_binToStr (UBuffer *, int encoding)
	Convert binary buffer to string buffer.
UIndex	ur_makeString (UThread *, int enc, int size)
	Generate and initialize a single string buffer.
UBuffer *	ur_makeStringCell (UThread *, int enc, int size, UCell *cell)
	Generate a single string and set cell to reference it.
UIndex	ur_makeStringUtf8 (UThread *, const uint8_t *it, const uint8_t *end)
	Generate and initialize a single string buffer from memory holding a UTF-8 string.
void	ur_strInit (UBuffer *, int enc, int size)
	Initialize buffer to type UT_STRING.
void	ur_strAppendCStr (UBuffer *, const char *)
	Append a null-terminated ASCII string to a string buffer.
void	ur_strAppendChar (UBuffer *, int)
	Append a single UCS2 character to a string.
void	ur_strAppendInt (UBuffer *, int32_t)
	Append an integer to a string.
void	ur_strAppendInt64 (UBuffer *, int64_t)
	Append an 64-bit integer to a string.
void	ur_strAppendHex (UBuffer *, uint32_t n, uint32_t hi)
	Append a hexidecimal integer to a string.
void	ur_strAppendDouble (UBuffer *, double)
	Append a double to a string.
void	ur_strAppendIndent (UBuffer *, int depth)
	Append tabs to a string.
void	ur_strAppend (UBuffer *, const UBuffer *strB, UIndex itB, UIndex endB)
	Append another string buffer to this string.
void	ur_strTermNull (UBuffer *)
	Terminate with null character so buffer can be used as a C string.
int	ur_strIsAscii (const UBuffer *)
	Test if all characters are ASCII.
void	ur_strFlatten (UBuffer *)
	Convert a UTF-8 or UCS-2 string buffer to Latin-1 if possible.
void	ur_strLowercase (UBuffer *str, UIndex start, UIndex send)
	Convert characters of string slice to lowercase.
void	ur_strUppercase (UBuffer *str, UIndex start, UIndex send)
	Convert characters of string slice to uppercase.
UIndex	ur_strFindChar (const UBuffer *, UIndex start, UIndex end, int ch)
	Find the first instance of a character in a string.
UIndex	ur_strFindChars (const UBuffer *, UIndex start, UIndex end, uint8_t *charSet, int len)
	Find the first character of a set in a string.
UIndex	ur_strFind (const USeriesIter *, const USeriesIter *, int matchCase)
	Find string in another string.
UIndex	ur_strMatch (const USeriesIter *, const USeriesIter *, int matchCase)
	Compare characters in two strings.
int	ur_strChar (const UBuffer *, UIndex pos)
	Return the character at a given position.
char *	ur_cstring (const UBuffer *, UBuffer *bin, UIndex start, UIndex end)
	Make null terminated UTF-8 string in binary buffer.
UIndex	ur_makeBlock (UThread *, int size)
	Generate a single block of type UT_BLOCK.
UBuffer *	ur_makeBlockCell (UThread *, int type, int size, UCell *cell)
	Generate a single block and set cell to reference it.
UIndex	ur_blkClone (UThread *, UIndex blkN)
	Make deep copy of block.
void	ur_blkInit (UBuffer *, int type, int size)
	Initialize block buffer.
UCell *	ur_blkAppendNew (UBuffer *, int type)
	Add cell to end of block.
void	ur_blkAppendCells (UBuffer *, const UCell *cells, int count)
	Append cells to block.
void	ur_blkInsert (UBuffer *, UIndex it, const UCell *cells, int count)
	Insert cells into block.
void	ur_blkPush (UBuffer *, const UCell *cell)
	Copy cell to end of block.
UCell *	ur_blkPop (UBuffer *)
	Remove cell from end of block.
void	ur_blkSlice (UThread *, UBlockIter *, const UCell *cell)
	Set UBlockIter to block slice.
int	ur_blkSliceM (UThread *, UBlockIterM *, const UCell *cell)
	Set UBlockIterM to block slice.
int	ur_pathCell (UThread *, const UCell *pc, UCell *res)
	Get the value which a path refers to.
int	ur_setPath (UThread *, const UCell *path, const UCell *src)
	Set path.
UIndex	ur_makeContext (UThread *, int size)
	Generate and initialize a single context.
UBuffer *	ur_makeContextCell (UThread *, int size, UCell *cell)
	Generate a single context and set cell to reference it.
UBuffer *	ur_ctxClone (UThread *, const UBuffer *src, UCell *cell)
	Clone a new context and set cell to reference it.
UBuffer *	ur_ctxMirror (UThread *, const UBuffer *src, UCell *cell)
	Create a shallow copy of a context and set cell to reference the new context.
void	ur_ctxInit (UBuffer *, int size)
	Initialize context buffer.
void	ur_ctxReserve (UBuffer *, int size)
	Allocates enough memory to hold size words.
void	ur_ctxFree (UBuffer *)
	Free context data.
UBuffer *	ur_ctxSort (UBuffer *)
	Sort the internal context search table so ur_ctxLookup() can be used.
void	ur_ctxSetWords (UBuffer *, const UCell *it, const UCell *end)
	Add the set-word! values in a series of cells to the words in a context.
int	ur_ctxAppendWord (UBuffer *, UAtom atom)
	Append word to context.
int	ur_ctxAddWordI (UBuffer *, UAtom atom)
	Add word to context if it does not already exist.
UCell *	ur_ctxAddWord (UBuffer *, UAtom atom)
	Similar to ur_ctxAddWordI(), but safely returns the cell pointer.
int	ur_ctxLookupNoSort (const UBuffer *, UAtom atom)
	Find word in context by atom.
int	ur_ctxLookup (const UBuffer *, UAtom atom)
	Find word in context by atom.
const UBuffer *	ur_sortedContext (UThread *, const UCell *)
	Get context and make sure it is ready for ur_ctxLookup().
void	ur_vecInit (UBuffer *, int form, int elemSize, int size)
	Initialize buffer to type UT_VECTOR.
void	ur_arrInit (UBuffer *, int size, int count)
	Initialize array buffer.
void	ur_arrReserve (UBuffer *, int count)
	Allocates enough memory to hold count elements.
void	ur_arrExpand (UBuffer *, int index, int count)
	Create space in the array for count elements starting at index.
void	ur_arrErase (UBuffer *, int start, int count)
	Remove elements from the array.
void	ur_arrFree (UBuffer *)
	Free array data.
void	ur_arrAppendInt32 (UBuffer *, int32_t)
	Append int32_t to array.
void	ur_arrAppendFloat (UBuffer *, float)
	Append float to array.

---

Detailed Description

The Urlan programmer interface.

This is a C library which provides a garbage collected datatype system and data format which can be used for building domain specific languages.

---

Enumeration Type Documentation

enum UrlanRecyclePhase

Enumerator:

UR_RECYCLE_MARK	Phase passed to UDatatype::recycle.
UR_RECYCLE_SWEEP	Phase passed to UDatatype::recycle.

---

Function Documentation

void ur_arrAppendFloat	(	UBuffer *	buf,
		float	n
	)

Append float to array.

Parameters:

	buf	Array buffer with elemSize of 4.
	n	Number to append.

void ur_arrAppendInt32	(	UBuffer *	buf,
		int32_t	n
	)

Append int32_t to array.

Parameters:

	buf	Array buffer with elemSize of 4.
	n	Number to append.

void ur_arrErase	(	UBuffer *	buf,
		int	start,
		int	count
	)

Remove elements from the array.

Parameters:

	buf	Initialized array buffer.
	start	Start index of erase.
	count	Number of elements to remove.

void ur_arrExpand	(	UBuffer *	buf,
		int	index,
		int	count
	)

Create space in the array for count elements starting at index.

The memory in the new space is uninitialized.

Parameters:

	buf	Initialized array buffer.
	index	Position to expand at.
	count	Number of elements to expand.

void ur_arrFree

(

UBuffer *

buf

)

Free array data.

buf->ptr and buf->used are set to zero.

void ur_arrInit	(	UBuffer *	buf,
		int	size,
		int	count
	)

Initialize array buffer.

The buf type, form, flags, and used members are set to zero.

Parameters:

	buf	Uninitialized buffer.
	size	Element byte size. Must be less than 256.
	count	Number of elements to allocate.

void ur_arrReserve	(	UBuffer *	buf,
		int	count
	)

Allocates enough memory to hold count elements.

buf->used is not changed.

Parameters:

	buf	Initialized array buffer.
	count	Total number of elements.

int ur_isDatatype	(	const UCell *	cell,
		const UCell *	datatype
	)

Test if cell is of a certain datatype.

Parameters:

	cell	Cell to test.
	datatype	Valid cell of type UT_DATATYPE.

Returns:

Non-zero if cell type matches datatype.

int ur_markBuffer	(	UThread *	ut,
		UIndex	bufN
	)

Makes sure the buffer is marked as used.

If the buffer had not already been marked as used, then non-zero is returned, and the caller is expected to invoke the UDatatype::markBuf method.

Note:

This may only be called from inside a UDatatype::mark or UDatatype::markBuf method.

Parameters:

bufN

Buffer index into thread dataStore.

Returns:

Zero if already marked as used.

void ur_recycle

(

UThread *

ut

)

Perform garbage collection on thread dataStore.

This is a precise, tracing, mark-sweep collector. If starts with held buffers and the datatypes trace any buffers they reference.

Any UBuffer pointers to the thread dataStore must be considered invalid after this call. Note that while the buffer structures may move, the data that they point to (the UBuffer::ptr member) will not change.

int ur_serialize	(	UThread *	ut,
		UIndex	blkN,
		UCell *	res
	)

Serialize block.

Parameters:

	blkN	Index to valid block buffer.
	res	Cell to be set to new output binary.

Returns:

UR_OK/UR_THROW

void ur_vecInit	(	UBuffer *	buf,
		int	form,
		int	elemSize,
		int	size
	)

Initialize buffer to type UT_VECTOR.

Parameters:

	form	Form.
	elemSize	Byte size of each element. May be zero if form is a standard type (UR_ATOM_U32, UR_ATOM_F32, etc.).
	size	Number of elements to reserve.

---