ChaiScript is a header-only C++ embedded scripting language loosely based on ECMA script. It is designed for ease of use and tight integration with C++.

Usage

The original ChaiScript repository has been split into multiple build2 packages to allow for greater flexibility. The libchaiscript package is used to get access to the ChaiScript header-only library. The package chaiscript makes ChaiScript's own interpreter chai available to be used. chaiscript-stdlib exports the compiled and dynamically loadable standard library module for the basic ChaiScript engine. Typically, you will not need to use this one.

Make sure to add the or alpha or stable section of the cppget.org repository to your project's repositories.manifest to be able to fetch the packages.

:
role: prerequisite
location: https://pkg.cppget.org/1/stable
# trust: ...

If the cppget.org repository is not an option then add this Git repository itself instead as a prerequisite.

:
role: prerequisite
location: https://github.com/build2-packaging/chaiscript.git

Add the respective dependencies in your project's manifest file to make the packages available for import. Hereby, all packages should use the same version constraint.

depends: libchaiscript ^ 6.1.0
# or
depends: { libchaiscript chaiscript chaiscript-stdlib } ^ 6.1.0

The header-only C++ library to use ChaiScript as an embedded language can be imported by the following declaration in a buildfile.

import chaiscript = libchaiscript%lib{chaiscript}

Using the chai interpreter for ChaiScript scripts, as a REPL, or as build-time dependency with immediate and standard importation is supported. Because it is not able to change the code of chai, there is no way for now to provide any metadata in the executable.

import chai = chaiscript%exe{chai}
# or
import! chai = chaiscript%exe{chai}

To import the dynamically loadable module which provides the standard library for a ChaiScript instance, we need to rely on metadata. A dynamic module should not be linked to your executable but instead loaded at runtime. Hence, to use it properly for running ChaiScript scripts for tests or other things, you would need the module as a prerequisite but only use its directory as input. This can be accomplished by immediate importation with metadata support.

import! [metadata, rule_hint=cxx.link] \
    stdlib_module = chaiscript-stdlib%libs{chaiscript_stdlib}
stdlib_dir = [dir_path] $($stdlib_module: chaiscript_stdlib.dir)

Configuration

Multithread Support

Multithread support is enabled by default and may be turned off by using the following configuration variable. On Unix-based targets, pthread will be linked when enabled.

config [bool] config.libchaiscript.multithread_support_enabled ?= true

Dynamic Module Loading

The support to dynamically load ChaiScript modules is enabled by default and may be turned off by using the following configuration variable.

config [bool] config.libchaiscript.dynload_enabled ?= true

Use of GNU readline

For now, the use of the GNU readline library for the ChaiScript interpreter chai is disabled by default to allow for out-of-the-box CI builds.

If readline is available on the system, we recommend to enable it.

config [bool] config.chaiscript.use_readline ?= false

Issues and Notes

• Supported Platforms:
  • Linux: GCC, Clang but not withlibc++
  • Windows: MSVC, GCC, and Clang
  • MacOS: chaiscript-stdlib is not supported

• ChaiScript is not made for C++20 and higher language standards. As the library is header-only, we do not restrict the language standard of the library package libchaiscript but instead keep it to be cxx.std = latest. Especially when using Clang, this may result in compilation errors in a project that uses ChaiScript, such as it has been with its own samples and tests. For now, the workaround is to force the C++17 standard with cxx.std = 17. If this is not an option, this package will probably not work with your project.
• Using Clang on Windows with MSVC, the object copy count test given in the compiled_tests.cpp file fails due to the wrong number of destructor and move calls. This is most likely an implementation issue of ChaiScript and, looking into the up-to-date develop branch, fixed in the prerelease of version 7.0.0.
• This package does not build or execute the fuzzer test.
• This package does not build or execute the performance tests because valgrind would be needed.
• Not all unit tests based on ChaiScript scripts are sucessfull when using Clang with libc++. This seems to be an implementation issue of the ChaiScript library itself.
• To fix the strange inclusion scheme of the statically generated libraries parser and stdlib, their content actually needed to be copied and adjusted.
• If there would ever be a new version, check against new script files for testing and adjust all the symbolic links.

Contributing

Thanks in advance for your help and contribution to keep this package up-to-date. For now, please, file an issue on GitHub for everything that is not described below.

Recommend Updating Version

Please, file an issue on GitHub with the new recommended version.

Update Version by Pull Request

1. Fork the repository on GitHub and clone it to your local machine.
2. Run git submodule init and git submodule update to get the current upstream directory.
3. Inside the upstream directory, checkout the new library version X.Y.Z by calling git checkout vX.Y.Z that you want to be packaged.
4. If needed, change source files, buildfiles, and symbolic links accordingly to create a working build2 package. Make sure not to directly depend on the upstream directory inside the build system but use symbolic links instead.
5. Test if the packages compile and execute examples and tools.
6. Update library version in all manifest files if it has changed or add package update by using +n for the n-th update.
7. Make an appropriate commit message by using imperative mood and a capital letter at the start and push the new commit to the master branch.
8. Run bdep ci and test for errors.
9. If everything works fine, make a pull request on GitHub and write down the bdep ci link to your CI tests.
10. After a successful pull request, we will run the appropriate commands to publish a new package version.

Update Version Directly if You Have Permissions

1. Inside the upstream directory, checkout the new library version X.Y.Z by calling git checkout vX.Y.Z that you want to be packaged.
2. If needed, change source files, buildfiles, and symbolic links accordingly to create a working build2 package. Make sure not to directly depend on the upstream directory inside the build system but use symbolic links instead.
3. Test if the packages compile and execute examples and tools.
4. Update library version in all manifest files if it has changed or add package update by using +n for the n-th update.
5. Make an appropriate commit message by using imperative mood and a capital letter at the start and push the new commit to the master branch.
6. Run bdep ci and test for errors and warnings.
7. When successful, run bdep release --tag --push to push new tag version to repository.
8. Run bdep publish to publish the package to cppget.org.

Notes:

Current Version: 6.1.0

Changes since 6.0.0

• Add namespacing support #290 @stephenberry
• Add utf parsing support
• cheatsheet.md updates
• add_class utility support for scoped enums #306 @StanEpp
• Parser optimizations #300 @niXman
• Various JSON fixes #377 #400 #409 #371 @totalgee @dinghram @arcoRocks
• Various cleanups, bugfixes and warning fixes and minor performance improvements
• Support for C++17 compilers!
• Support for UTF8 BOM #439 @AlekMosingiewicz @MarioLiebisch

Changes since 5.8.6

6.0.0 is a massive rework compared to 5.x. It now requires a C++14 enabled compiler

Compiler Requirements

• MSVC 2015 or greater
• g++ 4.9 or greater
• clang 3.6 or greater

Breaking Changes

• Instantiating a ChaiScript object now, by default, builds the stdlib in
  • This was done to address the most common support issues of loading stdlib dynamically at runtime
  • If you want the old behavior, use include/chaiscript/chaiscript_basic.hpp
• Headers have been reorganized to fully separate stdlib/parser/engine from each other (some faster builds)
• Bootstrap functions no longer return a reference to the module added to (compile time savings)
• It's now no longer possible modify AST_Nodes (compile time, runtime efficiency)
• Function annotations no longer exist (simplifies code, reduces compile time, compile size)

New Features Added

• Modular optimization system; this can be accessed via the ChaiScript_Basic interface
• Execution tracing capability; also accessed via ChaiScript_Basic interface
• range-based for loops for( id : container ) { } (much better performance than other loop types)
• If-init expressions (ala C++17)
• Support for passing r-value references to functions
• Support for containing unique_ptr
• Add helpers for exposing enum classes to ChaiScript
• Allow typed ChaiScript defined functions to perform conversions on call #303

Improvements

• Compile time improvements
• Compile size improvements
• Significant runtime improvements (see "Modular optimization system")
• Significant parser improvements, both with parse-time and parser initialization time (Thanks @niXman)
• Fix type conversion to bool in conditionals

Improvements Still Need To Be Made

• File location tracking has been rewritten; this currently means error location reporting is not as good as it was
• Tracing capability needs to be tested and vetted

Changes since 5.8.5

• Optimize away return statements in lambdas also
• Allow conversions to bool in conditionals
• Don't allow class statements inside of scopes
• Properly error when a dynamic object non-function member is called

Changes since 5.8.4

• Fix order of operations for prefix operators
• Make sure atomics are initialized properly
• Remove parsing of unused prefix & operator

Changes since 5.8.3

• Fix case with some numeric conversions mixed with numerics that do not need conversion

Changes since 5.8.2

• Add support for reference of pointer return types

Changes since 5.8.1

• Allow casting to non-const & std::shared_ptr

Changes since 5.8.0

• Fix parsing of floats to be locale independent #250
• Various warning fixes on various platforms

Changes since 5.7.1

• Make all parser iterator operations range checked
• Parse in-string eval statements once, not once for each execution
• Fix parsing of operators (ie 1<-1 now parses)
• Fix variable scoping for functors
• Exception reduction
• Various object lifetime fixes
• Add JSON support for load / save #207
• Numeric overload resolution fixes #209
• Fix long long #208
• Add octal escapes in strings #211
• Fixed sizing of binary literals #213
• Added support for != with bool values #217
• Various value assignment vector fixes
• Fixed broken hex escape sequences from @ChristianKaeser
• Multiply defined symbols fixes #232 @RaptorFactor
• Add add_class helper #233 @vrennert
• Cheatsheet fixes #235 @mlamby
• Fix parsing of strings inside of in-string eval statements
• Allow lower-case global keyword
• Enable thread-local on MSVC (should be significant performance boost)

Changes since 5.7.0

• Build time reduction
• Build size reduction
• Performance increases
• Fixed ~20 crash-bugs found with fuzzy testing #194
  • Let unhandled exceptions propogate to user
  • Report eval_error when break statement is not in loop
  • Fix handling of 0 length scripts closes #193
  • Don't crash on arity mismatch - Specifically affects the case where no overloads exist for a given function
  • Fix error printing for bind calls
  • Handle unexpected continue statement
  • Check arity during bind
  • Don't allow arith conversion on variadic function
  • Correct bind parameter match count
  • Add in expected Boxed_Value exception cases
  • Check access to AST, don't allow ; in func def
  • Don't attempt arithmetic unary & call
  • Don't crash on 0 param call to bind
  • Catch errors during member function dispatch
  • Properly handle type of const bool &
• Automatic deduction of lambda type signatures
• Work with non-polymorphic parent/child conversions
• Move to codecov for coverage reporting
• Add .at method for Map objects
• Various corrections for support of move-only objects

Changes since 5.6.0

• Significant code cleanups and reduction
• Smaller builds
• Faster compiles
• Less runtime memory usage
• ~2x faster runtimes
• biicode support
• method_missing feature added #164 @arBmind
• Generic objects with dynamic properties support
• Add ability to call functions contained in properties
• Add lambda captures
• Create cheatsheet.md for all-in-one reference of features
• Fix support for libc++
• Eliminate clone of return value stored locally
• Eliminate 'return' statements when last line of function
• Reduce number of runtime exceptions occuring
• Reduce copies / moves of return values.
• make use statement return value of last statement in file
• Add ability to access fixed array sizes
• Add support for scientific notation floating point literals #174 @totalgee

Changes since 5.5.1

• Throw exception on integer divide by 0

• Add optional type specification to function declarations

  def func(int i, j, double k) {
    // i must be an int.
    // j can be anything
    // k must be a double
    // normal conversion rules still apply
  }
  

• Many minor fixes for compiler warnings

• Add support for std::future and std::async

  var f := async(someFunction);
  var f2 := async(someFunction2);
  
  // someFunction and someFunction2 are running in parallel now
  f.get();
  f2.get();
  

• Fully support r-value returns, supporting move-only objects and reducing object copies

Changes since 5.5.0

• 30% performance increase
• Fix handling of object stack, resulting in greatly reduced memory usage
• Code cleanups

Changes since 5.4.0

• 2x performance increase
• Significant code cleanups
• Throw exception if user attempts to call function on null object
• Allow user defined type conversions
• Fix object lifetime for nested function calls made at the global scope
• Fix returning of boolean values from function calls

Changes since 5.3.1

• Decreased compile time and build size
• Make "reflection" module built in (losing some of the time / build size gains)
• Add new "class" syntax for ChaiScript defined methods and attributes see: unittests/class.chai for examples
• Minor performance enhancements
• major to_string performance enhancements
• Provide API for retrieving registered type name #124
• Added strong reference to container to range object #132

Changes since 5.3.0

• Add automatic conversion of arithmetic return types, following the same rules as conversion of arithmetic types when passing parameters
• Add automatic casting up the inheritence hierarchy when possible.
• Enable travis.ci testing
• Allow users to add globals from within script
• Various static analysis fixes
• Code modernization to C++11
• Unofficial support for Haiku added
• Fix #121 - Inability to compile on cygwin
• Formatting fixes and spelling corrections
• Apply "include what you use" https://code.google.com/p/include-what-you-use/
• Apply clang-modernize
• Various threading fixes
• Performance improvements

Changes since 5.2.0

• Official support for MSVC with C++11. All major platforms and compilers are now support for C++11 release

Changes since 4.2.0

• Enhanced unit tests
• Add continue statement, fix various use cases for for loops
• Fix use of suffixed numbers in vector initialization
• Code cleanups
• Eliminate global data, which makes code more portable and thread safe
• Fix issue #79
• Merge pretty_print fixes from @mgee #82
• Compiler warning fixes for latest compiler releases
• Fix threading problems
• Fix linking error on MacOS Mavericks #88
• Allow non-const globals
• Make sure user cannot name a variable with :: in it #91
• Fix various string / map / vector size and count calls for compilers which have weird overloads for them. #90 #93 #95
• Make module search path relative to the currently running executable
• Build and work with wstring windows builds
• fix for some new line cases in the middle of a vector initialization from jespada

Changes since 5.1.0

• Add support for automatic conversion of arithmetic types when possible and when no ambiguous method dispatch exists.

Changes since 5.0.0

• Fix sizing of numeric constants to match that of the C++ standard
• Add support for u,ll,l,f suffixes for numeric constants
• Siginificant improvement in error reporting

Changes since 4.0.0

• Dropped boost in favor of C++11
• Separated out stdlib to make more options for compile time improvements

Changes since 3.1.0

• svenstaro: Unused variables and CMake consistency fixes
• Added support for returning pointers from functions (#13)
• Compile with -pedantic (#9)
• Fix issues with multiple ChaiScript object types having the same attribute name (#15)
• Prevent variable redeclaration in same scope (#22)
• mgee: Boxed_Number improvements (#27)
• Support switch statements (#34)
• Fix uint16 comparions (#26)
• Add ability to add const_var globals in Module objects (#14)
• Add support for ternary operators ?:
• Add headers to CMakeLists so they show up in IDEs
• Add ability to get vector of defined objects and vector of defined functions
• Fix memory leak in cyclical references
• Clean up static analysis issues discovered
• Fix vector construction to be consistent with map construction
• Increased unit tests to 161
• Performance enhancements

Changes since 3.0.0

• Numeric operations performance increased approximately 10x
• Looping operations performance increased up to 2x
• Engine start up time decreased
• Several parsing bugs related to index operators fixed
• Added full support for all C algebraic types: double, long double, float, int, long, char, uint8_t, uint16_t, uint32_t, uint64_t, int8_t, int16_t, int32_t, int64_t
• Enhanced support for capturing of exceptions thrown from ChaiScript in C++

Changes since 2.3.3

• Code simplifications
• Fully integrate documentation with source code in doxygen style comments
• Unit tests increased from 114 to 137
• Automatic conversion between boost::function objects and ChaiScript functions
• Many bug fixes
• Minor performance improvements
• Namespace reorganization to make end user code more accessible
• clang support
• VisualStudio 2010 Support
• Support for C++ base classes and automatic upcasting
• Remove __ reserved identifiers
• Better code organization to reduce #ifdefs
• clanmills: command line options for chai eval
• clanmills: parser cleanups and code reduction
• Function introspection and reflection
• Correct function dispatch order to account for base classes and provide a defined order of dispatch
• Predictable object lifetime that emulates C++ stack lifetime
• emarcotte: pkgconfig support
• standardize on method/member naming and indentation
• 64bit Visual Studio support
• Better support for const objects
• Drastic reduction of runtime exceptions - making debug builds orders of magnitude faster
• Support for platforms with no loadable module support
• Add helper macro for registering class