diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-12-16 22:15:39 -0500 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-12-17 08:42:04 -0500 |
| commit | fc2687ffc8dcb8117bb957bea6b4e7bbdb45ca71 (patch) | |
| tree | 3d6fbf9348c246646809d9d03e6c9fa842150474 /docs | |
| parent | b85d92151bbb865028249cfc215a3c3caa19ec5d (diff) | |
•ReBQN documentation
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/doc/index.html | 1 | ||||
| -rw-r--r-- | docs/doc/rebqn.html | 78 | ||||
| -rw-r--r-- | docs/index.html | 2 |
3 files changed, 80 insertions, 1 deletions
diff --git a/docs/doc/index.html b/docs/doc/index.html index cd9f7f0e..2935fc92 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -76,4 +76,5 @@ <p>Environment:</p> <ul> <li><a href="embed.html">Embedded BQN</a></li> +<li><a href="rebqn.html">ReBQN</a></li> </ul> diff --git a/docs/doc/rebqn.html b/docs/doc/rebqn.html new file mode 100644 index 00000000..9911d7c0 --- /dev/null +++ b/docs/doc/rebqn.html @@ -0,0 +1,78 @@ +<head> + <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/> + <link href="../style.css" rel="stylesheet"/> + <title>ReBQN</title> +</head> +<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div> +<h1 id="rebqn"><a class="header" href="#rebqn">ReBQN</a></h1> +<p>The function <code><span class='Function'>•BQN</span></code> evaluates a source code string passed to it as BQN in an isolated environment and returns the result. There are a few things you might want to change about this. <code><span class='Function'>•ReBQN</span></code> is a function that <em>generates</em> <code><span class='Function'>•BQN</span></code>-like functions, using a <a href="namespace.html">namespace</a> <code><span class='Value'>𝕩</span></code> for configuration. It can create a "REPL" function that saves state between evaluations, or redefine primitives, and might support extra functionality like keywords in the future.</p> +<p>Here are some quick examples of <code><span class='Function'>•ReBQN</span></code> functionality. First, let's make a REPL function by setting <code><span class='Value'>repl</span></code> to <code><span class='String'>"strict"</span></code> (no re-definitions allowed) instead of the default <code><span class='String'>"none"</span></code>. We can now define a variable in one <code><span class='Function'>Repl</span></code> call and refer to it later.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=cmVwbCDihpAg4oCiUmVCUU4ge3JlcGzih5Aic3RyaWN0In0gICMgTG93ZXJjYXNlIGZvciBmdW5jdGlvbiByZXN1bHQKClJlcGwgImEg4oaQIOKGlTEwIiAgICAgICAgICAgICAgICAgIyBVcHBlcmNhc2UgdG8gY2FsbAoKUmVwbCAi4oy9IGEi">↗️</a><pre> <span class='Value'>repl</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>repl</span><span class='Gets'>⇐</span><span class='String'>"strict"</span><span class='Brace'>}</span> <span class='Comment'># Lowercase for function result +</span> + <span class='Function'>Repl</span> <span class='String'>"a ← ↕10"</span> <span class='Comment'># Uppercase to call +</span>⟨ 0 1 2 3 4 5 6 7 8 9 ⟩ + + <span class='Function'>Repl</span> <span class='String'>"⌽ a"</span> +⟨ 9 8 7 6 5 4 3 2 1 0 ⟩ +</pre> +<p>This option also powers the results shown on the BQN website: to process a document, a REPL function is created, and used to evaluate every line! Next, we can define a little ASCII calculator using a list of primitives. To mix it up a bit I've made monadic <code><span class='Function'>/</span></code> here a Range function.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Y2FsY0ZucyDihpAg4p+oJysn4oC/KywgJy0n4oC/LSwgJyon4oC/w5csICcvJ+KAvyjihpXiipjDtynin6kKCmNhbGMg4oaQIOKAolJlQlFOIHtwcmltaXRpdmVz4oeQY2FsY0Zuc30KCkNhbGMgIjcgLyA5IC0gMioyIiAgIyBCUU4gb3JkZXIgb2Ygb3BlcmF0aW9ucwoKQ2FsYyAiLyA5Ig==">↗️</a><pre> <span class='Value'>calcFns</span> <span class='Gets'>←</span> <span class='Bracket'>⟨</span><span class='String'>'+'</span><span class='Ligature'>‿</span><span class='Function'>+</span><span class='Separator'>,</span> <span class='String'>'-'</span><span class='Ligature'>‿</span><span class='Function'>-</span><span class='Separator'>,</span> <span class='String'>'*'</span><span class='Ligature'>‿</span><span class='Function'>×</span><span class='Separator'>,</span> <span class='String'>'/'</span><span class='Ligature'>‿</span><span class='Paren'>(</span><span class='Function'>↕</span><span class='Modifier2'>⊘</span><span class='Function'>÷</span><span class='Paren'>)</span><span class='Bracket'>⟩</span> + + <span class='Value'>calc</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>primitives</span><span class='Gets'>⇐</span><span class='Value'>calcFns</span><span class='Brace'>}</span> + + <span class='Function'>Calc</span> <span class='String'>"7 / 9 - 2*2"</span> <span class='Comment'># BQN order of operations +</span>1.4 + + <span class='Function'>Calc</span> <span class='String'>"/ 9"</span> +⟨ 0 1 2 3 4 5 6 7 8 ⟩ +</pre> +<p>Options can be used in any combination. Here's a calculator REPL:</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Y2FsY1JlcGwg4oaQIOKAolJlQlFOIHtyZXBs4oeQInN0cmljdCIsIHByaW1pdGl2ZXPih5BjYWxjRm5zfQoKQ2FsY1JlcGwgImIg4oaQIDEgLSBh4oaQNiIKCkNhbGNSZXBsICJhICogYiI=">↗️</a><pre> <span class='Value'>calcRepl</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>repl</span><span class='Gets'>⇐</span><span class='String'>"strict"</span><span class='Separator'>,</span> <span class='Value'>primitives</span><span class='Gets'>⇐</span><span class='Value'>calcFns</span><span class='Brace'>}</span> + + <span class='Function'>CalcRepl</span> <span class='String'>"b ← 1 - a←6"</span> +¯5 + + <span class='Function'>CalcRepl</span> <span class='String'>"a * b"</span> +¯30 +</pre> +<h2 id="repl-mode"><a class="header" href="#repl-mode">REPL mode</a></h2> +<p>The <code><span class='Value'>repl</span></code> property can have the values <code><span class='String'>"none"</span></code>, <code><span class='String'>"strict"</span></code>, and <code><span class='String'>"loose"</span></code>. If no value is given it's equivalent to <code><span class='String'>"none"</span></code>, which means that the resulting function has no memory and each evaluation is independent from the others. But the values <code><span class='String'>"strict"</span></code> and <code><span class='String'>"loose"</span></code> make evaluations take place in a shared <a href="lexical.html">scope</a>. Now a variable defined at the top level of one source string is visible when later ones are evaluated, and can be viewed and modified.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ZG8g4oaQIOKAolJlQlFOIHtyZXBs4oeQImxvb3NlIn0KCkRvwqggImHihpA0IuKAvyLin6hhLGLihpA14p+pIuKAvyJ74p+oYeKGqfCdlaksYuKfqX04Ig==">↗️</a><pre> <span class='Value'>do</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>repl</span><span class='Gets'>⇐</span><span class='String'>"loose"</span><span class='Brace'>}</span> + + <span class='Function'>Do</span><span class='Modifier'>¨</span> <span class='String'>"a←4"</span><span class='Ligature'>‿</span><span class='String'>"⟨a,b←5⟩"</span><span class='Ligature'>‿</span><span class='String'>"{⟨a↩𝕩,b⟩}8"</span> +⟨ 4 ⟨ 4 5 ⟩ ⟨ 8 5 ⟩ ⟩ +</pre> +<p>A different <code><span class='Function'>•ReBQN</span></code> result has its own scope and can't access these variables.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ZG9Ob3Qg4oaQIOKAolJlQlFOIHtyZXBs4oeQImxvb3NlIn0KCkRvTm90ICJiIiAjIHN1cnByaXNlZCB3aGVuIHRoaXMgZmFpbHM=">↗️</a><pre> <span class='Value'>doNot</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>repl</span><span class='Gets'>⇐</span><span class='String'>"loose"</span><span class='Brace'>}</span> + + <span class='Function'>DoNot</span> <span class='String'>"b"</span> <span class='Comment'># surprised when this fails +</span>ERROR +</pre> +<p>The difference in <code><span class='String'>"strict"</span></code> and <code><span class='String'>"loose"</span></code> is that a loose REPL can define a variable again, which just changes its value (under the covers, the <code><span class='Gets'>←</span></code> is treated as a <code><span class='Gets'>↩</span></code>).</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=RG8gImEg4oaQIMKvMSIKRG8gImEg4oaQIGLigL9hIgoKKOKAolJlQlFOIHtyZXBs4oeQInN0cmljdCJ9KeKOikDCqCAiYeKGkDEi4oC/ImHihpAyIiAgIyBTZWNvbmQgb25lIGVycm9ycw==">↗️</a><pre> <span class='Function'>Do</span> <span class='String'>"a ← ¯1"</span> +¯1 + <span class='Function'>Do</span> <span class='String'>"a ← b‿a"</span> +⟨ 5 ¯1 ⟩ + + <span class='Paren'>(</span><span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>repl</span><span class='Gets'>⇐</span><span class='String'>"strict"</span><span class='Brace'>}</span><span class='Paren'>)</span><span class='Modifier2'>⎊</span><span class='String'>@</span><span class='Modifier'>¨</span> <span class='String'>"a←1"</span><span class='Ligature'>‿</span><span class='String'>"a←2"</span> <span class='Comment'># Second one errors +</span>⟨ 1 @ ⟩ +</pre> +<h2 id="primitives"><a class="header" href="#primitives">Primitives</a></h2> +<p>The <code><span class='Value'>primitives</span></code> property specifies the full set of primitives available to the new interpreter. Without it, the existing set of primitives is kept. With it, they're all thrown out, and the ones provided are used instead. Since you often would rather extend or modify what's there, the system value <code><span class='Value'>•primitives</span></code> returns the current primitives set in the form used by <code><span class='Function'>•ReBQN</span></code>.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MyDihpEg4oCicHJpbWl0aXZlcwoKZXh0IOKGkCDigKJSZUJRTiB7cHJpbWl0aXZlc+KHkOKAonByaW1pdGl2ZXPiiL7in6gn4oiRJywrwrTin6nigL/in6gn4oiPJyzDl8K04p+pfQoKRXh0ICLiiI8xK+KGlTciCkV4dCAi4oiRKDHihpPihpUp4oq4KOKKoy/LnDA9fCkyOCIgICMgU3VtIG9mIGRpdmlzb3Jz">↗️</a><pre> <span class='Number'>3</span> <span class='Function'>↑</span> <span class='Value'>•primitives</span> +⟨ ⟨ '+' + ⟩ ⟨ '-' - ⟩ ⟨ '×' × ⟩ ⟩ + + <span class='Value'>ext</span> <span class='Gets'>←</span> <span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>primitives</span><span class='Gets'>⇐</span><span class='Value'>•primitives</span><span class='Function'>∾</span><span class='Bracket'>⟨</span><span class='String'>'∑'</span><span class='Separator'>,</span><span class='Function'>+</span><span class='Modifier'>´</span><span class='Bracket'>⟩</span><span class='Ligature'>‿</span><span class='Bracket'>⟨</span><span class='String'>'∏'</span><span class='Separator'>,</span><span class='Function'>×</span><span class='Modifier'>´</span><span class='Bracket'>⟩</span><span class='Brace'>}</span> + + <span class='Function'>Ext</span> <span class='String'>"∏1+↕7"</span> +5040 + <span class='Function'>Ext</span> <span class='String'>"∑(1↓↕)⊸(⊣/˜0=|)28"</span> <span class='Comment'># Sum of divisors +</span>28 +</pre> +<p>Appending to <code><span class='Value'>•primitives</span></code> means everything from BQN's there in addition to the given functions.</p> +<p>What's allowed? The format for <code><span class='Value'>primitives</span></code> is a list of pairs, where each pair contains one character—the glyph—and one function or modifier. A primitive can't be data, at least at present, because the compiler is only designed to handle the primitive types found in base BQN and extending this doesn't seem terribly important. The type of the primitive's value is very important, because it determines the <a href="expression.html#syntactic-role">role</a> it has. Said another way, it's setting the rules of syntax!</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKAolJlQlFOIHtwcmltaXRpdmVz4oeQ4p+oJ14n4oC/e/CdlajwnZS98J2VqfCdlL3wnZWofSwnJSfigL/iiL7in6l9KXvwnZS9fSAiMCAlXiAx4oC/MiI=">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>•ReBQN</span> <span class='Brace'>{</span><span class='Value'>primitives</span><span class='Gets'>⇐</span><span class='Bracket'>⟨</span><span class='String'>'^'</span><span class='Ligature'>‿</span><span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Function'>𝔽</span><span class='Value'>𝕨</span><span class='Brace'>}</span><span class='Separator'>,</span><span class='String'>'%'</span><span class='Ligature'>‿</span><span class='Function'>∾</span><span class='Bracket'>⟩</span><span class='Brace'>}</span><span class='Paren'>)</span><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Brace'>}</span> <span class='String'>"0 %^ 1‿2"</span> +⟨ 0 1 2 0 ⟩ +</pre> +<p>Above, <code><span class='Value'>^</span></code> becomes a 1-modifier, so that it modifies <code><span class='Value'>%</span></code> rather than being called directly on <code><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span></code> as a function.</p> +<p>The glyph can be any character that's not being used by BQN already. Characters like <code><span class='Value'>c</span></code> or <code><span class='Bracket'>⟩</span></code> or <code><span class='Value'>:</span></code> will result in an error, as they'd break BQN syntax. Other than that, the sky's the limit! Or rather, the Unicode consortium is the limit. If they don't recognize your symbol, you're going to have to petition to make it an emoji or something. Oh well.</p> diff --git a/docs/index.html b/docs/index.html index c14dcff4..6aa53d48 100644 --- a/docs/index.html +++ b/docs/index.html @@ -27,13 +27,13 @@ <li>A low-dependency C implementation using bytecode compilation: <a href="running.html">installation</a></li> <li>Basic <a href="spec/system.html">system functions</a> for common math, file, and IO operations</li> <li>Documentation with examples, visuals, explanations, and rationale for features</li> +<li>Replace or extend primitives to make a <a href="doc/rebqn.html">BQN-like language</a> suited for specialized domains</li> </ul> <p>BQN <strong>will provide</strong>:</p> <ul> <li>State of the art array performance: takes some time, but I developed many of Dyalog APL's current algorithms and know we'll get there</li> <li>Interfaces to connect with other languages, like a C FFI and JSON and CSV tools</li> <li>A standard system to install and use libraries and packages, and support for package managers</li> -<li>Replace or extend primitives to make a BQN-like language suited for specialized domains</li> </ul> <p>At present, I think BQN is a good choice for learning array programming, scripting, medium-scale number crunching, and recreational programming. For some examples of BQN in action, this repository holds the dreaded <a href="https://github.com/mlochbaum/BQN/blob/master/src/c.bqn">self-hosted compiler</a> and the friendlier <a href="https://github.com/mlochbaum/BQN/blob/master/md.bqn">markdown processor</a> used to generate the site. See also my scripts at <a href="https://github.com/mlochbaum/bqn-libs">bqn-libs</a>, this <a href="https://github.com/frasiyav/BQN-Gnuplot/blob/main/Gnuplot.bqn">gnuplot interface</a>, some nicely commented Advent of Code 2021 <a href="https://gitlab.com/icen/aoc21">solutions</a>, or something else from the <a href="community/index.html">community</a> page.</p> <h2 id="what-kind-of-name-is-bqn"><a class="header" href="#what-kind-of-name-is-bqn">What kind of name is "BQN"?</a></h2> |