Boron 0.1.0

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.
UThreadur_makeThread (const UThread *ut)
 Create new thread.
int ur_destroyThread (UThread *ut)
 Remove UThread from environment thread list and free memory.
UThreadur_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().
UBufferur_errorBlock (UThread *ut)
 Get thread error block.
UBufferur_threadContext (UThread *ut)
 Get thread global context.
UBufferur_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 UCellur_wordCell (UThread *ut, const UCell *cell)
 Get word value for read-only operations.
UCellur_wordCellM (UThread *ut, const UCell *cell)
 Get modifiable word value.
int ur_setWord (UThread *ut, const UCell *word, const UCell *src)
 Set word.
const UBufferur_bufferEnv (UThread *ut, UIndex n)
 Get buffer from either the thread or shared environment dataStore.
const UBufferur_bufferSeries (const UThread *ut, const UCell *cell)
 Get series buffer.
UBufferur_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.


Generated on 27 Jan 2012 by Doxygen 1.5.1