/* Boron Developer Manual (Doxygen format) */

/**
\mainpage Boron Developer Manual

\section intro_sec Introduction
 
Boron is an interpreted scripting language built with the
Urlan datatype system.

This manual is a reference to help programmers develop their own
domain languages or extend Boron with their own types and functions.

\subsection start_sec Getting Started

Study the \ref urlan_core and the <a href="examples.html">examples</a>.

\section store_sec Data Stores

The primary structures are an environment and a thread, each of which contains
a data store.  Both structures are created with boron_makeEnv().
Each data store is an array of UBuffer structs.

The environment data store holds static data which can be accessed by any
thread.  It is created once with ur_freezeEnv() and buffer pointers are obtained
with ur_bufferEnv().

The thread data store (UThread::dataStore) is garbage collected.
Buffers are added by ur_genBuffers() and buffer pointers are obtained with
ur_buffer() or ur_bufferEnv().  There are a number of type-specific functions,
such as ur_makeContext() and ur_makeString(), that call ur_genBuffers()
internally.

Garbage collection occurs when ur_genBuffers() cannot find free buffers in
the dataStore or when ur_recycle() is called.

\note
When the dataStore expands, the memory location of all it's buffers will move.
Therefore, any UBuffer pointers must be considered invalid after any new
buffers are created.


\file unset.h
This header provides stubs for custom UDatatype methods.
If your datatype does not implement certain methods, then use these.


\file urlan_atoms.h
This header provides fixed atoms which are always present.


\example calculator.c
This example shows how to use the Urlan library to implement a simple
calculator language.


\example boron_mini.c
This is a basic example of how to use the Boron interpreter.


\defgroup urlan Urlan Datatype System
The Urlan Datatype System.

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


\file urlan.h
\ingroup urlan
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.


\union UCell
\ingroup urlan_core
A cell holds a single value of a simple type or a reference (often to a
UBuffer) for a complex type.
It will always be 16 bytes.
Normally cells are contained in block UBuffers.

\var UCell::id
Basic type identification.

\var UCell::datatype
For datatype! type.

\var UCell::word
For word!, lit-word!, set-word!, get-word! types.

\var UCell::number
For int!, double! types.

\var UCell::coord
For coord! type.

\var UCell::vec3
For vec3! type.

\var UCell::series
For binary!, bitset!, string!, file!, block!, paren!, path! types.

\var UCell::context
For context! type.

\var UCell::port
For port! type.

\var UCell::error
For error! type.


\struct UCellId
Basic type identification.
This represents the first 32 bits of a UCell and is typically initialized
with ur_setId().

\var UCellId::type
::UrlanDataType.

\var UCellId::flags
Bit field for type-specific properties.
The only flag defined for all datatypes is ::UR_FLAG_SOL.

\var UCellId::ext
Extra datatype specific field.

\def UR_FLAG_INT_HEX
This UCellId::flags bit indicates that an UR_INT value is printed as hexidecimal.

\def UR_FLAG_SOL
This UCellId::flags bit indicates that the cell starts a new line of code.


\struct UCellDatatype
UCell structure for datatype! type.

\var UCellDatatype::n
The ::UrlanDataType.  It will be UrlanDataType::UT_TYPEMASK if multiple mask
bits are set.
This is normally accessed with the #ur_datatype() macro.

\var UCellDatatype::mask0
Low 32 bits of type mask.

\var UCellDatatype::mask1
Middle 32 bits of type mask.


\struct UCellWord
UCell structure for word types.

\var UCellWord::type
::UrlanDataType.

\var UCellWord::flags
Bit field for type-specific properties.

\var UCellWord::binding
Specifies what ::UrlanWordBindings the UCellWord::ctx refers to.

\var UCellWord::_pad0
Padding.

\var UCellWord::ctx
Normally the buffer id of a context.

\var UCellWord::index
Normally the word index into a context.

\var UCellWord::atom
The name of the word.


\struct UCellNumber
UCell structure for number types.

\var UCellNumber::id
Type and flags.

\var UCellNumber::i64
Integer for char! and int! types.
This should be accessed with the #ur_char() or #ur_int() macros.

\var UCellNumber::d
Double for double!, date!, and time! type.
This should be accessed with the #ur_double() macro.


\struct UCellCoord
UCell structure for coord type.

\var UCellCoord::type
UrlanDataType.

\var UCellCoord::flags
Bit field for type-specific properties.

\var UCellCoord::len
Number of integers used in array \b n.
This will aways be between 2 and 6 for the \c coord! type.

\var UCellCoord::n
Holds six, 16-bit integers.


\struct UCellVec3
UCell structure for vec3! type.

\var UCellVec3::id
The standard UCell header.

\var UCellVec3::xyz
The three float values.


\struct UCellSeries
UCell structure for series types.

\var UCellSeries::id
Type and flags.

\var UCellSeries::buf
Buffer id.

\var UCellSeries::it
Iterator index.

\var UCellSeries::end
Slice end index.  This will be -1 if no slice end is set.


\struct UCellError
UCell structure for error! type.

\var UCellError::exType
The ::UrlanErrorType.

\var UCellError::messageStr
Index of message string! buffer.

\var UCellError::traceBlk
Index of block! buffer where error occurred.


\struct UBuffer urlan.h
\ingroup urlan_core
The UBuffer struct holds information about a resource, usually a chunk of
memory.

\var UBuffer::type
::UrlanDataType identifier.

\var UBuffer::elemSize
This typically holds the byte size of each element.

\var UBuffer::form
This can indicate a specific form of the data (such as a string encoding).

\var UBuffer::flags
Indicates special features of the buffer (#UR_STATIC, #UR_STRING_ENC_UP).

\var UBuffer::used
This typically holds the number of elements in the buffer.

\var UBuffer::ptr
This typically holds a pointer to a chunk of memory.

\def UR_STATIC
This UBuffer::flags bit is set when the UBuffer::ptr points to memory
outside of the Urlan datatype system and must not be freed.  It indicates
that the UBuffer::used member should not be modifed and that the #ur_avail
& #ur_testAvail macros must not be used on the buffer.

\def ur_avail
Returns the capacity of a UBuffer that is known to have been allocated.
This macro is quicker than #ur_testAvail, but must not be used when the
UBuffer::ptr is NULL.

\def ur_testAvail
Returns the capacity of a UBuffer.  Unlike #ur_avail, this can be safely
used even when the buffer memory has not been allocated.


\struct UThread
\ingroup urlan_core
The UThread struct stores the data specific to a thread of execution.
Note that it does not actually contain anything specific to evaluation;
it just holds buffers of data.

\var UThread::dataStore
An array of buffers.

\var UThread::holds
An array of buffer ids which will not be garbage collected.

\var UThread::gcBits
Used by ur_recycle() to denote buffers which are in use.

\var UThread::freeBufCount
Number of unused buffers.

\var UThread::freeBufList
Buffer index of an unused buffer.

\var UThread::env
Pointer to the shared environment.

\var UThread::types
Pointer to the datatypes.

\var UThread::wordCell
Method to get cell referenced by word for user-defined bindings.

\var UThread::wordCellM
Method to get modifiable cell referenced by word for user-defined bindings.


\struct UEnvParameters urlan.h
\ingroup urlan_core
The UEnvParameters struct allows the user to override default buffer
and structure sizes.

This is initialized with the ur_envParam() or boron_envParam() functions.


\fn void (*UEnvParameters::threadMethod)(UThread*, enum UThreadMethod)
Function to handle initialization and cleanup of user data attached to
threads.
*/
