An embeddable, thread-safe implementation of the cubescript language
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

91 lines
3.9 KiB

5 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
4 years ago
5 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
3 years ago
3 years ago
5 years ago
3 years ago
5 years ago
4 years ago
5 years ago
4 years ago
  1. # libcubescript
  2. ![CubeScript REPL](https://ftp.octaforge.org/q66/random/libcs_repl.gif)
  3. ## Overview
  4. Libcubescript is an embeddable implementation of the CubeScript scripting
  5. language. CubeScript is the console/config language of the Cube engines/games
  6. (and derived engines/games). It's a simplistic language defined around the
  7. idea of everything being a string, with Lisp-like syntax (allowing various
  8. control structures to be defined as commands).
  9. ## Benefits and use cases
  10. CubeScript is suitable for any use that calls for a simple scripting language
  11. that is easy to embed. It's particularly strong at macro processing, so it can
  12. be used as a preprocessor, or for any string-heavy use. Since it has descended
  13. from a console language for a video game, it can still be used for that very
  14. purpose, as well as a configuration file language.
  15. Its thread-friendliness allows for usage in any context that requires parallel
  16. processing and involvement of the scripting system in it.
  17. As far as benefits over the original implementation go, while it is based on
  18. the original implementation, it's largely rewritten; thus, it's gained many
  19. advantages, including:
  20. * Independent implementation (can be embedded in any project)
  21. * No global state (multiple CubeScripts in a single program)
  22. * Modern C++17 API (no macros, use of strongly typed enums, lambdas, ranges etc.)
  23. * C++17 lambdas can be used as commands (including captures and type inference)
  24. * Error handling including recovery (protected call system similar to Lua)
  25. * Stricter parsing (strings cannot be left unfinished etc.)
  26. * Loop control statements (`break` and `continue`)
  27. * No manual memory mangement, values manage themselves
  28. * Clean codebase that is easy to read and contribute to
  29. * Support for arbitrary size integers and floats (can be set at compile time)
  30. * Allows building into a static or shared library, supports `-fvisibility=hidden`
  31. There are some features that are a work in progress and will come later:
  32. * More helpful debug information (proper line infos at both parse and run time)
  33. * A degree of thread safety (see below)
  34. * Custom allocator support (control over how heap memory is allocated)
  35. * Coroutines
  36. The API is currently very unstable, as is the actual codebase. Therefore you
  37. should not use the project in production environments just yet, but you're
  38. also free to experiment - feedback is welcome.
  39. **The project is also open for contributions.** You can use pull requests on
  40. GitHub and there is also a discussion channel `#octaforge` on FreeNode; this
  41. project is a part of the larger OctaForge umbrella.
  42. ## Threads and coroutines
  43. *(In progress)*
  44. Libcubescript supports integration with coroutines and threads by providing a
  45. concept of threads itself. You can create a thread (child state) using the
  46. main state and it will share global data with the main state, but it also
  47. has its own call stack.
  48. The "global" state is thread safe, allowing concurrent access from multiple
  49. threads. The "local" state can be yielded as a part of the coroutine without
  50. affecting any other threads.
  51. This functionality is not exposed into the language itself, but it can be
  52. utilized in the outside native code.
  53. ## Building and usage
  54. The only dependency is libostd:
  55. https://git.octaforge.org/tools/libostd.git/
  56. https://github.com/OctaForge/libostd
  57. If libostd can work on your system, so can libcubescript.
  58. The supplied Makefile builds a static library on Unix-like OSes. Link this
  59. library together with your application and everything should just work. It also
  60. builds the REPL.
  61. The project also bundles the linenoise line editing library which has been modified
  62. to compile cleanly as C++ (with the same flags as libcubescript). It's used strictly
  63. for the REPL only (you don't need it to build libcubescript itself). The version
  64. in the repository tracks Git revision https://github.com/antirez/linenoise/commit/c894b9e59f02203dbe4e2be657572cf88c4230c3.
  65. ## Licensing
  66. See COPYING.md for licensing information.