Common tasks

Functions
word_t	croc_ex_lookup (CrocThread *t, const char *name)
word_t	croc_ex_pushRegistryVar (CrocThread *t, const char *name)
void	croc_ex_setRegistryVar (CrocThread *t, const char *name)
word_t	croc_ex_throwNamedException (CrocThread *t, const char *exName, const char *fmt,...)
word_t	croc_ex_vthrowNamedException (CrocThread *t, const char *exName, const char *fmt, va_list args)
word_t	croc_ex_CFileToNativeStream (CrocThread *t, FILE *f, const char *mode)
int	croc_ex_isHaltException (CrocThread *t, word_t index)

Detailed Description

Miscellaneous useful stuff.

Function Documentation

word_t croc_ex_lookup	(	CrocThread *	t,
		const char *	name
	)

Given a dotted name, looks up the value given by that name and pushes it onto the stack.

This is to alleviate tedious repeated calls to croc_field to access a chain of fields. For example, if you want to call the doctools.console.help Croc stdlib function, you can do it like so:

croc_ex_lookup(t, "doctools.console.help");
croc_pushNull(t);
croc_pushGlobal(t, "math");
croc_call(t, -3, 0); // prints out the help for the math module to the console

The name must be properly formatted – it can't be empty, and none of the components between periods can be empty.

Returns

the stack index of the pushed value.

word_t croc_ex_pushRegistryVar	(	CrocThread *	t,
		const char *	name
	)

Pushes the value of the field named name from the registry.

Since the registry is a namespace, this will throw an exception if no field of that name exists in the registry.

Returns

the stack index of the pushed value.

void croc_ex_setRegistryVar	(	CrocThread *	t,
		const char *	name
	)

Expects one value on top of the stack, and assigns it to the field named name in the registry.

Pops the value.

word_t croc_ex_throwNamedException	(	CrocThread *	t,
		const char *	exName,
		const char *	fmt,
			...
	)

Very similar to croc_eh_throwStd, except instead of being limited to the standard exception types, you can throw any exception type given by exName.

This uses croc_ex_lookup to look up exName, so you can use a dotted name here too.

Returns

a dummy value like croc_eh_throw.

word_t croc_ex_vthrowNamedException	(	CrocThread *	t,
		const char *	exName,
		const char *	fmt,
		va_list	args
	)

Same as croc_ex_throwNamedException, but takes a va_list instead of variadic arguments.

Returns

a dummy value like croc_eh_throw.

word_t croc_ex_CFileToNativeStream	(	CrocThread *	t,
		FILE *	f,
		const char *	mode
	)

Given a C stdio FILE*, creates a new Croc stream.NativeStream instance which will read from or write to that FILE*, and pushes that instance.

Parameters

f	is the FILE* to wrap. It will be flushed before creating the instance. Do not use this FILE* at the same time Croc is using it! The NativeStream uses an unbuffered, lower-level OS interface to access the underlying file, and C's stdio functions can make weird things happen because of buffering.
mode	will be passed as the mode parameter to the NativeStream constructor. This is a string which defines what script code can do with it: if the character 'r' is in the string, the stream will be readable; 'w' makes it writable; 's' makes it seekable; and 'c' makes it closable.

Returns

the stack index of the pushed value.

int croc_ex_isHaltException	(	CrocThread *	t,
		word_t	index
	)

Returns

nonzero if the value in slot index is an instance of the HaltException standard exception type. You shouldn't really catch halt exceptions, so if you use croc_tryCall or croc_tryMethodCall and they caught an exception, you should test if it was a halt exception and rethrow it if so.