2015-07-31 18:53:29 +00:00
|
|
|
# libcubescript
|
|
|
|
|
2016-09-15 22:00:31 +00:00
|
|
|
![CubeScript REPL](https://ftp.octaforge.org/q66/random/libcs_repl.gif)
|
2016-09-12 21:43:33 +00:00
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
## Overview
|
|
|
|
|
2016-09-10 15:16:27 +00:00
|
|
|
Libcubescript is an embeddable implementation of the CubeScript scripting
|
|
|
|
language. CubeScript is the console/config language of the Cube engines/games
|
2016-08-27 18:26:52 +00:00
|
|
|
(and derived engines/games). It's a simplistic language defined around the
|
|
|
|
idea of everything being a string, with Lisp-like syntax (allowing various
|
|
|
|
control structures to be defined as commands).
|
2015-07-31 18:53:29 +00:00
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
## Benefits and use cases
|
|
|
|
|
|
|
|
CubeScript is suitable for any use that calls for a simple scripting language
|
|
|
|
that is easy to embed. It's particularly strong at macro processing, so it can
|
|
|
|
be used as a preprocessor, or for any string-heavy use. Since it has descended
|
|
|
|
from a console language for a video game, it can still be used for that very
|
|
|
|
purpose, as well as a configuration file language.
|
|
|
|
|
|
|
|
Its thread-friendliness allows for usage in any context that requires parallel
|
|
|
|
processing and involvement of the scripting system in it.
|
|
|
|
|
|
|
|
As far as benefits over the original implementation go, while it is based on
|
|
|
|
the original implementation, it's largely rewritten; thus, it's gained many
|
|
|
|
advantages, including:
|
2015-08-08 16:24:05 +00:00
|
|
|
|
2016-09-10 15:13:43 +00:00
|
|
|
* Independent implementation (can be embedded in any project)
|
|
|
|
* No global state (multiple CubeScripts in a single program)
|
2021-03-20 07:22:15 +00:00
|
|
|
* Modern C++20 API
|
|
|
|
* C++ lambdas can be used as commands (including captures and type inference)
|
2016-09-10 15:13:43 +00:00
|
|
|
* Error handling including recovery (protected call system similar to Lua)
|
2016-09-30 21:26:31 +00:00
|
|
|
* Stricter parsing (strings cannot be left unfinished etc.)
|
2016-09-14 21:24:13 +00:00
|
|
|
* Loop control statements (`break` and `continue`)
|
2016-09-10 15:13:43 +00:00
|
|
|
* No manual memory mangement, values manage themselves
|
2016-08-27 18:26:52 +00:00
|
|
|
* Clean codebase that is easy to read and contribute to
|
2016-09-10 15:13:43 +00:00
|
|
|
* Support for arbitrary size integers and floats (can be set at compile time)
|
2016-08-27 18:26:52 +00:00
|
|
|
* Allows building into a static or shared library, supports `-fvisibility=hidden`
|
2021-03-21 18:23:23 +00:00
|
|
|
* Custom allocator support (control over how heap memory is allocated)
|
2016-08-27 18:26:52 +00:00
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
There are some features that are a work in progress and will come later:
|
2016-08-27 18:26:52 +00:00
|
|
|
|
2016-09-20 20:32:46 +00:00
|
|
|
* More helpful debug information (proper line infos at both parse and run time)
|
2016-09-12 20:58:28 +00:00
|
|
|
* A degree of thread safety (see below)
|
|
|
|
* Coroutines
|
|
|
|
|
|
|
|
The API is currently very unstable, as is the actual codebase. Therefore you
|
|
|
|
should not use the project in production environments just yet, but you're
|
|
|
|
also free to experiment - feedback is welcome.
|
|
|
|
|
|
|
|
**The project is also open for contributions.** You can use pull requests on
|
|
|
|
GitHub and there is also a discussion channel `#octaforge` on FreeNode; this
|
|
|
|
project is a part of the larger OctaForge umbrella.
|
2016-08-27 18:26:52 +00:00
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
## Threads and coroutines
|
|
|
|
|
2018-04-28 20:25:03 +00:00
|
|
|
*(In progress)*
|
|
|
|
|
|
|
|
Libcubescript supports integration with coroutines and threads by providing a
|
|
|
|
concept of threads itself. You can create a thread (child state) using the
|
|
|
|
main state and it will share global data with the main state, but it also
|
|
|
|
has its own call stack.
|
|
|
|
|
|
|
|
The "global" state is thread safe, allowing concurrent access from multiple
|
|
|
|
threads. The "local" state can be yielded as a part of the coroutine without
|
|
|
|
affecting any other threads.
|
|
|
|
|
|
|
|
This functionality is not exposed into the language itself, but it can be
|
|
|
|
utilized in the outside native code.
|
2016-09-12 20:58:28 +00:00
|
|
|
|
|
|
|
## Building and usage
|
2016-08-27 18:26:52 +00:00
|
|
|
|
2021-03-20 07:22:15 +00:00
|
|
|
There are no dependencies (other than a suitable compiler and the standard
|
|
|
|
library).
|
2015-08-08 16:24:05 +00:00
|
|
|
|
2021-03-27 23:56:11 +00:00
|
|
|
Libcubescript is built using `meson`. After installing it, you can do
|
|
|
|
something like this:
|
2020-09-27 07:00:12 +00:00
|
|
|
|
|
|
|
~~~
|
|
|
|
mkdir build && cd build
|
|
|
|
meson ..
|
2021-03-20 07:22:15 +00:00
|
|
|
ninja all
|
2020-09-27 07:00:12 +00:00
|
|
|
~~~
|
|
|
|
|
2021-03-27 23:56:11 +00:00
|
|
|
Link the `libcubescript` library together with your application and everything
|
|
|
|
should just work. It also builds the REPL by default.
|
2016-09-01 16:42:28 +00:00
|
|
|
|
2021-03-27 23:56:11 +00:00
|
|
|
The project also bundles the `linenoise` line editing library which has been
|
|
|
|
modified to compile cleanly as C++ (with the same flags as `libcubescript`).
|
2021-03-20 07:22:15 +00:00
|
|
|
It's used strictly for the REPL only (you don't need it to build libcubescript
|
|
|
|
itself). The version in the repository tracks Git revision
|
2021-03-28 00:05:09 +00:00
|
|
|
https://github.com/antirez/linenoise/commit/97d2850af13c339369093b78abe5265845d78220.
|
2016-02-23 22:26:23 +00:00
|
|
|
|
2021-03-27 23:56:11 +00:00
|
|
|
For the REPL (when not disabled with `-Drepl=disabled`) you have a choice of
|
|
|
|
two line editing libraries. The `readline` library can be used (but is always
|
|
|
|
disabled by default, so you need to enable it manually). On Unix-like systems,
|
|
|
|
`linenoise` can be used (and is fully featured) and is enabled by default; on
|
|
|
|
Windows it's disabled. There is also a fallback without any line editing, used
|
|
|
|
when you don't have either (but then there is no line editing or history).
|
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
## Licensing
|
|
|
|
|
2016-02-07 21:22:39 +00:00
|
|
|
See COPYING.md for licensing information.
|