boron.h File Reference

The Boron programmer interface. More...

#include "urlan.h"

Go to the source code of this file.

Data Structures
struct	UCellCFuncEval
	Structure of CFUNC a1 argument when boron_defineCFunc() signature is ":eval". More...
struct	UPortDevice
	The UPortDevice struct holds methods for a class of input/ouput device. More...

Macros
#define	CFUNC(name)
	Macro to define C functions.
#define	CFUNC_OPTIONS   a1[-1].id.ext
	Macro to get uint16_t option flags from inside a C function.
#define	boron_evalPos(a1)
	Macro to access :eval function program counter from inside CFUNC.
#define	boron_evalAvail(a1)
	Macro to get the number of cells available for evaluation following UCellCFuncEval::pos inside CFUNC.

Enumerations
enum	UserAccess { UR_ACCESS_DENY , UR_ACCESS_ALLOW , UR_ACCESS_ALWAYS }
enum	PortForm { UR_PORT_SIMPLE , UR_PORT_EXT }

Functions
UEnvParameters *	boron_envParam (UEnvParameters *)
	Initialize UEnvParameters structure to default Boron values.
UThread *	boron_makeEnv (UEnvParameters *)
	Make Boron environment and initial thread.
void	boron_freeEnv (UThread *)
	Destroy Boron environment.
UStatus	boron_defineCFunc (UThread *, UIndex ctxN, const BoronCFunc *funcs, const char *spec, int slen)
	Add C functions to context.
void	boron_addPortDevice (UThread *, const UPortDevice *, UAtom name)
	Register port device.
UBuffer *	boron_makePort (UThread *, const UPortDevice *, void *ext, UCell *res)
	Create port buffer.
void	boron_setAccessFunc (UThread *, int(*func)(UThread *, const char *))
	Set the callback function that will request security access from the user.
UStatus	boron_requestAccess (UThread *, const char *msg,...)
	Request user permission to access a resource.
void	boron_bindDefault (UThread *, UIndex blkN)
	Bind block in thread dataStore to default contexts.
UStatus	boron_load (UThread *, const char *file, UCell *res)
	Load block! from file and give it default bindings.
UCell *	boron_evalUtf8 (UThread *, const char *script, int len)
	Run script and put result in the last stack cell.
UIndex	boron_evalRecurse (UThread *, UCell *res)
	Begin a section where boron_evalBlock() can be recursively called.
void	boron_evalSetTop (UThread *, UIndex top)
	Reset evaluator operation stack position.
int	boron_reframeDoBlock (UThread *, UIndex blkN, UCell *res, int flags)
	Reuse the current CFUNC call frame for a EOP_DO_BLOCK operation.
void	boron_reset (UThread *)
	Reset thread after exception.
UStatus	boron_throwWord (UThread *, UAtom atom, UIndex stackPos)
	Throw named exception.
int	boron_catchWord (UThread *, UAtom atom)
	Check if named exception was thrown.
char *	boron_cstr (UThread *, const UCell *strC, UBuffer *bin)
	Make null terminated UTF-8 string in binary buffer.
char *	boron_cpath (UThread *, const UCell *strC, UBuffer *bin)
	Make null terminated UTF-8 string in binary buffer.
UStatus	boron_badArg (UThread *, UIndex atom, int argN)
	Throw a standardized error for an unexpected function argument.
void	boron_randomSeed (UThread *, uint32_t)
	Seed the thread RNG.
uint32_t	boron_random (UThread *)
	Get the next number from the thread RNG.

Detailed Description

The Boron programmer interface.

Macro Definition Documentation

CFUNC

#define CFUNC

(

name

)

Value:

static UStatus name( UThread* ut, UCell* a1, UCell* res )

Macro to define C functions.

If the function takes multiple arguments, just index off of a1. For instance, the third argument is (a1+2).

Parameters

ut	The ubiquitous thread pointer.
a1	Pointer to argument cells.
res	Pointer to result cell.

Examples

boron_mini.c.

CFUNC_OPTIONS

#define CFUNC_OPTIONS   a1[-1].id.ext

Macro to get uint16_t option flags from inside a C function.

Only use this if options were declared in the boron_defineCFunc() signature.

Enumeration Type Documentation

PortForm

enum PortForm

Enumerator
UR_PORT_SIMPLE	Denotes that UBuffer::ptr is the UPortDevice pointer.
UR_PORT_EXT	Denotes that UBuffer::ptr points to extension data and that the first member is the UPortDevice pointer.

UserAccess

enum UserAccess

Enumerator
UR_ACCESS_DENY	Forbid access to the resource.
UR_ACCESS_ALLOW	Grant access to the resource.
UR_ACCESS_ALWAYS	Grant access to the resource and allow all future requests.

Function Documentation

boron_addPortDevice()

void boron_addPortDevice	(	UThread *	ut,
		const UPortDevice *	dev,
		UAtom	name )

Register port device.

A single device struct may be added multiple times with different names.

Parameters

dev	Pointer to UPortDevice.
name	Name of device.

boron_badArg()

UStatus boron_badArg	(	UThread *	ut,
		UIndex	atom,
		int	argN )

Throw a standardized error for an unexpected function argument.

Parameters

atom	Datatype name.
argN	Zero-based argument number.

Returns

UR_THROW

boron_evalRecurse()

UIndex boron_evalRecurse	(	UThread *	ut,
		UCell *	result )

Begin a section where boron_evalBlock() can be recursively called.

Use boron_evalSetTop() where the recursive section ends.

Returns

Evaluator operation stack position before EOP_RUN_RECURSE is pushed.

boron_evalSetTop()

void boron_evalSetTop	(	UThread *	ut,
		UIndex	top )

Reset evaluator operation stack position.

Parameters

top	New evaluator operation stack position.

boron_evalUtf8()

UCell * boron_evalUtf8	(	UThread *	ut,
		const char *	script,
		int	len )

Run script and put result in the last stack cell.

To preserve the last value the caller must push a new value on top (e.g. boron_stackPush(ut, UT_UNSET)).

If an exception occurs, the thrown value is at the bottom of the stack (use the ur_exception macro).

Returns

Result on stack or NULL if an exception is thrown.

Examples

boron_mini.c.

boron_makePort()

UBuffer * boron_makePort	(	UThread *	ut,
		const UPortDevice *	pdev,
		void *	ext,
		UCell *	res )

Create port buffer.

Parameters

pdev	Device pointer.
ext	Pointer to port extension data or zero.
res	Result port cell.

Returns

UBuffer with type, form, and ptr initialized.

This is usually called from inside a UPortDevice::open method.

The UBuffer::type is set to UT_PORT.

If ext is zero then the UBuffer::form is set to UR_PORT_SIMPLE and the UBuffer::ptr member is set to pdev. If ext is non-zero then the form is set to UR_PORT_EXT, ptr is set to ext, and pdev is copied to the start of ext.

boron_reframeDoBlock()

int boron_reframeDoBlock	(	UThread *	ut,
		UIndex	blkN,
		UCell *	res,
		int	flags )

Reuse the current CFUNC call frame for a EOP_DO_BLOCK operation.

This should be called as the final statement inside a BoronCFunc to immediately do the specified block.

Parameters

res	Address for result. May be NULL to discard result.
flags	May be zero or FUNC_FLAG_NOTRACE.

Returns

CFUNC_REFRAMED.