mirror of
https://github.com/ChaiScript/ChaiScript.git
synced 2026-04-30 19:09:26 +08:00
092ec417d2
* Fix #628: Add EBNF grammar for railroad diagram generation Add a formal EBNF grammar file (grammar/chaiscript.ebnf) that can be pasted into rr (https://www.bottlecaps.de/rr/ui) to produce navigable railroad diagrams of ChaiScript's syntax. The grammar was validated against the parser implementation and covers all language constructs including class inheritance, guard conditions, raw strings, and const declarations that were missing from the original proposal. A reference section was added to the cheatsheet, and a regression test exercises every documented grammar construct. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address review: add grammar railroad diagram link to README Add a Grammar section to readme.md linking to the EBNF grammar file and to mingodad's railroad diagram generator for direct viewing. Requested by @lefticus in PR #673 review. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: leftibot <leftibot@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
124 lines
5.0 KiB
Markdown
124 lines
5.0 KiB
Markdown
<a href="https://www.patreon.com/bePatron?u=2977989&redirect_uri=https%3A%2F%2Fwww.patreon.com%2Flefticus">
|
|
<img height="40" width="204" src="https://s3-us-west-1.amazonaws.com/widget-images/become-patron-widget-medium%402x.png">
|
|
</a>
|
|
|
|
|
|
Master Status: [](https://travis-ci.org/ChaiScript/ChaiScript) [](https://ci.appveyor.com/project/lefticus/chaiscript) [](http://codecov.io/github/ChaiScript/ChaiScript?branch=master)
|
|
|
|
Develop Status: [](https://travis-ci.org/ChaiScript/ChaiScript) [](https://ci.appveyor.com/project/lefticus/chaiscript/branch/develop) [](http://codecov.io/github/ChaiScript/ChaiScript?branch=develop)
|
|
|
|
ChaiScript
|
|
|
|
http://www.chaiscript.com
|
|
|
|
(c) 2009-2012 Jonathan Turner
|
|
(c) 2009-2017 Jason Turner
|
|
|
|
Release under the BSD license, see "license.txt" for details.
|
|
|
|
|
|
Introduction
|
|
============
|
|
|
|
[](https://gitter.im/ChaiScript/ChaiScript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
|
|
ChaiScript is one of the only embedded scripting language designed from the
|
|
ground up to directly target C++ and take advantage of modern C++ development
|
|
techniques, working with the developer how they would expect it to work. Being a
|
|
native C++ application, it has some advantages over existing embedded scripting
|
|
languages:
|
|
|
|
1. It uses a header-only approach, which makes it easy to integrate with
|
|
existing projects.
|
|
2. It maintains type safety between your C++ application and the user scripts.
|
|
3. It supports a variety of C++ techniques including callbacks, overloaded
|
|
functions, class methods, and stl containers.
|
|
|
|
|
|
Requirements
|
|
============
|
|
|
|
ChaiScript requires a C++17 compiler to build with support for variadic
|
|
templates. It has been tested with gcc 7 and clang 6 (with libcxx).
|
|
|
|
Installation using vcpkg
|
|
========================
|
|
|
|
You can download and install ChaiScript using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
|
|
|
|
git clone https://github.com/Microsoft/vcpkg.git
|
|
cd vcpkg
|
|
./bootstrap-vcpkg.sh
|
|
./vcpkg integrate install
|
|
vcpkg install chaiscript
|
|
|
|
The ChaiScript port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
|
|
|
|
Usage
|
|
=====
|
|
|
|
* Add the ChaiScript include directory to your project's header search path
|
|
* Add `#include <chaiscript/chaiscript.hpp>` to your source file
|
|
* Instantiate the ChaiScript engine in your application. For example, create a
|
|
new engine with the name `chai` like so: `chaiscript::ChaiScript chai`
|
|
* The default behavior is to load the ChaiScript standard library from a
|
|
loadable module. A second option is to compile the library into your code,
|
|
see below for an example.
|
|
|
|
Once instantiated, the engine is ready to start running ChaiScript source. You
|
|
have two main options for processing ChaiScript source: a line at a time using
|
|
`chai.eval(string)` and a file at a time using `chai.eval_file(fname)`
|
|
|
|
To make functions in your C++ code visible to scripts, they must be registered
|
|
with the scripting engine. To do so, call add:
|
|
|
|
chai.add(chaiscript::fun(&my_function), "my_function_name");
|
|
|
|
Once registered the function will be visible to scripts as "my_function_name"
|
|
|
|
Examples
|
|
========
|
|
|
|
ChaiScript is similar to ECMAScript (aka JavaScript(tm)), but with some
|
|
modifications to make it easier to use. For usage examples see the "samples"
|
|
directory, and for more in-depth look at the language, the unit tests in the
|
|
"unittests" directory cover the most ground.
|
|
|
|
For examples of how to register parts of your C++ application, see
|
|
"example.cpp" in the "samples" directory. Example.cpp is verbose and shows every
|
|
possible way of working with the library. For further documentation generate
|
|
the doxygen documentation in the build folder or see the website
|
|
http://www.chaiscript.com.
|
|
|
|
|
|
Grammar
|
|
=======
|
|
|
|
A formal EBNF grammar for ChaiScript is available in
|
|
[grammar/chaiscript.ebnf](grammar/chaiscript.ebnf). To view it as a railroad
|
|
diagram, paste the grammar into
|
|
[mingodad's railroad diagram generator](https://mingodad.github.io/plgh/json2ebnf.html)
|
|
or [bottlecaps.de/rr](https://www.bottlecaps.de/rr/ui).
|
|
|
|
|
|
The shortest complete example possible follows:
|
|
|
|
```C++
|
|
/// main.cpp
|
|
|
|
#include <chaiscript/chaiscript.hpp>
|
|
|
|
double function(int i, double j)
|
|
{
|
|
return i * j;
|
|
}
|
|
|
|
int main()
|
|
{
|
|
chaiscript::ChaiScript chai;
|
|
chai.add(chaiscript::fun(&function), "function");
|
|
|
|
double d = chai.eval<double>("function(3, 4.75);");
|
|
}
|
|
```
|