add initial doxygen documentation infra
parent
c4e311d71a
commit
8b1aaa63fe
|
@ -1,7 +1,7 @@
|
||||||
subprojects/libostd
|
|
||||||
*.o
|
*.o
|
||||||
*.core
|
*.core
|
||||||
*.so
|
*.so
|
||||||
build/
|
build/
|
||||||
.idea/
|
.idea/
|
||||||
.vscode/
|
.vscode/
|
||||||
|
doc/output
|
||||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,107 @@
|
||||||
|
# Libcubescript Documentation {#index}
|
||||||
|
|
||||||
|
## What is Cubescript?
|
||||||
|
|
||||||
|
ubescript is a minimal scripting language first introduced in the Cube FPS
|
||||||
|
and carried over into derived games and game engines such as Sauerbraten.
|
||||||
|
Originally being little more than a few hundred lines of code, serving
|
||||||
|
primarily as the console and configuration file format of the game, it
|
||||||
|
grew more advanced features as well as a bytecode VM.
|
||||||
|
|
||||||
|
Nowadays, it is a minimal but relatively fully featured scripting language
|
||||||
|
based around the concept that everything can be interpreted as a string.
|
||||||
|
It excels at its original purpose as well as things like text preprocessing.
|
||||||
|
It comes with a Lisp-like syntax and a variety of standard library functions.
|
||||||
|
|
||||||
|
## What is Libcubescript?
|
||||||
|
|
||||||
|
Libcubescript is a project that aims to provide an independent, improved,
|
||||||
|
separate implementation of the language, available as a library, intended to
|
||||||
|
satisfy the needs of the OctaForge project. It was originally forked from
|
||||||
|
Cubescript as present in the Tesseract game/engine and gradually rewritten;
|
||||||
|
right now, very little of the original code remains. At language level it is
|
||||||
|
mostly compatible with the other implementations (although with a stricter
|
||||||
|
parser and extra features), while the standard library does not aim to be
|
||||||
|
fully compatible. Some features are also left up to the user to customize,
|
||||||
|
so that it is not tied to game engines feature-wise.
|
||||||
|
|
||||||
|
Like the codebase it is derived from, it is available under the permissive
|
||||||
|
zlib license, and therefore compatible with just about anything.
|
||||||
|
|
||||||
|
## Benefits and differences
|
||||||
|
|
||||||
|
There's a variety of things that set this implementation apart:
|
||||||
|
|
||||||
|
* It's independent and can be embedded in any project
|
||||||
|
* There is no global state, so you can have as many Cubescripts as you want,
|
||||||
|
in one program
|
||||||
|
* Written in C++20, following modern language conventions, both internally
|
||||||
|
and at API level
|
||||||
|
* That means the ability to use lambdas as commands, including captures,
|
||||||
|
type inference and so on
|
||||||
|
* There is a robust allocator system in place, and all memory the library
|
||||||
|
uses is allocated through it; that gives you complete control over its
|
||||||
|
memory (for tracking, sandboxing, limits, etc.)
|
||||||
|
* A large degree of memory safety, with no manual management
|
||||||
|
* Strings are interned, with a single reference counted instance of any
|
||||||
|
string existing at a time, which lowers memory usage and simplifies its
|
||||||
|
management
|
||||||
|
* Minimal stack memory usage, which means no artificial limits on recursion
|
||||||
|
depth as well as safe usage from threads and coroutines with small stacks
|
||||||
|
* Errors will no longer cause the interpreter to march on, instead acting
|
||||||
|
like real errors
|
||||||
|
* Protected calls allow you to catch errors in a similar way to exceptions,
|
||||||
|
and nearly every error can be caught
|
||||||
|
* Stricter parsing, with things like unfinished strings being caught
|
||||||
|
* Loops now have `break` and `continue` statements
|
||||||
|
* Customizable integer and floating point types
|
||||||
|
* Full support for symbol visibility in API
|
||||||
|
* Highly portable and cross-platform, no dependencies other than a compiler
|
||||||
|
* Clean codebase that is easy to pick up and contribute to
|
||||||
|
|
||||||
|
## Building and usage
|
||||||
|
|
||||||
|
The library has absolutely no dependencies other than a C++20 compiler,
|
||||||
|
similarly there are no dependencies on system or architecture specific
|
||||||
|
things, so it should work on any OS and any CPU.
|
||||||
|
|
||||||
|
The C++20 support does not have to be complete. These are the baselines
|
||||||
|
(which are ensured by the CI):
|
||||||
|
|
||||||
|
* GCC 10
|
||||||
|
* Clang 10 (with libstdc++ or libc++)
|
||||||
|
* Microsoft Visual C++ 2019
|
||||||
|
|
||||||
|
Older versions of either of these are known not to work.
|
||||||
|
|
||||||
|
You will need [Meson](https://mesonbuild.com/) to build the project. Most
|
||||||
|
Unix-like systems have it in their package management, on Windows there is
|
||||||
|
an installer available on their website. Being written in Python, you can
|
||||||
|
also use `pip` to get an up to date version on any OS.
|
||||||
|
|
||||||
|
Once you have it, compiling is simple, e.g. on Unix-likes you can do:
|
||||||
|
|
||||||
|
~~~
|
||||||
|
mkdir build && cd build
|
||||||
|
meson ..
|
||||||
|
ninja all
|
||||||
|
~~~
|
||||||
|
|
||||||
|
Refer to Meson's manual for how to customize whether you want a shared or
|
||||||
|
static library and so on. By default, you will get a shared library plus
|
||||||
|
a REPL (interactive interpreter). The REPL also serves as an example of
|
||||||
|
how to use the API.
|
||||||
|
|
||||||
|
If you don't want the REPL, use `-Drepl=disabled`. When compiled, it can
|
||||||
|
have support for line editing and command history. This is provided through
|
||||||
|
`linenoise` (which is a minimal single-file line editing library bundled
|
||||||
|
with the project, and is the default). In case you're on a platform that
|
||||||
|
`linenoise` does not support (highly unlikely), there is a fallback without
|
||||||
|
any line editing as well. Pass `-Dlinenoise=disabled` to use the fallback.
|
||||||
|
|
||||||
|
The version of `linenoise` bundled with the project is `cpp-linenoise`, available
|
||||||
|
at https://github.com/yhirose/cpp-linenoise. Our version is modified, so that
|
||||||
|
it builds cleanly with our flags, and so that it supports the "hints" feature
|
||||||
|
available in original `linenoise`. Other than the modifications, it is baseed
|
||||||
|
on upstream git revision `a927043cdd5bfe203560802e56a7e7ed43156ed3`. The reason
|
||||||
|
we use this instead of upstream `linenoise` is Windows support.
|
|
@ -1,3 +1,13 @@
|
||||||
|
/** @file cubescript.hh
|
||||||
|
*
|
||||||
|
* @brief The main include file for the library.
|
||||||
|
*
|
||||||
|
* Include this file (like `#include <cubescript/cubescript.hh>`) to access
|
||||||
|
* the API. You should generally not include the individual sub-files.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_HH
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,12 @@
|
||||||
|
/** @file callable.hh
|
||||||
|
*
|
||||||
|
* @brief Internal callable data structure.
|
||||||
|
*
|
||||||
|
* There is no public API in this file.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
|
||||||
|
|
||||||
|
@ -10,6 +19,7 @@
|
||||||
namespace cubescript {
|
namespace cubescript {
|
||||||
namespace internal {
|
namespace internal {
|
||||||
|
|
||||||
|
/** @private */
|
||||||
template<typename R, typename ...A>
|
template<typename R, typename ...A>
|
||||||
struct callable {
|
struct callable {
|
||||||
private:
|
private:
|
||||||
|
|
|
@ -1,3 +1,12 @@
|
||||||
|
/** @file error.hh
|
||||||
|
*
|
||||||
|
* @brief Error handling API.
|
||||||
|
*
|
||||||
|
* Defines structures and methods used for error handling in the library.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,14 @@
|
||||||
|
/** @file ident.hh
|
||||||
|
*
|
||||||
|
* @brief Identifier management.
|
||||||
|
*
|
||||||
|
* Identifiers in `libcubescript` represent variables, aliases, commands
|
||||||
|
* and so on. This file contains the handles for those and everything you
|
||||||
|
* need to interface with them.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,50 @@
|
||||||
|
/** @file platform.hh
|
||||||
|
*
|
||||||
|
* @brief Utility macros and platform abstraction.
|
||||||
|
*
|
||||||
|
* Defines utility macros that you are not supposed to use yourself.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
|
||||||
|
|
||||||
namespace cubescript {
|
namespace cubescript {
|
||||||
|
|
||||||
|
#ifdef LIBCS_GENERATING_DOC
|
||||||
|
|
||||||
|
/** @brief Public API tag.
|
||||||
|
*
|
||||||
|
* All public API of the library is tagged like this.
|
||||||
|
*
|
||||||
|
* On Windows, the behavior of this is conditional. If `LIBCUBESCRIPT_DLL` is
|
||||||
|
* not defined, it expands to no value (that means we're either building or
|
||||||
|
* using a static library). If it is defined, it will tag the API with either
|
||||||
|
* `dllexport` (when building the lib, defined with `LIBCUBESCRIPT_BUILD`)
|
||||||
|
* or `dllimport` (when using the lib).
|
||||||
|
*
|
||||||
|
* On Unix-like systems with GCC-style compilers, this will mark the API as
|
||||||
|
* externally visible. The library is by default built so that symbols are
|
||||||
|
* normally hidden, so any external API needs to be tagged.
|
||||||
|
*
|
||||||
|
* @see LIBCUBESCRIPT_LOCAL
|
||||||
|
*/
|
||||||
|
#define LIBCUBESCRIPT_EXPORT
|
||||||
|
|
||||||
|
/** @brief Private API tag.
|
||||||
|
*
|
||||||
|
* Since symbols are private by default, this usually has no purpose. However,
|
||||||
|
* when marking entire structures exported, this affects all methods inside;
|
||||||
|
* in those cases this can be used to mark specific methods as for use only
|
||||||
|
* inside of the library (private methods not called in any public header).
|
||||||
|
*
|
||||||
|
* @see LIBCUBESCRIPT_EXPORT
|
||||||
|
*/
|
||||||
|
#define LIBCUBESCRIPT_LOCAL
|
||||||
|
|
||||||
|
#else
|
||||||
|
|
||||||
#if defined(__CYGWIN__) || (defined(_WIN32) && !defined(_XBOX_VER))
|
#if defined(__CYGWIN__) || (defined(_WIN32) && !defined(_XBOX_VER))
|
||||||
# ifdef LIBCUBESCRIPT_DLL
|
# ifdef LIBCUBESCRIPT_DLL
|
||||||
# ifdef LIBCUBESCRIPT_BUILD
|
# ifdef LIBCUBESCRIPT_BUILD
|
||||||
|
@ -24,6 +66,8 @@ namespace cubescript {
|
||||||
# endif
|
# endif
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
#endif /* LIBCS_GENERATING_DOC */
|
||||||
|
|
||||||
} /* namespace cubescript */
|
} /* namespace cubescript */
|
||||||
|
|
||||||
#endif /* LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH */
|
#endif /* LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH */
|
||||||
|
|
|
@ -1,3 +1,13 @@
|
||||||
|
/** @file state.hh
|
||||||
|
*
|
||||||
|
* @brief State API.
|
||||||
|
*
|
||||||
|
* The state is the main handle using which you interact with the language
|
||||||
|
* from C++. It represents a single Cubescript thread.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,14 @@
|
||||||
|
/** @file util.hh
|
||||||
|
*
|
||||||
|
* @brief Utility API.
|
||||||
|
*
|
||||||
|
* This contains various utilities that don't quite fit within the other
|
||||||
|
* structures, but provide convenience; this includes things such as parsing
|
||||||
|
* of lists, strings and numbers.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,15 @@
|
||||||
|
/** @file value.hh
|
||||||
|
*
|
||||||
|
* @brief Value API.
|
||||||
|
*
|
||||||
|
* This file contains value handles. These include the main value handle,
|
||||||
|
* which represents any Cubescript value as a tagged union (and you use it
|
||||||
|
* for handling of things such as command arguments and return values), as
|
||||||
|
* well as string references and bytecode references.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
|
||||||
|
|
||||||
|
|
|
@ -1,14 +1,89 @@
|
||||||
|
/** @file cubescript_conf.hh
|
||||||
|
*
|
||||||
|
* @brief Library configuration.
|
||||||
|
*
|
||||||
|
* This is the one file you are allowed to touch as a user - it contains
|
||||||
|
* settings that are used when building the library, notably the integer
|
||||||
|
* and floating point types used and their formats (used for conversions).
|
||||||
|
*
|
||||||
|
* Usually you will not want to touch this, but occasionally you might want
|
||||||
|
* to, e.g. to make a build of the library that uses double precision floats
|
||||||
|
* or larger integers.
|
||||||
|
*
|
||||||
|
* @copyright See COPYING.md in the project tree for further information.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
|
#ifndef LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
|
||||||
#define LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
|
#define LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
|
||||||
|
|
||||||
#include <type_traits>
|
#include <type_traits>
|
||||||
|
|
||||||
namespace cubescript {
|
namespace cubescript {
|
||||||
|
/** @brief The integer type used.
|
||||||
|
*
|
||||||
|
* While Cubescript is a stringly typed language, it uses integers and
|
||||||
|
* floats internally in a transparent manner where possible, and allows
|
||||||
|
* you to retrieve and pass integers and floats in commands and so on.
|
||||||
|
*
|
||||||
|
* This is the integer type used. By default, it's `int`, which is a
|
||||||
|
* 32-bit signed integer on most platforms. Keep in mind that is is
|
||||||
|
* necessary for this type to be a signed integer type.
|
||||||
|
*
|
||||||
|
* @see float_type
|
||||||
|
* @see INTEGER_FORMAT
|
||||||
|
*/
|
||||||
using integer_type = int;
|
using integer_type = int;
|
||||||
|
|
||||||
|
/** @brief The floating point type used.
|
||||||
|
*
|
||||||
|
* By default, this is `float`, which is on most platforms an IEEE754
|
||||||
|
* binary32 data type.
|
||||||
|
*
|
||||||
|
* @see integer_type
|
||||||
|
* @see FLOAT_FORMAT
|
||||||
|
* @see ROUND_FLOAT_FORMAT
|
||||||
|
*/
|
||||||
using float_type = float;
|
using float_type = float;
|
||||||
|
|
||||||
|
/** @brief The integer format used.
|
||||||
|
*
|
||||||
|
* This is a formatting specifier as in `printf`, corresponding to the
|
||||||
|
* `integer_type` used. It is used to handle conversions from the type
|
||||||
|
* to strings, as well as in the default integer variable handler when
|
||||||
|
* printing.
|
||||||
|
*
|
||||||
|
* There are no special restrictions imposed on the floating point type
|
||||||
|
* other than that it actually has to be floating point.
|
||||||
|
*
|
||||||
|
* @see integer_type
|
||||||
|
* @see FLOAT_FORMAT
|
||||||
|
*/
|
||||||
constexpr auto const INTEGER_FORMAT = "%d";
|
constexpr auto const INTEGER_FORMAT = "%d";
|
||||||
|
|
||||||
|
/** @brief The float format used.
|
||||||
|
*
|
||||||
|
* This is a formatting specifier as in `printf`, corresponding to the
|
||||||
|
* `float_type` used. It is used to handle conversions from the type to
|
||||||
|
* strings, as well as in the default float variable handler when printing.
|
||||||
|
*
|
||||||
|
* When the floating point value is equivalent to its integer value (i.e.
|
||||||
|
* it has no decimal point), ROUND_FLOAT_FORMAT is used.
|
||||||
|
*
|
||||||
|
* @see float_type
|
||||||
|
* @see ROUND_FLOAT_FORMAT
|
||||||
|
* @see INTEGER_FORMAT
|
||||||
|
*/
|
||||||
constexpr auto const FLOAT_FORMAT = "%.7g";
|
constexpr auto const FLOAT_FORMAT = "%.7g";
|
||||||
|
|
||||||
|
/** @brief The round float format used.
|
||||||
|
*
|
||||||
|
* This is a formatting specifier as in `printf`, corresponding to the
|
||||||
|
* `float_type` used. It's like `FLOAT_FORMAT` but used when the value
|
||||||
|
* has no decimal point.
|
||||||
|
*
|
||||||
|
* @see float_type
|
||||||
|
* @see FLOAT_FORMAT
|
||||||
|
*/
|
||||||
constexpr auto const ROUND_FLOAT_FORMAT = "%.1f";
|
constexpr auto const ROUND_FLOAT_FORMAT = "%.1f";
|
||||||
} /* namespace cubescript */
|
} /* namespace cubescript */
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue