more readme
parent
f97f896017
commit
ced9112c5c
62
README.md
62
README.md
|
@ -1,14 +1,27 @@
|
||||||
# libcubescript
|
# libcubescript
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
Libcubescript is an embeddable implementation of the CubeScript scripting
|
Libcubescript is an embeddable implementation of the CubeScript scripting
|
||||||
language. CubeScript is the console/config language of the Cube engines/games
|
language. CubeScript is the console/config language of the Cube engines/games
|
||||||
(and derived engines/games). It's a simplistic language defined around the
|
(and derived engines/games). It's a simplistic language defined around the
|
||||||
idea of everything being a string, with Lisp-like syntax (allowing various
|
idea of everything being a string, with Lisp-like syntax (allowing various
|
||||||
control structures to be defined as commands).
|
control structures to be defined as commands).
|
||||||
|
|
||||||
Libcubescript is originally based on the implementation from the Cube 2 engine,
|
## Benefits and use cases
|
||||||
but largely rewritten. Here are some of the benefits over the original
|
|
||||||
implementation:
|
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)
|
* Independent implementation (can be embedded in any project)
|
||||||
* No global state (multiple CubeScripts in a single program)
|
* 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)
|
* Support for arbitrary size integers and floats (can be set at compile time)
|
||||||
* Allows building into a static or shared library, supports `-fvisibility=hidden`
|
* 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)
|
* 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
|
The API is currently very unstable, as is the actual codebase. Therefore you
|
||||||
also changing very quickly.
|
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:
|
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
|
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.
|
in the repository tracks Git revision https://github.com/antirez/linenoise/commit/c894b9e59f02203dbe4e2be657572cf88c4230c3.
|
||||||
|
|
||||||
|
## Licensing
|
||||||
|
|
||||||
See COPYING.md for licensing information.
|
See COPYING.md for licensing information.
|
||||||
|
|
Loading…
Reference in New Issue