The main object that the ChaiScript user will use. More...

#include <chaiscript_engine.hpp>

Inheritance diagram for chaiscript::ChaiScript_Basic:

Classes
struct	State
	Represents the current state of the ChaiScript system. More...

Public Member Functions
	ChaiScript_Basic (const ModulePtr &t_lib, std::unique_ptr< parser::ChaiScript_Parser_Base > &&parser, std::vector< std::string > t_module_paths={}, std::vector< std::string > t_use_paths={}, const std::vector< chaiscript::Options > &t_opts=chaiscript::default_options())
	Constructor for ChaiScript. More...

	ChaiScript_Basic (std::unique_ptr< parser::ChaiScript_Parser_Base > &&parser, std::vector< std::string > t_module_paths={}, std::vector< std::string > t_use_paths={}, const std::vector< chaiscript::Options > &t_opts=chaiscript::default_options())
	Constructor for ChaiScript. More...

parser::ChaiScript_Parser_Base &	get_parser () noexcept

const Boxed_Value	eval (const AST_Node &t_ast)

AST_NodePtr	parse (const std::string &t_input, const bool t_debug_print=false)

std::string	get_type_name (const Type_Info &ti) const

template<typename T >
std::string	get_type_name () const

Boxed_Value	use (const std::string &t_filename)
	Loads and parses a file. More...

ChaiScript_Basic &	add_global_const (const Boxed_Value &t_bv, const std::string &t_name)
	Adds a constant object that is available in all contexts and to all threads. More...

ChaiScript_Basic &	add_global (const Boxed_Value &t_bv, const std::string &t_name)
	Adds a mutable object that is available in all contexts and to all threads. More...

ChaiScript_Basic &	set_global (const Boxed_Value &t_bv, const std::string &t_name)

State	get_state () const
	Returns a state object that represents the current state of the global system. More...

void	set_state (const State &t_state)
	Sets the state of the system. More...

std::map< std::string, Boxed_Value >	get_locals () const

void	set_locals (const std::map< std::string, Boxed_Value > &t_locals)
	Sets all of the locals for the current thread state. More...

template<typename T >
ChaiScript_Basic &	add (const T &t_t, const std::string &t_name)
	Adds a type, function or object to ChaiScript. More...

ChaiScript_Basic &	add (const Type_Conversion &d)
	Add a new conversion for upcasting to a base class. More...

ChaiScript_Basic &	add (const ModulePtr &t_p)
	Adds all elements of a module to ChaiScript runtime. More...

std::string	load_module (const std::string &t_module_name)
	Load a binary module from a dynamic library. More...

void	load_module (const std::string &t_module_name, const std::string &t_filename)
	Load a binary module from a dynamic library. More...

Boxed_Value	operator() (const std::string &t_script, const Exception_Handler &t_handler=Exception_Handler())
	Evaluates a string. More...

template<typename T >
T	eval (const std::string &t_input, const Exception_Handler &t_handler=Exception_Handler(), const std::string &t_filename="__EVAL__")
	Evaluates a string and returns a typesafe result. More...

template<typename Type >
decltype(auto)	boxed_cast (const Boxed_Value &bv) const
	casts an object while applying any Dynamic_Conversion available

Boxed_Value	eval (const std::string &t_input, const Exception_Handler &t_handler=Exception_Handler(), const std::string &t_filename="__EVAL__")
	Evaluates a string. More...

Boxed_Value	eval_file (const std::string &t_filename, const Exception_Handler &t_handler=Exception_Handler())
	Loads the file specified by filename, evaluates it, and returns the result. More...

template<typename T >
T	eval_file (const std::string &t_filename, const Exception_Handler &t_handler=Exception_Handler())
	Loads the file specified by filename, evaluates it, and returns the type safe result. More...

void	import (const std::string &t_namespace_name)
	Imports a namespace object into the global scope of this ChaiScript instance. More...

void	register_namespace (const std::function< void(Namespace &)> &t_namespace_generator, const std::string &t_namespace_name)
	Registers a namespace generator, which delays generation of the namespace until it is imported, saving memory if it is never used. More...

Detailed Description

The main object that the ChaiScript user will use.

Constructor & Destructor Documentation

◆ ChaiScript_Basic() [1/2]

chaiscript::ChaiScript_Basic::ChaiScript_Basic	(	const ModulePtr &	t_lib,
		std::unique_ptr< parser::ChaiScript_Parser_Base > &&	parser,
		std::vector< std::string >	t_module_paths = `{}`,
		std::vector< std::string >	t_use_paths = `{}`,
		const std::vector< chaiscript::Options > &	t_opts = `chaiscript::default_options()`
	)

inline

Constructor for ChaiScript.

Parameters

[in]	t_lib	Standard library to apply to this ChaiScript instance
[in]	t_modulepaths	Vector of paths to search when attempting to load a binary module
[in]	t_usepaths	Vector of paths to search when attempting to "use" an included ChaiScript file

◆ ChaiScript_Basic() [2/2]

chaiscript::ChaiScript_Basic::ChaiScript_Basic	(	std::unique_ptr< parser::ChaiScript_Parser_Base > &&	parser,
		std::vector< std::string >	t_module_paths = `{}`,
		std::vector< std::string >	t_use_paths = `{}`,
		const std::vector< chaiscript::Options > &	t_opts = `chaiscript::default_options()`
	)

inlineexplicit

Constructor for ChaiScript.

This version of the ChaiScript constructor attempts to find the stdlib module to load at runtime generates an error if it cannot be found.

Parameters

[in]	t_modulepaths	Vector of paths to search when attempting to load a binary module
[in]	t_usepaths	Vector of paths to search when attempting to "use" an included ChaiScript file

Member Function Documentation

◆ add() [1/3]

template<typename T >

ChaiScript_Basic& chaiscript::ChaiScript_Basic::add	(	const T &	t_t,
		const std::string &	t_name
	)

inline

Adds a type, function or object to ChaiScript.

Objects are added to the local thread state.

Parameters

[in]	t_t	Item to add
[in]	t_name	Name of item to add

Returns: Reference to current ChaiScript object

Examples:

chaiscript::ChaiScript chai;
chai.add(chaiscript::user_type<MyClass>(), "MyClass"); // Add explicit type info (not strictly necessary)
chai.add(chaiscript::fun(&MyClass::function), "function"); // Add a class method
MyClass obj;
chai.add(chaiscript::var(&obj), "obj"); // Add a pointer to a locally defined object

See also: Adding Items to ChaiScript

◆ add() [2/3]

ChaiScript_Basic& chaiscript::ChaiScript_Basic::add ( const Type_Conversion & d )

inline

Add a new conversion for upcasting to a base class.

See also: chaiscript::base_class

Parameters

[in] d Base class / parent class

Example:

chaiscript::ChaiScript chai;

chai.add(chaiscript::base_class<std::runtime_error, chaiscript::dispatch_error>());

◆ add() [3/3]

ChaiScript_Basic& chaiscript::ChaiScript_Basic::add ( const ModulePtr & t_p )

inline

Adds all elements of a module to ChaiScript runtime.

Parameters

[in] t_p The module to add.

See also: chaiscript::Module

◆ add_global()

ChaiScript_Basic& chaiscript::ChaiScript_Basic::add_global	(	const Boxed_Value &	t_bv,
		const std::string &	t_name
	)

inline

Adds a mutable object that is available in all contexts and to all threads.

Parameters

[in]	t_bv	Boxed_Value to add as a global
[in]	t_name	Name of the value to add

Warning: The user is responsible for making sure the object is thread-safe if necessary ChaiScript is thread-safe but provides no threading locking mechanism to the script

◆ add_global_const()

ChaiScript_Basic& chaiscript::ChaiScript_Basic::add_global_const	(	const Boxed_Value &	t_bv,
		const std::string &	t_name
	)

inline

Adds a constant object that is available in all contexts and to all threads.

Parameters

[in]	t_bv	Boxed_Value to add as a global
[in]	t_name	Name of the value to add

Exceptions

chaiscript::exception::global_non_const If t_bv is not a constant object

See also: Boxed_Value::is_const

◆ eval() [1/2]

template<typename T >

T chaiscript::ChaiScript_Basic::eval	(	const std::string &	t_input,
		const Exception_Handler &	t_handler = `Exception_Handler()`,
		const std::string &	t_filename = `"__EVAL__"`
	)

inline

Evaluates a string and returns a typesafe result.

Template Parameters

T	Type to extract from the result value of the script execution

Parameters

[in]	t_input	Script to execute
[in]	t_handler	Optional Exception_Handler used for automatic unboxing of script thrown exceptions
[in]	t_filename	Optional filename to report to the user for where the error occured. Useful in special cases where you are loading a file internally instead of using eval_file

Returns: result of the script execution

Exceptions

chaiscript::exception::eval_error	In the case that evaluation fails.
chaiscript::exception::bad_boxed_cast	In the case that evaluation succeeds but the result value cannot be converted to the requested type.

◆ eval() [2/2]

Boxed_Value chaiscript::ChaiScript_Basic::eval	(	const std::string &	t_input,
		const Exception_Handler &	t_handler = `Exception_Handler()`,
		const std::string &	t_filename = `"__EVAL__"`
	)

inline

Evaluates a string.

Parameters

[in]	t_input	Script to execute
[in]	t_handler	Optional Exception_Handler used for automatic unboxing of script thrown exceptions
[in]	t_filename	Optional filename to report to the user for where the error occurred. Useful in special cases where you are loading a file internally instead of using eval_file

Returns: result of the script execution

Exceptions

exception::eval_error In the case that evaluation fails.

◆ eval_file() [1/2]

Boxed_Value chaiscript::ChaiScript_Basic::eval_file	(	const std::string &	t_filename,
		const Exception_Handler &	t_handler = `Exception_Handler()`
	)

inline

Loads the file specified by filename, evaluates it, and returns the result.

Parameters

[in]	t_filename	File to load and parse.
[in]	t_handler	Optional Exception_Handler used for automatic unboxing of script thrown exceptions

Returns: result of the script execution

Exceptions

chaiscript::exception::eval_error In the case that evaluation fails.

◆ eval_file() [2/2]

template<typename T >

T chaiscript::ChaiScript_Basic::eval_file	(	const std::string &	t_filename,
		const Exception_Handler &	t_handler = `Exception_Handler()`
	)

inline

Loads the file specified by filename, evaluates it, and returns the type safe result.

Template Parameters

T	Type to extract from the result value of the script execution

Parameters

[in]	t_filename	File to load and parse.
[in]	t_handler	Optional Exception_Handler used for automatic unboxing of script thrown exceptions

Returns: result of the script execution

Exceptions

chaiscript::exception::eval_error	In the case that evaluation fails.
chaiscript::exception::bad_boxed_cast	In the case that evaluation succeeds but the result value cannot be converted to the requested type.

◆ get_locals()

std::map<std::string, Boxed_Value> chaiscript::ChaiScript_Basic::get_locals ( ) const

inline

Returns: All values in the local thread state, added through the add() function

◆ get_state()

State chaiscript::ChaiScript_Basic::get_state ( ) const

inline

Returns a state object that represents the current state of the global system.

The global system includes the reserved words, global const objects, functions and types. local variables are thread specific and not included.

Returns: Current state of the global system

Example:

chaiscript::ChaiScript chai;

chaiscript::ChaiScript::State s = chai.get_state(); // represents bootstrapped initial state

◆ import()

void chaiscript::ChaiScript_Basic::import ( const std::string & t_namespace_name )

inline

Imports a namespace object into the global scope of this ChaiScript instance.

Parameters

[in] t_namespace_name Name of the namespace to import.

Exceptions

std::runtime_error In the case that the namespace name was never registered.

◆ load_module() [1/2]

std::string chaiscript::ChaiScript_Basic::load_module ( const std::string & t_module_name )

inline

Load a binary module from a dynamic library.

Works on platforms that support dynamic libraries.

Parameters

[in] t_module_name Name of the module to load

The module is searched for in the registered module path folders (chaiscript::ChaiScript::ChaiScript) and with standard prefixes and postfixes: ("lib"|"")<t_module_name>(".dll"|".so"|".bundle"|"").

Once the file is located, the system looks for the symbol "create_chaiscript_module_\<t_module_name\>". If no file can be found matching the search criteria and containing the appropriate entry point (the symbol mentioned above), an exception is thrown.

Exceptions

chaiscript::exception::load_module_error In the event that no matching module can be found.

◆ load_module() [2/2]

void chaiscript::ChaiScript_Basic::load_module	(	const std::string &	t_module_name,
		const std::string &	t_filename
	)

inline

Load a binary module from a dynamic library.

Works on platforms that support dynamic libraries.

Parameters

[in]	t_module_name	Module name to load
[in]	t_filename	Ignore normal filename search process and use specific filename

See also: ChaiScript::load_module(const std::string &t_module_name)

◆ operator()()

Boxed_Value chaiscript::ChaiScript_Basic::operator()	(	const std::string &	t_script,
		const Exception_Handler &	t_handler = `Exception_Handler()`
	)

inline

Evaluates a string.

Equivalent to ChaiScript::eval.

Parameters

[in]	t_script	Script to execute
[in]	t_handler	Optional Exception_Handler used for automatic unboxing of script thrown exceptions

Returns: result of the script execution

Exceptions

chaiscript::exception::eval_error In the case that evaluation fails.

◆ register_namespace()

void chaiscript::ChaiScript_Basic::register_namespace	(	const std::function< void(Namespace &)> &	t_namespace_generator,
		const std::string &	t_namespace_name
	)

inline

Registers a namespace generator, which delays generation of the namespace until it is imported, saving memory if it is never used.

Parameters

[in]	t_namespace_generator	Namespace generator function.
[in]	t_namespace_name	Name of the Namespace function being registered.

Exceptions

std::runtime_error In the case that the namespace name was already registered.

◆ set_locals()

void chaiscript::ChaiScript_Basic::set_locals ( const std::map< std::string, Boxed_Value > & t_locals )

inline

Sets all of the locals for the current thread state.

Parameters

[in] t_locals The map<name, value> set of variables to replace the current state with

Any existing locals are removed and the given set of variables is added

◆ set_state()

void chaiscript::ChaiScript_Basic::set_state ( const State & t_state )

inline

Sets the state of the system.

The global system includes the reserved words, global objects, functions and types. local variables are thread specific and not included.

Parameters

[in] t_state New state to set

Example:

chaiscript::ChaiScript chai;
chaiscript::ChaiScript::State s = chai.get_state(); // get initial state
chai.add(chaiscript::fun(&somefunction), "somefunction");
chai.set_state(s); // restore initial state, which does not have the recently added "somefunction"

◆ use()

Boxed_Value chaiscript::ChaiScript_Basic::use ( const std::string & t_filename )

inline

Loads and parses a file.

If the file is already open, it is not reloaded. The use paths specified at ChaiScript construction time are searched for the requested file.

Parameters

[in] t_filename Filename to load and evaluate

The documentation for this class was generated from the following file:

include/chaiscript/language/chaiscript_engine.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ChaiScript_Basic() [1/2]

◆ ChaiScript_Basic() [2/2]

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ add_global()

◆ add_global_const()

◆ eval() [1/2]

◆ eval() [2/2]

◆ eval_file() [1/2]

◆ eval_file() [2/2]

◆ get_locals()

◆ get_state()

◆ import()

◆ load_module() [1/2]

◆ load_module() [2/2]

◆ operator()()

◆ register_namespace()

◆ set_locals()

◆ set_state()

◆ use()