readme.md
1<a href="https://www.patreon.com/bePatron?u=2977989&redirect_uri=https%3A%2F%2Fwww.patreon.com%2Flefticus">
2 <img height="40" width="204" src="https://s3-us-west-1.amazonaws.com/widget-images/become-patron-widget-medium%402x.png">
3</a>
4
5
6Master Status: [](https://travis-ci.org/ChaiScript/ChaiScript) [](https://ci.appveyor.com/project/lefticus/chaiscript) [](http://codecov.io/github/ChaiScript/ChaiScript?branch=master)
7
8Develop Status: [](https://travis-ci.org/ChaiScript/ChaiScript) [](https://ci.appveyor.com/project/lefticus/chaiscript/branch/develop) [](http://codecov.io/github/ChaiScript/ChaiScript?branch=develop)
9
10<a href="https://scan.coverity.com/projects/5297">
11 <img alt="Coverity Scan Build Status"
12 src="https://img.shields.io/coverity/scan/5297.svg"/>
13</a>
14
15ChaiScript
16
17http://www.chaiscript.com
18
19(c) 2009-2012 Jonathan Turner
20(c) 2009-2017 Jason Turner
21
22Release under the BSD license, see "license.txt" for details.
23
24
25Introduction
26============
27
28[](https://gitter.im/ChaiScript/ChaiScript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
29
30ChaiScript is one of the only embedded scripting language designed from the
31ground up to directly target C++ and take advantage of modern C++ development
32techniques, working with the developer like he expects it to work. Being a
33native C++ application, it has some advantages over existing embedded scripting
34languages:
35
361. It uses a header-only approach, which makes it easy to integrate with
37 existing projects.
382. It maintains type safety between your C++ application and the user scripts.
393. It supports a variety of C++ techniques including callbacks, overloaded
40 functions, class methods, and stl containers.
41
42
43Requirements
44============
45
46ChaiScript requires a C++14 compiler to build with support for variadic
47templates. It has been tested with gcc 4.9 and clang 3.6 (with libcxx).
48For more information see the build
49[dashboard](http://chaiscript.com/ChaiScript-BuildResults/index.html).
50
51Usage
52=====
53
54* Add the ChaiScript include directory to your project's header search path
55* Add `#include <chaiscript/chaiscript.hpp>` to your source file
56* Instantiate the ChaiScript engine in your application. For example, create a
57 new engine with the name `chai` like so: `chaiscript::ChaiScript chai`
58* The default behavior is to load the ChaiScript standard library from a
59 loadable module. A second option is to compile the library into your code,
60 see below for an example.
61
62Once instantiated, the engine is ready to start running ChaiScript source. You
63have two main options for processing ChaiScript source: a line at a time using
64`chai.eval(string)` and a file at a time using `chai.eval_file(fname)`
65
66To make functions in your C++ code visible to scripts, they must be registered
67with the scripting engine. To do so, call add:
68
69 chai.add(chaiscript::fun(&my_function), "my_function_name");
70
71Once registered the function will be visible to scripts as "my_function_name"
72
73Examples
74========
75
76ChaiScript is similar to ECMAScript (aka JavaScript(tm)), but with some
77modifications to make it easier to use. For usage examples see the "samples"
78directory, and for more in-depth look at the language, the unit tests in the
79"unittests" directory cover the most ground.
80
81For examples of how to register parts of your C++ application, see
82"example.cpp" in the "samples" directory. Example.cpp is verbose and shows every
83possible way of working with the library. For further documentation generate
84the doxygen documentation in the build folder or see the website
85http://www.chaiscript.com.
86
87
88The shortest complete example possible follows:
89
90```C++
91/// main.cpp
92
93#include <chaiscript/chaiscript.hpp>
94
95double function(int i, double j)
96{
97 return i * j;
98}
99
100int main()
101{
102 chaiscript::ChaiScript chai;
103 chai.add(chaiscript::fun(&function), "function");
104
105 double d = chai.eval<double>("function(3, 4.75);");
106}
107```
108
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}