Compiler

.gitignore

@@ -1,4 +1,5 @@
 /engine/
+/compiler/
 dist/
 test/stories/
 /tests/specs/

LICENSE.md

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2017 Yannick Lohse
+Copyright (c) 2017 Yannick Lohse for the inkjs Player
+Copyright (c) 2022 Julien Zamor + Furkle for the inkjs Compiler
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -122,6 +122,32 @@ var result = EvaluateFunction("my_ink_function", ["arg1", "arg2"], true);
 // result.output is the text that was written to the output while the function was evaluated
 ```
 
+## Compiler
+
+### inklecate.js
+```shell
+$ node inklecate.js -h
+
+Usage: inklecate <options> <ink file>
+   -o <filename>:   Output file name
+   -c:              Count all visits to knots, stitches and weave points, not
+                    just those referenced by TURNS_SINCE and read counts.
+   -p:              Play mode
+
+```
+
+### online compiler
+```javascript
+const story  = (new inkjs.Compiler(`Hello World`)).Compile()
+// story is an inkjs.Story that can be played right away
+
+const jsonBytecode = story.ToJson();
+// the generated json can be further re-used
+```
+
+### Differences with the C# Compiler
+See [Differences with the C# Compiler](docs/compiler-differences.md).
+
 ## Compatibility table
 
 | _inklecate_ version | _inkjs_ version |

docs/compiler-differences.md

@@ -0,0 +1,34 @@
+# Differences with the C# Compiler
+
+## Handling `INCLUDE`s
+
+The C# compiler is intented to always be used on a file system and thus the question of how files are included follow a classic pattern.  
+Nevertheless, when using the compiler inside a browser, the concept of "file" is a blurry one.   
+Inkjs provides 2 file handlers :
+* A POSIX file handler : similar to the one used in the C# compiler that will look for files in folders
+* A JSON file handler : expects a JSON object of the form
+```
+{
+    "filename1.ink": "INCLUDE filename2.ink",
+    "filename2.ink": "This content is included",
+}
+```
+
+## Float and ints
+
+As the JSON format and javascript in general do not differentiate between float and integers, the inkjs runtime is known to behave differently from the C# runtime when dealing with floating point operations.
+
+The Ink language parser nevertheless enforces this typing and, when played directly from the output of the compiler (as opposed to exporting to JSON and then loading it), the Story object will actually behave like in the C# Runtime.
+
+This may lead to slight differences during play.  
+This [issue is known](https://github.com/y-lohse/inkjs/issues/934) and will be addressed in subsequent release.
+
+## Named classes/types
+
+As a major difference from the C# compiler, the Parsed Hierarchy classes are not publicly exposed and their name may be obscured when using the minified version of inkjs-full.  
+You'll have to rely on their `.typeName` property.
+
+Some typename are specific to this library :   
+* Constant declaration : `CONST` instead of `Constant`
+* List declaration : `LIST` instead of `VAR`
+* List definition (container) : `ListDefinition` instead of `List definition`

ink.d.ts

@@ -1,8 +1,12 @@
 import { Story, InkList } from './engine/Story'
+import { Compiler } from './compiler/Compiler'
+import { CompilerOptions } from './compiler/CompilerOptions'
 
 declare interface Inkjs {
     Story: typeof Story
     InkList: typeof InkList
+    Compiler: typeof Compiler
+    CompilerOptions: typeof CompilerOptions
 }
 
 declare let inkjs: Inkjs

jest.config.javascript.js

@@ -5,5 +5,8 @@ module.exports = {
   ],
   testPathIgnorePatterns: [
     "<rootDir>/src/"
-  ]
+  ],
+  setupFilesAfterEnv: [
+    "<rootDir>/tests/specs/setupTests.js"
+  ],
 };

jest.config.js

@@ -19,4 +19,7 @@ module.exports = {
   transform: {
     "^.+\\.ts$": "ts-jest"
   },
+  setupFilesAfterEnv: [
+    "<rootDir>/src/tests/specs/setupTests.ts"
+  ],
 };