inkcpp_rb 0.1.0

data/ext/inkcpp_rb/inkcpp/inkcpp/include/runner.h

@@ -0,0 +1,291 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "config.h"
+#include "system.h"
+#include "functional.h"
+#include "types.h"
+
+#ifdef INK_ENABLE_UNREAL
+#	include "Containers/UnrealString.h"
+#endif
+
+namespace ink::runtime
+{
+class choice;
+
+/**
+ * A runner to execute ink script from a story.
+ *
+ * An independant runner which can execute ink script from a
+ * story independant of other runners. Think of the ink story
+ * object like an executable file and the runners as 'threads'
+ * (not to be confused with ink threads, which are a language
+ * feature). Runners track their own instruction pointer, choice
+ * list, temporary variables, callstack, etc. They can either
+ * be started with their own globals store, or can share
+ * one with other runner instances.
+ * @see globals
+ * @see story
+ */
+class runner_interface
+{
+public:
+	virtual ~runner_interface(){};
+
+#pragma region Interface Methods
+	/**
+	 * Sets seed for PRNG used in runner.
+	 * Else runner is started with the current time as seed.
+	 * @param seed seed to use for PRNG
+	 */
+	virtual void set_rng_seed(uint32_t seed) = 0;
+
+	/**
+	 * Moves the runner to the specified path
+	 *
+	 * Clears any execution context and moves the runner
+	 *  to the content at the specified path.
+	 *
+	 * @param path path to search and move execution to
+	 * @return If the path was found
+	 */
+	virtual bool move_to(hash_t path) = 0;
+
+	/**
+	 * Can the runner continue?
+	 *
+	 * Checks if the runner can continue execution. If it
+	 * can't, we are either at a choice or are out of content.
+	 * @see continue
+	 * @see has_choices
+	 *
+	 * @return Can continue be called
+	 */
+	virtual bool can_continue() const = 0;
+
+#ifdef INK_ENABLE_CSTD
+	/**
+	 * Continue execution until the next newline, then allocate a c-style
+	 * string with the output. This allocated string is managed by the runtime
+	 * and will be deleted at the next @ref ink::runtime::runner_interface::choose() "choose()" or
+	 * @ref ink::runtime::runner_interface::getline() "getline()"
+	 *
+	 * @return allocated c-style string with the output of a single line of execution
+	 */
+	virtual const char* getline_alloc() = 0;
+#endif
+
+	/**
+	 * @brief creates a snapshot containing the runner, globals and all other runners connected to the
+	 * globals.
+	 * @sa story::new_runner_from_snapshot, story::new_globals_from_snapshot
+	 */
+	virtual snapshot* create_snapshot() const = 0;
+
+#ifdef INK_ENABLE_STL
+	/**
+	 * Gets the next line of output using C++ STL string.
+	 *
+	 * Continue execution until the next newline, then return the output as
+	 * an STL C++ std::string. Requires INK_ENABLE_STL
+	 *
+	 * @return std::string with the next line of output
+	 */
+	virtual std::string getline() = 0;
+
+	/**
+	 * Gets the next line of output using C++ STL string.
+	 *
+	 * Continue execution until the next newline, then return the output to
+	 * an STL C++ std::ostream. Requires INK_ENABLE_STL
+	 */
+	virtual void getline(std::ostream&) = 0;
+
+	/**
+	 * Gets all the text until the next choice or end
+	 *
+	 * Continue execution until the next choice or the story ends,
+	 * then return the output as an STL C++ std::string.
+	 * Requires INK_ENABLE_STL
+	 *
+	 * @return std::string with the next line of output
+	 */
+	virtual std::string getall() = 0;
+
+	/**
+	 * Gets all the text until the next choice or end
+	 *
+	 * Continue execution until the next choice or the story ends,
+	 * then return the output to an STL C++ std::ostream.
+	 * Requires INK_ENABLE_STL
+	 */
+	virtual void getall(std::ostream&) = 0;
+#endif
+
+#ifdef INK_ENABLE_UNREAL
+	/**
+	 * Gets the next line of output using unreal string allocation
+	 *
+	 * Continue execution until the next newline, then return the output as
+	 * an Unreal FString. Requires INK_ENABLE_UNREAL
+	 *
+	 * @return FString with the next line of output
+	 */
+	virtual FString getline() = 0;
+#endif
+
+	/**
+	 * Choice iterator.
+	 *
+	 * Iterates over choices the runner is currently facing.
+	 *
+	 * @see end
+	 * @return constant iterator to the first choice
+	 */
+	virtual const choice* begin() const = 0;
+
+	/**
+	 * Terminal choice iterator.
+	 *
+	 * Pointer past the last choice the runner is currently facing.
+	 *
+	 * @see begin
+	 * @return end iterator
+	 */
+	virtual const choice* end() const = 0;
+
+	/**
+	 * Make a choice.
+	 *
+	 * Takes the choice at the given index and moves the instruction
+	 * pointer to that branch.
+	 *
+	 * @param index index of the choice to make
+	 */
+	virtual void choose(size_t index) = 0;
+
+	/** check if since last choice selection tags have been added */
+	virtual bool        has_tags() const            = 0;
+	/** return the number of current.
+	 *
+	 * The tags will be accumulated since last choice
+	 * order of tags wont change, and new are added at the end */
+	virtual size_t      num_tags() const            = 0;
+	/** access tag.
+	 * @param index tag id to fetch [0;@ref ink::runtime::runner_interface::num_tags() "num_tags()")
+	 */
+	virtual const char* get_tag(size_t index) const = 0;
+
+protected:
+	/** internal bind implementation. not for calling.
+	 * @private */
+	virtual void internal_bind(hash_t name, internal::function_base* function) = 0;
+
+public:
+	/**
+	 * Binds an external callable to the runtime
+	 *
+	 * Given a name and a callable object, register this function
+	 *  to be called back from the ink runtime.
+	 *
+	 * beside an exact signature match, the function can also have one of the following signatures:
+	 * + void(size_t argl, const ink::runtime::value* argv)
+	 * + ink::runtime::value(size_t argl, const ink::runtime::value* argv)
+	 * this provides a generic way to bind functions with abitrary length
+	 * @param name name hash
+	 * @param function callable
+	 * @param lookaheadSafe if false stop glue lookahead if encounter this function
+	 *                      this prevents double execution of external functions but can lead to
+	 *                      missing glues
+	 */
+	template<typename F>
+	inline void bind(hash_t name, F function, bool lookaheadSafe = false)
+	{
+		internal_bind(name, new internal::function(function, lookaheadSafe));
+	}
+
+	/**
+	 * Binds an external callable to the runtime
+	 *
+	 * Given a name and a callable object, register this function
+	 *  to be called back from the ink runtime.
+	 *
+	 * @param name name string
+	 * @param function callable
+	 * @param lookaheadSafe if false stop glue lookahead if encounter this function
+	 *                      this prevents double execution of external functions but can lead to
+	 *                      missing glues
+	 */
+	template<typename F>
+	inline void bind(const char* name, F function, bool lookaheadSafe = false)
+	{
+		bind(ink::hash_string(name), function, lookaheadSafe);
+	}
+
+#ifdef INK_ENABLE_UNREAL
+	/** bind and unreal delegate
+	 * @param name hash of external function name in ink script
+	 * @param functionDelegate
+	 * @param lookaheadSafe @ref #bind()
+	 */
+	template<typename D>
+	void bind_delegate(hash_t name, D functionDelegate, bool lookaheadSafe)
+	{
+		internal_bind(name, new internal::function_array_delegate(functionDelegate, lookaheadSafe));
+	}
+#endif
+
+#pragma endregion
+
+#pragma region Convenience Methods
+
+	/**
+	 * Shortcut for checking if the runner can continue.
+	 *
+	 * @see can_continue
+	 */
+	inline operator bool() const { return can_continue(); }
+
+	/**
+	 * Checks if we're currently facing any choices
+	 *
+	 * @return are there any choices available
+	 */
+	inline bool has_choices() const { return begin() != end(); }
+
+	/**
+	 * Returns the number of choices currently available
+	 *
+	 * @return number of choices
+	 */
+	size_t num_choices() const;
+
+	/**
+	 * Gets a choice
+	 *
+	 * Returns the choice object at a given index
+	 *
+	 * @see num_choices
+	 * @param index index of the choice to access
+	 * @return choice object with info on the choice
+	 */
+	const choice* get_choice(size_t index) const;
+
+	/**
+	 * Shorcut for accessing a choice
+	 *
+	 * @see get_choice
+	 * @param index index of the choice to access
+	 * @return choice object with info on the choice
+	 */
+	inline const choice* operator[](size_t index) { return get_choice(index); }
+
+#pragma endregion
+};
+} // namespace ink::runtime

data/ext/inkcpp_rb/inkcpp/inkcpp/include/snapshot.h

@@ -0,0 +1,61 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "types.h"
+
+namespace ink::runtime
+{
+/**
+ * Container for an InkCPP runtime snapshot.
+ * Each snapshot contains a @ref ink::runtime::globals_interface "globals store"
+ * and all assoziated @ref ink::runtime::runner_interface "runners/threads"
+ * For convinience there exist @ref ink::runtime::globals_interface::create_snapshot() and
+ * runner_interface::create_snapshot() . If the runner is assoziated to the globals the snapshot
+ * will be identical. If multiple runners are assoziated to the same globals all will be contained,
+ * and cann be reconsrtucted with the id parameter of @ref
+ * ink::runtime::story::new_runner_from_snapshot()
+ *
+ * @todo Currently the id is equal to the creation order, a way to name the single runner/threads is
+ * WIP
+ */
+class snapshot
+{
+public:
+	virtual ~snapshot(){};
+
+	/** Construct snapshot from blob.
+	 * Memory must be kept valid until the snapshot is deconstructed.
+	 * @param data pointer to blob
+	 * @param length number of bytes in blob
+	 * @param freeOnDestroy if the memory should be freed (delete[]) when the snapshot is
+	 * deconstructed
+	 * @return newly created snapshot
+	 */
+	static snapshot* from_binary(const unsigned char* data, size_t length, bool freeOnDestroy = true);
+
+	/** acces blob inside snapshot */
+	virtual const unsigned char* get_data() const     = 0;
+	/** size of blob inside snapshot */
+	virtual size_t               get_data_len() const = 0;
+	/** number of runners which are stored inside this snapshot */
+	virtual size_t               num_runners() const  = 0;
+
+#ifdef INK_ENABLE_STL
+	/** deserialize snapshot from file.
+	 * @param filename of input file
+	 * @throws ink_exception if it fails to open the file
+	 */
+	static snapshot* from_file(const char* filename);
+	/** serialize snapshot to file
+	 * @param filename output file filename, if already exist it will be overwritten
+	 * @throws ink_exception if it failt to open the file
+	 */
+	void             write_to_file(const char* filename) const;
+#endif
+};
+} // namespace ink::runtime

data/ext/inkcpp_rb/inkcpp/inkcpp/include/story.h

@@ -0,0 +1,219 @@
+/* Copyright (c) 2024 Julian Benda
+ *
+ * This file is part of inkCPP which is released under MIT license.
+ * See file LICENSE.txt or go to
+ * https://github.com/JBenda/inkcpp for full license details.
+ */
+#pragma once
+
+#include "types.h"
+
+namespace ink::runtime
+{
+/**
+ * A loaded ink story.
+ *
+ * Created by loading a binary ink story into memory. Once loaded,
+ * the story class can create "runners" which execute story code.
+ * A story can have any number of runners, which can optionally
+ * share globals (variables, visit counts, etc). through the
+ * globals object. By default, each runner gets its own newly
+ * created globals store.
+ * @see ink::runtime::runner_interface
+ * @see ink::runtime::globals_interface
+ */
+class story
+{
+public:
+	virtual ~story(){};
+#pragma region Interface Methods
+		/**
+		 * Creates a new global store
+		 *
+		 * Creates a new global store that can be passed in when
+		 * creating new runners for this story. Note: Can not be
+		 * used for other stories. It is tied to this story.
+		 *
+		 * @return managed pointer to a new global store
+		*/
+		virtual globals new_globals() = 0;
+	  /** Reconstructs globals from snapshot
+	   * @param obj snapshot to load
+	   */
+	  virtual globals new_globals_from_snapshot(const snapshot& obj) = 0;
+
+	  /**
+	   * Creates a new runner
+	   *
+	   * Creates a new runner whose initial instruction pointer
+	   * is the first instruction in this story. If no global
+	   * store is passed, a new one will be created for the runner.
+	   *
+	   * @param store globals to use for the runner
+	   * @return managed pointer to a new runner
+	   */
+	  virtual runner new_runner(globals store = nullptr) = 0;
+	  /**
+	   * @brief reconstruct runner from a snapshot
+	   * @attention runner must be snap_shotted from the same story
+	   * @attention if globals is explicit set,
+	   * make sure the globals are from the same snapshot as
+	   * @attention if you snap_shotted a multiple runner with shared global
+	   * please reconstruct it in the same fashion
+	   * @param obj
+	   * @param store can be set if explicit access to globals is required or multiple runner with a
+	   * shared global are used
+	   * @param runner_id if the snapshot was of a multiple runner one global situation load first the
+	   * global, and then each runner with global set and increasing idx
+	   */
+	  virtual runner new_runner_from_snapshot(
+	      const snapshot& obj, globals store = nullptr, unsigned runner_id = 0
+	  ) = 0;
+#pragma endregion
+
+#pragma region Factory Methods
+		/**
+		 * Creates a new story object from a file.
+		 *
+		 * Requires STL or other extension which allows files
+		 * to be loaded and read. Will allocate all the data
+		 * necessary to load the file and close it.
+		 *
+		 * @param filename filename of the binary ink data
+		 * @return new story object
+		*/
+		static story* from_file(const char* filename);
+
+		/**
+		 * Create a new story object from binary buffer
+		 *
+		 * No extensions required. Creates the story from binary
+		 * data already loaded into memory. By default, the story
+		 * will free this buffer when it is destroyed.
+		 *
+		 * @param data binary data
+		 * @param length of the binary data in bytes
+		 * @param freeOnDestroy if true, free this buffer once the story is destroyed
+		 * @return new story object
+		*/
+		static story* from_binary(unsigned char* data, size_t length, bool freeOnDestroy = true);
+#pragma endregion
+};
+}
+
+/** @namespace ink
+ * Namespace contaning all modules and classes from InkCPP
+ *
+ * (Unreal Blueprint Classes Excluded, but there will not be there in a normal build)
+ */
+
+/** @namespace ink::runtime
+ * Contaning all modules and classes used for the inkles ink runtime.
+ * A minimal example can be found at @ref src_main
+ */
+
+/** @mainpage InkCPP Documentation
+ * @tableofcontents
+ * Inkle Ink C++ Runtime with INK.JSON -> Binary Compiler.<br/>
+ * supports ussage in:
+ * + C++ (with CMAKE)
+ * + UE
+ * + Python [inkcpp_py](https://pypi.org/project/inkcpp-py/)
+ *
+ * @section cmake CMAKE usage
+ *
+ * The current erlease is available at the [release
+ * page](https://github.com/JBenda/inkcpp/releases/latest), as `<os>-lib.zip` (e.g.
+ * `linux-lib.zip`). <br/> to link the libraries you can use `find_package(inkcpp CONFIG)` which
+ * provides two targets:
+ * + inkcpp: the runtime enviroment
+ * + inkcpp_compiler: functionality to compile a story.json to story.bin
+ *
+ * To run your own `.ink` files you need a way to compile it to inks runtime format `.ink.json`. One
+ * way is to use `inklecate <story>.ink`.<br/> Which is available at the [official release
+ * page](https://github.com/inkle/ink/releases/latest).<br/>
+ * Alternativly set the enviroment variable `INKLECATE` so that `%INKLECATE%` executes inklecate.
+ *
+ * If you want to use the inkcpp with C link against the target inkcpp_c and `#include
+ * <ink/c/inkcpp.h>` The C-API documentation and example can be found @ref clib "here".
+ *
+ * Exampl with library extracted at /YOUR/PROJECT/linux-lib
+ * And the [Example project](../cmake_example.zip) is extracted to /YOUR/PROJECT
+ * @code {sh}
+ * cd /YOUR/PROJECT
+ * ls # expected output: CMakeLists.txt main.cpp test.ink test.ink.json linux-lib
+ * mkdir build
+ * cd build
+ * inkcpp_DIR=../linux-lib cmake .. -DCMAKE_BUILD_TYPE=Release  # linux
+ * set inkcpp_DIR=../win64-lib                                  # windows
+ * cmake ..                                                     # windows
+ * cmake --build . --config=Release
+ * cd ..
+ * ./build/main_cpp                                             # exact path depends on build system
+ * used
+ * @endcode
+ *
+ * @subsection cmake_flags CMake Flags
+ * + INKCPP_TEST: (ON|OFF) weather or not execute tests
+ *                requires `inklecate` to be in the PATH or `INKCPP_INKLECATE=OS` or `=ALL`
+ * + INKCPP_INKLECATE: (NONE|OS|ALL) download the current supported inklecate version from the
+ * official [release page](https://github.com/inkle/ink/releases/latest)</br> They are stored at
+ * `<build-dir>/inklecate/<os>/` and will be automatcilly used for the tests
+ *   + NONE: disable this function
+ *   + OS: only the version supported for the OS
+ *   + ALL: all versions
+ * + INKCPP_C: (ON|OFF) Build the inkcpp c bindings (and thest them if test is enabled)
+ * + INKCPP_PY: (ON|OFF) Build python bindings (build system only)
+ * + WHEEL_BUILD: (ON|OFF) Settings to work with a python wheel build (build system only)
+ * + INKCPP_DOC_BlueprintUE: (ON|OFF) enables nice blueprint renders for the documentation
+ *
+ * @subsection src_main main.cpp
+ * @include cmake_example/main.cpp
+ *
+ * @subsection src_cmake CMakeLists.txt
+ * @include cmake_example/CMakeLists.txt
+ *
+ * @subsection src_story_json test.ink
+ * @include cmake_example/test.ink
+ * compiled: [test.ink.json](../cmake_example/test.ink.json)
+ *
+ * @section ue Unreal Installation
+ *
+ * The easiest way is to install it via the [unreal
+ * marcetplace](https://www.unrealengine.com/marketplace/en-US/product/inkcpp). The overview to the
+ * UE Blueprint class and examples can be found at @ref unreal "here".
+ *
+ * The current release is also available at the [release
+ * page](https://github.com/JBenda/inkcpp/releases/latest), as `unreal.zip`.<br/>
+ * Unpack this foldor in `/PATH/TO/UNREAL_ENGINE/Engine/Plugins/` and it will be available
+ * as plugin in the plugin list. <br/>
+ * Or unpack this folder in `/PATH/TO/UNREAL_PROJECT/Plugins/` and it will be
+ * intigrated at the next startup.<br/> A MarketPlace appearance is work in progress :)
+ *
+ * If you want to use the newest version clone the project and install the unreal component.
+ * @code {sh}
+ * git clone https://github.com/JBenda/inkcpp
+ * cd inkcpp
+ * mkdir build
+ * mkdir plugin
+ * cd build
+ * cmake ..
+ * cmake --install . --component unreal --prefix ../plugin
+ * cd ../plugin
+ * # Should contain a folder named 'inkcpp'
+ * cp -r inkcpp /PATH/TO/UNREAL_PROJECT/Plugins
+ * @endcode
+ *
+ * @section py Python example
+ *
+ * You can install the current release from [pypi](https://pypi.org/project/inkcpp-py/) with <br/>
+ * `pip install inkcpp-py`.<br/>
+ * Or build it yourself from main with: <br/>
+ * `pip install .`
+ *
+ * Here can you find an
+ * [example](https://raw.githubusercontent.com/JBenda/inkcpp/master/inkcpp_py/example.py) inclusive
+ * [story](https://raw.githubusercontent.com/JBenda/inkcpp/master/inkcpp_py/unreal_example.ink).
+ *
+ * [Python module documentation](./inkcpp_py.html)
+ */