code.H3RALD.com — min: a0efcd6b54e03b142fdf0db7c69e11082dc1b95b

Writing reference docs.

h3rald h3rald@h3rald.com

Sun, 30 Oct 2016 19:10:14 +0100

commit

a0efcd6b54e03b142fdf0db7c69e11082dc1b95b

parent

36f1793980184ab8645063b8b66b991d9d0b4d1f

3 files changed, 217 insertions(+), 29 deletions(-)

jump to

doc/MiNiM_UserGuide.htm

doc/MiNiM_UserGuide.md

doc/reference.md

M doc/MiNiM_UserGuide.htm → doc/MiNiM_UserGuide.htm

@@ -79,6 +79,7 @@ <li><a href="#Overview">Overview</a></li>
   <li><a href="#Usage">Usage</a></li>
   <li><a href="#Reference">Reference</a>
   <ul>
+   <li><a href="#Notation">Notation</a></li>
    <li><a href="#L.code.lang..code..Module"><code>lang</code> Module</a>
    <ul>
     <li><a href="#bind">bind</a></li>
@@ -89,12 +90,14 @@ <li><a href="#define">define</a></li>
     <li><a href="#delete">delete</a></li>
     <li><a href="#eval">eval</a></li>
     <li><a href="#exit">exit</a></li>
+    <li><a href="#format-error">format-error</a></li>
     <li><a href="#from-json">from-json</a></li>
     <li><a href="#import">import</a></li>
+    <li><a href="#inspect">inspect</a></li>
     <li><a href="#load">load</a></li>
     <li><a href="#module">module</a></li>
-    <li><a href="#scope">scope</a></li>
-    <li><a href="#scope.">scope?</a></li>
+    <li><a href="#publish">publish</a></li>
+    <li><a href="#raise">raise</a></li>
     <li><a href="#sigils">sigils</a></li>
     <li><a href="#source">source</a></li>
     <li><a href="#symbols">symbols</a></li>
@@ -123,6 +126,44 @@ <h2 id="Usage">Usage<a href="#document-top" title="Go to top"></a></h2>
 
 <h2 id="Reference">Reference<a href="#document-top" title="Go to top"></a></h2>
 
+<h3 id="Notation">Notation<a href="#document-top" title="Go to top"></a></h3>
+
+<dl>
+<dt>*</dt>
+<dd>Any value.</dd>
+<dt>B</dt>
+<dd>A boolean value.</dd>
+<dt><span class="kwd">(*)</span></dt>
+<dd>A quotation.</dd>
+<dt><span class="kwd">(1)</span></dt>
+<dd>The first quotation on the stack.</dd>
+<dt><span class="kwd">(2)</span></dt>
+<dd>The second quotation on the stack.</dd>
+<dt><span class="kwd">(E)</span></dt>
+<dd>An error dictionary:
+<pre><code>(
+  (error &ldquo;MyError&rdquo;)
+  (message &ldquo;An error occurred&rdquo;)
+  (symbol &ldquo;symbol1&rdquo;)            ;Optional
+  (filename &ldquo;dir1/file1.min&rdquo;)   ;Optional
+  (line 3)                      ;Optional
+  (column 13)                   ;Optional
+)
+</code></pre></dd>
+<dt><span class="kwd">S</span></dt>
+<dd>A string value.</dd>
+<dt>S+</dt>
+<dd>One or more string values.</dd>
+<dt><span class="kwd">§</span></dt>
+<dd>String-like (a string or quoted sumbol).</dd>
+<dt><span class="kwd">false</span> </dt>
+<dd>false (boolean type).</dd>
+<dt><span class="kwd">true</span></dt>
+<dd>true (boolean type).</dd>
+<dt>&#x2205;</dt>
+<dd>No value.</dd>
+</dl>
+
 <h3 id="L.code.lang..code..Module"><code>lang</code> Module<a href="#document-top" title="Go to top"></a></h3>
 
 <h4 id="bind">bind<a href="#document-top" title="Go to top"></a></h4>
@@ -173,6 +214,20 @@ <p><em>Signature:</em> <span class="kwd"> &#x2205; <strong>&rArr;</strong> &#x2205;</span></p>
 
 <p>Exits the program or shell.</p>
 
+<h4 id="format-error">format-error<a href="#document-top" title="Go to top"></a></h4>
+
+<p><em>Signature:</em> <span class="kwd"> (E) <strong>&rArr;</strong> S</span></p>
+
+<p>Formats the error <span class="kwd">(E)</span> as a string.</p>
+
+<div class="sidebar"><p>Example</p>
+
+<p>The following:</p>
+
+<p><code>((error "MyError") (message "This is a test error")) format-error</code></p>
+
+<p>produces: <code>"(!) This is a test error"</code></p></div>
+
 <h4 id="from-json">from-json<a href="#document-top" title="Go to top"></a></h4>
 
 <p><em>Signature:</em> <span class="kwd"> S <strong>&rArr;</strong> *</span></p>
@@ -185,6 +240,12 @@ <p><em>Signature:</em> <span class="kwd"> § <strong>&rArr;</strong> &#x2205;</span></p>
 
 <p>Imports the a previously-loaded module <span class="kwd">§</span>, defining all its symbols in the current scope.</p>
 
+<h4 id="inspect">inspect<a href="#document-top" title="Go to top"></a></h4>
+
+<p><em>Signature:</em> <span class="kwd"> (*) <strong>&rArr;</strong> (S+)</span></p>
+
+<p>Returns a list of symbols published on <span class="kwd">(*)</span>&rsquo;s scope.</p>
+
 <h4 id="load">load<a href="#document-top" title="Go to top"></a></h4>
 
 <p><em>Signature:</em> <span class="kwd"> S <strong>&rArr;</strong> *?</span></p>
@@ -197,17 +258,22 @@ <p><em>Signature:</em> <span class="kwd"> (*) § <strong>&rArr;</strong> &#x2205;</span></p>
 
 <p>Creates a new module <span class="kwd">§</span> based on quotation <span class="kwd">(*)</span>.</p>
 
-<h4 id="scope">scope<a href="#document-top" title="Go to top"></a></h4>
+<h4 id="publish">publish<a href="#document-top" title="Go to top"></a></h4>
 
-<p><em>Signature:</em> <span class="kwd"> (*) <strong>&rArr;</strong> (*)</span></p>
+<p><em>Signature:</em> <span class="kwd"> § (*) <strong>&rArr;</strong> &#x2205;</span></p>
+
+<p>Publishes symbol <span class="kwd">§</span> to the scope of <span class="kwd">(*)</span>.</p>
+
+<div class="sidebar"><p>Example</p>
 
-<p>Unquotes <span class="kwd">(*)</span> creating a new scope and pushes a new copy of <span class="kwd">(*)</span> on the stack.</p>
+<p>Publish symbol <span class="kwd">my-local-symbol</span> to <span class="kwd">ROOT</span> scope:
+<code>'my-local-symbol ROOT publish</code></p></div>
 
-<h4 id="scope.">scope?<a href="#document-top" title="Go to top"></a></h4>
+<h4 id="raise">raise<a href="#document-top" title="Go to top"></a></h4>
 
-<p><em>Signature:</em> <span class="kwd"> (*) <strong>&rArr;</strong> (B)</span></p>
+<p><em>Signature:</em> <span class="kwd"> (E) <strong>&rArr;</strong> &#x2205;</span></p>
 
-<p>Returnes <span class="kwd">true</span> if <span class="kwd">(*)</span> defines a scope, <span class="kwd">false</span> otherwise.</p>
+<p>Raises the error specified via the dictionary <span class="kwd">(E)</span>.</p>
 
 <h4 id="sigils">sigils<a href="#document-top" title="Go to top"></a></h4>
 
@@ -256,7 +322,7 @@ 
 <h3 id="L.code.crypto..code..Module"><code>crypto</code> Module<a href="#document-top" title="Go to top"></a></h3>
     </div>
     <div id="footer">
-      <p><span class="copy"></span> Fabio Cevasco &ndash; October 22, 2016</p>
+      <p><span class="copy"></span> Fabio Cevasco &ndash; October 30, 2016</p>
       <p><span>Powered by</span> <a href="https://h3rald.com/hastyscribe"><span class="hastyscribe"></span></a></p>
     </div>
   </div>

M doc/MiNiM_UserGuide.md → doc/MiNiM_UserGuide.md

@@ -15,19 +15,55 @@ $4
 
  #}
 
+### Notation
+
+\*
+: Any value.
+B
+: A boolean value.
+{{q -> [(\*)](class:kwd)}}
+: A quotation.
+{{1 -> [(1)](class:kwd)}}
+: The first quotation on the stack.
+{{2 -> [(2)](class:kwd)}}
+: The second quotation on the stack.
+{{e -> [(E)](class:kwd)}}
+: An error dictionary:
+  <pre><code>(
+    (error "MyError")
+    (message "An error occurred")
+    (symbol "symbol1")            ;Optional
+    (filename "dir1/file1.min")   ;Optional
+    (line 3)                      ;Optional
+    (column 13)                   ;Optional
+  )
+  </code></pre>
+{{s -> [S](class:kwd)}}
+: A string value.
+S+
+: One or more string values.
+{{sl -> [§](class:kwd)}}
+: String-like (a string or quoted sumbol).
+{{f -> [false](class:kwd)}} 
+: false (boolean type).
+{{t -> [true](class:kwd)}}
+: true (boolean type).
+{{null -> &#x2205;}}
+: No value.
+
 ### `lang` Module
 
 {#op||bind||\* §||{{null}}||
-Binds the specified value (auto-quoted) to an existing symbol {{sl -> [§](class:kwd)}}.#}
+Binds the specified value (auto-quoted) to an existing symbol {{sl}}.#}
 
 {#op||call||(\*) §||\*?||
-Calls operator {{sl}} defined in scope [(\*)](class:kwd). #}
+Calls operator {{sl}} defined in scope {{q}}. #}
 
 {#op||debug||{{null}}||{{null}}||
 Toggles debug mode. #}
 
 {#op||debug?||{{null}}||B||
-Returns {{t -> [true](class:kwd)}} if debug mode is on, {{f -> [false](class:kwd)}} otherwise. #}
+Returns {{t}} if debug mode is on, {{f}} otherwise. #}
 
 {#op||define||\* §||{{null}}||
 Defines a new symbol {{sl}}, containing the specified value (auto-quoted).#}
@@ -36,28 +72,53 @@ {#op||delete||§||{{null}}||
 Deletes the specified symbol {{sl}}.#}
 
 {#op||eval||S||\*?||
-Parses and interprets {{s -> [S](class:kwd)}}. #}
+Parses and interprets {{s}}. #}
 
-{#op||exit||{{null -> &#x2205;}}||{{null}}||
+{#op||exit||{{null}}||{{null}}||
 Exits the program or shell. #}
 
+{#op||format-error||(E)||S||
+Formats the error {{e}} as a string.
+
+> %sidebar%
+> Example
+> 
+> The following: 
+> 
+> `((error "MyError") (message "This is a test error")) format-error`
+> 
+> produces: `"(!) This is a test error"`
+#}
+
 {#op||from-json||S||\*||
 Converts a JSON string into {{M -> MiNiM}} data.#}
 
 {#op||import||§||{{null}}||
 Imports the a previously-loaded module {{sl}}, defining all its symbols in the current scope. #}
 
+{#op||inspect||(\*)||(S+)||
+Returns a list of symbols published on {{q}}'s scope. #}
+
 {#op||load||S||\*?||
-Parses and interprets the specified {{M}} file {{s -> [S](class:kwd)}}, adding [.min](class:ext) if not specified. #}
+Parses and interprets the specified {{M}} file {{s}}, adding [.min](class:ext) if not specified. #}
 
 {#op||module||(\*) §||{{null}}||
 Creates a new module {{sl}} based on quotation {{q}}. #}
 
-{#op||scope||(\*)||(\*)||
-Unquotes {{q -> [(\*)](class:kwd)}} creating a new scope and pushes a new copy of {{q}} on the stack.#}
+{#op||publish||§ (*)||{{null}}||
+Publishes symbol {{sl}} to the scope of [(\*)](class:kwd).
 
-{#op||scope?||(\*)||(B)||
-Returnes {{t}} if {{q}} defines a scope, {{f}} otherwise. #}
+> %sidebar%
+> Example
+>
+> Publish symbol [my-local-symbol](class:kwd) to [ROOT](class:kwd) scope:
+> `'my-local-symbol ROOT publish`
+
+#}
+
+{#op||raise||(E)||{{null}}||
+Raises the error specified via the dictionary {{e}}.#}
+
 
 {#op||sigils||{{null}}||(S+)||
 Returns a list of all sigils defined in the [ROOT](class:kwd) scope.#}

M doc/reference.md → doc/reference.md

@@ -9,19 +9,55 @@ $4
 
  #}
 
+### Notation
+
+\*
+: Any value.
+B
+: A boolean value.
+{{q -> [(\*)](class:kwd)}}
+: A quotation.
+{{1 -> [(1)](class:kwd)}}
+: The first quotation on the stack.
+{{2 -> [(2)](class:kwd)}}
+: The second quotation on the stack.
+{{e -> [(E)](class:kwd)}}
+: An error dictionary:
+  <pre><code>(
+    (error "MyError")
+    (message "An error occurred")
+    (symbol "symbol1")            ;Optional
+    (filename "dir1/file1.min")   ;Optional
+    (line 3)                      ;Optional
+    (column 13)                   ;Optional
+  )
+  </code></pre>
+{{s -> [S](class:kwd)}}
+: A string value.
+S+
+: One or more string values.
+{{sl -> [§](class:kwd)}}
+: String-like (a string or quoted sumbol).
+{{f -> [false](class:kwd)}} 
+: false (boolean type).
+{{t -> [true](class:kwd)}}
+: true (boolean type).
+{{null -> &#x2205;}}
+: No value.
+
 ### `lang` Module
 
 {#op||bind||\* §||{{null}}||
-Binds the specified value (auto-quoted) to an existing symbol {{sl -> [§](class:kwd)}}.#}
+Binds the specified value (auto-quoted) to an existing symbol {{sl}}.#}
 
 {#op||call||(\*) §||\*?||
-Calls operator {{sl}} defined in scope [(\*)](class:kwd). #}
+Calls operator {{sl}} defined in scope {{q}}. #}
 
 {#op||debug||{{null}}||{{null}}||
 Toggles debug mode. #}
 
 {#op||debug?||{{null}}||B||
-Returns {{t -> [true](class:kwd)}} if debug mode is on, {{f -> [false](class:kwd)}} otherwise. #}
+Returns {{t}} if debug mode is on, {{f}} otherwise. #}
 
 {#op||define||\* §||{{null}}||
 Defines a new symbol {{sl}}, containing the specified value (auto-quoted).#}
@@ -30,28 +66,53 @@ {#op||delete||§||{{null}}||
 Deletes the specified symbol {{sl}}.#}
 
 {#op||eval||S||\*?||
-Parses and interprets {{s -> [S](class:kwd)}}. #}
+Parses and interprets {{s}}. #}
 
-{#op||exit||{{null -> &#x2205;}}||{{null}}||
+{#op||exit||{{null}}||{{null}}||
 Exits the program or shell. #}
 
+{#op||format-error||(E)||S||
+Formats the error {{e}} as a string.
+
+> %sidebar%
+> Example
+> 
+> The following: 
+> 
+> `((error "MyError") (message "This is a test error")) format-error`
+> 
+> produces: `"(!) This is a test error"`
+#}
+
 {#op||from-json||S||\*||
 Converts a JSON string into {{M -> MiNiM}} data.#}
 
 {#op||import||§||{{null}}||
 Imports the a previously-loaded module {{sl}}, defining all its symbols in the current scope. #}
 
+{#op||inspect||(\*)||(S+)||
+Returns a list of symbols published on {{q}}'s scope. #}
+
 {#op||load||S||\*?||
-Parses and interprets the specified {{M}} file {{s -> [S](class:kwd)}}, adding [.min](class:ext) if not specified. #}
+Parses and interprets the specified {{M}} file {{s}}, adding [.min](class:ext) if not specified. #}
 
 {#op||module||(\*) §||{{null}}||
 Creates a new module {{sl}} based on quotation {{q}}. #}
 
-{#op||scope||(\*)||(\*)||
-Unquotes {{q -> [(\*)](class:kwd)}} creating a new scope and pushes a new copy of {{q}} on the stack.#}
+{#op||publish||§ (*)||{{null}}||
+Publishes symbol {{sl}} to the scope of [(\*)](class:kwd).
 
-{#op||scope?||(\*)||(B)||
-Returnes {{t}} if {{q}} defines a scope, {{f}} otherwise. #}
+> %sidebar%
+> Example
+>
+> Publish symbol [my-local-symbol](class:kwd) to [ROOT](class:kwd) scope:
+> `'my-local-symbol ROOT publish`
+
+#}
+
+{#op||raise||(E)||{{null}}||
+Raises the error specified via the dictionary {{e}}.#}
+
 
 {#op||sigils||{{null}}||(S+)||
 Returns a list of all sigils defined in the [ROOT](class:kwd) scope.#}

all repos — min @ a0efcd6b54e03b142fdf0db7c69e11082dc1b95b

A small but practical concatenative programming language.