From ced9112c5c8f44e61c09a75c0295e54a83179a54 Mon Sep 17 00:00:00 2001 From: q66 Date: Mon, 12 Sep 2016 22:58:28 +0200 Subject: [PATCH] more readme --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 0820652..87bdb7b 100644 --- a/README.md +++ b/README.md @@ -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.