Contributing to KonsolScript

Resources for contributors to libkonsolscript and authors of KonsolScript plugins.

→ Script authors: see scripting.md

Table of Contents

  1. Source layout
  2. Adding a built-in module
  3. Writing a plugin
  4. Building the bundled plugins
  5. Embedding libkonsolscript in a host application

Source layout

libkonsolscript — the interpreter (shared library)

All files compiled into libkonsolscript.dll / .so / .dylib:

Path Contents
core/kse.cpp Engine core: tokenizer, evaluator (evalAtom → evalExpr chain), execute, loadScript, run
core/kse.hpp Engine public API and private declarations
core/kse_types.hpp Value, Token, CMD_* constants, KseException, ListVar, MapVar, ArrayVar, ClassDef, CallFrame
core/kse_dynload.hpp Platform DL helpers (lib_open/sym/close), DYNLIB_EXT, userPluginDir()
cls/kse_var.cpp Var: declarations (Number/String/Boolean/UDT/Class)
cls/kse_array.cpp Array: module; Engine::arrayGet / Engine::arraySet; ArrayException
cls/kse_math.cpp Math: module; MathException
cls/kse_string.cpp String: module
cls/kse_file.cpp File: module
cls/kse_time.cpp Time: module
cls/kse_konsol.cpp Konsol: module
cls/kse_class.cpp Class:Create / class instantiation
cls/kse_object.cpp Built-in Object and Exception class definitions
cls/kse_list.cpp List: module
cls/kse_map.cpp Map: module
cls/kse_json.cpp Json: module
cls/kse_os.cpp OS: and Path: modules
cls/kse_hash.cpp Hash: module
cls/kse_date.cpp Date: module
cls/kse_csv.cpp CSV: module
cls/kse_regex.cpp Regex: module
ctrl/kse_try.cpp try / catch / finally / throw
ctrl/kse_if.cpp if / else if / else
ctrl/kse_while.cpp while loop
ctrl/kse_for.cpp for loop
ctrl/kse_switch.cpp switch / case / default
ctrl/kse_foreach.cpp foreach loop
ctrl/kse_return.cpp return statement

Bundled plugins

Each plugin is a standalone shared library in its own subdirectory:

Path Module(s) Library
curl_plugin/kse_curl.cpp Curl: libcurl
sqlite_plugin/kse_sqlite.cpp SQLite: SQLite amalgamation
mysql_plugin/kse_mysql.cpp MySQL: / Maria: libmysqlclient / libmariadb
pg_plugin/kse_pg.cpp PG: libpq
redis_plugin/kse_redis.cpp Redis: hiredis
zip_plugin/kse_zip.cpp Zip: libzip
crypto_plugin/kse_crypto.cpp Crypto: OpenSSL
ws_plugin/kse_ws.cpp WS: libcurl ≥ 7.86
net_plugin/kse_net.cpp Net: ws2_32 (Windows) / sockets
jwt_plugin/kse_jwt.cpp JWT: OpenSSL (same as crypto_plugin)

minks — the CLI (single file)

Path Contents
main.cpp CLI entry point; argument parsing; --plugin-path, --check, --debug, --sandbox; REPL; install/remove/list package manager subcommands; uncaught KseException handler (exit code 2)

main.cpp links dynamically against libkonsolscript. Any other host application embedding the library must add its own catch (const KseException&) around engine.run().

Adding a built-in module

Register a new C++ module inside libkonsolscript without modifying the parser.

→ adding-a-module.md

Writing a plugin

Plugins are shared libraries that add new modules to KonsolScript without recompiling libkonsolscript. Use the PluginClass builder from minks_plugin.h.

→ plugin-system.md

Building the bundled plugins

Each plugin's build instructions (dependency install + make command) live in its own doc:

To build all plugins at once:

make plugin

Embedding libkonsolscript in a host application

Link libkonsolscript into any C++17 application to make it scriptable.

→ embedding-api.md