var'aq gojmeH qeS
var'aq ghojmeH qeS

"var'aq's Learning Advice, var'aq Tutorial"

This tutorial will take you through the basics of var'aq programming, starting with a general introduction to var'aq, then presenting the currently implemented keywords using example programs with each lesson building on the previous one. By the time you finish this tutorial, you should be able to use and understand code written in var'aq.

It is imperative, if you haven't already, to download the current version of var'aq, available from The var'aq Homepage, and unzip it into it's own folder that you can get to easily. If you have difficulty getting the interpreter to work, be sure to follow the instructions found on my main var'aq page to help you get started.

This tutorial is not intended to be all-inclusive. It is just enough to give you a feel for how var'aq programming works.

Table of Contents

• Introduction
• Hotlh/dump
• Lesson 1: Introducing processes
• Lesson 2: Declaring variables

Introduction

Purpose

This section will introduce you to the var'aq interpreter, define some basic terms, teach you how to push tokens onto the stack, and how to view the stack using the {Hotlh} keyword.

Objectives

When you finish this section, you will:

• Be familiar with the basic operating model of the interpreter.
• Know the definitions of some basic terms used in var'aq programming
• Be able to push tokens onto the stack.
• Be able to view the stack using the {Hotlh} keyword.

1.1 The interpreter

This is the central piece of software needed for var'aq programming. There are actually two separate interpreters included with the current release: varaq-kling, the Klingon-language interpreter, and varaq-engl, the English language interpreter. This tutorial considers only the Klingon-languge interpreter. It is written in Perl, but you don't need to know Perl to program in var'aq, any more than you need to know the inner workings of a calculator to use one. The interpreter takes the code entered, and translates them into a language your computer understands. In Windows, the interpreter opens in a DOS window, and all coding is text-based.

1.2 Basic terms

Token

This is anything separated by whitespace (spaces or tabs) that you input to the interpreter. "dog" is a single token, whereas "dog cat" will be seen as two separate tokens, and "dog cat horse" has three.

Variable

This is a "data bucket". A var'aq variable can hold any data you want it to. var'aq doesn't care if it's a string, an integer, or a decimal number. Variables may have any name you want it to, as long as the name does not contain whitespace. Thus, a variable name of "No_of_letters" is perfectly acceptable, but not "No of letters", which would be viewed as three separate tokens, and "No_of_letters" can refer to "Hello", just as easily as it can hold the number 123456.789

Process

This is everything entered between the '{' and '}' operators. The interpreter executes the process when it is called by name.

Keyword

This is a word that the interpreter "understands", and knows what to do with. Some examples are {pong}, the process-naming keyword, and {cher}, the variable-naming keyword. While var'aq allows you to define processes and variables with the same name as keywords, doing so is not recommended. It tends to confuse others who read your code.

Operator

Resembling a keyword, this is a single character that the interpreter "understands", and knows what to do with. Examples include '~', the quote operator, '{', the begin-process operator, and '}', the end-process operator.

Stack

This is a little hard to understand if you've never used a stack before, and I will try to explain it as clearly as I can, but complete understanding will come only with practice.
Think of the interpreter as having a pile of blank index cards. Whenever the interpreter comes across a token or process, it takes one card off the pile, writes the token/process on the card, and places it in another, smaller pile. This smaller pile is like the stack. Usually, the first item off the stack is the last item placed on it.

Push

This means to take a token/process and place it on top of the stack. It then becomes the first item considered when a process, keyword, or operator is executed.

Pop

This means to take a token/process off the top of the stack, do with it whatever is required of the process, keyword, or operator, then discard the token/process.

1.3 Pushing tokens onto the stack

This is the most basic thing you will do in var'aq programming, and forms the basis for stack operations.
To push a token onto the stack, simply enter it into the command line, and press enter.

Ex:

Entering 6, then pressing enter will push the number six onto the stack.

An alternative method is to enter all the tokens on a single line, and the interpreter will go from left to right, pushing the separate tokens onto the stack one by one.

Ex:

Enter 12 27 74, then hit enter. The interpreter will push these three tokens onto the stack in this order : First "12", then "27", then "74", leaving "74" on top of the stack, as it was the last token pushed on to it.

If you have a string token, enclose it in quotes, or use the '~' operator. The latter is not recommended, as the quote operator ('~') is normally used only for naming processes.

Ex:

If you enter Scott, then hit enter, the interpreter will tell you that Scott is an undefined function. To push the string "Scott" on to the stack, enclose it in quotes, like this:

"Scott"

String tokens may contain whitespace, so "Scott" and "Scott Willis" are both equally valid string tokens.

1.4 Using the {Hotlh} keyword

This is strictly a debugging keyword. Do not use it in your finished programs. I present it here only because I will be referring to it throughout this tutorial to help the reader learn about stack dynamics.

Use:

Start up the interpreter, and push three tokens onto the stack, like this:

12 27 "Scott"

Then, enter Hotlh. The line of output will look like this:

12 27 Scott

This keyword leaves the stack untouched. It simply displays the stack.

Return to Table of Contents

Lesson 1: Introducing processes

First, we will consider:

cha'

This keyword is used to display the top item on the stack. It pops the item on top of the stack, then slaps it on screen.

Ex:

Push "Scott". Use Hotlh to verify it is on the stack.
Output: Scott
Then type in cha', and hit enter.
Output: Scott
Use Hotlh to verify that the stack is empty.
Output: BLANK LINE

It took the first item off the stack, put it onscreen, and discarded it.

Example Program: nuqneH 'u'

To further demonstrate the use of the {cha'} keyword, we will take an example from the var'aq Homepage code snippets page, albeit in a modified form.

    ~ nuqneH { "nuqneH 'u'" cha' } pong

Let's take this bit by bit.

~

The quote operator. This causes the next token to be pushed onto the stack as a string.

nuqneH

This is the string that will become the name we use to call the function.

{

This operator tells the interpreter to begin gathering code to form a process, which we will later bind to the string "nuqneH".

"nuqneH 'u'"

This will push the string "nuqneH 'u'" onto the stack when the process is executed. The process isn't being executed yet, because the interpreter doesn't know its name.

cha'

This keyword is explained above.

}

This operator tells the interpreter to stop gathering code for the process, and to push the process onto the stack.

pong

This keyword tells the interpreter to pop a process, (in this case, the one we just entered), and then a string ("nuqneH"), and bind the process to the string. Now, every time you enter the word nuqneH without quotes, the interpreter will run the process the name indicates. This will be the case until you quit the interpreter, or bind another process to the string "nuqneH".

Now call the function:

nuqneH

Output: nuqneH 'u'

The words mean, "What do you want, universe?" in Klingon.

Return to Table of Contents

Lesson 2: Declaring variables

This lesson will introduce the concept of var'aq variables. Even if you are familiar with variables in other programming languages, var'aq variables work a little differently, so it is still important that you read this section.

cher

This keyword will pop a string and a value off the stack, then bind the value to the string. Then, whenever you type in the string without quotes, the value will be placed on top of the stack.

Ex:

Push "Scott", then "name" onto the stack.
Input: "Scott" "name"
Type in cher
Verify that both "Scott" and "name" are gone from the stack using Hotlh.
Enter name cha'
Output: Scott

Using cher is like making your own keyword, only the keyword points to a value instead of a set of instructions.

cher can also be used to bind a string to a number.

699742.4 "HovpoH" cher
HovpoH cha'
Output: 699742.4

Example program: Loopy

To illustrate the cher keyword, will we look at a program that writes a sentence of the user's choosing to the screen as many times as the user indicates.

~ loopy {

"What do you want to say?" cha'

'Ij "sentence" cher

"How many times do you want to say it?" cha'

'Ij "times" cher

times { sentence cha' } vangqa'

qaw

"There you have it, " sentence " written " times " times"

naQmoH cha'

} pong

To view this page, you need the Klingon.ttf and KlingonDagger.ttf fonts.

E-mail me!

Here's another way to send me e-mail!

Klingon™ is a trademark of Paramount, Inc. No infringement is intended.

This page is best viewed at a 800x600 resolution or higher

Top

©2003 De'wI' joH'a'