Boron Interpreter

The Boron Interpreter. More...

Files
file	boron.h
	The Boron programmer interface.

Functions
void	boron_reset (UThread *ut)
	Reset thread after exception.
char *	boron_cstr (UThread *ut, const UCell *strC, UBuffer *bin)
	Make null terminated UTF-8 string in binary buffer.
char *	boron_cpath (UThread *ut, const UCell *strC, UBuffer *bin)
	Make null terminated UTF-8 string in binary buffer.
UStatus	boron_throwWord (UThread *ut, UAtom atom, UIndex stackPos)
	Throw named exception.
int	boron_catchWord (UThread *ut, UAtom atom)
	Check if named exception was thrown.
UStatus	boron_defineCFunc (UThread *ut, UIndex ctxN, const BoronCFunc *funcTable, const char *spec, int slen)
	Add C functions to context.
UEnvParameters *	boron_envParam (UEnvParameters *par)
	Initialize UEnvParameters structure to default Boron values.
UThread *	boron_makeEnv (UEnvParameters *par)
	Make Boron environment and initial thread.
void	boron_freeEnv (UThread *ut)
	Destroy Boron environment.
UStatus	boron_load (UThread *ut, const char *file, UCell *res)
	Load block! from file and give it default bindings.
void	boron_setAccessFunc (UThread *ut, int(*func)(UThread *, const char *))
	Set the callback function that will request security access from the user.
UStatus	boron_requestAccess (UThread *ut, const char *msg,...)
	Request user permission to access a resource.
void	boron_randomSeed (UThread *ut, uint32_t seed)
	Seed the thread RNG.
uint32_t	boron_random (UThread *ut)
	Get the next number from the thread RNG.

Detailed Description

The Boron Interpreter.

Function Documentation

boron_catchWord()

int boron_catchWord	(	UThread *	ut,
		UAtom	atom )

Check if named exception was thrown.

Parameters

atom	Exception name.

Returns

Non-zero if the thrown exception is the named word.

boron_cpath()

char * boron_cpath	(	UThread *	ut,
		const UCell *	strC,
		UBuffer *	bin )

Make null terminated UTF-8 string in binary buffer.

Any trailing slash or backslash is removed.

Parameters

strC	Valid UT_STRING or UT_FILE cell.
bin	Binary buffer to use. If zero, then the temporary thread binary will be used.

Returns

Pointer to C string in bin.

boron_cstr()

char * boron_cstr	(	UThread *	ut,
		const UCell *	strC,
		UBuffer *	bin )

Make null terminated UTF-8 string in binary buffer.

Parameters

strC	Valid UT_STRING or UT_FILE cell.
bin	Binary buffer to use. If zero, then the temporary thread binary will be used.

Returns

Pointer to C string in bin.

boron_defineCFunc()

UStatus boron_defineCFunc	(	UThread *	ut,
		UIndex	ctxN,
		const BoronCFunc *	funcTable,
		const char *	spec,
		int	slen )

Add C functions to context.

C Function Rules:

• Arguments are in a held block; they are safe from garbage collection.
• Result is part of a held block; it is safe from garbage collection.
• Result will never be the same as any of the arguments.
• Must return UR_OK, UR_THROW or CFUNC_REFRAMED.

Parameters

ctxN	Context to add UT_CFUNC values to.
funcs	Table of BoronCFunc pointers.
spec	Function specifications starting with name, one function per line.
slen	Specification string length.

boron_freeEnv()

void boron_freeEnv

(

UThread *

ut

)

Destroy Boron environment.

Parameters

ut	Initial thread created by boron_makeEnvP().

boron_load()

UStatus boron_load	(	UThread *	ut,
		const char *	file,
		UCell *	res )

Load block! from file and give it default bindings.

Parameters

file	UTF-8 filename of Boron script or serialized data.
res	The result cell for the new block value.

Returns

UR_OK/UR_THROW.

boron_makeEnv()

UThread * boron_makeEnv

(

UEnvParameters *

par

)

Make Boron environment and initial thread.

Parameters

par	Environment parameters initialized with boron_envParam().

boron_random()

uint32_t boron_random

(

UThread *

ut

)

Get the next number from the thread RNG.

Returns

Value from 0 to 0xffffffff.

boron_requestAccess()

UStatus boron_requestAccess	(	UThread *	ut,
		const char *	msg,
			... )

Request user permission to access a resource.

Parameters

msg	Printf style format string.

Returns

UR_OK/UR_THROW.

See also

boron_setAccessFunc()

boron_reset()

void boron_reset

(

UThread *

ut

)

Reset thread after exception.

Clears all stacks and exceptions.

boron_setAccessFunc()

void boron_setAccessFunc	(	UThread *	ut,
		int(*	func )(UThread *, const char *) )

Set the callback function that will request security access from the user.

If this function is not set then boron_requestAccess() will always return UR_OK.

Parameters

func	Callback function that must return a UserAccess value.

See also

boron_requestAccess(), UserAccess

boron_throwWord()

UStatus boron_throwWord	(	UThread *	ut,
		UAtom	atom,
		UIndex	stackPos )

Throw named exception.

Parameters

atom	Exception name.
stackPos	If not zero, set word binding to UR_BIND_STACK.

Returns

UR_THROW