-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
28 changed files
with
960 additions
and
2 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| <!DOCTYPE html> | ||
| <!-- | ||
| AUTOMATICALLY GENERATED USING THE CATSPEAK BOOK GENERATOR: | ||
| https://github.com/katsaii/catspeak-lang | ||
| --><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="author" content="Katsaii"><meta name="description" content="Dubiously undocumented behaviour and quirks."><title>Catspeak Reference :: enum FutureState of Dubiously Undocumented</title><link rel="stylesheet" href="./style.css"></head><body><header><h1>Catspeak Reference</h1><nav><ul><li><a href="hom-welcome.html">Home</a></li><li><a href="lib-init.html">Library Reference</a></li><li><a href="dub-compatibility_v2.html"><mark>Dubiously Undocumented</mark></a></li></ul></nav><hr></header><article id="chapter-content"><aside id="chapters"><h2>Chapters</h2><ul><li><a href="dub-compatibility_v2.html">compatibility_v2</a><ul><li><a href="dub-struct-future.html">struct Future</a></li><li><a href="dub-enum-futurestate.html"><mark>enum FutureState</mark></a></li></ul></li></ul></aside><aside id="contents"></aside><main><article><h1 class="chapter-title">enum FutureState</h1><pre><code><span class="kw-key">enum</span> <span class="kw-typ">FutureState</span> { | ||
| <span class="kw-mac">UNRESOLVED</span>, | ||
| <span class="kw-mac">ACCEPTED</span>, | ||
| <span class="kw-mac">REJECTED</span>, | ||
| }</code></pre><blockquote class="stab deprecated"><strong>👎 Deprecated since 3.0.0</strong></blockquote><p>The different progress states of a <code class="inline-code">Future</code>.</p></article></main></article><footer><hr><article><em id="brand">Built using Catlog, the <a href="https://www.katsaii.com/catspeak-lang/">Catspeak</a> book generator.</em></article><article></article></footer></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| <!DOCTYPE html> | ||
| <!-- | ||
| AUTOMATICALLY GENERATED USING THE CATSPEAK BOOK GENERATOR: | ||
| https://github.com/katsaii/catspeak-lang | ||
| --><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="author" content="Katsaii"><meta name="description" content="Dubiously undocumented behaviour and quirks."><title>Catspeak Reference :: struct Future of Dubiously Undocumented</title><link rel="stylesheet" href="./style.css"></head><body><header><h1>Catspeak Reference</h1><nav><ul><li><a href="hom-welcome.html">Home</a></li><li><a href="lib-init.html">Library Reference</a></li><li><a href="dub-compatibility_v2.html"><mark>Dubiously Undocumented</mark></a></li></ul></nav><hr></header><article id="chapter-content"><aside id="chapters"><h2>Chapters</h2><ul><li><a href="dub-compatibility_v2.html">compatibility_v2</a><ul><li><a href="dub-struct-future.html"><mark>struct Future</mark></a></li><li><a href="dub-enum-futurestate.html">enum FutureState</a></li></ul></li></ul></aside><aside id="contents"><h2>Contents</h2><ul><li><a href="#accept">accept</a></li><li><a href="#andcatch">andCatch</a></li><li><a href="#andfinally">andFinally</a></li><li><a href="#andthen">andThen</a></li><li><a href="#reject">reject</a></li><li><a href="#resolved">resolved</a></li></ul></aside><main><article><h1 class="chapter-title">struct Future</h1><pre><code><span class="kw-key">function</span> <span class="kw-typ">Future</span>() <span class="kw-key">constructor</span> { | ||
| <span class="kw-com">// 6 fields omitted</span> | ||
| }</code></pre><blockquote class="stab deprecated"><strong>👎 Deprecated since 3.0.0</strong></blockquote><p>Constructs a new future, allowing for deferred execution of code depending | ||
| on whether it was accepted or rejected.</p><section><h1 class="heading" id="accept"><a href="#accept">§</a> accept</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">accept</span> = <span class="kw-key">function</span>( | ||
| <span class="kw-var">value</span>? : <span class="kw-typ">Any</span>, | ||
| )</code></pre><p>Accepts this future with the supplied argument.</p><p><strong>Arguments</strong></p><ul><li><p><code class="inline-code">value</code> <em>(optional)</em></p><p>The value to reject.</p></li></ul></section><section><h1 class="heading" id="andcatch"><a href="#andcatch">§</a> andCatch</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">andCatch</span> = <span class="kw-key">function</span>( | ||
| <span class="kw-var">callback</span> : <span class="kw-typ">Function</span>, | ||
| ) -> <span class="kw-typ">Struct</span>.<span class="kw-typ">Future</span></code></pre><p>Sets the callback function to invoke if an error occurrs whilst the | ||
| process is running.</p><p><strong>Arguments</strong></p><ul><li><p><code class="inline-code">callback</code></p><p>The function to invoke.</p></li></ul><p><strong>Returns</strong> <code class="inline-code">Struct.Future</code></p></section><section><h1 class="heading" id="andfinally"><a href="#andfinally">§</a> andFinally</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">andFinally</span> = <span class="kw-key">function</span>( | ||
| <span class="kw-var">callback</span> : <span class="kw-typ">Function</span>, | ||
| ) -> <span class="kw-typ">Struct</span>.<span class="kw-typ">Future</span></code></pre><p>Sets the callback function to invoke if this promise is resolved.</p><p><strong>Arguments</strong></p><ul><li><p><code class="inline-code">callback</code></p><p>The function to invoke.</p></li></ul><p><strong>Returns</strong> <code class="inline-code">Struct.Future</code></p></section><section><h1 class="heading" id="andthen"><a href="#andthen">§</a> andThen</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">andThen</span> = <span class="kw-key">function</span>( | ||
| <span class="kw-var">callback</span> : <span class="kw-typ">Function</span>, | ||
| ) -> <span class="kw-typ">Struct</span>.<span class="kw-typ">Future</span></code></pre><p>Sets the callback function to invoke once the process is complete.</p><p><strong>Arguments</strong></p><ul><li><p><code class="inline-code">callback</code></p><p>The function to invoke.</p></li></ul><p><strong>Returns</strong> <code class="inline-code">Struct.Future</code></p></section><section><h1 class="heading" id="reject"><a href="#reject">§</a> reject</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">reject</span> = <span class="kw-key">function</span>( | ||
| <span class="kw-var">value</span>? : <span class="kw-typ">Any</span>, | ||
| )</code></pre><p>Rejects this future with the supplied argument.</p><p><strong>Arguments</strong></p><ul><li><p><code class="inline-code">value</code> <em>(optional)</em></p><p>The value to reject.</p></li></ul></section><section><h1 class="heading" id="resolved"><a href="#resolved">§</a> resolved</h1><pre><code><span class="kw-key">static</span> <span class="kw-var">resolved</span> = <span class="kw-key">function</span>() | ||
| -> <span class="kw-typ">Bool</span></code></pre><p>Returns whether this future has been resolved. A resolved future | ||
| may be the result of being accepted OR rejected.</p><p><strong>Returns</strong> <code class="inline-code">Bool</code></p></section></article></main></article><footer><hr><article><em id="brand">Built using Catlog, the <a href="https://www.katsaii.com/catspeak-lang/">Catspeak</a> book generator.</em></article><article></article></footer></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| <!DOCTYPE html> | ||
| <!-- | ||
| AUTOMATICALLY GENERATED USING THE CATSPEAK BOOK GENERATOR: | ||
| https://github.com/katsaii/catspeak-lang | ||
| --><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="author" content="Katsaii"><meta name="description" content="A brief overview of Catspeak."><title>Catspeak Reference :: Getting Started of Home</title><link rel="stylesheet" href="./style.css"></head><body><header><h1>Catspeak Reference</h1><nav><ul><li><a href="hom-welcome.html"><mark>Home</mark></a></li><li><a href="lib-init.html">Library Reference</a></li><li><a href="dub-compatibility_v2.html">Dubiously Undocumented</a></li></ul></nav><hr></header><article id="chapter-content"><aside id="chapters"><h2>Chapters</h2><ul><li><a href="hom-welcome.html">Welcome</a></li><li><a href="hom-getting-started.html"><mark>Getting Started</mark></a></li><li><a href="hom-license.html">License</a></li></ul></aside><aside id="contents"><h2>Contents</h2><ul><li><a href="#installation">Installation</a></li><li><a href="#introduction">Introduction</a></li><li><a href="#parsing">Parsing</a></li><li><a href="#compiling">Compiling</a></li><li><a href="#executing">Executing</a></li><li><a href="#basic-usage">Basic Usage</a></li><li><a href="#interfacing-with-gml">Interfacing with GML</a></li></ul></aside><main><article><h1 class="chapter-title">Getting Started</h1><section><h1 class="heading" id="installation"><a href="#installation">§</a> <strong>Installation</strong></h1><ul><li><p>Get a recent release of Catspeak from the <a href="https://github.com/NuxiiGit/catspeak-lang/releases">GitHub releases page</a>. | ||
| You should see a download for a file with the extension <code class="inline-code">.yymps</code>.</p></li><li><p>Open your project file in the GameMaker IDE.</p></li><li><p>Navigate to the toolbar at the top of the IDE and find "Tools". Click this | ||
| and select "Import Local Package" from the drop-down menu.</p></li><li><p>Select the <code class="inline-code">.yymps</code> file you downloaded, and follow the wizard to import | ||
| the Catspeak resources. If you're not sure what to import, click "Add All".</p></li></ul><p>Now you're setup, see the <a href="#basic-usage">Basic Usage</a> section for some | ||
| introductory examples, or read through the <a href="#introduction">Introduction</a> section | ||
| for a full-fat overview.</p></section><section><h1 class="heading" id="introduction"><a href="#introduction">§</a> <strong>Introduction</strong></h1><p>Catspeak is the spiritual successor to the old GML function <code class="inline-code">execute_string</code>. | ||
| This means that custom user code can be executed as a string by your game | ||
| for modding support or a debug console. In nerdspeak: Catspeak is a compiler | ||
| backend and virtual machine for executing arbitrary code at runtime.</p><p>Unlike <code class="inline-code">execute_string</code>, Catspeak is slightly more involved, requiring three | ||
| separate steps:</p><ul><li><p><a href="#parsing">Parsing</a></p></li><li><p><a href="#compiling">Compiling</a></p></li><li><p><a href="#executing">Executing</a></p></li></ul></section><section><h1 class="heading" id="parsing"><a href="#parsing">§</a> <strong>Parsing</strong></h1><p>Parsing is the first step. This involves taking the human-readable form of | ||
| Catspeak source code, and converting it into an executable form. This can | ||
| be done from a string or a UTF-8 encoded buffer.</p><p>Parsing code from a string using <code class="inline-code">Catspeak.parseString</code>:</p><pre><code><span class="kw-key">var</span> <span class="kw-var">hir</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">parseString</span>(<span class="kw-val">@' | ||
| let n = 0 | ||
| while n <= 10 { | ||
| n += 1 | ||
| } | ||
| return "blast off!" | ||
| '</span>); | ||
| </code></pre><p>Parsing code from a file called "my_mod.meow", using <code class="inline-code">Catspeak.parse</code>:</p><pre><code><span class="kw-key">var</span> <span class="kw-var">file</span> = <span class="kw-fun">buffer_load</span>(<span class="kw-val">"my_mod.meow"</span>); | ||
|
|
||
| <span class="kw-key">var</span> <span class="kw-var">hir</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">parse</span>(<span class="kw-var">file</span>); | ||
|
|
||
| <span class="kw-fun">buffer_delete</span>(<span class="kw-var">file</span>); | ||
| </code></pre><p>The parser produces a <strong>hierarchical intermediate-representation</strong> (HIR), | ||
| storing information like what functions are defined, where they are defined, | ||
| how many variables are used, what functions are being called and when, etc.</p><p>This information is stored as a JSON object, so you can cache this to a file | ||
| to avoid parsing large mods every time the game loads.</p></section><section><h1 class="heading" id="compiling"><a href="#compiling">§</a> <strong>Compiling</strong></h1><p>Compiling is the second step. This involves taking the executable form of a | ||
| Catspeak program (the HIR obtained from <a href="#parsing">Parsing</a>) and transforms it | ||
| into a callable GML function.</p><p>Compiling a <code class="inline-code">program</code> from the <code class="inline-code">hir</code> using <code class="inline-code">Catspeak.compile</code>:</p><pre><code><span class="kw-key">var</span> <span class="kw-var">program</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">compile</span>(<span class="kw-var">hir</span>); | ||
| </code></pre></section><section><h1 class="heading" id="executing"><a href="#executing">§</a> <strong>Executing</strong></h1><p>Executing is the third and final step; this is the fun part. After compiling | ||
| a program, it can be called like any ordinary GML function like:</p><pre><code><span class="kw-fun">program</span>(); | ||
| </code></pre><p>As many times as you want:</p><pre><code><span class="kw-fun">program</span>(); | ||
| <span class="kw-fun">program</span>(); | ||
| <span class="kw-fun">program</span>(); | ||
| <span class="kw-key">repeat</span> (<span class="kw-val">10</span>) { | ||
| <span class="kw-fun">program</span>(); | ||
| } | ||
| </code></pre><p>When adding mod support, you should aim to pre-compile all of your mod scripts | ||
| at the start of the game, and then reuse the compiled program during gameplay. | ||
| Otherwise, your game may experience performance issues due to the slowness of | ||
| parsing and compiling programs relative to execution.</p></section><section><h1 class="heading" id="basic-usage"><a href="#basic-usage">§</a> <strong>Basic Usage</strong></h1><p>A minimal working example of a function which returns a message is:</p><pre><code><span class="kw-com">// parse Catspeak code</span> | ||
| <span class="kw-key">var</span> <span class="kw-var">hir</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">parseString</span>(<span class="kw-val">@' | ||
| let catspeak = "Catspeak" | ||
|
|
||
| return "hello! from within " + catspeak | ||
| '</span>); | ||
|
|
||
| <span class="kw-com">// compile Catspeak code into a callable GML function</span> | ||
| <span class="kw-key">var</span> <span class="kw-var">getMessage</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">compile</span>(<span class="kw-var">hir</span>); | ||
|
|
||
| <span class="kw-com">// call the Catspeak code just like you would any other GML function!</span> | ||
| <span class="kw-fun">show_message</span>(<span class="kw-fun">getMessage</span>()); | ||
| </code></pre></section><section><h1 class="heading" id="interfacing-with-gml"><a href="#interfacing-with-gml">§</a> <strong>Interfacing with GML</strong></h1><p>You can expose additional functions, constants, and assets to Catspeak programs | ||
| by using the methods on <code class="inline-code">Catspeak.interface</code>. For example, using the functions | ||
| <code class="inline-code">exposeFunction</code>, <code class="inline-code">exposeConstant</code>, and <code class="inline-code">exposeAsset</code> to make <code class="inline-code">show_message</code>, | ||
| <code class="inline-code">pi</code>, and <code class="inline-code">spr_player</code> available from within a Catspeak function:</p><pre><code><span class="kw-typ">Catspeak</span>.<span class="kw-var">interface</span>.<span class="kw-fun">exposeFunction</span>(<span class="kw-val">"show_message"</span>, <span class="kw-var">show_message</span>); | ||
| <span class="kw-typ">Catspeak</span>.<span class="kw-var">interface</span>.<span class="kw-fun">exposeConstant</span>(<span class="kw-val">"math_pi"</span>, <span class="kw-var">pi</span>); | ||
| <span class="kw-typ">Catspeak</span>.<span class="kw-var">interface</span>.<span class="kw-fun">exposeAsset</span>(<span class="kw-val">"sPlayer"</span>, <span class="kw-var">spr_player</span>); | ||
| </code></pre><p>Then using these from within a custom Catspeak function, like:</p><pre><code><span class="kw-key">var</span> <span class="kw-var">hir</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">parseString</span>(<span class="kw-val">@' | ||
| let tau = math_pi * 2; | ||
| show_message([sPlayer, tau]); | ||
| '</span>); | ||
| <span class="kw-key">var</span> <span class="kw-var">program</span> = <span class="kw-typ">Catspeak</span>.<span class="kw-fun">compile</span>(<span class="kw-var">hir</span>); | ||
| <span class="kw-fun">program</span>(); | ||
| </code></pre><p>This is necessary so that modders are sandboxed from each other, and don't have | ||
| unchecked access to your entire game state. There are many other ways of | ||
| exposing GML assets to Catspeak programs, see <a href="lib-struct-catspeakforeigninte+s.html">CatspeakForeignInterface</a></p></section></article></main></article><footer><hr><article><em id="brand">Built using Catlog, the <a href="https://www.katsaii.com/catspeak-lang/">Catspeak</a> book generator.</em></article><article></article></footer></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| <!DOCTYPE html> | ||
| <!-- | ||
| AUTOMATICALLY GENERATED USING THE CATSPEAK BOOK GENERATOR: | ||
| https://github.com/katsaii/catspeak-lang | ||
| --><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="author" content="Katsaii"><meta name="description" content="A brief overview of Catspeak."><title>Catspeak Reference :: License of Home</title><link rel="stylesheet" href="./style.css"></head><body><header><h1>Catspeak Reference</h1><nav><ul><li><a href="hom-welcome.html"><mark>Home</mark></a></li><li><a href="lib-init.html">Library Reference</a></li><li><a href="dub-compatibility_v2.html">Dubiously Undocumented</a></li></ul></nav><hr></header><article id="chapter-content"><aside id="chapters"><h2>Chapters</h2><ul><li><a href="hom-welcome.html">Welcome</a></li><li><a href="hom-getting-started.html">Getting Started</a></li><li><a href="hom-license.html"><mark>License</mark></a></li></ul></aside><aside id="contents"></aside><main><article><h1 class="chapter-title">License</h1><p>MIT License</p><p>Copyright (c) 2021-2024 Katsaii</p><p>Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions:</p><p>The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software.</p><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE.</p></article></main></article><footer><hr><article><em id="brand">Built using Catlog, the <a href="https://www.katsaii.com/catspeak-lang/">Catspeak</a> book generator.</em></article><article></article></footer></body></html> |
Oops, something went wrong.