2015-07-31 20:53:29 +02:00
|
|
|
# libcubescript
|
|
|
|
|
2016-09-16 00:00:31 +02:00
|
|
|
![CubeScript REPL](https://ftp.octaforge.org/q66/random/libcs_repl.gif)
|
2016-09-12 23:43:33 +02:00
|
|
|
|
2016-09-12 22:58:28 +02:00
|
|
|
## Overview
|
|
|
|
|
2016-09-10 17:16:27 +02: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 20:26:52 +02: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 20:53:29 +02:00
|
|
|
|
2016-09-12 22:58:28 +02: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 18:24:05 +02:00
|
|
|
|
2016-09-10 17:13:43 +02:00
|
|
|
* Independent implementation (can be embedded in any project)
|
|
|
|
* No global state (multiple CubeScripts in a single program)
|
2021-03-20 08:22:15 +01:00
|
|
|
* Modern C++20 API
|
|
|
|
* C++ lambdas can be used as commands (including captures and type inference)
|
2016-09-10 17:13:43 +02:00
|
|
|
* Error handling including recovery (protected call system similar to Lua)
|
2016-09-30 23:26:31 +02:00
|
|
|
* Stricter parsing (strings cannot be left unfinished etc.)
|
2016-09-14 23:24:13 +02:00
|
|
|
* Loop control statements (`break` and `continue`)
|
2016-09-10 17:13:43 +02:00
|
|
|
* No manual memory mangement, values manage themselves
|
2016-08-27 20:26:52 +02:00
|
|
|
* Clean codebase that is easy to read and contribute to
|
2016-09-10 17:13:43 +02:00
|
|
|
* Support for arbitrary size integers and floats (can be set at compile time)
|
2016-08-27 20:26:52 +02:00
|
|
|
* Allows building into a static or shared library, supports `-fvisibility=hidden`
|
2021-03-21 19:23:23 +01:00
|
|
|
* Custom allocator support (control over how heap memory is allocated)
|
2016-08-27 20:26:52 +02:00
|
|
|
|
2016-09-12 22:58:28 +02:00
|
|
|
There are some features that are a work in progress and will come later:
|
2016-08-27 20:26:52 +02:00
|
|
|
|
2016-09-20 22:32:46 +02:00
|
|
|
* More helpful debug information (proper line infos at both parse and run time)
|
2016-09-12 22:58:28 +02: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 20:26:52 +02:00
|
|
|
|
2016-09-12 22:58:28 +02:00
|
|
|
## Threads and coroutines
|
|
|
|
|
2018-04-28 22:25:03 +02: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 22:58:28 +02:00
|
|
|
|
|
|
|
## Building and usage
|
2016-08-27 20:26:52 +02:00
|
|
|
|
2021-03-20 08:22:15 +01:00
|
|
|
There are no dependencies (other than a suitable compiler and the standard
|
|
|
|
library).
|
2015-08-08 18:24:05 +02:00
|
|
|
|
2020-09-27 09:00:12 +02:00
|
|
|
Libostd is built using Meson. Therefore, you need to install Meson and then
|
|
|
|
you can compile it as usual. Typically, this will be something like
|
|
|
|
|
|
|
|
~~~
|
|
|
|
mkdir build && cd build
|
|
|
|
meson ..
|
2021-03-20 08:22:15 +01:00
|
|
|
ninja all
|
2020-09-27 09:00:12 +02:00
|
|
|
~~~
|
|
|
|
|
2021-03-20 08:22:15 +01:00
|
|
|
Link the libcubescript library together with your application and everything
|
|
|
|
should just work. It also builds the REPL.
|
2016-09-01 18:42:28 +02:00
|
|
|
|
2021-03-20 08:22:15 +01: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).
|
|
|
|
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
|
|
|
|
https://github.com/antirez/linenoise/commit/c894b9e59f02203dbe4e2be657572cf88c4230c3.
|
2016-02-23 23:26:23 +01:00
|
|
|
|
2016-09-12 22:58:28 +02:00
|
|
|
## Licensing
|
|
|
|
|
2016-02-07 22:22:39 +01:00
|
|
|
See COPYING.md for licensing information.
|