18 KiB
Executable File
var'aq Specification
For better flavor text please read the Original var'aq spec 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.
1 Language Overview
var'aq 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.
1.2 Filetypes
.vq -- application/varaq-- a standard var'aq source file.vqe -- application/varaq-engl-- an English-keyword var'aq source file
2 Language Basics
This section describes the fundamental var'aq language constructs and data types.
2.1 Stack Operations
These operations directly manipulate the var'aq 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.
2.1.1 pop/woD
obj woD -
Pops and discards the top item on the stack. The literal meaning is discard.
Errors: stackUnderflow
2.1.2 dup/latlh
obj latlh obj obj
Duplicates the top object on the stack.
Errors: stackUnderflow
2.1.3 exch/tam
obj1 obj2 tam obj2 obj1
Inverts the order of the top two objects on the stack.
Errors: stackUnderflow
2.1.4 clear/chImmoH
... obj chIm -
Empties the stack.
Errors: none
2.1.5 remember/qaw
- qaw flag
Puts a flag (like PostScript's mark) on the stack. The internal representation of the flag is not available to the programmer.
Errors: none
2.1.6 forget/qawHa'
... flag ... qawHa' ...
Clears the stack down to the flag and pops the flag. If there is no flag present, the stack is emptied completely.
Errors: none
2.1.7 dump/Hotlh (lit. scan)
... Hotlh ...
Prints the contents of the operand stack to STDOUT without changing them. Note: the Hotlh 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 var'aq developer. In particular, the output format of this operator is implementation-defined and will not be specified in this document. Hotlh may be redefined to take such arguments as the implementor feels appropriate.
Errors: implementation-defined.
2.1.8 disinter
Returns the value just above the top mark on the stack without disturbing the stack above it.
2.2 Data/Code Operations
var'aq, 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.
2.2.1 ~ (quote/lI'moH)
- ~ obj obj
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.)
The literal meaning of this operator's name is "make useful". Errors: none
2.2.2 {
Begins the creation of an anonymous procedure. The process is implementation-dependent.
2.2.3 }
- } proc
Completes procedure construction and pushes a reference to the completed procedure on the stack. Does not execute the procedure.
Errors: noDefinedProc
2.2.4 name/pong
obj id pong -
Associates obj with id and places it in the system lookup space. Conventionally used to associate new operator names with procedure objects.
Example: ~ add3 { boq boq cha' } pong
Pushes the name add3 and a procedure object on the stack, then binds the name to the procedure.
Errors: stackUnderflow, noDefinedProc
2.2.5 set/cher
obj id cher -
Reassigns the value of a value already in the system lookup space. Used primarily for variable assignments.
Errors: stackUnderflow, noSuchName
2.2.6 (* ... *) (comment)
Marks a comment in a program. All such comments are treated as single tokens and ignored.
2.2.7 //name
Causes the interpreter to import a file with the name name.vq(e) and execute it as if it is part of the currently executing program. Essentially equivalent to #include in C.
An example can be found at the top of the test.vqe example.
Note: you must use either absolute paths or paths relitive to the location of the interpeter
2.3 Control Flow
var'aq supports a small but sufficient supply of conditional and iterative operators.
2.3.1 ifyes/HIja'chugh
bool proc HIja'chugh -
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.
Errors: stackUnderflow, noDefinedProc
2.3.2 ifno/ghobe'chugh
bool proc ghobe'chugh -
Similar to HIja'chugh above, but executes proc only if bool is false.
Errors: stackUnderFlow, noDefinedProc
2.3.3 choose/wIv
bool wIv bool bool
Duplicates a boolean value on top of the stack. Allows paired HI'ja'chugh/ghobe'chugh clauses.
Note: 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.
2.3.4 eval/chov
proc chov -
Pops a proc object off the stack and executes it.
Errors: stackUnderflow, noDefinedProc
2.3.5 escape/nargh
bool nargh -
Exit the current procedure. Useful for exit conditions on loops. Will terminate the current session if used top-level.
2.3.6 repeat/vangqa'
val proc vangqa' -
Pops val and proc off the stack and executes proc val times.
2.4 List Operations
var'aq supports a series of operators for management of lists (ghomHom, 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.
Note that "objects" as they stand in var'aq are largely singletons as in JavaScript; there is no inherent concept of object-orientation or anything like it in standard var'aq.
2.4.1 (
Begins a list definition.
2.4.2 )
( item1 item2 ... ) list
Creates a list and pushes it onto the stack.
2.4.3 split/SIj
list SIj item1 list
Pops a list off the stack and returns the first item and the rest of the list.
2.4.4 cons/muv
list item1 ... muv list
Takes an object and adds it to the head of a list. Equivalent to the LISP cons operator.
2.4.5 shatter/ghorqu'
list ghorqu' item1 item2 ...
Reduces a list to its component elements and pushes them on the stack in order.
Note: The precise meaning of the construction ghorqu' is a bit obscure; the rendering shatter is idiomatic and may derive from a nonstandard dialect. Standard Klingon would generally prefer jor, meaning explode.)
2.4.6 empty?/chIm'a'
list chIm'a' bool
Examines a list on the stack and returns 1 if its value is null (pagh), a 0 if it contains anything.
2.4.7 consume
obj1 obj2 ... mark consume list
Pops all objects on the stack down to mark and returns them in a list.
Note: some implementations also have an operator known as bite/chop, equivalent to the Lisp cdr. This is not required in any standard var'aq implementation and can easily be rendered by the function
~ chop { SIj woD } pong
2.5 String Operators
tlheghjangwI'mey
2.5.1 strtie/tlheghrar
str1 str2 tlheghrar str3
Concatenates the top two strings on the stack into one.
2.5.2 compose/naQmoH
mark str1 str2 ... strn naQmoH strn'
Pops objects (executing proc objects if necessary) off the stack until a marker (placed by qaw) is hit and combines them into one string.
2.5.3 streq?/tlheghrap'a'
str1 str2 tlheghrap'a' bool
Pops the top two strings on the stack, compares them, and returns 1 if identical, 0 if not.
2.5.4 strcut/tlheghpe'
str startval endval tlheghpe' substr
Pops two values and a string and returns the section of the string between character startval and character endval.
2.5.5 strmeasure/tlheghjuv
str tlheghjuv val
Pops a string off the stack and returns its length in characters.
2.5.6 explode/jor
str jor list
Separates individual "words" in a string by whitespace.
3 Mathematical Operators
mI'jangwI'mey
3.1 Arithmetic Operations
toghwI'mey
Arithmetic operators usually work with real numbers unless otherwise stated. The number operators (sec 3.3) can convert them to integers if necessary.
3.1.1 add/boq
a b boq sum
Pops the top two values on the stack and replaces them with their sum.
3.1.2 sub/boqHa'
a b boqHa' difference
Pops the top two values on the stack and replaces them with a - b.
3.1.3 mul/boq'egh
a b boq'egh product
Pops the top two values on the stack and replaces them with their product.
3.1.4 div/boqHa''egh
a b wav quotient
Pops the top two values on the stack and replaces them with a/b.
3.1.5 idiv/HabboqHa''egh (lit. full-divide)
a b HabboqHa''egh quotient
Pops the top two values on the stack and replaces them with the results of an integer division operation.
3.1.6 mod/chuv (lit. leftover)
a b chuv remainder
Pops the top two values and returns the remainder of a mod b.
3.1.7 pow/boqHa'qa' (lit. remultiply)
base exp boqHa'qa' real
Pops the top two values and returns base^exp.
3.1.8 sqrt/loS'ar (lit. fourth-howmuch)
angle loS'ar real
Returns the square root of val.
3.1.9 add1/wa'boq
a wa'boq a+1
Increments the top value on the stack by one.
3.1.10 sub1/wa'boqHa'
a wa'boqHa' a-1
Decrements the top value on the stack by one.
3.2 Trigonometric and Logarithmic Operators
SIHpojjangwI'mey 'ej ghurjangwI'mey
3.2.1 sin/yu'egh (lit. wave)
angle yu'egh real
Returns the sine of val.
3.2.2 cos/yu'eghHa' (lit. counter-wave)
angle yu'eghHa' cos(val)
Returns the cosine of val.
3.2.3 tan/qojmI' (lit. cliffnumber)
angle qojmI' tan(val)
Returns the tangent of val.
3.2.4 atan/qojHa' (lit. anticliff)
num den qojHa' angle
Returns the arctangent of num / den.
3.2.5 ln/ghurtaH
num ghurtaH real
Returns the natural log of num.
3.2.6 log/maHghurtaH
num maHghurtaH real
Returns the base 10 log of num.
3.2.7 log3/wejghurtaH
num wejghurtaH real
Returns the base 3 log of num.
3.3 Numerical Operators and Constants
This section describes operators that operate on numbers themselves, as well as common system-level constants.
3.3.1 clip/poD
real poD int
Removes the fractional portion of a real number (equivalent to floor(real).
3.3.2 smooth/Hab (lit. smooth)
real Hab int
Rounds a number to the nearest integer.
3.3.3 howmuch/'ar
num 'ar num2
Returns the absolute value of num.
3.3.4 setrand/mIScher
num mIScher -
Sets the random number generator seed value to num. Not common, since most var'aq implementations have a rather arcane formula for picking a pseudo-random seed value.
3.3.5 rand/mIS
num mIS real
Returns a random real number in the range 0 to num. If there is no meaningful input on the stack,
3.3.6 pi/HeHmI'
Pushes the value pi (~3.14159...) onto the stack. The Klingon name literally means "edge-number".
3.3.7 e/ghurmI'
Pushes the value e onto the stack. The Klingon name literally means "growth-number".
3.3.8 int?/HabmI''a'
val HabmI''a' bool Pops the top value on the stack and returns 1 if it is an integer, 0 if not.
3.3.9 number?/mI''a'
val mI''a' bool
Pops the top value off the stack and returns 1 if it's a number, 0 if it's something else.
3.3.10 numberize/mI'moH
str mi'moH val
Pops a string off the stack, converts it into a numerical value, and returns it.
3.4 Bitwise operators
Though var'aq 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.
3.4.1 isolate/mobmoH
a b mobmoH result
Performs a bitwise AND on a and b.
3.4.2 mix/DuD
a b DuD result
Performs a bitwise OR on a and b.
3.4.3 contradict/tlhoch
a b tlhoch result
Performs a bitwise XOR on a and b.
3.4.4 compl/Qo'moH
val Qo'moH ~val
Returns the one's-complement of val. Note: The literal meaning is something like "make it say no".
3.4.5 shiftright/nIHghoS
a b nIHghoS result
Shifts a right b places, preserving the sign of the value.
3.4.6 shiftleft/poSghoS
a b poSghoS result
Shifts a left b places.
4 Relational and Logical Operators
4.1 Relational Operators and Predicate Functions
yu'jangwI'mey
4.1.1 gt?/law''a'
a b law''a' bool
Pops a and b off the stack, compares them, and returns a boolean value of true if a is larger.
4.1.2 lt?/puS'a'
a b puS'a' bool
Pops a and b off the stack, compares them, and returns a boolean value of true if a is smaller.
4.1.3 eq?/rap'a'
a b rap'a' bool
Pops a and b off the stack, compares them, and returns a boolean value of true if a is the same as b.
4.1.4 ge?/law'rap'a'
a b law'rap'a' bool
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.
4.1.5 le?/puSrap'a'
a b puSrap'a' bool
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.
4.1.6 ne?/rapbe'a'
a b rapbe'a' bool
Pops a and b off the stack, compares them, and returns a boolean value of true if a is not equal to b.
4.1.7 null?/pagh'a'
obj pagh'a' bool
Examines the top object on the stack and returns a 1 if null, a 0 if not.
4.1.8 negative?/taH'a'
val taH'a' bool
Pops the top number on the stack and returns a 1 if less than 0, a 0 if not.
4.2 Logical Operators
vItjangwI'mey
Note that these are strictly logical operators, not bitwise.
4.2.1 and/je
a b je bool
Evaluates b and a and returns a 1 if both are true, a 0 if not.
4.2.2 or/joq
a b joq bool
Evaluates b and a and returns a 1 if one or both are true, a 0 if both are false.
4.2.3 xor/ghap
a b ghap bool
Evaluates b and a and returns a 1 if only one is true, a 0 otherwise.
4.2.4 not/ghobe'
val ghobe' bool
Evaluates val and returns 1 if true, 0 if not.
5 Input/Output and File Operators
The var'aq Level 0 specification essentially handles console I/O and files in a manner very similar to the UNIX model.
5.1 Console I/O
The console I/O model at this point is very simple: write, read, error.
5.1.1 disp/cha'
obj cha' -
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.
5.1.2 listen/'Ij
- 'Ij str
Reads one line of input and stores it as a string on top of the stack.
5.1.3 complain/bep
str bep -
Pops str and prints it to stderr.
6 System Variables
patSarwI'mey
This section describes var'aq keywords that do no more than put set values on the stack. Many of them are not precisely constants but more like environment variables.
6.1 I/O-related Constants
6.1.1 newline/chu'DonwI'
- chu'DonwI' '\n'
Prints a carriage return.
6.1.2 tab/chu'tut
- chu'DonwI' '\t'
Advances by one tab stop.
6.2 Environment Constants
6.2.1 whereami/nuqDaq_jIH
- nuqDaq_jIH "string of your local ip address"
Returns the IP address of the machine the interpreter is running on.
6.2.2 version/pongmI'
- pongmI' "string of version"
Returns the current interpreter version number. The reference interpreter returns a date stamp.
6.2.3 argv/taghDe'
- taghDe' (arg1, arg2, ...)
Pushes the command line arguments on the stack as a list.
7 New Operators
The following are all new operators that are not included in the original perl implementation of var'aq
7.1 Stack Operations
These are stolen directly from Forth (specifically the FORTH-79 Handy Reference from the book Forth for the Complete Idiot),
They are very useful for doing operations without clobbering the stack
7.1.1 over/QI
obj1 obj2 QI obj1 obj2 obj1
Make a copy of the second item on top of the stack.
The direct Klingon translation for QI is bridge, as in a bridge over a river, which works close enough.
Errors: stackUnderflow
7.1.2 pick/woH
N woH objN
Make a copy of the Nth item on top of the stack.
For example 1 woH is the same as latlh & 2 woH is the same as QI
Errors: stackUnderflow, stackOverflow
7.1.3 rot/jIr
obj1 obj2 obj3 jIr obj2 obj3 obj1
Rotate the third item to the top of the stack.
Errors: stackUnderflow
7.1.4 depth/juv
- juv num
Count the number of items on the stack and push that number to the top of the stack.
Errors: stackUnderflow