inkcpp_rb 0.1.0

data/ext/inkcpp_rb/inkcpp/inkcpp_test/ink/simple-1.1.1-inky.json

@@ -0,0 +1,160 @@
+{
+  "inkVersion": 21,
+  "root": [
+    [
+      {
+        "->": "start"
+      },
+      [
+        "done",
+        {
+          "#f": 5,
+          "#n": "g-0"
+        }
+      ],
+      null
+    ],
+    "done",
+    {
+      "start": [
+        [
+          "^Once upon a time...",
+          "\n",
+          [
+            "ev",
+            {
+              "^->": "start.0.2.$r1"
+            },
+            {
+              "temp=": "$r"
+            },
+            "str",
+            {
+              "->": ".^.s"
+            },
+            [
+              {
+                "#n": "$r1"
+              }
+            ],
+            "/str",
+            "/ev",
+            {
+              "*": ".^.^.c-0",
+              "flg": 18
+            },
+            {
+              "s": [
+                "^There were two choices.",
+                {
+                  "->": "$r",
+                  "var": true
+                },
+                null
+              ]
+            }
+          ],
+          [
+            "ev",
+            {
+              "^->": "start.0.3.$r1"
+            },
+            {
+              "temp=": "$r"
+            },
+            "str",
+            {
+              "->": ".^.s"
+            },
+            [
+              {
+                "#n": "$r1"
+              }
+            ],
+            "/str",
+            "/ev",
+            {
+              "*": ".^.^.c-1",
+              "flg": 18
+            },
+            {
+              "s": [
+                "^There were four lines of content.",
+                {
+                  "->": "$r",
+                  "var": true
+                },
+                null
+              ]
+            }
+          ],
+          {
+            "c-0": [
+              "ev",
+              {
+                "^->": "start.0.c-0.$r2"
+              },
+              "/ev",
+              {
+                "temp=": "$r"
+              },
+              {
+                "->": ".^.^.2.s"
+              },
+              [
+                {
+                  "#n": "$r2"
+                }
+              ],
+              "\n",
+              {
+                "->": ".^.^.g-0"
+              },
+              {
+                "#f": 5
+              }
+            ],
+            "c-1": [
+              "ev",
+              {
+                "^->": "start.0.c-1.$r2"
+              },
+              "/ev",
+              {
+                "temp=": "$r"
+              },
+              {
+                "->": ".^.^.3.s"
+              },
+              [
+                {
+                  "#n": "$r2"
+                }
+              ],
+              "\n",
+              {
+                "->": ".^.^.g-0"
+              },
+              {
+                "#f": 5
+              }
+            ],
+            "g-0": [
+              "^They lived happily ever after.",
+              "\n",
+              "end",
+              {
+                "#f": 5
+              }
+            ]
+          }
+        ],
+        {
+          "#f": 1
+        }
+      ],
+      "#f": 1
+    }
+  ],
+  "listDefs": {}
+}

data/ext/inkcpp_rb/inkcpp/notes/ArchitectureNotes.md

@@ -0,0 +1,54 @@
+# Container Metadata
+
+Even though the inkcpp binary compiler flattens the hierarchical JSON structure into a flat sequence of commands with diverts, we still need to maintain some metadata about the container structure so we can properly record visit counts.
+
+## Container Instructions Layout
+
+Only containers which have visit or turn tracking flags are recorded in any way. All other containers may as well no longer exist.
+
+The first command at the start of any container is a {{START_CONTAINER_MARKER}}.
+
+Inline child container are written in-place as the interpreter should enter them normally when it reaches them.
+
+Named containers specified in a container's meta-data are compiled in order after we finish writing out all commands for the parent container.
+* Before writing any of them, we write a {{DIVERT}} command which jumps to {{END_CONTAINER_MARKER}} for the parent below. This way we don't wander into these child containers when we run out of content in our own container.
+* After writing each named child, we write a similar {{DIVERT}} as above. This way, when any of these containers finish, the interpreter does not wander into their siblings.
+* Both these diverts are written with a special {{DIVERT_IS_FALLTHROUGH}} flag. Its important will be clear later.
+
+After writing all these named children, the last command, a {{END_CONTAINER_MARKER}} is written.
+
+## Container Start/End Instruction
+
+{{START_CONTAINER_MARKER}} and {{END_CONTAINER_MARKER}} both have a {{container_t}} argument to uniquely identify the container starting or ending. These numbers have no relation to the original container names. They are assigned sequentially starting from 0 to each container which requires tracking.
+
+The {{START}} command pushes that container ID onto the current container stack. {{END}} pops them.
+
+TODO: Notes on implied DONE and the done IP cache.
+
+## Container Map
+
+A "container map" is included in the ink binary metadata before any instructions. It's an array in the following format:
+
+32-bit instruction offset (offset_t)
+32-bit container id (container_t)
+
+The array is terminated with a 0xFFFFFFFF.
+
+Each container has two entries in the array: one for its start and one for its end. There is no distinction between start and end in the array.
+
+The "start" offset points to the instruction just after the {{START_CONTAINER_MARKER}} command. If you were to jump to it, you'd avoid hitting the {{START_CONTAINER_MARKER}} next step.
+
+The "end" offset points to the instruction just after the {{END_CONTAINER_MARKER}} instruction. If you were to jump to it, you'd avoid hitting the {{END_CONTAINER_MARKER}} next step.
+
+The container map is used for handling visit counts that result from an interpreter jump (caused by a {{DIVERT}} or selecting a choice). In normal execution, the {{START_CONTAINER_MARKER}} and {{END_CONTAINER_MARKER}} are pushing/popping container indicies and updating visit counts. If we jump, we're passing over all these commands. We need a way of both updating the visit counts (for each new container we enter) and updating our own container stack so the interpreter knows where it is in the container hierarchy.
+
+### Jump Algorithm
+
+1. Determine if we are jumping forward (dest > ip) or backward (ip < dest)
+2. Linear search the container map, starting from the beginning for a forward jump or the end for a backward jump
+	* Find the entry just "before" the current pointer. 
+
+
+### Special: "Falling Through" Diverts
+
+TODO: Can we simplify jump algorithm here? Are there certain guarantees?

data/ext/inkcpp_rb/inkcpp/notes/ListNotes.md

@@ -0,0 +1,69 @@
+[##](##) general construction:
+
++ A list is a bit vector!
++ Further we will call each bit vector which represents a list a _flag_.
++ Each flag is tide to a number, which is equal to the  position in the bit vector, which we will call _flag value_
++ Each flag has a string representation, further be called _key_.
++ Each multi list is associated to zero ore more list types
+	+ when adding a new element the list type of that element get added to associated lists
+	+ when removing the last element of an list type then the type get removed from associated lists
+		+ __except:__ the list of associated types will be empty, than nothing happen
+		+ -> only an empty initialized list has no d list
++ each list key will be an element variable at global scope -> no two keys can have the same name
++ a list_type is a variable defined with `LIST` therefore mentioned in the `declList` section of the InkJson
+
+## List operators
+
++ `+(list lh,list rh)` lh = lh ∪ rh
++ `+(list, fag)` add the element to the list
++ `L^(list lh, flag rh)` (interesection) creates an empty list or a list with rh set if it's part of lh
++ `L^(list lh, list rh)` (interesection) = lh ∩ rh
++ `-(list lh, list rh)` remove elements lh = lh / (lh ∩ rh)
++ `-(list lh, flag rh)` removes element from list
++ `+(list l, int i)` l << i (bits get shifted out)
++ `-(list l, int i)` l >> i (bits get shifted out)
++ `LIST_COUNT(list l)` returns the number of flags sets
++ `LIST_MIN(list l)` returns the flag with the lowest numerical representation which is set
++ `LIST_MAX(list l)` return the flag with the highest numerical representation which is set
++ `lrnd(list l)` return a random flag which is set
+	+ for the user it is `LIST_RANDOM`, but in InkJson it is called `lrnd`
++ `LIST_ALL(list l)` returns a list which all elements of associated list of l
++ `LIST_INVERT(list l)` returns a list which each flag is toggeld of all associated lists
++ `<(list lh, list rh)` return true if `LIST_MAX(lh) < LIST_MIN(rh)`
++ `>(list lh, list rh)` returns true if `LIST_MIN(lh) > LIST_MAX(rh)`
++ `==(list lh, list rh)` returns true if the setted flags of both are equal
++ `!=(list lh, list rh)` return true if `lh == rh` returns false
++ `>=(list lh, list rh)` returns true if `LIST_MAX(lh) >= LIST_MAX(rh) && LIST_MIN(lh) >= LIST_MIN(rh)`
++ `<=(list lh, list rh)` returns true if `LIST_MAX(lh) <= LIST_MAX(rh) && LIST_MIN(lh) <= LIST_MIN(rh)`
++ `?(list lh, entry rh)` returns true if rh is element of lh
++ `?(list lh, list rh)` returns true if every flag of rh is set in lh
++ `!?(list lh, entry rh)` returns `not ?(lh,rh)`
++ `!?(list lh, list rh)` returns `not ? (lh,rh)`
+
+## Datatype
+
++ Each list has a id(`listId`), this mapping is arbitrary. To allow usage as array index we start with 0 an increased it for each list_type
++ A flag is identified by `flagId`, it's correspond to the flag value. (flagId - min flagId of that list = flag value)
+
+### list_element
+
+`uint32_t` with bit[0-15] are the listId and bit[16-31] the flag value.
+
+### list
+
+`uint32_t` position in list_table
+
+### list_table
+
+Datatype to manage lists (similar to string_table)
+
+It contains:
+
++ a reference to the string_table
++ A array `keys` which maps each flagId to an key, who lives in string_table
++ A array `flag_start` which maps each listId to an offset, which leads to value 0 for that list in the entry bitmap.
++ A array `fids` which maps each listId to the flagId for the value 0 of that list (used to get key from keys).
++ A array of entries, each entry contains:
+	+ a bitmap, where 1 represent that the list is associated to the corresponding list
+	+ a bitmap, where 1 represent that the list contains the flag
+	+ the two bitmaps are WORD align for better memory access

data/ext/inkcpp_rb/inkcpp/notes/OperationNotes.md

@@ -0,0 +1,35 @@
+Operations are everything which works only on the evaluation stack!
+(eg. ADD, NOT, EQUAL, etc.)
+
+To use them include `executioner.h`, this will take care of including the other
+needed header in the correct order.
+
+The `executioner` need to instantiation time all resources needed for all
+supported operations (a string_table for now).
+
+Then you can execute a command with the call operator of the `executioner`.
+`void operator()(Command, eval_stack&)`
+
+The executioner then iterates through a compile time created and optimization
+list of all types. To determine how many arguments needed
+(with `size_t command_num_args(Command)`) and then finds the matching operator
+for the value type.
+
+Type casting is solved with a cast matrix, where each entry is defined with:
+`template<> constexpr value_type cast<value_type,value_type> = value_type`
+`template<> constexpr value_type cast<t1,t2> = resulting_type`
+
+! At the moment we must ensure that `(int)(t1) < (int)(t2)`!
+
+The gain:
+
+* Operation handling can be separated in different files
+  (`numeric_operations.h, string_operations.h`). The value class only knows what
+  data it contains, and not how to handle it => adding new types or operators
+  is know possible without changing many `switch cases`.
+* Values are acquired with `get<value_type>()` witch allows changing type
+  without breaking unnoticed code.
+* Not one huge file.
+* The `executioner` knows the resources for the operations
+  => no need to pass a string_table to each add.
+* everything is without virtualisation => no/negligible runtime overhead.

data/ext/inkcpp_rb/inkcpp/notes/TagsNotes.md

@@ -0,0 +1,24 @@
+Tags are accessible via runner functions:
+
+- `bool has_tags()` are there any tags now?
+- `size_t num_tags()` how many tags are there right now?
+- `const char* get_tag(size_t i)` get string value of tag
+
+Tags are acquired until a choice appears. After choosing the acquired tags will
+be cleared.
+```
+# Tag1
+# Tag 2
+Some Text # Tag3
+* A # Tag 4
+* B # Tag 5
+- out # Tag6
+```
+
+Will produce:
+> Some Text: Tag1, Tag2, Tag3
+> * A
+> * B
+> <1
+> A
+> out: Tag4, Tag6

data/ext/inkcpp_rb/inkcpp/notes/WhitespaceNotes.md

@@ -0,0 +1,28 @@
+In which I figure out what in the nine fucks ink is doing to whitespace so I can emulate it.
+
+There seem to be _numerous_ places in which ink deals with whitespace so I will just document each here and try to figure out what they're doing and why.
+
+# Push To Output Stream
+
+Ink processes whitespace in strings as they are added to the output stream. See _PushToOutputStream_ and _PushToOutputStreamIndividual_ in StoryState.cs.
+
+## PushToOutputStream
+
+Calls _TrySplittingHeadTailWhitespace_ on incoming strings in case they contain newlines. I'm not really sure *how* this could happen since newlines are split off by the Ink compiler already. How could a newline possibly be in an incoming string? I guess maybe if it's stored in a variable? Seems like quite the edge case. 
+
+DECISION: NOT IMPLEMENTING. Will review if the case comes up.
+
+After running this split, the split strings are sent to _PushToOutputStreamIndividual_.
+
+## PushToOutputStreamIndividual
+
+Lots going on here.
+
+First, if the incoming element is glue, trim newlines from the output stream.
+
+ALREADY IMPLEMENTED. See *basic_stream::append(const data&)*.
+
+Otherwise, for text:
+
+1. We trim whitespace at the _beginning_ and _ending_ of function calls (not tunnels). This is made more complicated by glue.
+

data/ext/inkcpp_rb/inkcpp/proofing/README.md

@@ -0,0 +1,3 @@
+In the future, there'll be machinery in here to run the ink-proof tests as a test phase during build. For now, it just houses the ink-proof submodule so we can generate the HTML page for it on master.
+
+See windows_builds.yml in the .github folder

data/ext/inkcpp_rb/inkcpp/proofing/inkcpp_runtime_driver

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+import shutil
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PATH = os.path.join(ROOT, 'deps', 'inkcpp', 'inkcpp_cl')
+ARGS = ["inkcpp_cl", "--ommit-choice-tags", "-p"] + sys.argv[1:]
+os.execv(PATH, ARGS)
+sleep(2)
+

data/ext/inkcpp_rb/inkcpp/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "inkcpp-py"
+readme = "README.md"
+license = { file = "LICENSE.txt" }
+keywords = ["ink", "inkpp", "inklecate"]
+dynamic = ["version", "description", "authors", "requires-python"]
+
+[project.urls]
+Repository = "https://github.com/JBenda/inkcpp.git"
+Issues = "https://github.com/JBenda/inkcpp/issues"
+
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "ninja",
+    "cmake>=3.16",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.mypy]
+files = "setup.py"
+python_version = "3.7"
+strict = true
+show_error_codes = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = ["ninja"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+# minversion = "6.0"
+# addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
+# xfail_strict = true
+# filterwarnings = [
+#     "error",
+#     "ignore:(ast.Str|Attribute s|ast.NameConstant|ast.Num) is deprecated:DeprecationWarning:_pytest",
+# ]
+testpaths = ["inkcpp_py/tests"]
+addopts = [
+  "--import-mode=importlib",
+]
+
+# [tool.cibuildwheel]
+# test-command = "pytest {project}/tests"
+# test-extras = ["test"]
+# test-skip = ["*universal2:arm64"]
+# Setuptools bug causes collision between pypy and cpython artifacts
+# before-build = "rm -rf {project}/build"
+
+[tool.ruff]
+target-version = "py37"
+
+[tool.ruff.lint]
+extend-select = [
+  "B",    # flake8-bugbear
+  "I",    # isort
+  "PGH",  # pygrep-hooks
+  "RUF",  # Ruff-specific
+  "UP",   # pyupgrade
+]

data/ext/inkcpp_rb/inkcpp/setup.py

@@ -0,0 +1,166 @@
+# based on https://github.com/pybind/cmake_example/blob/master/setup.py
+
+import os
+import re
+import sys
+import subprocess
+import glob
+import json
+from pathlib import Path
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+
+# echo "[\n$(find shared/** inkcpp/** inkcpp_compiler/** inkcpp_py/** -not -path '*/.*' | tr '\n' ' ' | sed -e 's/[^ ]\+/"\0"/g' -e 's/[[:blank:]]*$//' -e 's/ /,\n/g')\n]"
+# + "CMakeLists.txt"
+
+# Convert distutils Windows platform specifiers to CMake -A arguments
+PLAT_TO_CMAKE = {
+    "win32": "Win32",
+    "win-amd64": "x64",
+    "win-arm32": "ARM",
+    "win-arm64": "ARM64",
+}
+
+def src_files(dir):
+    dir = os.fsencode(dir)
+    files = []
+    for file in os.listdir(dir):
+        if file[0] == '.':
+            continue
+        file = os.path.join(dir, file)
+        if os.path.isdir(file):
+            files += src_files(file)
+        else:
+            files.append(file.decode("utf-8"))
+    return files
+
+def glob_src_files():
+    files = []
+    dirs = ['./inkcpp', './inkcpp_compiler', './inkcpp_py', './shared']
+    for dir in dirs:
+        files += src_files(dir)
+    return files
+        
+
+class CMakeExtension(Extension):
+    def __init__(self, name: str, sourcedir: str = "") -> None:
+        src_files = glob_src_files()
+        # src_files = json.load(open('inkcpp_py/sources.json'))
+        src_files += ["CMakeLists.txt", "Config.cmake.in"]
+        super().__init__(name, sources=src_files)
+        self.sourcedir = os.fspath(Path(sourcedir).resolve())
+    
+class CMakeBuild(build_ext):
+ def build_extension(self, ext: CMakeExtension) -> None:
+        # Must be in this form due to bug in .resolve() only fixed in Python 3.10+
+        ext_fullpath = Path.cwd() / self.get_ext_fullpath(ext.name)
+        extdir = ext_fullpath.parent.resolve()
+
+        # Using this requires trailing slash for auto-detection & inclusion of
+        # auxiliary "native" libs
+
+        debug = int(os.environ.get("DEBUG", 0)) if self.debug is None else self.debug
+        cfg = "Debug" if debug else "Release"
+
+        # CMake lets you override the generator - we need to check this.
+        # Can be set with Conda-Build, for example.
+        cmake_generator = os.environ.get("CMAKE_GENERATOR", "")
+
+        # Set Python_EXECUTABLE instead if you use PYBIND11_FINDPYTHON
+        # EXAMPLE_VERSION_INFO shows you how to pass a value into the C++ code
+        # from Python.
+        cmake_args = [
+            f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY={extdir}{os.sep}",
+            f"-DPYTHON_EXECUTABLE={sys.executable}",
+            f"-DCMAKE_BUILD_TYPE={cfg}",  # not used on MSVC, but no harm
+            f"-DINKCPP_PY=ON",
+            f"-DWHEEL_BUILD=ON",
+        ]
+        build_args = [
+            f"--target=inkcpp_py",
+        ]
+        # Adding CMake arguments set as environment variable
+        # (needed e.g. to build for ARM OSx on conda-forge)
+        if "CMAKE_ARGS" in os.environ:
+            cmake_args += [item for item in os.environ["CMAKE_ARGS"].split(" ") if item]
+
+        if self.compiler.compiler_type != "msvc":
+            # Using Ninja-build since it a) is available as a wheel and b)
+            # multithreads automatically. MSVC would require all variables be
+            # exported for Ninja to pick it up, which is a little tricky to do.
+            # Users can override the generator with CMAKE_GENERATOR in CMake
+            # 3.15+.
+            if not cmake_generator or cmake_generator == "Ninja":
+                try:
+                    import ninja
+
+                    ninja_executable_path = Path(ninja.BIN_DIR) / "ninja"
+                    cmake_args += [
+                        "-GNinja",
+                        f"-DCMAKE_MAKE_PROGRAM:FILEPATH={ninja_executable_path}",
+                    ]
+                except ImportError:
+                    pass
+
+        else:
+            # Single config generators are handled "normally"
+            single_config = any(x in cmake_generator for x in {"NMake", "Ninja"})
+
+            # CMake allows an arch-in-generator style for backward compatibility
+            contains_arch = any(x in cmake_generator for x in {"ARM", "Win64"})
+
+            # Specify the arch if using MSVC generator, but only if it doesn't
+            # contain a backward-compatibility arch spec already in the
+            # generator name.
+            if not single_config and not contains_arch:
+                cmake_args += ["-A", PLAT_TO_CMAKE[self.plat_name]]
+
+            # Multi-config generators have a different way to specify configs
+            if not single_config:
+                cmake_args += [
+                    f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_{cfg.upper()}={extdir}"
+                ]
+                build_args += ["--config", cfg]
+
+        if sys.platform.startswith("darwin"):
+            # Cross-compile support for macOS - respect ARCHFLAGS if set
+            archs = re.findall(r"-arch (\S+)", os.environ.get("ARCHFLAGS", ""))
+            if archs:
+                cmake_args += ["-DCMAKE_OSX_ARCHITECTURES={}".format(";".join(archs))]
+
+        # Set CMAKE_BUILD_PARALLEL_LEVEL to control the parallel build level
+        # across all generators.
+        if "CMAKE_BUILD_PARALLEL_LEVEL" not in os.environ:
+            # self.parallel is a Python 3 only way to set parallel jobs by hand
+            # using -j in the build_ext call, not supported by pip or PyPA-build.
+            if hasattr(self, "parallel") and self.parallel:
+                # CMake 3.12+ only.
+                build_args += [f"-j{self.parallel}"]
+
+        build_temp = Path(self.build_temp) / ext.name
+        if not build_temp.exists():
+            build_temp.mkdir(parents=True)
+
+        print([f for f in os.listdir(ext.sourcedir)])
+        print("'{}'".format(ext.sourcedir), cmake_args)
+        subprocess.run(
+            ["cmake", ext.sourcedir, *cmake_args], cwd=build_temp, check=True
+        )
+        subprocess.run(
+            ["cmake", "--build", ".", *build_args], cwd=build_temp, check=True
+        )            
+
+setup(
+    name="inkcpp-py",
+    version="0.1.6",
+    author="Julian Benda",
+    author_email="julian.benda@ovgu.de",
+    description="Python bindings for InkCPP a Inkle runtime written in C++",
+    long_description="For all issues and ideas please visit the repository at https://github.com/JBenda/inkcpp",
+    zip_safe=False,
+    ext_modules=[CMakeExtension("inkcpp_py")],
+    cmdclass={"build_ext": CMakeBuild},
+    python_requires=">=3.7",
+    py_modules=[],
+)

data/ext/inkcpp_rb/inkcpp/shared/CMakeLists.txt

@@ -0,0 +1,14 @@
+add_library(inkcpp_shared INTERFACE)
+
+target_include_directories(inkcpp_shared
+	INTERFACE
+	$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/public>
+	$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/private>
+	$<INSTALL_INTERFACE:inkcpp>
+)
+FILE(GLOB PUBLIC_HEADERS "public/*")
+set_target_properties(inkcpp_shared PROPERTIES PUBLIC_HEADER "${PUBLIC_HEADERS}")
+
+# Unreal installation
+install(DIRECTORY "public/" DESTINATION "inkcpp/Source/shared/Public" COMPONENT unreal EXCLUDE_FROM_ALL)
+install(DIRECTORY "private/" DESTINATION "inkcpp/Source/shared/Private/" COMPONENT unreal EXCLUDE_FROM_ALL)