M lib/utils.hex → lib/utils.hex

@@ -1,6 +1,6 @@ 
 ;;; fail
 ;; s -> 
-;; Throws an error and prints %%s%% to stderr.
+;; Throws an error and prints %:s%% to stderr.
 (
   warn
   0x1 exit
@@ -13,28 +13,28 @@ (dup puts) "_" ::
 
 ;; isi
 ;; a -> i
-;; Pushes %%0x1%% on the stack if %%a%% is an integer, %%0x0%% otherwise.
+;; Pushes %%0x1%% on the stack if %:a%% is an integer, %%0x0%% otherwise.
 (
   type "integer" ==
 ) "isi" ::
 
 ;; iss
 ;; a -> i
-;; Pushes %%0x1%% on the stack if %%a%% is a string, %%0x0%% otherwise.
+;; Pushes $0x1$$ on the stack if %:a%% is a string, $0x0$$ otherwise.
 (
   type "string" ==
 ) "iss" ::
 
 ;; isq
 ;; a -> i
-;; Pushes %%0x1%% on the stack if %%a%% is a quotation, %%0x0%% otherwise.
+;; Pushes $0x1$$ on the stack if %%a%% is a quotation, $0x0$$ otherwise.
 (
   type "quotation" ==
 ) "isq" ::
 
 ;; insert
 ;; (q1|s1) a i -> (q2|s2)
-;; Inserts item %%a%% at position %%i%% within a quotation or string.
+;; Inserts item %:a%% at position %:i%% within a quotation or string.
 (
   "_index" :
   "_item" :
@@ -86,7 +86,7 @@ 
 
 ;;; push
 ;; (q1|s1) a -> (q2|s2)
-;; Pushes %%a%% to the end of a quotation or string.
+;; Pushes %:a%% to the end of a quotation or string.
 (
   "_item" :
   "_list" :
@@ -193,7 +193,7 @@ 
 
 ;;; replace-all
 ;; s1 s2 s3 -> s4
-;; Replaces all occurrences of %%s2%% with %%s3%% in %%s1%%.
+;; Replaces all occurrences of %:s2%% with %%s3%% in %:s1%%.
 (
   "_rep"  :
   "_src"  :
@@ -270,7 +270,7 @@ ) "max" ::
 
 ;;; intpl
 ;; s1 q -> s2
-;; Substitutes %%$0%% to %%$9%% placeholders in %%s1%% with items in %%q%%.
+;; Substitutes %:$0%% to %%$9%% placeholders in %:s1%% with items in %:q%%.
 (
   "_s" :
   "_q" :
@@ -293,7 +293,7 @@ ) "intpl" ::
 
 ;;; each
 ;; q1 q2 -> *
-;; Applies %%q2%% to each element of %%q1%%.
+;; Applies %:q2%% to each element of %:q1%%.
 (
   "_fn" :
   "_list" :

M scripts/web.hex → scripts/web.hex

@@ -16,7 +16,7 @@ d-releases ls . "releases" :
 d-templates "/page.html" cat "t-page" :
 
 ; Symbols to substitute with the corresponding links 
-("split" "run" "get" "puts" ":" "." "#" "==" "'" "swap" "dup"
+("split" "run" "get" "puts" ":" "::" "." "#" "==" "'" "swap" "dup"
 "+" "*" "-" "each" "cat" "print" "read" "dec" "write" "append" "!") "symbol-links" :
 
 ;; Syntax highlighting
@@ -30,6 +30,8 @@ "$\""
     "$0x" 
     "$:" 
     "$$"
+    "%:"
+    "%%"
 ) "highlight-delimiters" :
 
 (
@@ -40,6 +42,8 @@ "<span class=\"hex-string\">\""
     "<span class=\"hex-integer\">0x"
     "<span class=\"hex-symbol\">"
     "</span>"
+    "<code>"
+    "</code"
 ) "highlight-replacements" :
 
 ; Highlight syntax in text
@@ -104,6 +108,7 @@ (t-symbol "#" ==)("free" "t-href" :) when
     (t-symbol "!" ==)("eval" "t-href" :) when
     (t-symbol "'" ==)("quote" "t-href" :) when
     (t-symbol "+" ==)("add" "t-href" :) when
+    (t-symbol "::" ==)("operator" "t-href" :) when
     (t-symbol "*" ==)("multiply" "t-href" :) when
     (t-symbol "-" ==)("subtract" "t-href" :) when
     ("<a href=\"https://hex.2c.fyi/spec#" t-href "-symbol\">" t-symbol "</a>") () map "" join "t-repl" :

M web/contents/spec.html → web/contents/spec.html

@@ -248,8 +248,8 @@ </p>
     <p>All symbols are stored in a single <a href="#registry">registry</a>, implemented as a simple dictionary.
         Therefore, all symbols in hex are global, and not lexically scoped. The main driver for this is to keep the
         language as simple as possible.</p>
-    <p>You can define your own symbols and delete them using the <a href="#memory-management-symbols">memory management
-            symbols</a> provided natively. However, native symbols <em>cannot</em> be deleted.</p>
+    <p>You can store your own symbols and free them using the <a href="#memory-management-symbols">memory management
+            symbols</a> provided natively. However, native symbols <em>cannot</em> be freed.</p>
     <h3 id="stack">Stack<a href="#top"></a></h3>
     <p>The stack is a fundamental data structure in hex that holds values and controls the flow of execution. hex is a
         stack-based language, meaning that all operations are performed on a stack of values. The order according to
@@ -277,7 +277,8 @@ a hex program, it is looked up in the registry, and its associated value or function is pushed onto the stack.
     </p>
     <p>Native symbols can perform manipulations on the stack; they can pop values from the stack and push values back
         in.</p>
-    <p>By contrast, you can only define literals as user-defined symbols, but you can define a quotation which can then
+    <p>In the canonical implementation, native symbols are implemented as native C functions that are executed whenever the corresponding native symbol is pushed on the stack.</p>
+    <p>By contrast, you can only store hex literals as user-defined symbols. When storing a quotation as a symbol, it can be used as data (a list of values) or  a portion of an hex program which that can then
         be <em>dequoted</em> through symbols like {{sym-.}}, which pushes all the items in a quotations
         on the stack, one by one.</p>
     <p>Consider the following example hex program:</p>
@@ -290,6 +291,11 @@ because the logic to do so is in a quotation. To "execute" (dequote) a quotation, you must use the {{sym-.}}
         symbol, which pushes all the items in the quotation on the stack, which is equivalent
         to the following program:</p>
     <pre><code>    $0x3$$ $:dup$$ $:*$$ $:*$$ $:puts$$ $; prints 9$$</code></pre>
+    <p>While the {{sym-:}} symbol can be used to store quotations that can then be dequoted later using {{sym-.}}, typically you want to define operators which are <em>immediately dequoted</em> when pushed on the stack, thus behaving in a similar way as their native counterparts.</p>
+    <p>You can achieve this using the {{sym-::}} symbol, and the previous example can be rewritten as follows:</p>
+    <pre><code>    ($:dup$$ $:*$$ $:*$$) $"square"$$ $:::$$
+    $0x3$$ $:square$$ $:puts$$ $; prints 9$$</code></pre>
+    <p>In this case, you no longer need to explicitly dequote $:square$$ using $:.$$, because it has been stored as an <em>operator</em> and hex knows it has to be immediately dequoted when pushed on the stack.</p>
     <h3 id="registry">Registry<a href="#top"></a></h3>
     <p>The registry in hex is a simple dictionary that stores symbols and their associated values or functions. The
         registry is used to look up symbols when they are encountered in a hex program and to store user-defined symbols
@@ -527,6 +533,10 @@ <h5 id="store-symbol"><code>$::$$</code> Symbol<a href="#top"></a></h5>
     <p><mark>a s &rarr;</mark></p>
     <aside>OPCODE: <code>10</code></aside>
     <p>Stores the literal <code>a</code> in the registry as the symbol <code>s</code>.</p>
+    <h5 id="operator-symbol"><code>$:::$$</code> Symbol<a href="#top"></a></h5>
+    <p><mark>a s &rarr;</mark></p>
+    <aside>OPCODE: <code>11<code></aside>
+    <p>Stores the literal <code>a</code> in the registry as the symbol <code>s</code>. If %:a%% is a quotation, it will be immediately dequoted when pushed on the stack.</p>
     <h5 id="free-symbol"><code>$:#$$</code> Symbol<a href="#top"></a></h5>
     <p><mark>s &rarr;</mark></p>
     <aside>OPCODE: <code>11</code></aside>