Updated spec.
h3rald h3rald@h3rald.com
Sun, 25 May 2025 12:17:21 +0200
1 files changed,
72 insertions(+),
70 deletions(-)
jump to
M
web/contents/spec.html
→
web/contents/spec.html
@@ -433,35 +433,36 @@
<h4 id="bytecode-example">Full Bytecode Example<a href="#top"></a></h4> <p>Consider the following hex program:</p> <pre><code>( - $"_n"$$ $:$$ + $"_n"$$ $:$$ ($:_n$$ $0x0$$ $:<=$$) ($0x1$$) ($:_n$$ $:dup$$ $0x1$$ $:-$$ $:factorial$$ $:*$$) $:if$$ - $"_n"$$ $:#$$ -) $"factorial"$$ $:::$$ + $"_n"$$ $:#$$ +) $"factorial"$$ $:::$$ $0x5$$ $:factorial$$ $:dec$$ $:puts$$</code></pre> <p>This gets compiled to the following bytecode:</p> + <pre><code>01 68 65 78 01 02 00 02 02 5f 6e 09 66 61 63 74 -6f 72 69 61 6c 03 08 02 -02 5f 6e 10 03 03 00 00 -00 01 01 00 31 03 01 01 -01 01 03 06 00 00 00 19 -01 01 01 22 00 01 00 23 -14 02 02 5f 6e 12 02 09 -66 61 63 74 6f 72 69 61 -6c 11 01 01 05 00 01 00 -38 45</code></pre> +6f 72 69 61 6c 03 07 02 +02 5f 6e 03 03 00 00 00 +01 01 00 30 03 01 01 01 +01 03 06 00 00 00 19 01 +01 01 21 00 01 00 22 14 +02 02 5f 6e 12 02 09 66 +61 63 74 6f 72 69 61 6c +11 01 01 05 00 01 00 37 +44</code></pre> <p>And here is an annotated breakdown:</p> <pre><code>$; Header with symbol table of size 2$$ 01 68 65 78 01 02 00 02 $; Symbol Table: _n, factorial$$ 02 5f 6e 09 66 61 63 74 6f 72 69 61 6c -$; Push quotation of eight items$$ -03 08 +$; Push quotation of seven items$$ +03 07 $; Push string "_n"$$ 02 02 5f 6e 10 $; Symbol :$$@@ -471,7 +472,7 @@ $; Lookup first symbol (_n)$$
00 00 00 $; Push integer 0x0$$ 01 01 00 - 31 $; Symbol <=$$ + 30 $; Symbol <=$$ $; Push quotation of one item$$ 03 01 $; Push integer 0x1$$@@ -483,10 +484,10 @@ 00 00 00
19 $; Symbol dup$$ $; Push integer 0x1$$ 01 01 01 - 22 $; symbol -$$ + 21 $; symbol -$$ $; Lookup second symbol (factorial)$$ 00 01 00 - 23 $; Symbol *$$ + 22 $; Symbol *$$ 14 $; Symbol if$$ 02 02 5f 6e 12 $; Symbol ::$$@@ -497,8 +498,8 @@ $; Push integer 5$$
01 01 05 $; Lookup second symbol (factorial)$$ 00 01 00 -38 $; Symbol dec$$ -45 $; Symbol puts$$</code></pre> +37 $; Symbol dec$$ +44 $; Symbol puts$$</code></pre> <h3 id="native-symbols">Native Symbol Reference<a href="#top"></a></h3> <p>hex provides a set of 64 ($0x40$$) native symbols that are built-in and pre-defined in the registry. The@@ -615,115 +616,111 @@ <h5 id="quote-symbol"><code>$:'$$</code> Symbol<a href="#top"></a></h5>
<p><mark>a → q</mark></p> <aside>OPCODE: <code>1f</code></aside> <p>Pushes the literal <code>a</code> wrapped in a quotation on the stack.</p> - <h5 id="debug-symbol"><code>$:debug$$</code> Symbol<a href="#top"></a></h5> - <p><mark>q → *</mark></p> - <aside>OPCODE: <code>20</code></aside> - <p>Dequotes <code>q</code> with debugging enabled.</p> <h4 id="arithmetic-symbols">Arithmetic Symbols<a href="#top"></a></h4> <h5 id="add-symbol"><code>$:+$$</code> Symbol<a href="#top"></a></h5> <p><mark> i1 i2 → i</mark></p> - <aside>OPCODE: <code>21</code></aside> + <aside>OPCODE: <code>20</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>22</code></aside> + <aside>OPCODE: <code>21</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>23</code></aside> + <aside>OPCODE: <code>22</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>24</code></aside> + <aside>OPCODE: <code>23</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>25</code></aside> + <aside>OPCODE: <code>24</code></aside> <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<a href="#top"></a></h4> <h5 id="bitwise-and-symbol"><code>$:&$$</code> Symbol<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>26</code></aside> + <aside>OPCODE: <code>25</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>27</code></aside> + <aside>OPCODE: <code>26</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>28</code></aside> + <aside>OPCODE: <code>27</code></aside> <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<a href="#top"></a></h5> <p><mark> i → i</mark></p> - <aside>OPCODE: <code>29</code></aside> + <aside>OPCODE: <code>28</code></aside> <p>Pushes the result of a bitwise not of <code>i</code> on the stack.</p> <h5 id="bitwise-leftshift-symbol"><code>$:<<$$</code> Symbol<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>2a</code></aside> + <aside>OPCODE: <code>29</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>2b</code></aside> + <aside>OPCODE: <code>2a</code></aside> <p>Pushes the result of shifting <code>i1</code> by <code>i2</code> bits to the right.</p> <h4 id="comparisons-symbols">Comparisons Symbols<a href="#top"></a></h4> <h5 id="equal-symbol"><code>$:==$$</code> Symbol<a href="#top"></a></h5> <p><mark> a1 a2 → i</mark></p> - <aside>OPCODE: <code>2c</code></aside> + <aside>OPCODE: <code>2b</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>2d</code></aside> + <aside>OPCODE: <code>2c</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>2e</code></aside> + <aside>OPCODE: <code>2d</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>2f</code></aside> + <aside>OPCODE: <code>2e</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 12 → i</mark></p> - <aside>OPCODE: <code>30</code></aside> + <aside>OPCODE: <code>2f</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 i2 → i</mark></p> - <aside>OPCODE: <code>31</code></aside> + <aside>OPCODE: <code>30</code></aside> <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<a href="#top"></a></h4> <h5 id="and-symbol"><code>$:and$$</code> Symbol<a href="#top"></a></h5> <p><mark> i1 i2 → i</mark></p> - <aside>OPCODE: <code>32</code></aside> + <aside>OPCODE: <code>31</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 i2 → i</mark></p> - <aside>OPCODE: <code>33</code></aside> + <aside>OPCODE: <code>32</code></aside> <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<a href="#top"></a></h5> <p><mark> i → i</mark></p> - <aside>OPCODE: <code>34</code></aside> + <aside>OPCODE: <code>33</code></aside> <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<a href="#top"></a></h5> <p><mark> i1 i2 → i</mark></p> - <aside>OPCODE: <code>35</code></aside> + <aside>OPCODE: <code>34</code></aside> <p>Pushes <code>0x1</code> on the stack if <code>i1</code> and <code>i2</code> are different, or <code>0x0</code> otherwise.@@ -731,33 +728,33 @@ </p>
<h4 id="type-checking-and-conversion-symbols">Type Checking and Conversion Symbols<a href="#top"></a></h4> <h5 id="int-symbol"><code>$:int$$</code> Symbol<a href="#top"></a></h5> <p><mark>s → i</mark></p> - <aside>OPCODE: <code>36</code></aside> + <aside>OPCODE: <code>35</code></aside> <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<a href="#top"></a></h5> <p><mark> i → s</mark></p> - <aside>OPCODE: <code>37</code></aside> + <aside>OPCODE: <code>36</code></aside> <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<a href="#top"></a></h5> <p><mark> i → s</mark></p> - <aside>OPCODE: <code>38</code></aside> + <aside>OPCODE: <code>37</code></aside> <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<a href="#top"></a></h5> <p><mark> s → i</mark></p> - <aside>OPCODE: <code>39</code></aside> + <aside>OPCODE: <code>38</code></aside> <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<a href="#top"></a></h5> <p><mark> s → i</mark></p> - <aside>OPCODE: <code>3a</code></aside> + <aside>OPCODE: <code>39</code></aside> <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$$@@ -765,12 +762,12 @@ and
$0x7f$$, <code>$0xffffffff$$</code> is pushed on the stack.</p> <h5 id="chr-symbol"><code>$:chr$$</code> Symbol<a href="#top"></a></h5> <p><mark> i → s</mark></p> - <aside>OPCODE: <code>3b</code></aside> + <aside>OPCODE: <code>3a</code></aside> <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<a href="#top"></a></h5> <p><mark> a → s</mark></p> - <aside>OPCODE: <code>3c</code></aside> + <aside>OPCODE: <code>3b</code></aside> <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>).@@ -778,99 +775,99 @@ </p>
<h4 id="list-symbols">List (Strings and Quotations) Symbols<a href="#top"></a></h4> <h5 id="cat-symbol"><code>$:cat$$</code> Symbol<a href="#top"></a></h5> <p><mark> (s1 s2|q1 q2) → (s|q)</mark></p> - <aside>OPCODE: <code>3d</code></aside> + <aside>OPCODE: <code>3c</code></aside> <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<a href="#top"></a></h5> <p><mark> (s|q) → i</mark></p> - <aside>OPCODE: <code>3e</code></aside> + <aside>OPCODE: <code>3d</code></aside> <p>Pushes the length of a string or a quotation on the stack.</p> <h5 id="get-symbol"><code>$:get$$</code> Symbol<a href="#top"></a></h5> <p><mark> (s|q) i → a</mark></p> - <aside>OPCODE: <code>3f</code></aside> + <aside>OPCODE: <code>3e</code></aside> <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<a href="#top"></a></h5> <p><mark> (s a|q a) → i</mark></p> - <aside>OPCODE: <code>40</code></aside> + <aside>OPCODE: <code>3f</code></aside> <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<a href="#top"></a></h5> <p><mark> q s1 → s2</mark></p> - <aside>OPCODE: <code>41</code></aside> + <aside>OPCODE: <code>40</code></aside> <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> <h5 id="split-symbol"><code>$:split$$</code> Symbol<a href="#top"></a></h5> <p><mark> s1 s2 → q</mark></p> - <aside>OPCODE: <code>42</code></aside> + <aside>OPCODE: <code>41</code></aside> <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="sub-symbol"><code>$:sub$$</code> Symbol<a href="#top"></a></h5> <p><mark> s1 s2 s3 → s4</mark></p> - <aside>OPCODE: <code>43</code></aside> + <aside>OPCODE: <code>42</code></aside> <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> <h5 id="map-symbol"><code>$:map$$</code> Symbol<a href="#top"></a></h5> <p><mark> q1 q2 → q3</mark></p> - <aside>OPCODE: <code>44</code></aside> + <aside>OPCODE: <code>43</code></aside> <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>. <h4 id="input-output-symbols">Input/Output Symbols<a href="#top"></a></h4> <h5 id="puts-symbol"><code>$:puts$$</code> Symbol<a href="#top"></a></h5> <p><mark> a →</mark></p> - <aside>OPCODE: <code>45</code></aside> + <aside>OPCODE: <code>44</code></aside> <p>Prints <code>a</code> to standard output, followed by a new line.</p> <h5 id="warn-symbol"><code>$:warn$$</code> Symbol<a href="#top"></a></h5> <p><mark> a →</mark></p> - <aside>OPCODE: <code>46</code></aside> + <aside>OPCODE: <code>45</code></aside> <p>Prints <code>a</code> to standard error, followed by a new line.</p> <h5 id="print-symbol"><code>$:print$$</code> Symbol<a href="#top"></a></h5> <p><mark> a →</mark></p> - <aside>OPCODE: <code>47</code></aside> + <aside>OPCODE: <code>46</code></aside> <p>Prints <code>a</code> to standard output.</p> <h5 id="gets-symbol"><code>$:gets$$</code> Symbol<a href="#top"></a></h5> <p><mark> → s</mark></p> - <aside>OPCODE: <code>48</code></aside> + <aside>OPCODE: <code>47</code></aside> <p>Reads a line from standard input and pushes it on the stack as a string.</p> <h4 id="file-symbols">File Symbols<a href="#top"></a></h4> <h5 id="read-symbol"><code>$:read$$</code> Symbol<a href="#top"></a></h5> <p><mark>s1 → (s2|q)</mark></p> - <aside>OPCODE: <code>49</code></aside> + <aside>OPCODE: <code>48</code></aside> <p>Reads the content of the file <code>s1</code> and pushes it on the stack as a string, if the file is in textual format, or as a quotation of integers representing bytes, if the file is in binary format.</p> <h5 id="write-symbol"><code>$:write$$</code> Symbol<a href="#top"></a></h5> <p><mark>(s1|q) s2 →</mark></p> - <aside>OPCODE: <code>4a</code></aside> + <aside>OPCODE: <code>49</code></aside> <p>Writes the string <code>s1</code> or the array of integers representing bytes <code>q</code> to the file <code>s2</code>. <h5 id="append-symbol"><code>$:append$$</code> Symbol<a href="#top"></a></h5> <p><mark>(s1|q) s2 →</mark></p> - <aside>OPCODE: <code>4b</code></aside> + <aside>OPCODE: <code>4a</code></aside> <p>Appends the string <code>s1</code> or the array of integers representing bytes <code>q</code> to the file <code>s2</code>. </p> <h4 id="shell-symbols">Shell Symbols<a href="#top"></a></h4> <h5 id="args-symbol"><code>$:args$$</code> Symbol<a href="#top"></a></h5> <p><mark> → q</mark></p> - <aside>OPCODE: <code>4c</code></aside> + <aside>OPCODE: <code>4b</code></aside> <p>Pushes the command line arguments as a quotation on the stack.</p> <h5 id="exit-symbol"><code>$:exit$$</code> Symbol<a href="#top"></a></h5> <p><mark> i →</mark></p> - <aside>OPCODE: <code>4d</code></aside> + <aside>OPCODE: <code>4c</code></aside> <p>Exits the program with the exit code <code>i</code>.</p> <h5 id="exec-symbol"><code>$:exec$$</code> Symbol<a href="#top"></a></h5> <p><mark> s → i</mark></p> - <aside>OPCODE: <code>4e</code></aside> + <aside>OPCODE: <code>4d</code></aside> <p>Executes the string <code>s</code> as a shell command, and pushes the command return code on the stack. </p> <h5 id="run-symbol"><code>$:run$$</code> Symbol<a href="#top"></a></h5> <p><mark> s → q</mark></p> - <aside>OPCODE: <code>4f</code></aside> + <aside>OPCODE: <code>4e</code></aside> <p>Executes the string <code>s</code> as a shell command, capturing its output and errors. It pushes a quotation on@@ -881,4 +878,9 @@ <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> + <h5 id="timestamp-symbol"><code>$:timestamp$$</code> Symbol<a href="#top"></a></h5> + <p><mark>→ (i1 i2)</mark></p> + <aside>OPCODE: <code>4f</code></aside> + <p>Pushes a quotation on the stack containing two integers corresponding to the unix timestamp in seconds + (<code>i1</code>) and the microseconds associated with it (<code>i2</code>).</p> </article>