JDBtracker
/
libcubescript
forked from OctaForge/libcubescript
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

more readme

master
Daniel Kolesa 2016-09-12 22:58:28 +02:00
parent f97f896017
commit ced9112c5c
1 changed files with 55 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
README.md
View File

@ -1,14 +1,27 @@
# libcubescript
## Overview
Libcubescript is an embeddable implementation of the CubeScript scripting
language. CubeScript is the console/config language of the Cube engines/games
(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).
Libcubescript is originally based on the implementation from the Cube 2 engine,
but largely rewritten. Here are some of the benefits over the original
implementation:
## 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:
* Independent implementation (can be embedded in any project)
* No global state (multiple CubeScripts in a single program)
@ -20,13 +33,46 @@ implementation:
* Support for arbitrary size integers and floats (can be set at compile time)
* Allows building into a static or shared library, supports `-fvisibility=hidden`
Upcoming features:
There are some features that are a work in progress and will come later:
* Thread safety (safely call into a single Cubescript state from multiple threads)
* A degree of thread safety (see below)
* Custom allocator support (control over how heap memory is allocated)
* Coroutines
* Loop control statements (`break` and `continue`)
The API is currently unstable and a work in progress. The codebase itself is
also changing very quickly.
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.
## 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
The only dependency is OctaSTD:
@ -44,4 +90,6 @@ to compile cleanly as C++ (with the same flags as libcubescript). It's used stri
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.
## Licensing
See COPYING.md for licensing information.