ChaiScript
Namespaces | Classes | Typedefs | Enumerations | Functions | Variables
chaiscript Namespace Reference

Namespace chaiscript contains every API call that the average user will be concerned with. More...

Namespaces

 bootstrap
 Classes and functions useful for bootstrapping of ChaiScript and adding of new types.
 
 detail
 Classes and functions reserved for internal use.
 
 dispatch
 Classes and functions specific to the runtime dispatch side of ChaiScript.
 
 eval
 Classes and functions that are part of the runtime eval system.
 
 exception
 Classes which may be thrown during error cases when ChaiScript is executing.
 
 parser
 Classes and functions used during the parsing process.
 

Classes

struct  AST_Node
 Struct that doubles as both a parser ast_node and an AST node. More...
 
struct  AST_Node_Trace
 
class  Boxed_Number
 Represents any numeric type, generically. Used internally for generic operations between POD values. More...
 
class  Boxed_Value
 A wrapper for holding any valid C++ type. More...
 
struct  Build_Info
 
class  ChaiScript
 
class  ChaiScript_Basic
 The main object that the ChaiScript user will use. More...
 
struct  ChaiScript_Prelude
 
struct  File_Position
 Convenience type for file positions. More...
 
class  Function_Params
 
struct  is_nothrow_forward_constructible
 
class  json_wrap
 
class  Module
 Holds a collection of ChaiScript settings which can be applied to the ChaiScript runtime. More...
 
struct  Name_Validator
 
struct  Operators
 
struct  Parse_Location
 
class  Std_Lib
 
struct  str_equal
 
struct  str_less
 
class  Type_Conversions
 
class  Type_Conversions_State
 
class  Type_Info
 Compile time deduced information about a type. More...
 

Typedefs

using ModulePtr = std::shared_ptr< Module >
 Convenience typedef for Module objects to be added to the ChaiScript runtime.
 
using Exception_Handler = std::shared_ptr< detail::Exception_Handler_Base >
 Used in the automatic unboxing of exceptions thrown during script evaluation. More...
 
using AST_NodePtr = std::unique_ptr< AST_Node >
 Typedef for pointers to AST_Node objects. Used in building of the AST_Node tree.
 
using Proxy_Function = std::shared_ptr< dispatch::Proxy_Function_Base >
 Common typedef used for passing of any registered function in ChaiScript.
 
using Const_Proxy_Function = std::shared_ptr< const dispatch::Proxy_Function_Base >
 Const version of Proxy_Function. More...
 
using Type_Conversion = std::shared_ptr< chaiscript::detail::Type_Conversion_Base >
 
using Create_Module_Func) = ModulePtr(*)(
 Signature of module entry point that all binary loadable modules must implement.
 
using AST_NodePtr_Const = std::unique_ptr< const AST_Node >
 
using Namespace = dispatch::Dynamic_Object
 Namespace alias to provide cleaner and more explicit syntax to users.
 

Enumerations

enum  Options { No_Load_Modules, Load_Modules, No_External_Scripts, External_Scripts }
 
enum  AST_Node_Type {
  Id, Fun_Call, Unused_Return_Fun_Call, Arg_List,
  Equation, Var_Decl, Assign_Decl, Array_Call,
  Dot_Access, Lambda, Block, Scopeless_Block,
  Def, While, If, For,
  Ranged_For, Inline_Array, Inline_Map, Return,
  File, Prefix, Break, Continue,
  Map_Pair, Value_Range, Inline_Range, Try,
  Catch, Finally, Method, Attr_Decl,
  Logical_And, Logical_Or, Reference, Switch,
  Case, Default, Noop, Class,
  Binary, Arg, Global_Decl, Constant,
  Compiled
}
 Types of AST nodes available to the parser and eval.
 
enum  Operator_Precedence {
  Ternary_Cond, Logical_Or, Logical_And, Bitwise_Or,
  Bitwise_Xor, Bitwise_And, Equality, Comparison,
  Shift, Addition, Multiplication, Prefix
}
 

Functions

template<typename B , typename D , typename ... Arg>
std::shared_ptr< Bmake_shared (Arg &&... arg)
 
template<typename B , typename D , typename ... Arg>
std::unique_ptr< Bmake_unique (Arg &&... arg)
 
template<typename T >
constexpr auto parse_num (const std::string_view t_str) noexcept -> typename std::enable_if< std::is_integral< T >::value, T >::type
 
template<typename T >
auto parse_num (const std::string_view t_str) -> typename std::enable_if<!std::is_integral< T >::value, T >::type
 
template<typename Container , typename ... T>
constexpr auto make_container (T &&... t)
 
template<typename ... T>
auto make_vector (T &&... t)
 
template<typename Type >
decltype(auto) boxed_cast (const Boxed_Value &bv, const Type_Conversions_State *t_conversions=nullptr)
 Function for extracting a value stored in a Boxed_Value object. More...
 
template<typename T >
Boxed_Value var (T &&t)
 Creates a Boxed_Value. More...
 
template<typename T >
Boxed_Value const_var (const T &t)
 Takes an object and returns an immutable Boxed_Value. More...
 
Boxed_Value void_var ()
 
Boxed_Value const_var (bool b)
 
template<typename ... T>
Exception_Handler exception_specification ()
 creates a chaiscript::Exception_Handler which handles one type of exception unboxing More...
 
template<typename T >
Proxy_Function constructor ()
 Generates a constructor function for use with ChaiScript. More...
 
template<typename T >
Proxy_Function fun (T &&t)
 Creates a new Proxy_Function object from a free function, member function or data member. More...
 
template<typename T , typename Q >
Proxy_Function fun (T &&t, const Q &q)
 Creates a new Proxy_Function object from a free function, member function or data member and binds the first parameter of it. More...
 
template<typename Base , typename Derived >
Type_Conversion base_class ()
 Used to register a to / parent class relationship with ChaiScript. More...
 
template<typename Callable >
Type_Conversion type_conversion (const Type_Info &t_from, const Type_Info &t_to, const Callable &t_func)
 
template<typename From , typename To , typename Callable >
Type_Conversion type_conversion (const Callable &t_function)
 
template<typename From , typename To >
Type_Conversion type_conversion ()
 
template<typename To >
Type_Conversion vector_conversion ()
 
template<typename To >
Type_Conversion map_conversion ()
 
template<typename T >
constexpr Type_Info user_type (const T &) noexcept
 Creates a Type_Info object representing the type passed in. More...
 
template<typename T >
constexpr Type_Info user_type () noexcept
 Creates a Type_Info object representing the templated type. More...
 

Variables

template<class From , class To >
constexpr bool is_nothrow_forward_constructible_v = is_nothrow_forward_constructible<From, To>::value
 

Detailed Description

Namespace chaiscript contains every API call that the average user will be concerned with.

Typedef Documentation

§ Const_Proxy_Function

using chaiscript::Const_Proxy_Function = typedef std::shared_ptr<const dispatch::Proxy_Function_Base>

Const version of Proxy_Function.

Points to a const Proxy_Function. This is how most registered functions are handled internally.

§ Exception_Handler

Used in the automatic unboxing of exceptions thrown during script evaluation.

Exception specifications allow the user to tell ChaiScript what possible exceptions are expected from the script being executed. Exception_Handler objects are created with the chaiscript::exception_specification() function.

Example:

try {
chai.eval("throw(runtime_error(\"error\"))", chaiscript::exception_specification<int, double, float, const std::string &, const std::exception &>());
} catch (const double e) {
} catch (int) {
} catch (float) {
} catch (const std::string &) {
} catch (const std::exception &e) {
// This is the one what will be called in the specific throw() above
}

It is recommended that if catching the generic std::exception& type that you specifically catch the chaiscript::exception::eval_error type, so that there is no confusion.

try {
chai.eval("throw(runtime_error(\"error\"))", chaiscript::exception_specification<const std::exception &>());
// Error in script parsing / execution
} catch (const std::exception &e) {
// Error explicitly thrown from script
}

Similarly, if you are using the ChaiScript::eval form that unboxes the return value, then chaiscript::exception::bad_boxed_cast should be handled as well.

try {
chai.eval<int>("1.0", chaiscript::exception_specification<const std::exception &>());
// Error in script parsing / execution
// Error unboxing return value
} catch (const std::exception &e) {
// Error explicitly thrown from script
}
See also
chaiscript::exception_specification for creation of chaiscript::Exception_Handler objects
Exception Handling

Function Documentation

§ base_class()

template<typename Base , typename Derived >
Type_Conversion chaiscript::base_class ( )

Used to register a to / parent class relationship with ChaiScript.

Necessary if you want automatic conversions up your inheritance hierarchy.

Create a new to class registration for applying to a module or to the ChaiScript engine Currently, due to limitations in module loading on Windows, and for the sake of portability, if you have a type that is introduced in a loadable module and is used by multiple modules (through a tertiary dll that is shared between the modules, static linking the new type into both loadable modules would not be portable), you need to register the type relationship in all modules that use the newly added type in a polymorphic way.

Example:

class Base
{};
class Derived : public Base
{};
chai.add(chaiscript::to_class<Base, Derived>());

§ boxed_cast()

template<typename Type >
decltype(auto) chaiscript::boxed_cast ( const Boxed_Value bv,
const Type_Conversions_State t_conversions = nullptr 
)

Function for extracting a value stored in a Boxed_Value object.

Template Parameters
TypeThe type to extract from the Boxed_Value
Parameters
[in]bvThe Boxed_Value to extract a typed value from
Returns
Type equivalent to the requested type
Exceptions
exception::bad_boxed_castIf the requested conversion is not possible

boxed_cast will attempt to make conversions between value, &, *, std::shared_ptr, std::reference_wrapper, and std::function (const and non-const) where possible. boxed_cast is used internally during function dispatch. This means that all of these conversions will be attempted automatically for you during ChaiScript function calls.

  • non-const values can be extracted as const or non-const
  • const values can be extracted only as const
  • Boxed_Value constructed from pointer or std::reference_wrapper can be extracted as reference, pointer or value types
  • Boxed_Value constructed from std::shared_ptr or value types can be extracted as reference, pointer, value, or std::shared_ptr types

Conversions to std::function objects are attempted as well

Example:

// All of the following should succeed
std::shared_ptr<int> spi = chaiscript::boxed_cast<std::shared_ptr<int> >(bv);
int i = chaiscript::boxed_cast<int>(bv);
int *ip = chaiscript::boxed_cast<int *>(bv);
int &ir = chaiscript::boxed_cast<int &>(bv);
std::shared_ptr<const int> cspi = chaiscript::boxed_cast<std::shared_ptr<const int> >(bv);
const int ci = chaiscript::boxed_cast<const int>(bv);
const int *cip = chaiscript::boxed_cast<const int *>(bv);
const int &cir = chaiscript::boxed_cast<const int &>(bv);

std::function conversion example

Boxed_Value bv = chai.eval("`+`"); // Get the functor for the + operator which is built in
std::function<int (int, int)> f = chaiscript::boxed_cast<std::function<int (int, int)> >(bv);
int i = f(2,3);
assert(i == 5);

§ const_var()

template<typename T >
Boxed_Value chaiscript::const_var ( const T &  t)

Takes an object and returns an immutable Boxed_Value.

If the object is a std::reference or pointer type the value is not copied. If it is an object type, it is copied.

Parameters
[in]tObject to make immutable
Returns
Immutable Boxed_Value
See also
chaiscript::Boxed_Value::is_const
chaiscript::var

Example:

enum Colors
{
Blue,
Green,
Red
};
chai.add(chaiscript::const_var(Blue), "Blue"); // add immutable constant
chai.add(chaiscript::const_var(Red), "Red");
chai.add(chaiscript::const_var(Green), "Green");
Todo:
support C++11 strongly typed enums
See also
Adding Objects

§ constructor()

template<typename T >
Proxy_Function chaiscript::constructor ( )

Generates a constructor function for use with ChaiScript.

Template Parameters
TThe signature of the constructor to generate. In the form of: ClassType (ParamType1, ParamType2, ...)

Example:

// Create a new function that creates a MyClass object using the (int, float) constructor
// and call that function "MyClass" so that it appears as a normal constructor to the user.
chai.add(constructor<MyClass (int, float)>(), "MyClass");

§ exception_specification()

template<typename ... T>
Exception_Handler chaiscript::exception_specification ( )

creates a chaiscript::Exception_Handler which handles one type of exception unboxing

See also
Exception Handling

§ fun() [1/2]

template<typename T >
Proxy_Function chaiscript::fun ( T &&  t)

Creates a new Proxy_Function object from a free function, member function or data member.

Parameters
[in]tFunction / member to expose

Example:

int myfunction(const std::string &);
class MyClass
{
public:
void memberfunction();
int memberdata;
};
chai.add(fun(&myfunction), "myfunction");
chai.add(fun(&MyClass::memberfunction), "memberfunction");
chai.add(fun(&MyClass::memberdata), "memberdata");
See also
Adding Functions

§ fun() [2/2]

template<typename T , typename Q >
Proxy_Function chaiscript::fun ( T &&  t,
const Q &  q 
)

Creates a new Proxy_Function object from a free function, member function or data member and binds the first parameter of it.

Parameters
[in]tFunction / member to expose
[in]qValue to bind to first parameter

Example:

struct MyClass
{
void memberfunction(int);
};
MyClass obj;
// Add function taking only one argument, an int, and permanently bound to "obj"
chai.add(fun(&MyClass::memberfunction, std::ref(obj)), "memberfunction");
See also
Adding Functions

§ user_type() [1/2]

template<typename T >
constexpr Type_Info chaiscript::user_type ( const T &  )
noexcept

Creates a Type_Info object representing the type passed in.

Template Parameters
TType of object to get a Type_Info for, derived from the passed in parameter
Returns
Type_Info for T

Example:

§ user_type() [2/2]

template<typename T >
constexpr Type_Info chaiscript::user_type ( )
noexcept

Creates a Type_Info object representing the templated type.

Template Parameters
TType of object to get a Type_Info for
Returns
Type_Info for T

Example:

chaiscript::Type_Info ti = chaiscript::user_type<int>();

§ var()

template<typename T >
Boxed_Value chaiscript::var ( T &&  t)

Creates a Boxed_Value.

If the object passed in is a value type, it is copied. If it is a pointer, std::shared_ptr, or std::reference_type a copy is not made.

Parameters
tThe value to box

Example:

int i;
chai.add(chaiscript::var(i), "i");
chai.add(chaiscript::var(&i), "ip");
See also
Adding Objects