Boron 0.2.8
Data Structures | Macros | Enumerations | Enumerator | Functions
Core Programmer Interface

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...
 

Macros

#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. More...
 
UThreadur_makeThread (const UThread *ut)
 Create new thread. More...
 
int ur_destroyThread (UThread *ut)
 Remove UThread from environment thread list and free memory. More...
 
UThreadur_makeEnv (int atomLimit, const UDatatype **dtTable, unsigned int dtCount, unsigned int thrSize, void(*thrMethod)(UThread *, UThreadMethod))
 Allocate UEnv and initial UThread. More...
 
void ur_freeEnv (UThread *ut)
 Free environment and all threads. More...
 
void ur_freezeEnv (UThread *ut)
 Move the startup thread dataStore to the shared environment. More...
 
int ur_datatypeCount (UThread *ut)
 Get number of datatypes installed in the environment. More...
 
UAtom ur_internAtom (UThread *ut, const char *it, const char *end)
 Add a single atom to the shared environment. More...
 
UAtom * ur_internAtoms (UThread *ut, const char *words, UAtom *atoms)
 Add atoms to the shared environment. More...
 
void ur_genBuffers (UThread *ut, int count, UIndex *index)
 Generate new buffers in dataStore. More...
 
void ur_destroyBuffer (UThread *ut, UBuffer *buf)
 Destroy buffer in dataStore. More...
 
UIndex ur_holdBuffer (UThread *ut, UIndex bufN)
 Keeps buffer in thread dataStore from being garbage collected by ur_recycle(). More...
 
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. More...
 
UBufferur_threadContext (UThread *ut)
 Get thread global context. More...
 
UBufferur_envContext (UThread *ut)
 Get shared global context. More...
 
int ur_error (UThread *ut, int errorType, const char *fmt,...)
 Append error! to the error block. More...
 
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. More...
 
int ur_isTrue (const UCell *cell)
 
int ur_same (UThread *ut, const UCell *a, const UCell *b)
 
int ur_equal (UThread *ut, const UCell *a, const UCell *b)
 
int ur_equalCase (UThread *ut, const UCell *a, const UCell *b)
 Case-sensitive equality test. More...
 
int ur_compare (UThread *ut, const UCell *a, const UCell *b)
 
int ur_compareCase (UThread *ut, const UCell *a, const UCell *b)
 Case-sensitive ordering comparison. More...
 
void ur_toStr (UThread *ut, const UCell *cell, UBuffer *str, int depth)
 Append data representation of cell to a string. More...
 
void ur_toText (UThread *ut, const UCell *cell, UBuffer *str)
 Append textual representation of cell to a string. More...
 
const UCellur_wordCell (UThread *ut, const UCell *cell)
 Get word value for read-only operations. More...
 
UCellur_wordCellM (UThread *ut, const UCell *cell)
 Get modifiable word value. More...
 
int ur_setWord (UThread *ut, const UCell *word, const UCell *src)
 Set word. More...
 
const UBufferur_bufferEnv (UThread *ut, UIndex n)
 Get buffer from either the thread or shared environment dataStore. More...
 
const UBufferur_bufferSeries (const UThread *ut, const UCell *cell)
 Get series buffer. More...
 
UBufferur_bufferSeriesM (UThread *ut, const UCell *cell)
 Get modifiable series buffer. More...
 
void ur_seriesSlice (const UThread *ut, USeriesIter *si, const UCell *cell)
 Set USeriesIter to series slice. More...
 
int ur_seriesSliceM (UThread *ut, USeriesIterM *si, const UCell *cell)
 Set USeriesIterM to modifiable series slice. More...
 
UIndex ur_tokenize (UThread *ut, const char *it, const char *end, UCell *res)
 Convert a UTF-8 data string into a block. More...
 

Detailed Description

Enumeration Type Documentation

Indentifers for the built-in datatypes.

These values match the datatype name atom.

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.

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
blkNBlock id.
itPosition in block blkN.
const char* ur_atomCStr ( UThread ut,
UAtom  atom 
)

Get name of atom.

Parameters
atomValid 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
nBuffer 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
cellPointer 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
cellPointer 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_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.

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
bufPointer 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
utThread 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_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.

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
errorTypeUrlanErrorType (UR_ERR_TYPE, UR_ERR_SCRIPT, etc.).
fmtError message with printf() style formatting.
Returns
UR_THROW
See Also
ur_errorBlock
UBuffer* ur_errorBlock ( UThread ut)

Get thread error block.

Returns
Pointer to block of errors.
void ur_freeEnv ( UThread ut)

Free environment and all threads.

Caller must make sure no other threads are running.

Parameters
utUThread created with ur_makeEnv(). It is safe to pass zero.
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
utUThread 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
countNumber of buffers to obtain.
indexReturn 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
itStart of word.
endEnd of word.
Returns
Atom of word or UR_INVALID_ATOM if an error was generated.
UAtom* ur_internAtoms ( UThread ut,
const char *  words,
UAtom *  atoms 
)

Add atoms to the shared environment.

Parameters
wordsC string containing words separated by whitespace.
atomsReturn area for atoms of the words.
Returns
Pointer marking the end of the entries set in atoms.
int ur_isTrue ( const UCell cell)
Returns
Non-zero if cell is not none! or false.
UThread* ur_makeEnv ( int  atomLimit,
const UDatatype **  dtTable,
unsigned int  dtCount,
unsigned int  thrSize,
void(*)(UThread *, UThreadMethod thrMethod 
)

Allocate UEnv and initial UThread.

Parameters
atomLimitMaximum number of atoms. Memory usage is (24 * atomLimit) bytes.
dtTableArray of pointers to user defined datatypes. Pass zero if dtCount is zero.
dtCountNumber of datatypes in dtTable.
thrSizeByte size of each thread in the environment. Pass zero if no extra memory is needed.
thrMethodCallback function to initialize and cleanup threads. This may be zero.
Returns
Pointer to initial thread.
UThread* ur_makeThread ( const UThread ut)

Create new thread.

Parameters
utExisting thread.
Returns
Pointer to new thread in the same environment as ut.
int ur_same ( UThread ut,
const UCell a,
const UCell b 
)
Returns
Non-zero if values are the same.
void ur_seriesSlice ( const UThread ut,
USeriesIter *  si,
const UCell cell 
)

Set USeriesIter to series slice.

Parameters
siIterator struct to fill.
cellPointer to a valid series cell.
int ur_seriesSliceM ( UThread ut,
USeriesIterM *  si,
const UCell cell 
)

Set USeriesIterM to modifiable series slice.

Parameters
siIterator struct to fill.
cellPointer 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
wordWord to set.
srcSource value to copy.
Returns
UR_OK/UR_THROW
UBuffer* ur_threadContext ( UThread ut)

Get thread global context.

Returns
Pointer to thread global context.
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
itStart of string.
endEnd of string.
resCell 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.
void ur_toStr ( UThread ut,
const UCell cell,
UBuffer str,
int  depth 
)

Append data representation of cell to a string.

Parameters
strString to add to.
void ur_toText ( UThread ut,
const UCell cell,
UBuffer str 
)

Append textual representation of cell to a string.

Parameters
strString to add to.
const UCell* ur_wordCell ( UThread ut,
const UCell cell 
)

Get word value for read-only operations.

Parameters
cellPointer 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.
UCell* ur_wordCellM ( UThread ut,
const UCell cell 
)

Get modifiable word value.

Parameters
cellPointer 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.

Generated on Wed Oct 16 2013 by Doxygen 1.8.3.1