Macros
#define	croc_compiler_compileModuleEx(t, name, modName)

#define	croc_compiler_compileStmtsEx(t, name)

#define	croc_compiler_compileExprEx(t, name)

#define	croc_compiler_compileModuleDTEx(t, name, modName)

#define	croc_compiler_compileStmtsDTEx(t, name)

Functions
uword_t	croc_compiler_setFlags (CrocThread *t, uword_t flags)

uword_t	croc_compiler_getFlags (CrocThread *t)

int	croc_compiler_compileModule (CrocThread t, const char name, const char **modName)

int	croc_compiler_compileStmts (CrocThread t, const char name)

int	croc_compiler_compileExpr (CrocThread t, const char name)

int	croc_compiler_compileModuleDT (CrocThread t, const char name, const char **modName)

int	croc_compiler_compileStmtsDT (CrocThread t, const char name)

word_t	croc_compiler_processDocComment (CrocThread *t)

word_t	croc_compiler_parseDocCommentText (CrocThread *t)

Detailed Description

The interface to the Croc compiler.

Macro Definition Documentation

#define croc_compiler_compileModuleEx	(	t,
		name,
		modName
	)

Value:

do {\
		CrocThread* _compilerThread_ = (t);\
        if(croc_compiler_compileModule(_compilerThread_, (name), (modName)) < 0)\
			croc_eh_throw(_compilerThread_);\
    } while(0)

Like croc_compiler_compileModule, but if compilation failed, rethrows the exception.

Also returns nothing.

#define croc_compiler_compileStmtsEx	(	t,
		name
	)

Value:

do {\
		CrocThread* _compilerThread_ = (t);\
        if(croc_compiler_compileStmts(_compilerThread_, (name)) < 0)\
			croc_eh_throw(_compilerThread_);\
    } while(0)

Like croc_compiler_compileStmts, but if compilation failed, rethrows the exception.

Also returns nothing.

#define croc_compiler_compileExprEx	(	t,
		name
	)

Value:

do {\
		CrocThread* _compilerThread_ = (t);\
        if(croc_compiler_compileExpr(_compilerThread_, (name)) < 0)\
			croc_eh_throw(_compilerThread_);\
    } while(0)

Like croc_compiler_compileExpr, but if compilation failed, rethrows the exception.

Also returns nothing.

#define croc_compiler_compileModuleDTEx	(	t,
		name,
		modName
	)

Value:

do {\
		CrocThread* _compilerThread_ = (t);\
        if(croc_compiler_compileModuleDT(_compilerThread_, (name), (modName)) < 0)\
			croc_eh_throw(_compilerThread_);\
    } while(0)

Like croc_compiler_compileModuleDT, but if compilation failed, rethrows the exception.

Also returns nothing.

#define croc_compiler_compileStmtsDTEx	(	t,
		name
	)

Value:

do {\
		CrocThread* _compilerThread_ = (t);\
        if(croc_compiler_compileStmtsDT(_compilerThread_, (name)) < 0)\
			croc_eh_throw(_compilerThread_);\
    } while(0)

Like croc_compiler_compileStmtsDT, but if compilation failed, rethrows the exception.

Also returns nothing.

Function Documentation

uword_t croc_compiler_setFlags	(	CrocThread *	t,
		uword_t	flags
	)

Enable and disable VM-wide compiler flags.

These control whether or not code is generated for various optional language features.

Parameters

flags

must be an or-ing together of the members of the CrocCompilerFlags enum. The flags are as follows:

CrocCompilerFlags_TypeConstraints enables code generation for parameter type constraints. If you leave out this flag, no parameter typechecking is done when calling functions.
CrocCompilerFlags_Asserts enables code generation for assert() statements. If you leave out this flag, assert statements become no-ops.
CrocCompilerFlags_Debug enables outputting debug info (which includes line numbers, local variable info, and upvalue names). If you leave out this flag, no debug info will be emitted, saving space at the cost of worse error messages/tracebacks. This flag does not yet work properly. Debug info is always on.
CrocCompilerFlags_Docs will cause the compiler to parse documentation comments and place doc decorators on the program items they document, meaning run-time accessible documentation will be available. If you leave out this flag, doc comments are ignored (unless you use one of the DT compilation functions below).
CrocCompilerFlags_All enables all features except runtime docs. This is the default setting.
CrocCompilerFlags_AllDocs enables all optional features.

Returns: the previous value of the compiler flags. This is so you can set the flags, compile something, then put the flags back the way they were, like so:

int oldFlags;

oldFlags = croc_compiler_setFlags(t, CrocCompilerFlags_AllDocs);

// compile some code here...

croc_compiler_setFlags(t, oldFlags); // restore them

uword_t croc_compiler_getFlags ( CrocThread * t )

Returns: the current VM-wide compiler flags as described in croc_compiler_setFlags.

int croc_compiler_compileModule	(	CrocThread *	t,
		const char *	name,
		const char **	modName
	)

Compiles the module whose source is a string on top of the stack.

The top slot will be replaced with the result of compilation.

Parameters

	name	is the filename that will be used in locations such as compilation errors and debug info.
[out]	modName	is required, and will be assigned a string which is the name of the module as given in the module's `'module'` statement. You can use this to see if the module name matches the name it was imported as.

Returns

different things depending on whether compilation was successful or not.

If it was successful, returns a positive stack slot of the resulting function definition, which will have replaced the source code on top of the stack.

If it failed, returns one of the CrocCompilerReturn values explaining why compilation failed. In this case, the source on top of the stack will be replaced with an exception object which you can then rethrow if you want to.

If you don't care about handling compilation failure, use croc_compiler_compileModuleEx instead.

int croc_compiler_compileStmts	(	CrocThread *	t,
		const char *	name
	)

Very similar to croc_compiler_compileModule, but the source will be parsed as a list of statements without a 'module' statement at the beginning.

There is no modName parameter as a result.

If you don't care about handling compilation failure, use croc_compiler_compileStmtsEx instead.

int croc_compiler_compileExpr	(	CrocThread *	t,
		const char *	name
	)

Compiles a single Croc expression as a string on top of the stack into a funcdef which takes variadic arguments and returns the result of evaluating that expression.

Just like with the other compilation functions, the source stack slot is replaced by either the funcdef on success or the exception object on failure.

If you don't care about handling compilation failure, use croc_compiler_compileExprEx instead.

int croc_compiler_compileModuleDT	(	CrocThread *	t,
		const char *	name,
		const char **	modName
	)

Similar to croc_compiler_compileModule, but additionally extracts the module's top-level documentation table as described in the spec.

When you use this function, doc comments are parsed and turned into doctables, regardless of whether the compiler's CrocCompilerFlags_Docs flag is enabled. The CrocCompilerFlags_Docs compiler flag only controls whether or not runtime doc decorators are attached to program items.

Returns: a positive number if compilation succeeded. In this case, there will be two items on top of the stack: the module's funcdef on top, and the doc table below it. In case of failure, there will only be one value, the exception object, just like croc_compiler_compileModule.

If you don't care about handling compilation failure, use croc_compiler_compileModuleDTEx instead.

int croc_compiler_compileStmtsDT	(	CrocThread *	t,
		const char *	name
	)

Just like croc_compiler_compileStmts, but extracts the top-level documentation table like croc_compiler_compileModuleDT, leaving it on the stack under the funcdef the same way.

If you don't care about handling compilation failure, use croc_compiler_compileStmtsDTEx instead.

word_t croc_compiler_processDocComment ( CrocThread * t )

This is a low-level interface to the documentation comment parser.

It expects two values on top of the stack: the doc comment text as a string on top, and a doctable below it which only has the members "file", "line", "kind", and "name" filled in. It will parse the doc comment, filling in the other fields of the doctable. The comment source will then be popped, leaving just the doctable on top of the stack.

Returns: the stack index of the doctable.

word_t croc_compiler_parseDocCommentText ( CrocThread * t )

Expects a string on top of the stack which will be parsed into a doc comment paragraph list.

This doesn't actually parse a whole doc comment like croc_compiler_processDocComment does, so section commands are not allowed, but span and structure commands are.

The source slot will be replaced by the resulting paragraph list (an array as described in the doc comment spec).

Returns: the stack index of the result.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation