zongor
/
varaq-wasm-c
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
varaq-wasm-c/docs/varaqspec.html

919 lines
28 KiB
HTML
Raw Normal View History

inital commit
2023-02-04 14:06:00 -05:00
<title>var'aq Interim Specification 2 January 2001</title>
<h1><i>var'aq</i> Preliminary Specification</h1><br>
<i><a href="mailto:connorbd@yahoo.com">Brian Connors</a><br>
29 May 2000<br>
last updated 02 January 2001</i>
<hr>
<h3>0 Introduction</h3><p>
This specification documents the
programming language <i>var'aq</i>. <i>var'aq</i> is a programming
language created as part of an exercise to imagine the hacker culture of
<a href="http://www.startrek.com">Star Trek's</a> Klingon race. The
Klingon culture was chosen because it is probably the best-realized of all
such cultures in the Science Fiction/Fantasy genres of literature, and the
Klingon language is sufficiently different from English to make language
design a significant challenge. <p>
<h4>0.1 Language Levels</h4> <p>
<i>var'aq</i> is divided into three implementation levels, each a subset
of its successor. An implementation conforming to the current
<i>var'aq</i> spec should be labeled with the level of conformance.<p>
<ul>
<li><b>Level 0</b> -- The focus of this preliminary spec, a Level 0
<i>var'aq</i> implementation minimally contains all operators and data
structures listed in this specification. Level 0 covers all basic
mathematical, relational, and logical operators and a minimal set of
Turing-complete control constructs and I/O operators. A Level 0
implementation does not necessarily have to be written in Klingon, but
if not an external Klingon-to-English translation filter is required.
<li><b>Level 1</b> -- <B>NOT YET DOCUMENTED</b> -- A Level 1
implementation constitutes a full text-mode implementation of
<i>var'aq</i>, including basic concurrency support, stream-based
file I/O, support for the
<i>var'aq</i> Standard MPI Binding (not yet available), and full support
for Klingon-language constructs. Also includes support for packages
(<i>jangwI'ghom</i>).
<li><b>Level 2</b> -- <B>NOT YET DOCUMENTED</b> -- A Level 2
implementation has all of the above, as well as package support, virtual
device support
(minimally, printer, framebuffer, and network connection as well as
console), and is suitable for use as a scripting or systems programming
language. A POSIX binding is optional but highly recommended.
</ul>
<p>
<h3>0.2 Legalese, Credit, Etc.</h3><p>
<i>var'aq</i> was concieved by <a href="mailto:connorbd@yahoo.com">Brian
Connors</a> and implemented by Brian with help from <a
href="http://www.catseye.mb.ca">Chris Pressey</a> and <a
href="mailto:mark@kli.org">Mark Shoulson</a>. It is an independent
project and is not connected with the <a
href="http://www.startrek.com">Star Trek</a> people (i.e.
Paramount/Viacom).<p>
This document is (c)2000-2001 Brian Connors and may be distributed freely as
long as this copyright notice is retained. You may freely implement for
private use a <i>var'aq</i> implementation with no restriction; you must
contact me for certification (i.e. I make sure you're following the spec)
in order to distribute your implementation as freeware. This specification
may not be used for commercial purposes without a separate licensing
arrangement.<p>
<h3>0.3 Apologies</h3><p>
You'll notice that I tend to drift in and out of character in this document.
The only thing I can say to this is that character isn't a great concern in a
specification document; I may do an extensive revision later on, but as I
write this <i>var'aq</i> isn't even alpha-quality code, and the spec is
subject to change anyway. Just enjoy and try to keep up; we'll worry about
"realism" later. Thank you for your patience.<p>
<h3>1 Language Overview</h3><p>
<i>var'aq</i> 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>
<h4>1.1 Notation Used In This Specification</h4><p>
All operator names will be given in English and Klingon. The notation and
format of the operator entries are cribbed from <a
href="http://www.adobe.com">Adobe's</a> PostScript Language
Specification.<p>
<h4>1.2 Basic Concepts</h4><p>
<i>var'aq</i> is a fairly simple, RPN-based language where pretty much
everything is an operator. It is fairly loosely typed and little
distinction is made between code and data. Typechecking is not strictly
required (and in fact does not exist in the current reference
implementation) but is encouraged.<p>
<h4>1.3 Data Types</h4><p>
<i>var'aq</i> recognizes only a few data types so as to keep the programming
model as simple as possible. <p>
<h4>1.3.1 number/mI'</h4><p>
<i>var'aq</i> numbers are a bit nonspecific as to representation; there is no
support for complex numbers in a Level 0 implementation (Level 1 and above do
include support). In general, integers (<i>HabmI'</i>) and reals are
considered interchangeable where possible, and the interpreter is expected to
use whichever is more efficient. Note that integer operations such as
<b>Habwav</b> and the bitwise operators will generally silently truncate the
operands (optionally giving a runtime warning if so requested by the user).<p>
<h4>1.3.2 function/jangwI'</h4><p>
A function in <i>var'aq</i> is understood to be much the same thing as a
lambda closure, i.e. a procedure with a return value (thus the Klingon term
jangwI', meaning "answerer"). Functions are defined using the <b>{ }</b>
operators, and may be assigned names using the <b>pong</b> operator.<p>
<h4>1.3.3 list/ghomHom</h4><p>
<i>var'aq</i> lists (<i>ghomHom</i>, meaning "cluster" (sort of)) are in some
ways very similar to those of Lisp. <p>
<h4>1.3.4 string/tlhegh</h4><p>
Strings in <i>var'aq</I> (and Klingon programming in general) seem to be
considered something of a black art; Klingon computer science appears to have
no real concept of anything like regular expressions, and as a result decent
string handling is the territory of those trusted to write things like
language compilers (ngoq poSmoH? The idea would baffle a Klingon... so
insecure, so random...). Brute-force string comparisons seem to be the order
of the day in current practice. That said, <i>var'aq</i> strings also have a
couple of important properties: a) white space is not significant; b) they can
be decomposed into lists using the <b>joq</b> operator; and c) they can be
used as literal names (though it's not a terribly good idea).
<h4>1.4 Basic Assumptions</h4><p>
<h4>1.4.1 Number Representations</h4><p>
All standard <i>var'aq</i> systems are assumed to be binary machines using
eight or sixteen-bit bytes (word size is unimportant). Negative integer
values are represented as two's-complement. A floating-point implementation is
not specified, though the Klingon floating-point standard is not drastically
different from IEEE floating point (differing bit positions, primarily). If a
standard float must be chosen, go with IEEE double-precision.<p>
<h4>1.4.2 Garbage Collection</h4><p>
All <i>var'aq</i> implementations are required to use garbage collection
(<i>woDHa'</i>, roughly meaning "retrieve" or "unwaste"). No standard
algorithm is specified, and this requirement may be ignored if the implementor
uses an environment where this is assumed (Perl, for example).<p>
<h4>1.4.3 Filetypes</h4><p>
Klingon military computer systems use a sort of modular-database storage
scheme in which the concept of "file" doesn't mean a whole lot. However, on
systems where files are the common way of doing business, the following
extensions and MIME types are standard:<p>
<ul>
<li><b>.vq -- application/varaq</b> -- a standard <i>var'aq</i> source file
<li><b>.vqe -- application/varaq-engl</b> -- an English-keyword
<i>var'aq</i> source file
<li><b>.vql -- application/vqlib</b> -- a <i>var'aq</i> library source file
<li><b>.vqx -- application/vqexe</b> -- a <i>var'aq</i> executable resource
file
</ul>
Note that this is being specified here mainly as a matter of convenience. The
<i>var'aq</i> resource file format has not yet been defined.<p>
<h3>2 Language Basics</h3><p>
This section describes the fundamental <i>var'aq</i> language constructs
and data types. <p>
<h4>2.1 Stack Operations</h4><p>
These operations directly manipulate the <i>var'aq</i> 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>
<h4>2.1.1 pop/woD</h4><p>
<i>obj <b>woD</b> -</i><p>
Pops and discards the top item on the stack. The literal meaning is
<i>discard</i>.<p>
Errors: stackUnderflow<p>
<h4>2.1.2 dup/latlh</h4><p>
<i>obj <b>latlh</b> obj obj</i><p>
Duplicates the top object on the stack.<p>
Errors: stackUnderflow<p>
<h4>2.1.3 exch/tam</h4><p>
<i>obj1 obj2 <b>tam</b> obj2 obj1</i><p>
Inverts the order of the top two objects on the stack. <p>
Errors: stackUnderflow<p>
<h4>2.1.4 clear/chImmoH</h4><p>
<i>... obj <b>chIm</b> -</i><p>
Empties the stack.<p>
Errors: none<p>
<h4>2.1.5 remember/qaw</h4><p>
<i>- <b>qaw</b> flag</i><p>
Puts a flag (like PostScript's <b>mark</b>) on the stack. The internal
representation of the flag is not available to the programmer. <p>
Errors: none<p>
<h4>2.1.6 forget/qawHa'</h4><p>
<i>... flag ... <b>qawHa'</b> ...</i><p>
Clears the stack down to the flag and pops the flag. If there is no flag
present, the stack is emptied completely.<p>
Errors: none<p>
<h4>2.1.7 dump/Hotlh (lit. scan)</h4><p>
<i>... <b>Hotlh</b> ...</i><p>
Prints the contents of the operand stack to STDOUT without changing them.
<i>Note</i>: the <i>Hotlh</i> 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 <i>var'aq</i> developer. In particular, the output
format of this operator is implementation-defined and will not be
specified in this document. <i>Hotlh</i> may be redefined to take such
arguments as the implementor feels appropriate.<p>
Errors: implementation-defined.
<h4>2.2 Data/Code Operations</h4><p>
<i>var'aq</i>, 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>
<h4>2.2.1 ~ (quote/lI'moH)</h4><p>
<i>- <b>~ obj</b> obj</i><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>
The literal meaning of this operator's name is "make useful".
Errors: none<p>
<h4>2.2.2 { </h4><p>
Begins the creation of an anonymous procedure. The process is
implementation-dependent.<p>
<h4>2.2.3 }</h4><p>
<i>- <b>}</b> proc</i><p>
Completes procedure construction and pushes a reference to the completed
procedure on the stack. Does not execute the procedure.<p>
Errors: noDefinedProc
<h4>2.2.4 name/pong</h4><p>
<i>obj id <b>pong</b> -</i><p>
Associates <i>obj</i> with <i>id</i> and places it in the system lookup
space. Conventionally used to associate new operator names with procedure
objects.<p>
Example: <i>~ add3 { chel chel cha' } pong</i> <p>
Pushes the name <i>add3</i> and a procedure object on the stack, then
binds the name to the procedure. <p>
Errors: stackUnderflow, noDefinedProc<p>
<h4>2.2.5 set/cher</h4><p>
<i>obj id <b>cher</b> -</i><p>
Reassigns the value of a value already in the system lookup space. Used
primarily for variable assignments.<p>
Errors: stackUnderflow, noSuchName<p>
<h4>2.2.6 (* ... *) (comment)</h4><p>
Marks a comment in a program. All such comments are treated as single tokens
and ignored.<p>
<h4>2.2.7 //<i>name</i></h4><p>
Causes the interpreter to import a file with the name <i>name</i>.vql and
execute it as if it is part of the currently executing program. This can be
handled by an external static linker if there is no shlib-like facility in the
interpreter. Essentially equivalent to <code>#include</code> in C. <p>
<h4>2.3 Control Flow</h4><p>
<i>var'aq</i> supports a small but sufficient supply of conditional and
iterative operators. <p>
<h4>2.3.1 ifyes/HIja'chugh</h4><p>
<i>bool proc <b>HIja'chugh</b> -</i><p>
Pops the proc object off the stack, then evaluates the boolean. If it's
true, the proc object is evaluated; otherwise, it's thrown out. <p>
Errors: stackUnderflow, noDefinedProc<p>
<h4>2.3.2 ifno/ghobe'chugh</h4><p>
<i>bool proc <b>ghobe'chugh</b> -</i><p>
Similar to <i>HIja'chugh</i> above, but executes proc only if bool is false.
<p>
Errors: stackUnderFlow, noDefinedProc<p>
<h4>2.3.3 choose/wIv</h4><p>
<i>bool <b>wIv</b> bool bool</i><p>
Duplicates a boolean value on top of the stack. Allows paired
HI'ja'chugh/ghobe'chugh clauses.<p>
<b>Note:</b> 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>
<h4>2.3.4 eval/chov</h4><p>
<i>proc <b>chov</b> -</i><p>
Pops a proc object off the stack and executes it.<p>
Errors: stackUnderflow, noDefinedProc<p>
<h4>2.3.5 escape/nargh</h4><p>
<i>bool <b>nargh</b> -</i><p>
Exit the current procedure. Useful for exit conditions on
loops. Will terminate the current session if used top-level.<p>
<h4>2.3.6 repeat/vangqa'</h4><p>
<i>val proc <b>vangqa'</b> -</i><p>
Pops val and proc off the stack and executes proc val times. <p>
<h4>2.4 List Operations</h4><p>
<i>var'aq</i> supports a series of operators for management of lists
(<i>ghomHom</i>, 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>
Note that "objects" as they stand in <i>var'aq</i> are largely singletons as
in JavaScript; there is no inherent concept of object-orientation or anything
like it in standard <i>var'aq</i>.
<h4>2.4.1 (</h4><p>
Begins a list definition.<p>
<h4>2.4.2 ) </h4><p>
<i>( item1 item2 ... <b>)</b> list </i><p>
Creates a list and pushes it onto the stack.<p>
<h4>2.4.3 split/SIj</h4><p>
<i>list <b>SIj</b> item1 list</i><p>
Pops a list off the stack and returns the first item and the rest of the
list.<p>
<h4>2.4.4 cons/muv</h4><p>
<i>list item1 ... <b>muv</b> list</i><p>
Takes an object and adds it to the head of a list. Equivalent to the LISP
<b>cons</b> operator.
<h4>2.4.5 shatter/ghorqu'</h4><p>
<i>list <b>ghorqu'</b> item1 item2 ...</i><p>
Reduces a list to its component elements and pushes them on the stack in
order. <p>
<b>Note:</b> The precise meaning of the construction <i>ghorqu'</i> is
a bit obscure; the rendering <i>shatter</i> is idiomatic and may derive from a
nonstandard dialect. Standard Klingon would generally prefer <i>jor</i>,
meaning <i>explode</i>.)<p>
<h4>2.4.6 empty?/chIm'a'</h4><p>
<i>list <b>chIm'a'</b> bool</i><p>
Examines a list on the stack and returns 1 if its value is null (<i>pagh</i>),
a 0 if it contains anything.
<b>Note:</b> some implementations also have an
operator known as bite/<i>chop</i>, equivalent to the Lisp <i>cdr</i>. This is
not required in any standard <i>var'aq</i> implementation and can easily be
rendered by the function<p>
<pre><code>
~ chop { SIj woD } pong
</pre></code><p>
<h4>2.5 String Operators<br>
<i>tlheghjangwI'mey</i></h4><p>
String handling in <i>var'aq</i> is generally thought to be somewhat
deficient by Earth standards; all strings are handled as if whitespace is not
significant, and string management is a bit primitive. Substrings are
understood, as are very basic forms of pattern matching, but Klingon computer
science seems to regard string-handling facilities such as regular expressions
as something of a black art, left only to those responsible for writing
compilers and that sort of thing. <p>
<h4>2.5.1 strtie/tlheghrar</h4><p>
<i>str1 str2 <b>tlheghrar</b> str3</i><p>
Concatenates the top two strings on the stack into one.<p>
<h4>2.5.2 compose/naQmoH</h4><p>
<i>mark str1 str2 ... strn <b>naQmoH</b> strn'</i><p>
Pops objects (executing proc objects if necessary) off the stack until a
marker (placed by <b>qaw</b>) is hit and combines them into one string.
<h4>2.5.3 streq?/tlheghrap'a'</h4><p>
<i>str1 str2 <b>tlheghrap'a'</b> bool</i><p>
Pops the top two strings on the stack, compares them, and returns 1 if
identical, 0 if not.
<h4>2.5.4 strcut/tlheghpe'</h4><p>
<i>str startval endval <b>tlheghpe'</b> substr</i><p>
Pops two values and a string and returns the section of the string between
character <i>startval</i> and character <i>endval</i>.<p>
<h4>2.5.5 strmeasure/tlheghjuv</h4><p>
<i>str <b>tlheghjuv</b> val</i><p>
Pops a string off the stack and returns its length in characters. <p>
<h4>2.5.6 explode/jor</h4><p>
<i>str <b>jor</b> list</i><p>
Separates individual "words" in a string by whitespace.<p>
<h3>3 Mathematical Operators<br>
<i>mI'jangwI'mey</i></h3><p>
Klingon mathematical study is somewhat less sophisticated than Federation
standard, but it covers all the important concepts. A full set of arithmetic
and basic trigonometric operations is available. <p>
<h4>3.1 Arithmetic Operations<br>
<i>toghwI'mey</i></h4><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>
<i>(note: verisimilitude would require that the Klingon understanding of
math not necessarily coincide with ours. But I think it's safe to say that
this basic set of operations is enough to at least get a Klingon
battlecruiser out of spacedock.)</i><p>
<h4>3.1.1 add/boq</h4><p>
<i>a b <b>boq</b> sum</i><p>
Pops the top two values on the stack and replaces them with their sum.<p>
Note that the four basic operations are based around the term <i>boq</i>,
which literally means "to ally with". The metaphor is a bit strained but
is well-established enough that most Klingons do not think twice about it.<p>
<h4>3.1.2 sub/boqHa'</h4><p>
<i>a b <b>boqHa'</b> difference</i><p>
Pops the top two values on the stack and replaces them with a - b.<p>
<h4>3.1.3 mul/boq'egh</h4><p>
<i>a b <b>boq'egh</b> product</i><p>
Pops the top two values on the stack and replaces them with their
product.<p>
<h4>3.1.4 div/boqHa''egh</h4><p>
<i>a b <b>wav</b> quotient</i><p>
Pops the top two values on the stack and replaces them with a/b.<p>
<h4>3.1.5 idiv/HabboqHa''egh (lit. full-divide)</h4><p>
<i>a b <b>HabboqHa''egh</b> quotient</i><p>
Pops the top two values on the stack and replaces them with the results
of an integer division operation.<p>
<h4>3.1.6 mod/chuv (lit. leftover)</h4><p>
<i>a b <b>chuv</b> remainder</i><p>
Pops the top two values and returns the remainder of a mod b.<p>
<h4>3.1.7 pow/boqHa'qa' (lit. remultiply)</h4><p>
<i>base exp <b>boqHa'qa'</b> real</i><p>
Pops the top two values and returns base^exp.<p>
<h4>3.1.8 sqrt/loS'ar (lit. fourth-howmuch)</h4><p>
<i> angle <b>loS'ar</b> real </i><p>
Returns the square root of val.<p>
<h4>3.1.9 add1/wa'boq</h4><p>
<i>a <b>wa'boq</b> a+1</i><p>
Increments the top value on the stack by one.<p>
<h4>3.1.10 sub1/wa'boqHa'</h4><p>
<i>a <b>wa'boqHa'</b> a-1</i><p>
Decrements the top value on the stack by one.<p>
<h4>3.2 Trigonometric and Logarithmic Operators<br>
<i>SIHpojjangwI'mey 'ej ghurjangwI'mey</i></h4><p>
The standard Klingon unit of arc measure is the vatlhvI' (hundredth-part),
which is the same term used for percentage. However, Klingon
mathematicians are familiar with the concept of radians (botlhchuq,
center-distance) and all known <i>var'aq</i> implementations work in
radians for input and output.<p>
<h4>3.2.1 sin/joq (lit. wave)</h4><p>
<i>angle <b>joq</b> real</i><p>
Returns the sine of val.<p>
<h4>3.2.2 cos/joqHa' (lit. counter-wave)</h4><p>
<i>angle <b>joqHa'</b> cos(val)</i><p>
Returns the cosine of val.<p>
<h4>3.2.3 tan/qojmI' (lit. cliffnumber)</h4><p>
<i>angle <b>qojmI'</b> tan(val)</i><p>
Returns the tangent of val.<p>
<h4>3.2.4 atan/qojHa' (lit. anticliff)</h4><p>
<i>num den <b>qojHa'</b> angle</i><p>
Returns the arctangent of <i>num / den</i>.<p>
<h4>3.2.5 ln/ghurtaH</h4><p>
<i>num <b>ghurtaH</b> real</i><p>
Returns the natural log of <i>num</i>.
<h4>3.2.6 log/maHghurtaH</h4><p>
<i>num <b>maHghurtaH</b> real</i><p>
Returns the base 10 log of <i>num</i>.<p>
<h4>3.2.7 log3/wejghurtaH</h4></i><p>
<i>num <b>wejghurtaH</b> real</i><p>
Returns the base 3 log of <i>num</i>. (This function is actually
considered a level 1 function, and is believed to exist only for
historical purposes. Its use is very rare except among programmers whose
native language is Standard High Klingon (which historically used a base 3
number system) and is unknown among other users.)
<h4>3.3 Numerical Operators and Constants</h4><p>
This section describes operators that operate on numbers themselves, as
well as common system-level constants. (Note that some of these
functions look like verbs in English and adjectives in Klingon; the
idea is that where we might say <i>1.3 clip</i> to get 1 a Klingon
would be thinking <i>the clipped 1.3</i>.<p>
<h4>3.3.1 clip/poD</h4><p>
<i>real <b>poD</b> int</i><p>
Removes the fractional portion of a real number (equivalent to
floor(real).<p>
<h4>3.3.2 smooth/Hab (lit. smooth)</h4><p>
<i>real <b>Hab</b> int</i><p>
Rounds a number to the nearest integer.<p>
<h4>3.3.3 howmuch/'ar</h4><p>
<i>num <b>'ar</b> num2</i><p>
Returns the absolute value of <i>num</i>.<p>
<h4>3.3.4 setrand/mIScher</h4><p>
<i>num <b>mIScher</b> -</i><p>
Sets the random number generator seed value to <i>num</i>. Not common,
since most <i>var'aq</i> implementations have a rather arcane formula for
picking a pseudo-random seed value (security reasons, presumably).<p>
<h4>3.3.5 rand/mIS</h4><p>
<i>num <b>mIS</b> real</i><p>
Returns a random real number in the range 0 to <i>num</i>. If there is no
meaningful input on the stack,
<h4>3.3.6 pi/HeHmI'</h4><p>
Pushes the value pi (~3.14159...) onto the stack. The Klingon name
literally means "edge-number".<p>
<h4>3.3.7 e/ghurmI' </h4><p>
Pushes the value e onto the stack. The Klingon name literally means
"growth-number".<p>
<h4>3.3.8 int?/HabmI''a'</h4><p>
<i>val <b>HabmI''a'</b> bool</i>
Pops the top value on the stack and returns 1 if it is an integer, 0 if
not.<p>
<h4>3.3.9 number?/mI''a'</h4><p>
<i>val <b>mI''a'</b> bool</i><p>
Pops the top value off the stack and returns 1 if it's a number, 0 if it's
something else.
<h4>3.3.10 numberize/mI'moH</h4><p>
<i>str <b>mi'moH</b> val</i><p>
Pops a string off the stack, converts it into a numerical value, and returns
it.<p>
<h4>3.4 Bitwise operators</h4><p>
Though <i>var'aq</i> 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>
<b>Note:</b> The <i>var'aq</i> bitwise operators are quite controversial as of
this writing (they are considered inappropriately low-level) and may be
removed or altered in future versions of this specification.<p>
It is to be noted that the Klingon coinages for the operation (especially
<i>tlhoch</i> (contradict) for xor) are unusually obscure even for Klingon
hackerspeak and probably reflect fairly profound differences in shades of
meaning.<p>
<h4>3.4.1 isolate/mobmoH</h4><p>
<i>a b <b>mobmoH</b> result</i><p>
Performs a bitwise AND on a and b.<p>
<h4>3.4.2 mix/DuD</h4><p>
<i>a b <b>DuD</b> result</i><p>
Performs a bitwise OR on a and b.<p>
<h4>3.4.3 contradict/tlhoch</h4><p>
<i>a b <b>tlhoch</b> result</i><p>
Performs a bitwise XOR on a and b.<p>
<h4>3.4.4 compl/Qo'moH</h4><p>
<i>val <b>Qo'moH</b> ~val</i><p>
Returns the one's-complement of val. <b>Note:</b> The literal meaning is
something like "make it say no".<p>
<h4>3.4.5 shiftright/nIHghoS</h4><p>
<i>a b <b>nIHghoS</b> result</i><p>
Shifts a right b places, preserving the sign of the value.<p>
<h4>3.4.6 shiftleft/poSghoS</h4><p>
<i>a b <b>poSghoS</b> result</i><p>
Shifts a left b places.<p>
<h3>4 Relational and Logical Operators</h3><p>
<h4>4.1 Relational Operators and Predicate Functions<br>
<i>yu'jangwI'mey</i></h4><p>
The standard convention for anything that returns a boolean argument is to
end the keyword in the interrogative suffix <i>-'a'</i>, which in general
is analogous to Lisp's well-established -p (plain old Lisp) or -? (Scheme
and Dylan) predicate conventions; the English versions of the keywords
follow the Scheme convention for consistency with the Klingon. The
<i>tlhIngan Hubbeq Say'ghun'ogh
paq</i> (KDF Programmer's Style Guide) requires this convention; see that
document for further information.<p>
<h4>4.1.1 gt?/law''a'</h4><p>
<i>a b <b>law''a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is larger.<p>
<h4>4.1.2 lt?/puS'a'</h4><p>
<i>a b <b>puS'a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is smaller.<p>
<h4>4.1.3 eq?/rap'a'</h4><p>
<i>a b <b>rap'a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is the same as b.<p>
<h4>4.1.4 ge?/law'rap'a'</h4><p>
<i>a b <b>law'rap'a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is greater than or equal to b.<p>
<h4>4.1.5 le?/puSrap'a'</h4><p>
<i>a b <b>puSrap'a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is less than or equal to b.<p>
<h4>4.1.6 ne?/rapbe'a'</h4><p>
<i>a b <b>rapbe'a'</b> bool</i><p>
Pops a and b off the stack, compares them, and returns a boolean value of
true if a is not equal to b.<p>
<h4>4.1.7 null?/pagh'a'</h4><p>
<i>obj <b>pagh'a'</b> bool</i><p>
Examines the top object on the stack and returns a 1 if null, a 0 if not.<p>
<h4>4.1.8 negative?/taH'a'</h4>
<i>val <b>taH'a'</b> bool</i><p>
Pops the top number on the stack and returns a 1 if less than 0, a 0 if
not.<p>
<h4>4.2 Logical Operators<br>
<i>vItjangwI'mey</i></h4><p>
Note that these are strictly logical operators, not bitwise.<p>
<h4>4.2.1 and/je</h4><p>
<i>a b <b>je</b> bool</i><p>
Evaluates b and a and returns a 1 if both are true, a 0 if not.<p>
<h4>4.2.2 or/joq</h4><p>
<i>a b <b>joq</b> bool</i><p>
Evaluates b and a and returns a 1 if one or both are true, a 0 if both are
false.<p>
<h4>4.2.3 xor/ghap</h4><p>
<i>a b <b>ghap</b> bool</i><p>
Evaluates b and a and returns a 1 if only one is true, a 0 otherwise. <p>
<h3>5 Input/Output and File Operators</h3><p>
The <i>var'aq</i> Level 0 specification essentially handles console I/O
and files in a manner very similar to the UNIX model.
<h4>5.1 Console I/O</h4><p>
The console I/O model at this point is very simple: write, read, error.<p>
<h4>5.1.1 disp/cha'</h4><p>
<i>obj <b>cha'</b> -</i><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>
<h4>5.1.2 listen/'Ij</h4><p>
<i>- <b>'Ij</b> str</i><p>
Reads one line of input and stores it as a string on top of the stack.<p>
<h4>5.1.3 complain/bep</h4><p>
<i>str <b>bep</b> -</i><p>
Pops <i>str</i> and prints it to stderr.<p>
<h3>6 System Variables<br>
<i>patSarwI'mey</i></h3><p>
This section describes <i>var'aq</i> 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>
<h4>6.1 I/O-related Constants</h4><p>
<h4>6.1.1 newline/chu'DonwI'</h4><p>
Prints a carriage return.<p>
<h4>6.1.2 tab/chu'tut</h4><p>
Advances by one tab stop.<p>
<h4>6.2 Environment Constants</h4><p>
<h4>6.2.1 whereami/nuqDaq_jIH</h4><p>
Represents the location of the current host device. On Earth implementations,
usually returns the IP address of the machine the interpreter is running
on.<p>
<h4>6.2.2 version/pongmI'</h4><p>
Returns the current interpreter version number. The reference interpreter
returns a date stamp.<p>
<h4>6.2.3 argv/taghDe'</h4><p>
Pushes the command line arguments on the stack as a list.<p>