API Types

Macros
#define	CROC_VERSION   ((uint32_t)((0 << 16) | (1)))

Typedefs
typedef int64_t	crocint_t
typedef double	crocfloat_t
typedef struct CrocThread	CrocThread
typedef size_t	uword_t
typedef ptrdiff_t	word_t
typedef uint64_t	crocref_t
typedef uint32_t	crocchar_t
typedef word_t(*	CrocNativeFunc )(CrocThread *)
typedef void *(*	CrocMemFunc )(void *ctx, void *p, uword_t oldSize, uword_t newSize)

Enumerations
enum	CrocType {   CrocType_Null, CrocType_Bool, CrocType_Int, CrocType_Float,   CrocType_Nativeobj, CrocType_String, CrocType_Weakref, CrocType_Table,   CrocType_Namespace, CrocType_Array, CrocType_Memblock, CrocType_Function,   CrocType_Funcdef, CrocType_Class, CrocType_Instance, CrocType_Thread }
enum	CrocGCLimit {   CrocGCLimit_NurseryLimit, CrocGCLimit_MetadataLimit, CrocGCLimit_NurserySizeCutoff, CrocGCLimit_CycleCollectInterval,   CrocGCLimit_CycleMetadataLimit }
enum	CrocThreadState {   CrocThreadState_Initial, CrocThreadState_Waiting, CrocThreadState_Running, CrocThreadState_Suspended,   CrocThreadState_Dead }
enum	CrocThreadHook {   CrocThreadHook_Call = 1, CrocThreadHook_TailCall = 2, CrocThreadHook_Ret = 4, CrocThreadHook_Delay = 8,   CrocThreadHook_Line = 16 }
enum	CrocCallRet { CrocCallRet_Error = -1 }
enum	CrocUnsafeLib {   CrocUnsafeLib_None = 0, CrocUnsafeLib_File = 1, CrocUnsafeLib_OS = 2, CrocUnsafeLib_Debug = 4,   CrocUnsafeLib_All = CrocUnsafeLib_File | CrocUnsafeLib_OS, CrocUnsafeLib_ReallyAll = CrocUnsafeLib_All | CrocUnsafeLib_Debug }
enum	CrocAddons {   CrocAddons_None = 0, CrocAddons_Pcre = 1, CrocAddons_Devil = 4, CrocAddons_Net = 8,   CrocAddons_Glfw = 16, CrocAddons_OpenAL = 32, CrocAddons_ImGui = 64, CrocAddons_Safe = CrocAddons_Pcre | CrocAddons_ImGui,   CrocAddons_Unsafe = CrocAddons_Devil | CrocAddons_Net | CrocAddons_Glfw | CrocAddons_OpenAL, CrocAddons_All = CrocAddons_Safe | CrocAddons_Unsafe }
enum	CrocCompilerFlags {   CrocCompilerFlags_None = 0, CrocCompilerFlags_TypeConstraints = 1, CrocCompilerFlags_Asserts = 2, CrocCompilerFlags_Debug = 4,   CrocCompilerFlags_Docs = 8, CrocCompilerFlags_All = CrocCompilerFlags_TypeConstraints | CrocCompilerFlags_Asserts | CrocCompilerFlags_Debug, CrocCompilerFlags_AllDocs = CrocCompilerFlags_All | CrocCompilerFlags_Docs }
enum	CrocCompilerReturn { CrocCompilerReturn_UnexpectedEOF = -1, CrocCompilerReturn_LoneStatement = -2, CrocCompilerReturn_DanglingDoc = -3, CrocCompilerReturn_Error = -4 }
enum	CrocLocation { CrocLocation_Unknown = 0, CrocLocation_Native = -1, CrocLocation_Script = -2 }

Detailed Description

The basic types and enumerations used by the basic API.

Macro Definition Documentation

#define CROC_VERSION   ((uint32_t)((0 << 16) | (1)))

The current version of Croc as a 32-bit integer.

The upper 16 bits are the major, and the lower 16 are the minor.

Typedef Documentation

typedef int64_t crocint_t

The underlying C type used to store the Croc 'int' type, which is equivalent to int64_t.

typedef double crocfloat_t

The underlying C type used to store the Croc 'float' type, which is equivalent to 'double'.

typedef struct CrocThread CrocThread

An opaque type that represents a Croc thread.

This type is used in virtually every public API function.

typedef size_t uword_t

A nicer name for size_t.

typedef ptrdiff_t word_t

A nicer name for ptrdiff_t.

typedef uint64_t crocref_t

The type of native references, a way for native code to keep a Croc object from being collected.

typedef uint32_t crocchar_t

The type of Croc characters, a type big enough to hold any single Unicode codepoint.

typedef word_t(* CrocNativeFunc)(CrocThread *)

A typedef for the type signature of a native function.

Native functions receive the thread to operate on as their only parameter. They then do their work through the thread, and then return an integer indicating how many values it is returning. That many values must be on top of the stack.

typedef void*(* CrocMemFunc)(void *ctx, void *p, uword_t oldSize, uword_t newSize)

The type of the memory allocation function that the Croc library uses to allocate, reallocate, and free memory.

You pass a memory allocation function when you create a VM, and all allocations by the VM go through that function.

The memory function works as follows:

• If a new block is being requested, it will be called with a p of null, an oldSize of 0, and a newSize of the size of the requested block.
• If an existing block is to be resized, it will be called with p being the pointer to the block, an oldSize of the current block size, and a newSize of the new expected size of the block.
• If an existing block is to be deallocated, it will be called with p being the pointer to the block, an oldSize of the current block size, and a newSize of 0.

Parameters

ctx	is the context pointer that was associated with the VM upon creation. This pointer is just passed to the allocation function on every call; Croc doesn't use it.
p	is the pointer that is being operated on. If this is null, an allocation is being requested. Otherwise, either a reallocation or a deallocation is being requested.
oldSize	is the current size of the block pointed to by p. If p is null, this will always be 0.
newSize	is the new size of the block pointed to by p. If p is null, this is the requested size of the new block. Otherwise, if this is 0, a deallocation is being requested. Otherwise, a reallocation is being requested.

Returns

If a deallocation was requested, should return null. Otherwise, should return a non-null pointer. If memory cannot be allocated, the memory allocation function should fail somehow (longjump perhaps), not return null.

Enumeration Type Documentation

enum CrocType

An enumeration of all possible types of Croc values.

These correspond exactly to Croc's types.

Enumerator
CrocType_Null
CrocType_Bool
CrocType_Int
CrocType_Float
CrocType_Nativeobj
CrocType_String
CrocType_Weakref
CrocType_Table
CrocType_Namespace
CrocType_Array
CrocType_Memblock
CrocType_Function
CrocType_Funcdef
CrocType_Class
CrocType_Instance
CrocType_Thread

enum CrocGCLimit

An enumeration of the various limits which control the garbage collector's behavior.

Read about what they mean in the croc_gc_setLimit docs.

Enumerator
CrocGCLimit_NurseryLimit
CrocGCLimit_MetadataLimit
CrocGCLimit_NurserySizeCutoff
CrocGCLimit_CycleCollectInterval
CrocGCLimit_CycleMetadataLimit

enum CrocThreadState

An enumeration of the possible states Croc threads can be in.

Enumerator
CrocThreadState_Initial	Created, but hasn't been called yet.
CrocThreadState_Waiting	Resumed another thread and is waiting for it to yield.
CrocThreadState_Running	Running.
CrocThreadState_Suspended	Yielded.
CrocThreadState_Dead	Returned from the thread's main function.

enum CrocThreadHook

An enumeration of the different kinds of debug hooks.

Enumerator
CrocThreadHook_Call
CrocThreadHook_TailCall
CrocThreadHook_Ret
CrocThreadHook_Delay
CrocThreadHook_Line

enum CrocCallRet

An enumeration of possible return values from the croc_tryCall and croc_tryMethodCall functions.

These values will all be negative to distinguish them from the normal return value (how many values the function returned).

Enumerator
CrocCallRet_Error	Indicates that an exception was thrown.

enum CrocUnsafeLib

An enumeration of the unsafe standard libraries, to be passed to croc_vm_loadUnsafeLibs.

Enumerator
CrocUnsafeLib_None	No unsafe libs.
CrocUnsafeLib_File	The file lib.
CrocUnsafeLib_OS	The os lib.
CrocUnsafeLib_Debug	The debug lib.
CrocUnsafeLib_All	All unsafe libs, except the debug lib.
CrocUnsafeLib_ReallyAll	All unsafe libs plus the debug lib.

enum CrocAddons

An enumeration of the addon libraries.

You have to compile addons into the Croc library in order to be able to use them.

Enumerator
CrocAddons_None	No addon libs.
CrocAddons_Pcre	The pcre lib.
CrocAddons_Devil	The devil lib.
CrocAddons_Net	The net lib.
CrocAddons_Glfw	The glfw lib.
CrocAddons_OpenAL	The openal lib.
CrocAddons_ImGui	The openal lib.
CrocAddons_Safe	The safe addons.
CrocAddons_Unsafe	The unsafe addons.
CrocAddons_All	All addons, safe or not.

enum CrocCompilerFlags

An enumeration of flags which control compiler options, to be passed to croc_compiler_setFlags (and returned from croc_compiler_getFlags).

Enumerator
CrocCompilerFlags_None	No optional features.
CrocCompilerFlags_TypeConstraints	Enables parameter type constraint check codegen.
CrocCompilerFlags_Asserts	Enables assert() codegen.
CrocCompilerFlags_Debug	Enables debug info. Currently can't be disabled.
CrocCompilerFlags_Docs	Enables doc comment parsing and doc decorators.
CrocCompilerFlags_All	All features except doc comments.
CrocCompilerFlags_AllDocs	All features including doc comments.

enum CrocCompilerReturn

An enumeration of error values which the various compiler API functions can return.

These are useful for getting more info about why compilation failed, for writing things like command-line interpreters.

Enumerator
CrocCompilerReturn_UnexpectedEOF	Unexpected end-of-file (end of source).
CrocCompilerReturn_LoneStatement	A statement consisting of an expression which can't stand alone.
CrocCompilerReturn_DanglingDoc	A dangling doc comment at the end of the source.
CrocCompilerReturn_Error	Some other kind of compilation error.

enum CrocLocation

An enumeration of the kinds of runtime locations which can be passed to croc_eh_pushLocationObject.

Enumerator
CrocLocation_Unknown	For when location info could not be determined.
CrocLocation_Native	For when the location is inside a native function.
CrocLocation_Script	For when the location is inside a script function.