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)
|
2016-09-30 21:26:31 +00:00
|
|
|
* Modern C++14 API (no macros, use of strongly typed enums, lambdas, ranges etc.)
|
2016-08-27 18:26:52 +00:00
|
|
|
* C++14 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`
|
|
|
|
|
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)
|
2016-08-27 18:26:52 +00:00
|
|
|
* Custom allocator support (control over how heap memory is allocated)
|
2016-09-12 20:58:28 +00:00
|
|
|
* 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
|
|
|
|
|
|
|
|
*(I've just begun working on this, so many things do not apply yet)*
|
|
|
|
|
|
|
|
Libcubescript aims to provide a degree of thread safety by introducing a concept
|
|
|
|
of threads itself. A `CsState` essentially represents a thread - it contains a
|
|
|
|
pointer to CubeScript global state plus any sort of local state and a call/alias
|
|
|
|
stack. The main thread (i.e. the state created without any arguments) also owns
|
|
|
|
the globals; child states (threads) merely point to them.
|
|
|
|
|
|
|
|
Thus, by creating a child state (thread) you get access to all globals (which
|
|
|
|
is thread safe in the implementation) but you also get your own call/alias stack,
|
|
|
|
error buffer and other things that would otherwise be unsafe to access. Thus,
|
|
|
|
if you need to call into a single CubeScript from multiple threads, you simply
|
|
|
|
create a main state within your main program thread and a child state per each
|
|
|
|
spawned thread you want to use CubeScript from. Since they're isolated, there
|
|
|
|
is no problem - and libcubescript can remain almost entirely lockless.
|
|
|
|
|
|
|
|
Coroutines are a related concept in this case. We will reuse CubeScript threads
|
|
|
|
for them - merely extending them with a way to save the current execution state
|
|
|
|
and restore it later. The language itself (or rather, its standard library) will
|
|
|
|
be extended with new commands to resume and yield coroutines, as well as the
|
|
|
|
appropriate type extensions.
|
|
|
|
|
|
|
|
## Building and usage
|
2016-08-27 18:26:52 +00:00
|
|
|
|
|
|
|
The only dependency is OctaSTD:
|
|
|
|
|
|
|
|
https://git.octaforge.org/tools/octastd.git/
|
2015-08-08 16:24:05 +00:00
|
|
|
https://github.com/OctaForge/OctaSTD
|
|
|
|
|
2016-08-27 18:26:52 +00:00
|
|
|
If OctaSTD can work on your system, so can libcubescript.
|
2015-08-08 16:24:05 +00:00
|
|
|
|
2016-08-27 18:26:52 +00:00
|
|
|
The supplied Makefile builds a static library on Unix-like OSes. Link this
|
2016-09-01 16:42:28 +00:00
|
|
|
library together with your application and everything should just work. It also
|
|
|
|
builds the REPL.
|
|
|
|
|
|
|
|
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
|
2016-09-01 16:51:39 +00:00
|
|
|
for the REPL only (you don't need it to build libcubescript itself). The version
|
2016-09-04 19:46:16 +00:00
|
|
|
in the repository tracks Git revision https://github.com/antirez/linenoise/commit/c894b9e59f02203dbe4e2be657572cf88c4230c3.
|
2016-02-23 22:26:23 +00:00
|
|
|
|
2016-09-12 20:58:28 +00:00
|
|
|
## Licensing
|
|
|
|
|
2016-02-07 21:22:39 +00:00
|
|
|
See COPYING.md for licensing information.
|