ChaiScript
Classes | Public Member Functions | List of all members
chaiscript::ChaiScript_Basic Class Reference

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

#include <chaiscript_engine.hpp>

Inheritance diagram for chaiscript::ChaiScript_Basic:
chaiscript::ChaiScript

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_Baseget_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_Basicadd_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_Basicadd_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_Basicset_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_Valueget_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_Basicadd (const T &t_t, const std::string &t_name)
 Adds a type, function or object to ChaiScript. More...
 
ChaiScript_Basicadd (const Type_Conversion &d)
 Add a new conversion for upcasting to a base class. More...
 
ChaiScript_Basicadd (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 >
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 >
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_libStandard library to apply to this ChaiScript instance
[in]t_modulepathsVector of paths to search when attempting to load a binary module
[in]t_usepathsVector 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_modulepathsVector of paths to search when attempting to load a binary module
[in]t_usepathsVector 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_tItem to add
[in]t_nameName of item to add
Returns
Reference to current ChaiScript object

Examples:

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]dBase class / parent class

Example:

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_pThe 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_bvBoxed_Value to add as a global
[in]t_nameName 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_bvBoxed_Value to add as a global
[in]t_nameName of the value to add
Exceptions
chaiscript::exception::global_non_constIf 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
TType to extract from the result value of the script execution
Parameters
[in]t_inputScript to execute
[in]t_handlerOptional Exception_Handler used for automatic unboxing of script thrown exceptions
[in]t_filenameOptional 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_errorIn the case that evaluation fails.
chaiscript::exception::bad_boxed_castIn 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_inputScript to execute
[in]t_handlerOptional Exception_Handler used for automatic unboxing of script thrown exceptions
[in]t_filenameOptional 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_errorIn 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_filenameFile to load and parse.
[in]t_handlerOptional Exception_Handler used for automatic unboxing of script thrown exceptions
Returns
result of the script execution
Exceptions
chaiscript::exception::eval_errorIn 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
TType to extract from the result value of the script execution
Parameters
[in]t_filenameFile to load and parse.
[in]t_handlerOptional Exception_Handler used for automatic unboxing of script thrown exceptions
Returns
result of the script execution
Exceptions
chaiscript::exception::eval_errorIn the case that evaluation fails.
chaiscript::exception::bad_boxed_castIn 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::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_nameName of the namespace to import.
Exceptions
std::runtime_errorIn 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_nameName 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_errorIn 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_nameModule name to load
[in]t_filenameIgnore 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_scriptScript to execute
[in]t_handlerOptional Exception_Handler used for automatic unboxing of script thrown exceptions
Returns
result of the script execution
Exceptions
chaiscript::exception::eval_errorIn 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_generatorNamespace generator function.
[in]t_namespace_nameName of the Namespace function being registered.
Exceptions
std::runtime_errorIn 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_localsThe 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_stateNew state to set

Example:

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, it is not reloaded The use paths specified at ChaiScript construction time are searched for the requested file.

Parameters
[in]t_filenameFilename to load and evaluate

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