C++ API documentation is complete. ChaiScript keyword and language documentation about 75% complete (mostly ported from website.)
This commit is contained in:
Jason Turner
parent
f1918f147d
commit
8a0ef143c9
@ -25,6 +25,147 @@
|
||||
/// \sa http://www.chaiscript.com
|
||||
/// \sa http://www.github.com/ChaiScript/ChaiScript
|
||||
|
||||
/// \page LangObjectSystemRef ChaiScript Language Object Model Reference
|
||||
///
|
||||
///
|
||||
/// ChaiScript supports has an object system built in, for types defined within the ChaiScript system.
|
||||
///
|
||||
/// \code
|
||||
/// attr Rectangle::height
|
||||
/// attr Rectangle::width
|
||||
/// def Rectangle::Rectangle() { this.height = 10; this.width = 20 }
|
||||
/// def Rectangle::area() { this.height * this.width }
|
||||
///
|
||||
/// var rect = Rectangle()
|
||||
/// rect.height = 30
|
||||
/// print(rect.area())
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref keywordattr
|
||||
/// \sa \ref keyworddef
|
||||
|
||||
|
||||
/// \page LangKeywordRef ChaiScript Language Keyword Reference
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordattr attr
|
||||
/// Defines a ChaiScript object attribute
|
||||
///
|
||||
/// \code
|
||||
/// Attribute Definition ::= "attr" class_name "::" attribute_name
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref LangObjectSystemRef
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordbreak break
|
||||
/// Stops execution of a looping block.
|
||||
///
|
||||
/// \code
|
||||
/// Break Statement ::= "break"
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref keywordfor
|
||||
/// \sa \ref keywordwhile
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keyworddef def
|
||||
/// Begins a function or method definition
|
||||
///
|
||||
/// \code
|
||||
/// Function Definition ::= [annotation + CR/LF] "def" identifier "(" [arg ("," arg)*] ")" [":" guard] block
|
||||
/// Method Definition ::= [annotation + CR/LF] "def" class_name "::" method_name "(" [arg ("," arg)*] ")" [":" guard] block
|
||||
/// \endcode
|
||||
///
|
||||
/// annotation: meta-annotation on function, currently used as documentation. Optional.
|
||||
/// identifier: name of function. Required.
|
||||
/// args: comma-delimited list of parameter names. Optional.
|
||||
/// guards: guarding statement that act as a prerequisite for the function. Optional.
|
||||
/// { }: scoped block as function body. Required.
|
||||
///
|
||||
/// Functions return values in one of two ways:
|
||||
///
|
||||
/// By using an explicit return call, optionally passing the value to be returned.
|
||||
/// By implicitly returning the value of the last expression (if it is not a while or for loop).
|
||||
///
|
||||
/// Method definitions for known types extend those types with new methods. This includes C++ and ChaiScript defined types.
|
||||
/// Method definitions for unknown types implicitly define the named type.
|
||||
///
|
||||
/// \sa \ref LangObjectSystemRef
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordelse else
|
||||
/// \sa \ref keywordif
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordfor for
|
||||
/// \code
|
||||
/// For Block ::= "for" "(" [initial] ";" stop_condition ";" loop_expression ")" block
|
||||
/// \endcode
|
||||
/// This loop can be broken using the \ref keywordbreak command.
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordfun fun
|
||||
/// Begins an anonymous function declaration (sometimes called a lambda).
|
||||
///
|
||||
/// \code
|
||||
/// Lambda ::= "fun" "(" [variable] ("," variable)* ")" block
|
||||
/// \endcode
|
||||
///
|
||||
/// \b Examples:
|
||||
///
|
||||
/// \code
|
||||
/// // Generate an anonymous function object that adds 2 to its parameter
|
||||
/// var f = fun(x) { x + 2; }
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref keyworddef for more details on ChaiScript functions
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordif if
|
||||
/// Begins a conditional block of code that only executes if the condition evaluates as true.
|
||||
/// \code
|
||||
/// If Block ::= "if" "(" condition ")" block
|
||||
/// Else If Block ::= "else if" "(" condition ")" block
|
||||
/// Else Block ::= "else" block
|
||||
/// \endcode
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// if (true) {
|
||||
/// // do something
|
||||
/// } else if (false) {
|
||||
/// // do something else
|
||||
/// } else {
|
||||
/// // otherwise do this
|
||||
/// }
|
||||
/// \endcode
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordtry try
|
||||
/// \code
|
||||
/// Try Block ::= "try" block
|
||||
/// ("catch" ["(" variable ")"] [":" guards] block)+
|
||||
/// ["finally" block]
|
||||
/// \endcode
|
||||
///
|
||||
///
|
||||
/// <hr>
|
||||
/// \section keywordwhile while
|
||||
///
|
||||
/// Begins a conditional block of code that loops 0 or more times, as long as the condition is true
|
||||
///
|
||||
/// \code
|
||||
/// While Block ::= "while" "(" condition ")" block
|
||||
/// \endcode
|
||||
/// This loop can be broken using the \ref keywordbreak command.
|
||||
|
||||
|
||||
/// \namespace chaiscript
|
||||
/// \brief Namespace chaiscript contains every API call that the average user will be concerned with.
|
||||
|
||||
@ -311,7 +311,7 @@ namespace chaiscript
|
||||
|
||||
/// \brief Adds a constructor for a POD type
|
||||
/// \tparam T The type to add the constructor for
|
||||
/// \param[in] T The name of the type
|
||||
/// \param[in] type The name of the type
|
||||
/// \param[in,out] m The Module to add the constructor to
|
||||
template<typename T>
|
||||
ModulePtr construct_pod(const std::string &type, ModulePtr m = ModulePtr(new Module()))
|
||||
|
||||
@ -24,12 +24,49 @@
|
||||
|
||||
namespace chaiscript
|
||||
{
|
||||
|
||||
/**
|
||||
* boxed_cast function for casting a Boxed_Value into a given type
|
||||
* example:
|
||||
* int &i = boxed_cast<int &>(boxedvalue);
|
||||
*/
|
||||
|
||||
/// \brief Function for extracting a value stored in a Boxed_Value object
|
||||
/// \tparam Type The type to extract from the Boxed_Value
|
||||
/// \param[in] bv The Boxed_Value to extract a typed value from
|
||||
/// \returns Type equivalent to the requested type
|
||||
/// \throws exception::bad_boxed_cast If the requested conversion is not possible
|
||||
///
|
||||
/// boxed_cast will attempt to make conversions between value, &, *, boost::shared_ptr, boost::reference_wrapper,
|
||||
/// and boost::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.
|
||||
///
|
||||
/// \li non-const values can be extracted as const or non-const
|
||||
/// \li const values can be extracted only as const
|
||||
/// \li Boxed_Value constructed from pointer or boost::reference_wrapper can be extracted as reference,
|
||||
/// pointer or value types
|
||||
/// \li Boxed_Value constructed from boost::shared_ptr or value types can be extracted as reference,
|
||||
/// pointer, value, or boost::shared_ptr types
|
||||
///
|
||||
/// Conversions to boost::function objects are attempted as well
|
||||
///
|
||||
/// Example:
|
||||
/// \code
|
||||
/// // All of the following should succeed
|
||||
/// chaiscript::Boxed_Value bv(1);
|
||||
/// boost::shared_ptr<int> spi = chaiscript::boxed_cast<boost::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);
|
||||
/// boost::shared_ptr<const int> cspi = chaiscript::boxed_cast<boost::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);
|
||||
/// \endcode
|
||||
///
|
||||
/// boost::function conversion example
|
||||
/// \code
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// Boxed_Value bv = chai.eval("`+`"); // Get the functor for the + operator which is built in
|
||||
/// boost::function<int (int, int)> f = chaiscript::boxed_cast<boost::function<int (int, int)> >(bv);
|
||||
/// int i = f(2,3);
|
||||
/// assert(i == 5);
|
||||
/// \endcode
|
||||
template<typename Type>
|
||||
typename detail::Cast_Helper<Type>::Result_Type boxed_cast(const Boxed_Value &bv)
|
||||
{
|
||||
|
||||
@ -270,50 +270,97 @@ namespace chaiscript
|
||||
boost::shared_ptr<Data> m_data;
|
||||
};
|
||||
|
||||
/// Clean wrapper for providing the user with a Boxed_Value
|
||||
/// Suggested use: chai.add(var(myvariable), "myvariable");
|
||||
/// \brief Creates a Boxed_Value. If the object passed in is a value type, it is copied. If it is a pointer, boost::shared_ptr, or boost::reference_type
|
||||
/// a copy is not made.
|
||||
/// \param t The value to box
|
||||
///
|
||||
/// Example:
|
||||
/// \code
|
||||
/// int i;
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chai.add(chaiscript::var(i), "i");
|
||||
/// chai.add(chaiscript::var(&i), "ip");
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Boxed_Value var(T t)
|
||||
{
|
||||
return Boxed_Value(t);
|
||||
}
|
||||
|
||||
/// Wrapper for providing the user with a Boxed_Value that is const inside
|
||||
/// of the ChaiScript engine.
|
||||
/// Suggested use: chai.add(const_var(myvariable), "myvariable");
|
||||
/// \param t The value to box
|
||||
template<typename T>
|
||||
Boxed_Value const_var(T *t)
|
||||
{
|
||||
return Boxed_Value( const_cast<typename boost::add_const<T>::type *>(t) );
|
||||
}
|
||||
namespace detail {
|
||||
/// \brief Takes a value, copies it and returns a Boxed_Value object that is immutable
|
||||
/// \param[in] t Value to copy and make const
|
||||
/// \returns Immutable Boxed_Value
|
||||
/// \sa Boxed_Value::is_const
|
||||
template<typename T>
|
||||
Boxed_Value const_var_impl(const T &t)
|
||||
{
|
||||
return Boxed_Value(boost::shared_ptr<typename boost::add_const<T>::type >(new T(t)));
|
||||
}
|
||||
|
||||
/// boost::shared_ptr<T> overload for const_var
|
||||
template<typename T>
|
||||
Boxed_Value const_var(const boost::shared_ptr<T> &t)
|
||||
{
|
||||
return Boxed_Value( boost::const_pointer_cast<typename boost::add_const<T>::type>(t) );
|
||||
}
|
||||
/// \brief Takes a pointer to a value, adds const to the pointed to type and returns an immutable Boxed_Value.
|
||||
/// Does not copy the pointed to value.
|
||||
/// \param[in] t Pointer to make immutable
|
||||
/// \returns Immutable Boxed_Value
|
||||
/// \sa Boxed_Value::is_const
|
||||
template<typename T>
|
||||
Boxed_Value const_var_impl(T *t)
|
||||
{
|
||||
return Boxed_Value( const_cast<typename boost::add_const<T>::type *>(t) );
|
||||
}
|
||||
|
||||
/// boost::reference_wrapper<T> overload for const_var
|
||||
template<typename T>
|
||||
Boxed_Value const_var(const boost::reference_wrapper<T> &t)
|
||||
{
|
||||
return Boxed_Value( boost::cref(t.get()) );
|
||||
}
|
||||
/// \brief Takes a boost::shared_ptr to a value, adds const to the pointed to type and returns an immutable Boxed_Value.
|
||||
/// Does not copy the pointed to value.
|
||||
/// \param[in] t Pointer to make immutable
|
||||
/// \returns Immutable Boxed_Value
|
||||
/// \sa Boxed_Value::is_const
|
||||
template<typename T>
|
||||
Boxed_Value const_var_impl(const boost::shared_ptr<T> &t)
|
||||
{
|
||||
return Boxed_Value( boost::const_pointer_cast<typename boost::add_const<T>::type>(t) );
|
||||
}
|
||||
|
||||
/// Generic overload for const_var
|
||||
/// \brief Takes a boost::reference_wrapper value, adds const to the referenced type and returns an immutable Boxed_Value.
|
||||
/// Does not copy the referenced value.
|
||||
/// \param[in] t Reference object to make immutable
|
||||
/// \returns Immutable Boxed_Value
|
||||
/// \sa Boxed_Value::is_const
|
||||
template<typename T>
|
||||
Boxed_Value const_var_impl(const boost::reference_wrapper<T> &t)
|
||||
{
|
||||
return Boxed_Value( boost::cref(t.get()) );
|
||||
}
|
||||
}
|
||||
|
||||
/// \brief Takes an object and returns an immutable Boxed_Value. If the object is a boost::reference or pointer type
|
||||
/// the value is not copied. If it is an object type, it is copied.
|
||||
/// \param[in] t Object to make immutable
|
||||
/// \returns Immutable Boxed_Value
|
||||
/// \sa chaiscript::Boxed_Value::is_const
|
||||
/// \sa chaiscript::var
|
||||
///
|
||||
/// Example:
|
||||
/// \code
|
||||
/// enum Colors
|
||||
/// {
|
||||
/// Blue,
|
||||
/// Green,
|
||||
/// Red
|
||||
/// };
|
||||
/// chaiscript::ChaiScript chai
|
||||
/// chai.add(chaiscript::const_var(Blue), "Blue"); // add immutable constant
|
||||
/// chai.add(chaiscript::const_var(Red), "Red");
|
||||
/// chai.add(chaiscript::const_var(Green), "Green");
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Boxed_Value const_var(const T &t)
|
||||
{
|
||||
return Boxed_Value(boost::shared_ptr<typename boost::add_const<T>::type >(new T(t)));
|
||||
return detail::const_var_impl(t);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Return true if the two Boxed_Values share the same internal type
|
||||
*/
|
||||
|
||||
/// \returns true if the two Boxed_Values share the same internal type
|
||||
static bool type_match(Boxed_Value l, Boxed_Value r)
|
||||
{
|
||||
return l.get_type_info() == r.get_type_info();
|
||||
|
||||
@ -230,6 +230,18 @@ namespace chaiscript
|
||||
/// (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 base type
|
||||
/// relationship in all modules that use the newly added type in a polymorphic way.
|
||||
///
|
||||
/// Example:
|
||||
/// \code
|
||||
/// class Base
|
||||
/// {};
|
||||
/// class Derived : public Base
|
||||
/// {};
|
||||
///
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chai.add(chaiscript::base_class<Base, Derived>());
|
||||
/// \endcode
|
||||
///
|
||||
/// \todo Move share static type registration code into a mechanism that allows it to be properly
|
||||
/// shared by all modules
|
||||
template<typename Base, typename Derived>
|
||||
|
||||
@ -22,6 +22,17 @@
|
||||
|
||||
namespace chaiscript
|
||||
{
|
||||
/// \brief Generates a constructor function for use with ChaiScript
|
||||
///
|
||||
/// \tparam T The signature of the constructor to generate. In the form of: ClassType (ParamType1, ParamType2, ...)
|
||||
///
|
||||
/// Example:
|
||||
/// \code
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// // 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");
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Proxy_Function constructor()
|
||||
{
|
||||
|
||||
@ -184,9 +184,7 @@ namespace chaiscript
|
||||
|
||||
namespace exception
|
||||
{
|
||||
/**
|
||||
* Exception thrown if a function's guard fails to execute
|
||||
*/
|
||||
/// \brief Exception thrown if a function's guard fails
|
||||
class guard_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
@ -581,12 +579,11 @@ namespace chaiscript
|
||||
|
||||
namespace exception
|
||||
{
|
||||
/**
|
||||
* Exception thrown in the case that a multi method dispatch fails
|
||||
* because no matching function was found
|
||||
* at runtime due to either an arity_error, a guard_error or a bad_boxed_cast
|
||||
* exception
|
||||
*/
|
||||
/// \brief Exception thrown in the case that a method dispatch fails
|
||||
/// because no matching function was found
|
||||
///
|
||||
/// May be thrown due to an arity_error, a guard_error or a bad_boxed_cast
|
||||
/// exception
|
||||
class dispatch_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
|
||||
@ -65,24 +65,85 @@ namespace chaiscript
|
||||
}
|
||||
}
|
||||
|
||||
/// \brief Creates a new Proxy_Function object from a boost::function object
|
||||
/// \param[in] f boost::function to expose to ChaiScript
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// boost::function<int (char, float, std::string)> f = get_some_function();
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chai.add(fun(f), "some_function");
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Proxy_Function fun(const boost::function<T> &f)
|
||||
{
|
||||
return Proxy_Function(new dispatch::Proxy_Function_Impl<T>(f));
|
||||
}
|
||||
|
||||
/// \brief Creates a new Proxy_Function object from a free function, member function or data member
|
||||
/// \param[in] t Function / member to expose
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// int myfunction(const std::string &);
|
||||
/// class MyClass
|
||||
/// {
|
||||
/// public:
|
||||
/// void memberfunction();
|
||||
/// int memberdata;
|
||||
/// };
|
||||
///
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chai.add(fun(&myfunction), "myfunction");
|
||||
/// chai.add(fun(&MyClass::memberfunction), "memberfunction");
|
||||
/// chai.add(fun(&MyClass::memberdata), "memberdata");
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Proxy_Function fun(T t)
|
||||
{
|
||||
return dispatch::detail::Fun_Helper<boost::function_types::is_member_object_pointer<T>::value, boost::function_types::is_member_function_pointer<T>::value>::go(t);
|
||||
}
|
||||
|
||||
/// \brief Creates a new Proxy_Function object from a free function, member function or data member and binds the first parameter of it
|
||||
/// \param[in] t Function / member to expose
|
||||
/// \param[in] q Value to bind to first parameter
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// struct MyClass
|
||||
/// {
|
||||
/// void memberfunction(int);
|
||||
/// };
|
||||
///
|
||||
/// MyClass obj;
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// // Add function taking only one argument, an int, and permanently bound to "obj"
|
||||
/// chai.add(fun(&MyClass::memberfunction, boost::ref(obj)), "memberfunction");
|
||||
/// \endcode
|
||||
template<typename T, typename Q>
|
||||
Proxy_Function fun(T t, const Q &q)
|
||||
{
|
||||
return fun(detail::bind_first(t, q));
|
||||
}
|
||||
|
||||
/// \brief Creates a new Proxy_Function object from a free function or member function and binds the first and second parameters of it
|
||||
/// \param[in] t Function / member to expose
|
||||
/// \param[in] q Value to bind to first parameter
|
||||
/// \param[in] r Value to bind to second parameter
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// struct MyClass
|
||||
/// {
|
||||
/// void memberfunction(int);
|
||||
/// };
|
||||
///
|
||||
/// MyClass obj;
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// // Add function taking only no arguments, and permanently bound to "obj" and "1"
|
||||
/// // memberfunction() will be equivalent to obj.memberfunction(1)
|
||||
/// chai.add(fun(&MyClass::memberfunction, boost::ref(obj), 1), "memberfunction");
|
||||
/// \endcode
|
||||
template<typename T, typename Q, typename R>
|
||||
Proxy_Function fun(T t, const Q &q, const R &r)
|
||||
{
|
||||
|
||||
@ -212,13 +212,30 @@ namespace chaiscript
|
||||
};
|
||||
}
|
||||
|
||||
/// \brief Creates a Type_Info object representing the type passed in
|
||||
/// \tparam T Type of object to get a Type_Info for, derived from the passed in parameter
|
||||
/// \return Type_Info for T
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// int i;
|
||||
/// chaiscript::Type_Info ti = chaiscript::user_type(i);
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Type_Info user_type(T)
|
||||
Type_Info user_type(const T &/*t*/)
|
||||
{
|
||||
return detail::Get_Type_Info<T>::get();
|
||||
}
|
||||
|
||||
|
||||
/// \brief Creates a Type_Info object representing the templated type
|
||||
/// \tparam T Type of object to get a Type_Info for
|
||||
/// \return Type_Info for T
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// chaiscript::Type_Info ti = chaiscript::user_type<int>();
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
Type_Info user_type()
|
||||
{
|
||||
|
||||
@ -30,6 +30,7 @@ namespace chaiscript
|
||||
{
|
||||
namespace exception
|
||||
{
|
||||
/// \brief Thrown if an error occurs while attempting to load a binary module
|
||||
struct load_module_error : std::runtime_error
|
||||
{
|
||||
load_module_error(const std::string &t_reason) throw()
|
||||
@ -356,7 +357,35 @@ namespace chaiscript
|
||||
do_eval(chaiscript_prelude, "standard prelude");
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper function for loading a file
|
||||
*/
|
||||
std::string load_file(const std::string &t_filename) {
|
||||
std::ifstream infile(t_filename.c_str(), std::ios::in | std::ios::ate | std::ios::binary );
|
||||
|
||||
if (!infile.is_open()) {
|
||||
throw exception::file_not_found_error(t_filename);
|
||||
}
|
||||
|
||||
std::streampos size = infile.tellg();
|
||||
infile.seekg(0, std::ios::beg);
|
||||
|
||||
assert(size >= 0);
|
||||
|
||||
if (size == std::streampos(0))
|
||||
{
|
||||
return std::string();
|
||||
} else {
|
||||
std::vector<char> v(static_cast<unsigned int>(size));
|
||||
infile.read(&v[0], size);
|
||||
return std::string(v.begin(), v.end());
|
||||
}
|
||||
}
|
||||
|
||||
public:
|
||||
/// \brief Constructor for ChaiScript
|
||||
/// \param[in] t_modulepaths Vector of paths to search when attempting to load a binary module
|
||||
/// \param[in] t_usepaths Vector of paths to search when attempting to "use" an included ChaiScript file
|
||||
ChaiScript(const std::vector<std::string> &t_modulepaths = std::vector<std::string>(),
|
||||
const std::vector<std::string> &t_usepaths = std::vector<std::string>())
|
||||
: m_modulepaths(t_modulepaths), m_usepaths(t_usepaths)
|
||||
@ -374,15 +403,20 @@ namespace chaiscript
|
||||
build_eval_system();
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a shared object, that can be used by all threads, to the system
|
||||
*/
|
||||
/// \brief Adds a constant object that is available in all contexts and to all threads
|
||||
/// \param[in] t_bv Boxed_Value to add as a global
|
||||
/// \param[in] t_name Name of the value to add
|
||||
/// \throw exception::global_non_const If t_bv is not a constant object
|
||||
/// \sa Boxed_Value::is_const
|
||||
ChaiScript &add_global_const(const Boxed_Value &t_bv, const std::string &t_name)
|
||||
{
|
||||
m_engine.add_global_const(t_bv, t_name);
|
||||
return *this;
|
||||
}
|
||||
|
||||
/// \brief Represents the current state of the ChaiScript system. State and be saved and restored
|
||||
/// \sa ChaiScript::get_state
|
||||
/// \sa ChaiScript::set_state
|
||||
struct State
|
||||
{
|
||||
std::set<std::string> used_files;
|
||||
@ -390,11 +424,15 @@ namespace chaiscript
|
||||
std::set<std::string> active_loaded_modules;
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns a state object that represents the current
|
||||
* set of loaded files, the set of global variables and
|
||||
* the set of initialized functions
|
||||
*/
|
||||
/// \brief Returns a state object that represents the current state of the system
|
||||
/// \return Current state of the system
|
||||
///
|
||||
/// \b Example:
|
||||
///
|
||||
/// \code
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chaiscript::ChaiScript::State s = chai.get_state(); // represents bootstrapped initial state
|
||||
/// \endcode
|
||||
State get_state()
|
||||
{
|
||||
chaiscript::detail::threading::lock_guard<chaiscript::detail::threading::recursive_mutex> l(m_use_mutex);
|
||||
@ -407,9 +445,16 @@ namespace chaiscript
|
||||
return s;
|
||||
}
|
||||
|
||||
/**
|
||||
* Restores the state from a saved State object.
|
||||
*/
|
||||
/// \brief Sets the state of the system
|
||||
/// \param[in] t_state New state to set
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// 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"
|
||||
/// \endcode
|
||||
void set_state(const State &t_state)
|
||||
{
|
||||
chaiscript::detail::threading::lock_guard<chaiscript::detail::threading::recursive_mutex> l(m_use_mutex);
|
||||
@ -420,9 +465,19 @@ namespace chaiscript
|
||||
m_engine.set_state(t_state.engine_state);
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds an object to the system: type, function, object
|
||||
*/
|
||||
/// \brief Adds a type, function or object to ChaiScript
|
||||
/// \param[in] t_t Item to add
|
||||
/// \param[in] t_name Name of item to add
|
||||
/// \returns Reference to current ChaiScript object
|
||||
///
|
||||
/// \b Examples:
|
||||
/// \code
|
||||
/// 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
|
||||
/// \endcode
|
||||
template<typename T>
|
||||
ChaiScript &add(const T &t_t, const std::string &t_name)
|
||||
{
|
||||
@ -430,18 +485,42 @@ namespace chaiscript
|
||||
return *this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a module object to the system
|
||||
*/
|
||||
/// \brief Add a new conversion for upcasting to a base class
|
||||
/// \sa chaiscript::base_class
|
||||
/// \param[in] d Base class / parent class
|
||||
///
|
||||
/// \b Example:
|
||||
/// \code
|
||||
/// chaiscript::ChaiScript chai;
|
||||
/// chai.add(chaiscript::base_class<std::runtime_error, chaiscript::dispatch_error>());
|
||||
/// \endcode
|
||||
ChaiScript &add(const Dynamic_Cast_Conversion &d)
|
||||
{
|
||||
m_engine.add(d);
|
||||
return *this;
|
||||
}
|
||||
|
||||
/// \brief Adds all elements of a module to ChaiScript runtime
|
||||
/// \param[in] t_p The module to add.
|
||||
/// \sa chaiscript::Module
|
||||
ChaiScript &add(const ModulePtr &t_p)
|
||||
{
|
||||
t_p->apply(*this, this->get_eval_engine());
|
||||
return *this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a dynamic library containing a chaiscript module
|
||||
*/
|
||||
/// \brief Load a binary module from a dynamic library. Works on platforms that support
|
||||
/// dynamic libraries.
|
||||
/// \param[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"|"").
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// \throw exception::load_module_error In the event that no matching module can be found.
|
||||
void load_module(const std::string &t_module_name)
|
||||
{
|
||||
std::vector<exception::load_module_error> errors;
|
||||
@ -490,9 +569,13 @@ namespace chaiscript
|
||||
throw exception::load_module_error("Unable to find module: " + t_module_name + " Errors: " + errstring);
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a dynamic library and provide the file name to load it from
|
||||
*/
|
||||
/// \brief Load a binary module from a dynamic library. Works on platforms that support
|
||||
/// dynamic libraries.
|
||||
///
|
||||
/// \param[in] t_module_name Module name to load
|
||||
/// \param[in] t_filename Ignore normal filename search process and use specific filename
|
||||
///
|
||||
/// \sa ChaiScript::load_module(const std::string &t_module_name)
|
||||
void load_module(const std::string &t_module_name, const std::string &t_filename)
|
||||
{
|
||||
chaiscript::detail::threading::lock_guard<chaiscript::detail::threading::recursive_mutex> l(m_use_mutex);
|
||||
@ -510,62 +593,61 @@ namespace chaiscript
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Evaluate a string via eval method
|
||||
*/
|
||||
/// \brief Evaluates a string. Equivalent to ChaiScript::eval.
|
||||
///
|
||||
/// \param[in] t_script Script to execute
|
||||
///
|
||||
/// \return result of the script execution
|
||||
///
|
||||
/// \throw exception::eval_error In the case that evaluation fails.
|
||||
Boxed_Value operator()(const std::string &t_script)
|
||||
{
|
||||
return do_eval(t_script);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Helper function for loading a file
|
||||
*/
|
||||
std::string load_file(const std::string &t_filename) {
|
||||
std::ifstream infile(t_filename.c_str(), std::ios::in | std::ios::ate | std::ios::binary );
|
||||
|
||||
if (!infile.is_open()) {
|
||||
throw exception::file_not_found_error(t_filename);
|
||||
}
|
||||
|
||||
std::streampos size = infile.tellg();
|
||||
infile.seekg(0, std::ios::beg);
|
||||
|
||||
assert(size >= 0);
|
||||
|
||||
if (size == std::streampos(0))
|
||||
{
|
||||
return std::string();
|
||||
} else {
|
||||
std::vector<char> v(static_cast<unsigned int>(size));
|
||||
infile.read(&v[0], size);
|
||||
return std::string(v.begin(), v.end());
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/// \brief Evaluates a string and returns a typesafe result.
|
||||
///
|
||||
/// \tparam T Type to extract from the result value of the script execution
|
||||
/// \param[in] t_input Script to execute
|
||||
///
|
||||
/// \return result of the script execution
|
||||
///
|
||||
/// \throw exception::eval_error In the case that evaluation fails.
|
||||
/// \throw exception::bad_boxed_cast In the case that evaluation succeeds but the result value cannot be converted
|
||||
/// to the requested type.
|
||||
template<typename T>
|
||||
T eval(const std::string &t_input)
|
||||
{
|
||||
return boxed_cast<T>(do_eval(t_input));
|
||||
}
|
||||
|
||||
/// \brief Evaluates a string.
|
||||
///
|
||||
/// \param[in] t_input Script to execute
|
||||
///
|
||||
/// \return result of the script execution
|
||||
///
|
||||
/// \throw exception::eval_error In the case that evaluation fails.
|
||||
Boxed_Value eval(const std::string &t_input)
|
||||
{
|
||||
return do_eval(t_input);
|
||||
}
|
||||
|
||||
/**
|
||||
* Loads the file specified by filename, evaluates it, and returns the result
|
||||
*/
|
||||
/// \brief Loads the file specified by filename, evaluates it, and returns the result.
|
||||
/// \param[in] t_filename File to load and parse.
|
||||
/// \return result of the script execution
|
||||
/// \throw exception::eval_error In the case that evaluation fails.
|
||||
Boxed_Value eval_file(const std::string &t_filename) {
|
||||
return do_eval(load_file(t_filename), t_filename);
|
||||
}
|
||||
|
||||
/**
|
||||
* Loads the file specified by filename, evaluates it, and returns the as the specified type
|
||||
*/
|
||||
/// \brief Loads the file specified by filename, evaluates it, and returns the typesafe result.
|
||||
/// \tparam T Type to extract from the result value of the script execution
|
||||
/// \param[in] t_filename File to load and parse.
|
||||
/// \return result of the script execution
|
||||
/// \throw exception::eval_error In the case that evaluation fails.
|
||||
/// \throw exception::bad_boxed_cast In the case that evaluation succeeds but the result value cannot be converted
|
||||
/// to the requested type.
|
||||
template<typename T>
|
||||
T eval_file(const std::string &t_filename) {
|
||||
return boxed_cast<T>(do_eval(load_file(t_filename), t_filename));
|
||||
|
||||
242
include/chaiscript/language/chaiscript_prelude_docs.hpp
Normal file
242
include/chaiscript/language/chaiscript_prelude_docs.hpp
Normal file
@ -0,0 +1,242 @@
|
||||
|
||||
/// \brief Items in this namespace exist in the ChaiScript language runtime. They are not part of the C++ API
|
||||
namespace ChaiScript_Language
|
||||
{
|
||||
|
||||
/// \page LangStandardLibraryRef ChaiScript Language Standard Libary Reference
|
||||
///
|
||||
/// ChaiScript, at its core, has some very functional programming-inspired habits. Few places show this off as clearly
|
||||
/// as the prelude, itself a name taken as a nod to the popular functional language Haskell. This prelude is available
|
||||
/// to all standard ChaiScript applications, and provides a simple foundation for using numbers, strings, and ranges
|
||||
/// (the general category of containers and their iteration).
|
||||
///
|
||||
/// \section LibraryStrings Strings
|
||||
///
|
||||
|
||||
|
||||
/// \brief Converts o into a string.
|
||||
///
|
||||
/// \code
|
||||
/// eval> to_string(3).is_type("string") <br>
|
||||
/// true<br>
|
||||
/// \endcode
|
||||
string to_string(Object o);
|
||||
|
||||
|
||||
/// \brief Prints o to the terminal, without a trailing carriage return. Applies conversions to string automatically.
|
||||
/// \code
|
||||
/// eval> puts("hi, "); puts("there")
|
||||
/// hi, thereeval>
|
||||
/// \endcode
|
||||
/// \sa to_string
|
||||
/// \sa print
|
||||
void puts(Object o);
|
||||
|
||||
|
||||
/// \brief Prints o to the terminal, with a trailing carriage return. Applies conversions to string automatically
|
||||
/// \code
|
||||
/// eval> print("hello")
|
||||
/// hello
|
||||
/// eval>
|
||||
/// \endcode
|
||||
/// \sa to_string
|
||||
/// \sa puts
|
||||
void print(Object o);
|
||||
|
||||
/// \brief ChaiScript representation of std::string. It is an std::string but only some member are exposed to ChaiScript.
|
||||
///
|
||||
/// Because the ChaiScript string object is an std::string, it is directly convertable to and from std::string
|
||||
/// using the chaiscript::boxed_cast and chaiscript::var functions.
|
||||
///
|
||||
/// With the exception of string::trim, string::rtrim, string::ltrim, all members are direct passthroughs to the
|
||||
/// std::string of the same name.
|
||||
///
|
||||
/// \note Object and function notations are equivalent in ChaiScript. This means that
|
||||
/// \c "bob".find("b") and \c find("bob", "b") are exactly the same. Most examples below follow the
|
||||
/// second formation of the function calls.
|
||||
/// \sa \ref keyworddef for extending existing C++ classes in ChaiScript
|
||||
class string
|
||||
{
|
||||
public:
|
||||
/// \brief Finds the first instance of substr.
|
||||
/// \code
|
||||
/// eval> find("abab", "ab")
|
||||
/// 0
|
||||
/// \endcode
|
||||
int find(string s) const;
|
||||
|
||||
|
||||
/// \brief Finds the last instance of substr.
|
||||
/// \code
|
||||
/// eval> rfind("abab", "ab")
|
||||
/// 2
|
||||
/// \endcode
|
||||
int rfind(string s) const;
|
||||
|
||||
/// Finds the first of characters in list in the string.
|
||||
///
|
||||
/// \code
|
||||
/// eval> find_first_of("abab", "bec")
|
||||
/// 1
|
||||
/// \endcode
|
||||
int find_first_of(string list) const;
|
||||
|
||||
/// Finds the last of characters in list in the string.
|
||||
///
|
||||
/// \code
|
||||
/// eval> find_last_of("abab", "bec")
|
||||
/// 3
|
||||
/// \endcode
|
||||
int find_last_of(string list) const;
|
||||
|
||||
/// Finds the first non-matching character to list in the str string.
|
||||
///
|
||||
/// \code
|
||||
/// eval> find_first_not_of("abcd", "fec")
|
||||
/// 0
|
||||
/// \endcode
|
||||
int find_first_not_of(string list) const;
|
||||
|
||||
///find_last_not_of(str, list): Finds the last non-matching character to list in the str string.
|
||||
///
|
||||
/// \code
|
||||
/// eval> find_last_not_of("abcd", "fec")
|
||||
/// 3
|
||||
/// \endcode
|
||||
int find_last_not_of(string list) const;
|
||||
|
||||
/// Removes whitespace from the front of the string, returning a new string
|
||||
///
|
||||
/// \note This function is implemented as a ChaiScript function using the def member function notation.
|
||||
///
|
||||
/// \code
|
||||
/// eval> ltrim(" bob")
|
||||
/// bob
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref keyworddef
|
||||
string lstrim() const;
|
||||
|
||||
/// Removes whitespace from the back of the string, returning a new string
|
||||
///
|
||||
/// \note This function is implemented as a ChaiScript function using the def member function notation.
|
||||
///
|
||||
/// \code
|
||||
/// eval> rtrim("bob ") + "|"
|
||||
/// bob|
|
||||
/// \endcode
|
||||
///
|
||||
/// \sa \ref keyworddef
|
||||
string rtrim() const;
|
||||
|
||||
/// Removes whitespace from the front and back of the string, returning a new string
|
||||
///
|
||||
/// \note This function is implemented as a ChaiScript function using the def member function notation.
|
||||
///
|
||||
/// \code
|
||||
/// eval> trim(" bob ") + "|"
|
||||
/// bob|
|
||||
/// \endcode
|
||||
///
|
||||
/// Equivalent to rtrim(ltrim(" bob "));
|
||||
///
|
||||
/// \sa \ref keyworddef
|
||||
string trim() const;
|
||||
};
|
||||
|
||||
///Numbers
|
||||
///
|
||||
///max(a, b): Returns the maximum value of a or b.
|
||||
///
|
||||
///eval> max(4, 10)
|
||||
///10
|
||||
///min(a, b): Returns the minimum value of a or b.
|
||||
///
|
||||
///eval> min(4, 10)
|
||||
///4
|
||||
///even(x): Returns true if x is even, otherwise returns false.
|
||||
///
|
||||
///eval> even(4)
|
||||
///true
|
||||
///odd(x): Returns true if x is odd, otherwise returns false.
|
||||
///
|
||||
///eval> odd(4)
|
||||
///false
|
||||
///Containers
|
||||
///
|
||||
///for_each(container, f): Applies the function f over each element in the container.
|
||||
///
|
||||
///eval> for_each([1, 2, 3], print)
|
||||
///1
|
||||
///2
|
||||
///3
|
||||
///map(container, f): Applies f over each element in the container, joining all the results.
|
||||
///
|
||||
///eval> map([1, 2, 3], odd)
|
||||
///[true, false, true]
|
||||
///foldl(container, f, initial): Starts with the initial value and applies the function f to it and the first element of the container. The result is then applied to the second element, and so on until the elements are exhausted.
|
||||
///
|
||||
///eval> foldl([1, 2, 3, 4], `+`, 0)
|
||||
///10
|
||||
///sum(container): Returns the sum total of the values in the container.
|
||||
///
|
||||
///eval> sum([1, 2, 3, 4])
|
||||
///10
|
||||
///product(container): Returns the product of the value in the container.
|
||||
///
|
||||
///eval> product([1, 2, 3, 4])
|
||||
///24
|
||||
///take(container, num): Takes num elements from the container, returning them.
|
||||
///
|
||||
///eval> take([1, 2, 3, 4], 2)
|
||||
///[1, 2]
|
||||
///take_while(container, f): Takes elements from the container that match function f, stopping at the first non-match, returning them as a new Vector.
|
||||
///
|
||||
///eval> take_while([1, 2, 3], odd)
|
||||
///[1]
|
||||
///drop(container, num): Drops num elements from the container, returning the remainder.
|
||||
///
|
||||
///eval> drop([1, 2, 3, 4], 2)
|
||||
///[3, 4]
|
||||
///drop_while(container, f): Drops elements from the container that match f, stopping at the first non-match, returning the remainder.
|
||||
///
|
||||
///eval> drop_while([1, 2, 3], odd)
|
||||
///[2, 3]
|
||||
///reduce(container, f): Similar to foldl, this takes the first two elements as its starting values for f. This assumes container has at least 2 elements.
|
||||
///
|
||||
///eval> reduce([1, 2, 3, 4], `+`)
|
||||
///10
|
||||
///filter(container, f): Takes elements from container that match function f, return them.
|
||||
///
|
||||
///eval> filter([1, 2, 3, 4], odd)
|
||||
///[1, 3]
|
||||
///join(container, delim): Joins the elements of the container into a string, delimiting each with the delim string.
|
||||
///
|
||||
///eval> join([1, 2, 3], "*")
|
||||
///1*2*3
|
||||
///reverse(container): Returns the contents of the container in reversed order.
|
||||
///
|
||||
///eval> reverse([1, 2, 3, 4, 5, 6, 7])
|
||||
///[7, 6, 5, 4, 3, 2, 1]
|
||||
///generate_range(x, y): Generates a new Vector filled with values starting at x and ending with y.
|
||||
///
|
||||
///eval> generate_range(1, 10)
|
||||
///[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
|
||||
///concat(x, y): Returns a new Vector with x and y concatenated.
|
||||
///
|
||||
///eval> concat([1, 2, 3], [4, 5, 6])
|
||||
///[1, 2, 3, 4, 5, 6]
|
||||
///collate(x, y): Returns a new Vector with x and y as its values.
|
||||
///
|
||||
///eval> collate(1, 2)
|
||||
///[1, 2]
|
||||
///zip_with(f, x, y): Applies f to elements of x and y, returning a new Vector with the result of each application.
|
||||
///
|
||||
///eval> zip_with(`+`, [1, 2, 3], [4, 5, 6])
|
||||
///[5, 7, 9]
|
||||
///zip(x, y): Collates elements of x and y, returning a new Vector with the result.
|
||||
///
|
||||
///eval> zip([1, 2, 3], [4, 5, 6])
|
||||
///[[1, 4], [2, 5], [3, 6]]
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user