diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-02-20 22:33:12 -0500 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-02-20 22:33:12 -0500 |
| commit | c7d35616ae7daae86d0c552b1a284ede564768b2 (patch) | |
| tree | d25c767cab19428a0e3e27edffdf6db42303298f /docs/doc/embed.html | |
| parent | 05a552e83ff523cdc6af6f04de12d676539d89ed (diff) | |
Start documentation page on the JS embedding
Diffstat (limited to 'docs/doc/embed.html')
| -rw-r--r-- | docs/doc/embed.html | 13 |
1 files changed, 13 insertions, 0 deletions
diff --git a/docs/doc/embed.html b/docs/doc/embed.html new file mode 100644 index 00000000..a9fcf24f --- /dev/null +++ b/docs/doc/embed.html @@ -0,0 +1,13 @@ +<head> + <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/> + <link href="../style.css" rel="stylesheet"/> + <title>Using embedded BQN</title> +</head> +<div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">doc</a></div> +<h1 id="using-embedded-bqn">Using embedded BQN</h1> +<p>The Javascript implementation of BQN can be <a href="https://mlochbaum.github.io/BQN/try.html">used</a> as a standalone interpreter, but it can also be called from JS, which in combination with BQN's first-class functions allows the two language to interoperate well. Similar functionality will most likely be brought to other host languages in the future. Languages that (like JS) allow functions and arrays to be tagged with extra properties can host a full BQN implementation with good interoperability. Other languages would either require functions and arrays to be stored in specialized data structures, making interoperability a little harder, or would miss out on some inferred properties like function inverses and array fills.</p> +<p>There is only one mechanism to interface between the host language and BQN: you can evaluate a BQN program from the host and get the result back. Doesn't sound like much, especially considering these programs can't share any state such as global variables (BQN doesn't have those). But taking first-class functions and closures into account, it's all you could ever need!</p> +<h2 id="js-encodings">JS encodings</h2> +<p>It's often useful to pass BQN values directly from JS instead of creating them in BQN. BQN operations don't verify that their inputs are valid BQN values (this would have a large performance cost), so it's up to the JS programmer to make sure that values passed in are valid. To do this, you need to know how BQN values are encoded in JS. Each of the six <a href="types.html">types</a> has its own encoding.</p> +<p>The two atomic data values are simple: numbers are just JS numbers, and characters are strings containing a single code point. Arrays <em>are</em> JS arrays, but with some extra information. Since JS arrays are 1-dimensional, a BQN array <code><span class='Value'>a</span></code> is stored as the element list <code><span class='Function'>⥊</span><span class='Value'>a</span></code>. Its shape <code><span class='Function'>≢</span><span class='Value'>a</span></code>, a list of numbers, is <code><span class='Value'>a.sh</span></code> in JS (the shape isn't necessarily a BQN array so it doesn't have to have a <code><span class='Value'>sh</span></code> property). Optionally, its fill element is <code><span class='Value'>a.fill</span></code>.</p> +<p>Operations are all stored as JS functions, with one or two arguments for the inputs. The type is determined by the <code><span class='Number'>.m</span></code> property, which is <code><span class='Number'>1</span></code> for a 1-modifier and <code><span class='Number'>2</span></code> for a 2-modifier, and undefined or falsy for a function. Functions might be called with one or two arguments. In either case, <code><span class='Value'>𝕩</span></code> is the first argument; <code><span class='Value'>𝕨</span></code>, if present, is the second. Note that <code><span class='Function'>F</span><span class='Paren'>(</span><span class='Value'>x</span><span class='Separator'>,</span><span class='Value'>w</span><span class='Paren'>)</span></code> in Javascript corresponds to <code><span class='Value'>w</span> <span class='Function'>F</span> <span class='Value'>x</span></code> in BQN, reversing the visual ordering of the arguments! For modifiers there's no such reversal, as <code><span class='Value'>𝕗</span></code> is always the first argument, and for 2-modifiers <code><span class='Value'>𝕘</span></code> is the second argument. As in BQN, a modifier may or may not return a function.</p> |