Module Ocamlua

module Ocamlua: sig .. end

type lua_state 

An opaque datatype representing the underlying Lua state

type lua_value = 

type lua_table = (lua_value * lua_value) list 

An associative list corresponding to a Lua table. As in Lua, keys may be any valid value. In the case of duplicate keys, the last key in the list "wins".

type lua_closure = lua_value -> lua_value 

The type of a callback from Lua code to Ocaml code

val init_state : unit -> lua_state

Creates a new Ocamlua.lua_state. Each state created by this function is completely indepedent from one another: any side effects or operations in one state are not visible to any other state created by this function.

Some important implementation notes that may affect how you use the returned state: when you pass an Ocaml closure into Lua code as an argument to Ocamlua.call a reference to the passed closure is saved in a hash associated with the Lua state. This hash is not released until the Lua state itself is released, so be aware that if you pass in several distinct closures you may experience a stress on memory.

val load_file : lua_state -> string -> unit

load_file state fname loads the Lua source code contained in the file fname and immediately evaluates it. If the loaded code returns a value it is silently discarded.
Raises

• Ocamlua.No_such_file if fname can not be loaded by the Lua runtime
• Ocamlua.Syntax_error if the code contained in fname is not syntatically valid Lua code
• Ocamlua.Internal_error if during the execution of the code loaded from fname an internal error occurs
• Ocamlua.Runtime_error if during the execution of the code loaded from fname a runtime error occurs

val call : lua_state -> string -> lua_value list -> lua_value

call state f args calls the function accessible via the global name f in the state state with the (possibly zero) arguments args. The return value of this function is the value returned by f. If f returns more than 1 value they are silently discarded, if it returns 0 values then `Lua_Nil is returned.
Raises

• Ocamlua.Runtime_error if a Lua error is generated during the execution of f or an OCaml callbaack raises an exception (see Ocamlua.Runtime_error for details)
• Ocamlua.No_such_method if f does not exist in the global environment associated with state
• Ocamlua.Internal_error if a Lua internal error occurs
• Ocamlua.Bad_value if f returns a value that cannot be represented by the Ocamlua.lua_value type.

val eval_string : lua_state -> string -> unit

eval_string state code immediately loads and executes the Lua code in the string code in the context of state. Any side effects or actions taken during the execution of code will not be visible to any other states. It is not possible to change the environment of the loaded chunk. If the loaded chunk returns a value it is silently discarded.
Raises

• Ocamlua.Syntax_error if the Lua code in code is not syntatically valid
• Ocamlua.Runtime_error if a runtime error occurs during the execution of the loaded chunk
• Ocamlua.Internal_error if a Lua internal error occurs during the evaluation of the string

val table_of_list : lua_value list -> lua_value

Coverts a list Lua values into a Lua vector (with indices starting from 1).

val list_of_table : lua_table -> lua_value list

Converts a table of size n with keys 1, 2, ... n+1 into a list of Lua values. If the keys are of a non-numeric type or the keys do not have the expected order will throw a Failure exception.

type internal_error_code = 

Types of exceptional conditions that may occur during the execution of the Lua runtime

exception No_such_method of string

Raised by Ocamlua.call if the method to call does not exist. The string argument is the name of the function that does

exception Syntax_error of string

Raised by Ocamlua.eval_string and Ocamlua.load_file if the Lua source code being loaded has a syntax error. The string is the error reported by the Lua runtime

exception Runtime_error of string

Raised if a runtime error occurs during the execution of Lua code. This includes runtime errors generated by the Lua runtime (arithmetic errors, no such method, etc.) and errors generated via the error function. Exceptions thrown inside of an Ocaml callback are converted into a Lua error with the error string "Exception in ocaml callback" and if not caught, may propagate to the top level and become a Runtime_error (in this case the original exception information is lost).

exception Internal_error of internal_error_code

Thrown when more "exotic" errors are thrown by the Lua runtime. It is expected that these errors will be more uncommon and as such the various error conditions are represented by tag of the Ocamlua.internal_error_code argument.

exception Bad_value

Thrown when an error occurs converting a Lua value into an Ocaml representation to return to the calling code (note that the opposite can never happen, all values allowed by the Ocamlua.lua_value type can be represented as Lua values, up to the practical limits of the system). There are two ways a converion may fail: when the conversion of a value of an inconvertible type is attempted (e.g. a coroutine thread, arbitrary userdata, etc.) or when in the process of converting a table recurion is detected.

This exception is only thrown when a coversion error occurs when converting a value to return back into OCaml code. When conversion fails when attempting to call back into Ocaml code, the conversion error is converted into a Lua error, with the string "Bad arguments to ocaml callback".

exception No_such_file of string

Thrown by Ocamlua.load_file when the Lua cannot load code from the given file.