1 The first program

1.1 A program that says hello

use io
"Hello, Pinax!" io.println

$ pnx 01-hello.pnx
Hello, Pinax!

These two lines are the whole program. The first line, use io, opens the module io for input and output. The second puts a string on the stack and calls the word io.println, which takes the string off the top of the stack, writes it to standard output and ends the line.

Pinax code reads in this order: values, then the word. Values pile up on the stack; a word takes off what it needs, does its work and puts its results back. This is called postfix notation.

Follow the order in which the processor reads these two lines. It reads one token at a time from the left: a value goes onto the stack, a word is set to work. The top of the stack is written on the right, and — is an empty stack.

Note that the stack is empty when the program ends. A program that leaves values on it is refused (chapter 2).

1.2 Running with pnx

The command pnx reads a file and runs it. The first line of the output box above, $ pnx 01-hello.pnx, is the command that was run. Before running a file, pnx loads it: it splits the tokens and checks every name, type and stack. If anything is wrong, it refuses without running a single line.

"Hello" io.println

$ pnx 01-no-use.pnx
01-no-use.pnx:1:9: this path names neither a module in use nor a record

This program uses io.println without opening io. A message has the form file:line:column: reason; the column is where the offending token starts.

use io
use str
1 + 2 str.to_str io.println

$ pnx 01-plus.pnx
01-plus.pnx:3:3: a sign is attached to its number; arithmetic uses words (add, sub)

1.3 Remarks and line breaks

A line that starts with rem is a remark. rem after code makes the rest of the line a remark. The examples of this book use remarks to say what each line does.

rem A line that starts with rem is a comment: Pinax reads nothing on it.
use io
"one" io.println          rem rem after code: the rest of the line is a comment
"two"
  io.println              rem a line break is only a space: one call over two lines
"three" io.println "four" io.println    rem two calls on one line

$ pnx 01-comments.pnx
one
two
three
four

A line break is the same as a space. The code of one call may run over two lines, and one line may hold several pieces of work. Indentation and line breaks are for the reader; pnx fmt evens them out (chapter 15).

1.4 Making words

Here is a program that adds up 1 to 100, three ways.

use io
use str
rem The sum of 1 to 100, three ways.
word sum_loop (n int gives int)
  0 to total
  1 to i
  loop
    i n gt until
    total i add to total
    i 1 add to i
  end
  total
end
word sum_range (n int gives int) 1 n 1 add range sum end
word sum_formula (n int gives int) n n 1 add mul 2 div end
100 sum_loop str.to_str io.println
100 sum_range str.to_str io.println
100 sum_formula str.to_str io.println

$ pnx 01-sum.pnx
5050
5050
5050

word NAME (signature) body end defines a word. The signature (n int gives int) means “takes one int, named n, and gives one int”. When the body ends, the stack shall hold exactly the results the signature promises.

• sum_loop is a loop with the locals total and i. to NAME puts the top value into that name. loop … end repeats, and i n gt until means “leave when i is greater than n”.
• sum_range makes a stem of 1 to n with 1 n 1 add range and gives it to sum.
• sum_formula is the formula $\frac{𝑛\left(𝑛+1\right)}{2}$ written in postfix.

1.5 Taking arguments

The arguments of pnx FILE ARGUMENTS… are read with the module env.

use io
use env
word main ()
  1 env.arg or_else (e) "stranger" end to name      rem argument 1, or a word for nobody
  cat ("Hello, ", name, "!") io.println
end
main

$ pnx 01-greet.pnx Pinax
Hello, Pinax!

1 env.arg gives the first argument. There may be none, so this word can fail that is why or_else … end follows it right away, with the value to use instead. Calling a word that can fail and leaving the place after it empty is refused. Chapter 8 covers failures.