Refactor hex_type function to use hyphens in symbol names; documented all symbols in spec.
h3rald h3rald@h3rald.com
Thu, 12 Dec 2024 09:34:06 +0100
2 files changed,
120 insertions(+),
15 deletions(-)
M
src/hex.c
→
src/hex.c
@@ -387,9 +387,9 @@ return "string";
case HEX_TYPE_QUOTATION: return "quotation"; case HEX_TYPE_NATIVE_SYMBOL: - return "native symbol"; + return "native-symbol"; case HEX_TYPE_USER_SYMBOL: - return "user symbol"; + return "user-symbol"; case HEX_TYPE_INVALID: return "invalid"; default:
M
web/contents/spec.html
→
web/contents/spec.html
@@ -25,144 +25,249 @@ <h3 id="native-symbols">Native Symbols</h3>
<h4 id="memory-management-symbols">Memory Management Symbols</h4> <h5 id="store-symbol"><code>:</code> Symbol</h5> <p><mark>a s →</mark></p> + <p>Stores the literal <code>a</code> in the registry as the symbol <code>s</code>.</p> <h5 id="free-symbol"><code>#</code> Symbol</h5> <p><mark>s →</mark></p> + <p>Frees the symbol <code>s</code> from the registry.</p> <h4 id="control-flow-symbols">Control Flow Symbols</h4> <h5 id="if-symbol"><code>if</code> Symbol</h5> - <p><mark>q q q → *</mark></p> + <p><mark>q1 q2 q3 → *</mark></p> + <p>Dequotes quotation <code>q1</code>, if it pushes a positive integer on the stack it dequotes <code>q2</code>, + otherwise + dequotes <code>q3</code>.</p> <h5 id="when-symbol"><code>when</code> Symbol</h5> <p><mark>q1 q2 → *</mark></p> + <p>Dequotes quotation <code>q1</code>, if it pushes a positive integer on the stack it dequotes <code>q2</code>.</p> <h5 id="while-symbol"><code>while</code> Symbol</h5> <p><mark>q1 q2 → *</mark></p> + <p>Dequotes quotation <code>q1</code>, if it pushes a positive integer on the stack it dequotes <code>q2</code> and + repeats the process.</p> <h5 id="error-symbol"><code>error</code> Symbol</h5> <p><mark>→ s</mark></p> + <p>Pushes the last error message to the stack.</p> <h5 id="try-symbol"><code>try</code> Symbol</h5> <p><mark>q1 q2 → *</mark></p> + <p>Dequotes quotation <code>q1</code>, if it throws an error it dequotes <code>q2</code>.</p> <h4 id="stack-management-symbols">Stack Management Symbol</h4> <h5 id="dup-symbol"><code>dup</code> Symbol</h5> <p><mark> a → a a</mark></p> + <p>Duplicates literal <code>a</code> and pushes it on the stack.</p> <h5 id="stack-symbol"><code>stack</code> Symbol</h5> <p><mark> → q</mark></p> + <p>Pushes the items currently on the stack as a quotation on the stack.</p> <h5 id="clear-symbol"><code>clear</code> Symbol</h5> <p><mark> →</mark></p> + <p>Clears the stack.</p> <h5 id="pop-symbol"><code>pop</code> Symbol</h5> <p><mark> a →</mark></p> + <p>Removes the top item from the stack.</p> <h5 id="swap-symbol"><code>swap</code> Symbol</h5> <p><mark> a1 a2 → a2 a1</mark></p> + <p>Swaps the top two items on the stack.</p> <h4 id="evaluation-symbols">Evaluation Symbols</h4> <h5 id="i-symbol"><code>.</code> Symbol</h5> <p><mark>q → *</mark></p> + <p>Dequotes quotation <code>q</code>.</p> <h5 id="eval-symbol"><code>!</code> Symbol</h5> <p><mark>s →</mark></p> + <p>Evaluates the string <code>s</code> as an hex program.</p> <h5 id="quote-symbol"><code>'</code> Symbol</h5> <p><mark>a → q</mark></p> + <p>Pushes the literal <code>a</code> wrapped in a quotation on the stack.</p> <h4 id="arithmetic-symbols">Arithmetic Symbols</h4> <h5 id="add-symbol"><code>+</code> Symbol</h5> <p><mark> i1 i2 → i</mark></p> + <p>Pushes the result of the sum of <code>i1</code> and <code>i2</code> on the stack.</p> <h5 id="subtract-symbol"><code>-</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of the subtraction of <code>12</code> from <code>i1</code> on the stack.</p> <h5 id="multiply-symbol"><code>*</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of the multiplication of <code>i1</code> and <code>12</code> on the stack.</p> <h5 id="divide-symbol"><code>/</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> - <h5 id="module-symbol"><code>%</code> Symbol</h5> + <p>Pushes the result of the division of <code>i1</code> by <code>12</code> on the stack.</p> + <h5 id="modulo-symbol"><code>%</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of the modulo of <code>i1</code> by <code>12</code> on the stack.</p> <h4 id="bitwise-operations-symbols">Bitwise Operations Symbols</h4> <h5 id="bitwise-and-symbol"><code>&</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of a bitwise and of <code>i1</code> and <code>i2</code> on the stack.</p> <h5 id="bitwise-or-symbol"><code>|</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of a bitwise or of <code>i1</code> and <code>i2</code> on the stack.</p> <h5 id="bitwise-xor-symbol"><code>^</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of a bitwise xor of <code>i1</code> and <code>i2</code> on the stack.</p> <h5 id="bitwise-not-symbol"><code>~</code> Symbol</h5> <p><mark> i → i</mark></p> + <p>Pushes the result of a bitwise not of <code>i</code> on the stack.</p> <h5 id="bitwise-leftshift-symbol"><code><<</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of shifting <code>i1</code> by <code>i2</code> bits to the left.</p> <h5 id="bitwise-rightshift-symbol"><code>>></code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes the result of shifting <code>i1</code> by <code>i2</code> bits to the right.</p> <h4 id="comparisons-symbols">Comparisons Symbols</h4> <h5 id="equal-symbol"><code>==</code> Symbol</h5> - <p><mark> i1 12 → i</mark></p> + <p><mark> a1 a2 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>a1</code> and <code>a2</code> are equal, or <code>0x0</code> + otherwise.</p> <h5 id="notequal-symbol"><code>!=</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>a1</code> and <code>a2</code> are not equal, or <code>0x0</code> + otherwise.</p> <h5 id="greaterthan-symbol"><code>></code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> is greater than <code>i2</code>, or <code>0x0</code> + otherwise.</p> <h5 id="lessthan-symbol"><code><</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> is less than <code>i2</code>, or <code>0x0</code> + otherwise.</p> <h5 id="greaterthanequal-symbol"><code>>=</code> Symbol</h5> <p><mark> i1 12 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> is greater than or equal to <code>i2</code>, or + <code>0x0</code> otherwise. + </p> <h5 id="lessthanequal-symbol"><code><=</code> Symbol</h5> <p><mark> i1 i2 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> is less than or equal to <code>i2</code>, or + <code>0x0</code> otherwise. + </p> <h4 id="boolean-logic-symbols">Boolean Logic Symbols</h4> <h5 id="and-symbol"><code>and</code> Symbol</h5> <p><mark> i1 i2 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> and <code>i2</code> are non-zero integers, or + <code>0x0</code> otherwise. + </p> <h5 id="or-symbol"><code>or</code> Symbol</h5> <p><mark> i1 i2 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> or <code>i2</code> are non-zero integers, or + <code>0x0</code> otherwise. + </p> <h5 id="not-symbol"><code>not</code> Symbol</h5> <p><mark> i → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i</code> is zero, or <code>0x0</code> otherwise.</p> <h5 id="xor-symbol"><code>xor</code> Symbol</h5> <p><mark> i1 i2 → i</mark></p> + <p>Pushes <code>0x1</code> on the stack if <code>i1</code> and <code>i2</code> are different, or <code>0x0</code> + otherwise.</p> <h4 id="datatype-conversions-and-checking-symbols">Datatype Conversions and Checking Symbols</h4> <h5 id="int-symbol"><code>int</code> Symbol</h5> - <p><mark> (i|s) → i</mark></p> + <p><mark>s → i</mark></p> + <p>Converts the string <code>s</code> representing a hexadecimal integer to an integer value and pushes it on the + stack.</p> <h5 id="str-symbol"><code>str</code> Symbol</h5> - <p><mark> (i|s) → s</mark></p> + <p><mark> i → s</mark></p> + <p>Converts the integer <code>i</code> to a string representing a hexadecimal integer and pushes it on the stack. + </p> <h5 id="dec-symbol"><code>dec</code> Symbol</h5> <p><mark> i → s</mark></p> + <p>Converts the integer <code>i</code> to a string representing a decimal integer and pushes it on the stack.</p> <h5 id="hex-symbol"><code>hex</code> Symbol</h5> <p><mark> s → i</mark></p> + <p>Converts the string <code>s</code> representing a decimal integer to an integer value and pushes it on the stack. + </p> <h5 id="ord-symbol"><code>ord</code> Symbol</h5> <p><mark> s → i</mark></p> + <p>Pushes the ASCII value of the string <code>s</code> on the stack.</p> + <p>If <code>s</code> is longer than 1 character or if it is not representable using an ASCII code between 0x0 and + 0x7f, <code>0xffffffff</code> is pushed on the stack.</p> <h5 id="chr-symbol"><code>chr</code> Symbol</h5> <p><mark> i → s</mark></p> + <p>Pushes the ASCII character represented by the integer <code>i</code> on the stack.</p> + <p>If <code>i</code> is not between 0x0 and 0x7f, an empty string is pushed on the stack.</p> <h5 id="type-symbol"><code>type</code> Symbol</h5> <p><mark> a → s</mark></p> + <p>Pushes the type of the literal <code>a</code> on the stack (<code>integer</code>, <code>string</code>, + <code>quotation</code>, <code>native-symbol</code>, <code>user-symbol</code>, <code>invalid</code>, or + <code>unknown</code>). + </p> <h4 id="list-symbols">List (Strings and Quotations) Symbols</h4> <h5 id="cat-symbol"><code>cat</code> Symbol</h5> - <p><mark> (s s|q q) → (s|q)</mark></p> + <p><mark> (s1 s2|q1 q2) → (s|q)</mark></p> + <p>Pushes the result of the concatenation of two strings or two quotations on the stack.</p> <h5 id="len-symbol"><code>len</code> Symbol</h5> <p><mark> (s|q) → i</mark></p> + <p>Pushes the length of a string or a quotation on the stack.</p> <h5 id="get-symbol"><code>get</code> Symbol</h5> - <p><mark> (s|q) → a</mark></p> + <p><mark> (s|q) i → a</mark></p> + <p>Pushes the <code>i</code>th item of a string or a quotation on the stack.</p> <h5 id="index-symbol"><code>index</code> Symbol</h5> <p><mark> (s a|q a) → i</mark></p> + <p>Pushes the index of the first occurrence of the literal <code>a</code> in a string or a quotation on the stack. + If <code>a</code> is not found, <code>0xffffffff</code> is pushed on the stack.</p> <h5 id="join-symbol"><code>join</code> Symbol</h5> - <p><mark> q s → s</mark></p> + <p><mark> q s1 → s2</mark></p> + <p>Assuming that <code>q</code> is a quotation containing only strings, pushes the string <code>s2</code> obtained + by joining each element of <code>q</code> together using <code>s1</code> as a delimiter. </p> <h4 id="string-symbols">String Symbols</h4> <h5 id="split-symbol"><code>split</code> Symbol</h5> <p><mark> s1 s2 → q</mark></p> + <p>Pushes a quotation <code>q</code> containing the strings obtained by splitting <code>s1</code> using + <code>s2</code> as a delimiter. + </p> <h5 id="replace-symbol"><code>replace</code> Symbol</h5> - <p><mark> s1 s2 s3 →</mark></p> + <p><mark> s1 s2 s3 → s4</mark></p> + <p>Pushes the string <code>s4</code> obtained by replacing the first occurrence of <code>s2</code> in + <code>s1</code> by + <code>s3</code>. + </p> <h4 id="quotation-symbols">Quotation Symbols</h4> <h5 id="each-symbol"><code>each</code> Symbol</h5> <p><mark> q1 q2 → *</mark></p> + <p>Dequotes quotation <code>q1</code> and applies it to each item of quotation <code>q2</code>.</p> <h5 id="map-symbol"><code>map</code> Symbol</h5> - <p><mark> q1 q2 → q</mark></p> + <p><mark> q1 q2 → q3</mark></p> + <p>Dequotes quotation <code>q1</code> and applies it to each item of quotation <code>q2</code> to obtain a new + quotation <code>q3</code>. <h5 id="filter-symbol"><code>filter</code> Symbol</h5> <p><mark> q1 q2 → q</mark></p> + <p>Dequotes quotation <code>q1</code> and applies it to each item of quotation <code>q2</code> to obtain a new + quotation <code>q</code> containing only the items that returned a positive integer.</p> <h4 id="input-output-symbols">Input/Output Symbols</h4> <h5 id="puts-symbol"><code>puts</code> Symbol</h5> <p><mark> a →</mark></p> + <p>Prints <code>a</code> to standard output, followed by a new line.</p> <h5 id="warn-symbol"><code>warn</code> Symbol</h5> <p><mark> a →</mark></p> + <p>Prints <code>a</code> to standard error, followed by a new line.</p> <h5 id="print-symbol"><code>print</code> Symbol</h5> <p><mark> a →</mark></p> + <p>Prints <code>a</code> to standard output.</p> <h5 id="gets-symbol"><code>gets</code> Symbol</h5> <p><mark> → s</mark></p> + <p>Reads a line from standard input and pushes it on the stack as a string.</p> <h4 id="file-symbols">File Symbols</h4> <h5 id="read-symbol"><code>read</code> Symbol</h5> - <p><mark> s → s</mark></p> + <p><mark>s1 → s2</mark></p> + <p>Reads the content of the file <code>s1</code> and pushes it on the stack as a string.</p> <h5 id="write-symbol"><code>write</code> Symbol</h5> - <p><mark> s1 s2 → s</mark></p> + <p><mark>s1 s2 →</mark></p> + <p>Writes the string <code>s1</code> to the file <code>s2</code>. <h5 id="append-symbol"><code>append</code> Symbol</h5> - <p><mark> s1 s2 → s</mark></p> + <p><mark> s1 s2 →</mark></p> + <p>Appends the string <code>s1</code> to the file <code>s2</code>.</p> <h4 id="shell-symbols">Shell Symbols</h4> <h5 id="args-symbol"><code>args</code> Symbol</h5> <p><mark> → q</mark></p> + <p>Pushes the command line arguments as a quotation on the stack.</p> <h5 id="exit-symbol"><code>exit</code> Symbol</h5> <p><mark> i →</mark></p> + <p>Exits the program with the exit code <code>i</code>.</p> <h5 id="exec-symbol"><code>exec</code> Symbol</h5> <p><mark> s →</mark></p> + <p>Executes the string <code>s</code> as a shell command.</p> <h5 id="run-symbol"><code>run</code> Symbol</h5> <p><mark> s → q</mark></p> + <p>Executes the string <code>s</code> as a shell command, capturing its output and errors. It pushes a quotation on + the stack containing the following items: + </p> + <ul> + <li>the exit code of the command as an integer</li> + <li>the standard output of the command as a string</li> + <li>the standard error of the command as a string</li> + </ul> </article>