<p>For better flavor text please read the <ahref="https://www.oocities.org/connorbd/varaq/varaqspec.html">Original <code>var'aq</code> spec</a> the following is a trimmed down version of the spec with a couple of fixes and addendums to how this implementation of the language works.</p>
<h2id="1-language-overview">1 Language Overview</h2>
<p><em>var'aq</em> is a stack-based, RPN programming language with points of similarity to Lisp, Forth, and PostScript. It is more of a functional language than an imperative (Algol-like) language; most operations are dependent on the stack and bypass the local variable store altogether.</p>
<h3id="12-filetypes">1.2 Filetypes</h3>
<ul>
<li><code>.vq -- application/varaq</code> -- a standard <em>var'aq</em> source file</li>
<li><code>.vqe -- application/varaq-engl</code> -- an English-keyword <em>var'aq</em> source file</li>
</ul>
<h2id="2-language-basics">2 Language Basics</h2>
<p>This section describes the fundamental <em>var'aq</em> language constructs and data types.</p>
<p>These operations directly manipulate the <em>var'aq</em> operand stack. The operand stack can hold any of four kinds of data: numbers (real or integer), strings, functions, or arrays. It is best described as "translucent", similar to the transparent stack of Forth or PostScript but somewhat more restricted. The internal data representation of the stack is not available to the programmer.</p>
<h4id="211-popwod">2.1.1 pop/woD</h4>
<p><em>obj <code>woD</code> -</em></p>
<p>Pops and discards the top item on the stack. The literal meaning is <em>discard</em>.</p>
<p>Prints the contents of the operand stack to STDOUT without changing them. <em>Note</em>: the <em>Hotlh</em> operator is a debugging operator and is not intended for use in programs; it is merely documented here because it might be useful to a <em>var'aq</em> developer. In particular, the output format of this operator is implementation-defined and will not be specified in this document. <em>Hotlh</em> may be redefined to take such arguments as the implementor feels appropriate.</p>
<p>Errors: implementation-defined.</p>
<h4id="218-disinter">2.1.8 disinter</h4>
<p>Returns the value just above the top mark on the stack without disturbing the stack above it.</p>
<p><em>var'aq</em>, like many similar languages, does not distinguish between code and data. These operations include operators to associate names with objects and executable procedures, as well as operators to define and manage data structures. Note that variables and procedures live in a common namespace, since the act of pushing the content of a variable is essentially the same as executing the variable's name.</p>
<p>The ~ operator is a special form, as it is not a postfix operator. When the interpreter encounters a ~, it pushes the next token on the stack as is regardless of whether it is a defined name. (Attempting to push an undefined name without a ~ will generate an undefinedName error.)</p>
<p>The literal meaning of this operator's name is "make useful". Errors: none</p>
<h4id="222-">2.2.2 {</h4>
<p>Begins the creation of an anonymous procedure. The process is implementation-dependent.</p>
<h4id="223-">2.2.3 }</h4>
<p><em>- <code>}</code> proc</em></p>
<p>Completes procedure construction and pushes a reference to the completed procedure on the stack. Does not execute the procedure.</p>
<p>Errors: noDefinedProc</p>
<h4id="224-namepong">2.2.4 name/pong</h4>
<p><em>obj id <code>pong</code> -</em></p>
<p>Associates <em>obj</em> with <em>id</em> and places it in the system lookup space. Conventionally used to associate new operator names with procedure objects.</p>
<p>Marks a comment in a program. All such comments are treated as single tokens and ignored.</p>
<h4id="227-name">2.2.7 //<em>name</em></h4>
<p>Causes the interpreter to import a file with the name <em>name</em>.vq(e) and execute it as if it is part of the currently executing program. Essentially equivalent to <code>#include</code> in C.</p>
<p>An example can be found at the top of the <ahref="./examples/test.vqe">test.vqe</a> example.</p>
<p><code>Note:</code> you must use either absolute paths or paths relitive to the location of the interpeter</p>
<h3id="23-control-flow">2.3 Control Flow</h3>
<p><em>var'aq</em> supports a small but sufficient supply of conditional and iterative operators.</p>
<p>Similar to <em>HIja'chugh</em> above, but executes proc only if bool is false.</p>
<p>Errors: stackUnderFlow, noDefinedProc</p>
<h4id="233-choosewiv">2.3.3 choose/wIv</h4>
<p><em>bool <code>wIv</code> bool bool</em></p>
<p>Duplicates a boolean value on top of the stack. Allows paired HI'ja'chugh/ghobe'chugh clauses.</p>
<p><code>Note:</code> To the untrained eye, it may seem as though wIv and latlh are identical. This is true in the reference implementation, but may not be in any version that actually does some level of type checking. This bit of syntactic sugar should never be relied upon; always use wIv in this situation.</p>
<h4id="234-evalchov">2.3.4 eval/chov</h4>
<p><em>proc <code>chov</code> -</em></p>
<p>Pops a proc object off the stack and executes it.</p>
<p>Errors: stackUnderflow, noDefinedProc</p>
<h4id="235-escapenargh">2.3.5 escape/nargh</h4>
<p><em>bool <code>nargh</code> -</em></p>
<p>Exit the current procedure. Useful for exit conditions on loops. Will terminate the current session if used top-level.</p>
<p>Pops val and proc off the stack and executes proc val times.</p>
<h3id="24-list-operations">2.4 List Operations</h3>
<p><em>var'aq</em> supports a series of operators for management of lists (<em>ghomHom</em>, which seems to mean something like "cluster"). These primitives are the language's primary way of managing aggregate objects and work much like similar operators in LISP; a more sophisticated paradigm, such as OO extensions or the like, can be built with these operators.</p>
<p>Note that "objects" as they stand in <em>var'aq</em> are largely singletons as in JavaScript; there is no inherent concept of object-orientation or anything like it in standard <em>var'aq</em>.</p>
<p>Reduces a list to its component elements and pushes them on the stack in order.</p>
<p><code>Note:</code> The precise meaning of the construction <em>ghorqu'</em> is a bit obscure; the rendering <em>shatter</em> is idiomatic and may derive from a nonstandard dialect. Standard Klingon would generally prefer <em>jor</em>, meaning <em>explode</em>.)</p>
<h4id="246-emptychima">2.4.6 empty?/chIm'a'</h4>
<p><em>list <code>chIm'a'</code> bool</em></p>
<p>Examines a list on the stack and returns 1 if its value is null (<em>pagh</em>), a 0 if it contains anything.</p>
<h4id="247-consume">2.4.7 consume</h4>
<p><em>obj1 obj2 ... mark <code>consume</code> list</em></p>
<p>Pops all objects on the stack down to <em>mark</em> and returns them in a list.</p>
<p><code>Note:</code> some implementations also have an operator known as bite/<em>chop</em>, equivalent to the Lisp <em>cdr</em>. This is not required in any standard <em>var'aq</em> implementation and can easily be rendered by the function</p>
<p>Pops objects (executing proc objects if necessary) off the stack until a marker (placed by <code>qaw</code>) is hit and combines them into one string.</p>
<p>Arithmetic operators usually work with real numbers unless otherwise stated. The number operators (sec 3.3) can convert them to integers if necessary.</p>
<h4id="311-addboq">3.1.1 add/boq</h4>
<p><em>a b <code>boq</code> sum</em></p>
<p>Pops the top two values on the stack and replaces them with their sum.</p>
<h4id="312-subboqha">3.1.2 sub/boqHa'</h4>
<p><em>a b <code>boqHa'</code> difference</em></p>
<p>Pops the top two values on the stack and replaces them with a - b.</p>
<h4id="313-mulboqegh">3.1.3 mul/boq'egh</h4>
<p><em>a b <code>boq'egh</code> product</em></p>
<p>Pops the top two values on the stack and replaces them with their product.</p>
<h4id="314-divboqhaegh">3.1.4 div/boqHa''egh</h4>
<p><em>a b <code>wav</code> quotient</em></p>
<p>Pops the top two values on the stack and replaces them with a/b.</p>
<p>Sets the random number generator seed value to <em>num</em>. Not common, since most <em>var'aq</em> implementations have a rather arcane formula for picking a pseudo-random seed value.</p>
<h4id="335-randmis">3.3.5 rand/mIS</h4>
<p><em>num <code>mIS</code> real</em></p>
<p>Returns a random real number in the range 0 to <em>num</em>. If there is no meaningful input on the stack,</p>
<h4id="336-pihehmi">3.3.6 pi/HeHmI'</h4>
<p>Pushes the value pi (~3.14159...) onto the stack. The Klingon name literally means "edge-number".</p>
<h4id="337-eghurmi">3.3.7 e/ghurmI'</h4>
<p>Pushes the value e onto the stack. The Klingon name literally means "growth-number".</p>
<h4id="338-inthabmia">3.3.8 int?/HabmI''a'</h4>
<p><em>val <code>HabmI''a'</code> bool</em> Pops the top value on the stack and returns 1 if it is an integer, 0 if not.</p>
<h4id="339-numbermia">3.3.9 number?/mI''a'</h4>
<p><em>val <code>mI''a'</code> bool</em></p>
<p>Pops the top value off the stack and returns 1 if it's a number, 0 if it's something else.</p>
<p>Though <em>var'aq</em> makes no clear distinction between integers and reals, it is nevertheless useful to be able to manipulate a number on the bit level. The following operators assume that their operands will always be treated as integers; effects on floating-point values are undefined, and may be disallowed at the implementor's discretion.</p>
<p>Note that these are strictly logical operators, not bitwise.</p>
<h4id="421-andje">4.2.1 and/je</h4>
<p><em>a b <code>je</code> bool</em></p>
<p>Evaluates b and a and returns a 1 if both are true, a 0 if not.</p>
<h4id="422-orjoq">4.2.2 or/joq</h4>
<p><em>a b <code>joq</code> bool</em></p>
<p>Evaluates b and a and returns a 1 if one or both are true, a 0 if both are false.</p>
<h4id="423-xorghap">4.2.3 xor/ghap</h4>
<p><em>a b <code>ghap</code> bool</em></p>
<p>Evaluates b and a and returns a 1 if only one is true, a 0 otherwise.</p>
<h4id="424-notghobe">4.2.4 not/ghobe'</h4>
<p><em>val <code>ghobe'</code> bool</em></p>
<p>Evaluates val and returns 1 if true, 0 if not.</p>
<h3id="5-inputoutput-and-file-operators">5 Input/Output and File Operators</h3>
<p>The <em>var'aq</em> Level 0 specification essentially handles console I/O and files in a manner very similar to the UNIX model.</p>
<h4id="51-console-io">5.1 Console I/O</h4>
<p>The console I/O model at this point is very simple: write, read, error.</p>
<h4id="511-dispcha">5.1.1 disp/cha'</h4>
<p><em>obj <code>cha'</code> -</em></p>
<p>Pops the top object on the stack and writes it to STDOUT. Note that certain types of objects will generate meaningless output, particularly anonymous proc objects.</p>
<h4id="512-listenij">5.1.2 listen/'Ij</h4>
<p><em>- <code>'Ij</code> str</em></p>
<p>Reads one line of input and stores it as a string on top of the stack.</p>
<h4id="513-complainbep">5.1.3 complain/bep</h4>
<p><em>str <code>bep</code> -</em></p>
<p>Pops <em>str</em> and prints it to stderr.</p>
<h3id="6-system-variables">6 System Variables</h3>
<p><em>patSarwI'mey</em></p>
<p>This section describes <em>var'aq</em> keywords that do no more than put set values on the stack. Many of them are not precisely constants but more like environment variables.</p>
<p>These are stolen directly from <em>Forth</em> (specifically the <ahref="http://www.forth.org/Ting/Forth-for-the-Complete-Idiot/Forth-79-Handy-Reference.pdf"><em>FORTH-79 Handy Reference</em></a> from the book <em>Forth for the Complete Idiot</em>),</p>
<p>They are very useful for doing operations without clobbering the stack</p>
