web/contents/spec.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 |
<article>
<h2>Specification</h2>
<blockquote>
<p>Under construction.</p>
</blockquote>
<h3 id="introduction">Introduction</h3>
<h3 id="syntax">Syntax</h3>
<h4 id="comments">Comments</h4>
<h4 id="integer-literals">Integer Literals</h4>
<h4 id="string-literals">String Literals</h4>
<h4 id="quotation-literals">Quotation Literals</h4>
<h4 id="symbol-identifiers">Symbol Identifiers</h4>
<h3 id="data-types">Data Types</h3>
<h4 id="integers">Integers</h4>
<h4 id="strings">Strings</h4>
<h4 id="quotations">Quotations</h4>
<h4 id="symbols">Symbols</h4>
<h3 id="stack">Stack</h3>
<h4 id="pushing-literals">Pushing Literals</h4>
<h4 id="pushing-symbols">Pushing Symbols</h4>
<h3 id="registry">Registry</h3>
<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>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>
<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> 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>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</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> (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) 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 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 → 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 → 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>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 →</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 →</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>
|