Angliconian2 Tutorial

Building and installing Angliconian2

Ok, first we need to access to source to the Angliconian2 interpretor. To do this, we need a program called CVS. If you are on linux or any of the BSDs, chances are, you have it. If you do not, you need to install it.
Once you have CVS ready to be run, if you are not already in a terminal/console, get into one. cd into the directory you wish the interpretor to lie (example if you want it in your programming directory, type cd programming)
Now, type the following into your terminal:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/angliconian2 login
(hit enter at the password prompt)
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/angliconian2 co ang2

From there, type cd ang2

Now that we have the source for the interpretor, simply type make and hit enter (gmake on a BSD machine).

Once the interpretor is done being built, you can either install it or run it from where it is. To install (most likely what you want), type sudo make install (or just make install if you are root).

After an install, the interpretor is called ang2 and is located in /usr/local/bin and the example files are located in /usr/local/share/examples/ang2

Your first program

Ok, now we have our interpretor installed and ready for action. In your favorite editor, type the following code and save it to hello.a (or whatever you feel like saving it as):

{printn}Hello, World!

Now to run it, in a terminal in the same directory as your saved file, type 'ang2 hello.a'

This code is pretty self explanatory, printn stands for print to the screen with a newline at the end. By having printn surrounded by { and }, we are saying call the function printn. From there, everything after the } is a parameter (except for printn and print where a , does not mean a new parameter, it means print a comma).

Comments

Before we move on any further, you probably want to know how to place comments into your code. Commenting keeps other developers and yourself informed on what is going on by the code you have written.

Comments are easy in Angliconian2 because the language specifies that specific events start with a specific character, such as { for a function. So long as your comment does not start with :, [, {, !, /, or ., the interpretor will see you have a comment and simply skip that line of code.

Note that you cannot place a comment in a line after code. Parameters are simply text and not specified by certain characteristics so your comment will be seen as part of the line of code.

Variables and variable management

A variable is an object to keep track of your data. Variables in Angliconian2 are typeless, meaning a variable can contain a number, a string, or any such object.

To declare a variable, you simply type a : (colon) and then the variable name.

To set the value of a variable, you type a [ followed by the name and a ] and the value you wish to use.

In all functions that require a variable, or in places where you wish to place the variable's contents, you also use [, variable name, and ].

Any function that returns a value saves it into the first parameter of the function.

Here is a simple example where you guess the computer's number:

:mynumber
:yournumber

{rand}[mynumber], 10
{printn}Ok, I have my number. Guess from 1 - 10 what it is:
{inputn}[yournumber]
{printn}You guessed [yournumber]. My number was [mynumber]

This example is just to show how to use variables, it does not compare numbers or loop until the correct number is found.

In lines 1 and 2, the two variables mynumber and yournumber are declared respectively.

rand is a function that picks a random number from 1 to the number in the second parameter and stores the result in the first parameter.

We then print a simple statement saying we have a number

In line 6, we are asking for a number (input number) and storing it into yournumber. For general input there is also an input function with the same format.

Finally, we print what the numbers were.

Comparing data

Ok, now that we have ways of storing data, along with putting it on the screen and asking for data, we should like to know how to compare data.

The syntax to comare data is !Operand1!Operator!Operand2

Operand1 must be a variable and operand2 can be any type of data.

The different operators are the following:

= for equals
0 for not equal to
> for greator than
≤ for less than
>= for greator than or equal to
<= for less than or equal to

To end the segment of code for compared data, use *! (for end compare)

If you want to do an else if, or if the previous conditions failed and this condition is true, use *i instead of *! followed by on the next line your compare statement.

For just an else, or if all previous conditions failed, use *e instead of *!.

Here is an example to do some ifs to say where 5 is:

:five
[five]5

![five]!<!3
	{printn}[five] is less than 3
*i
![five]!>!7
	{printn}[five] is greater than 7
*i
![five]!=!4
	{printn}[five] is 4
*e
	{printn}[five] is greater than 3, less than 7, and not 4
*!

Jumping to different places in your code

Now that we can store and compare data, we want to know how to jump to different places in code in order to perform loops.

First we need to declare a place to jump to. We do this by placing a / (forward slash) followed by the name of our label.

Then later on, we jump by placing a . (period) and the label name.

Here is a simple guess the number game:

:mynumber
:yournumber

{rand}[mynumber], 10
/guess
{print}Guess a number 1-10: 
{inputn}[yournumber]
![yournumber]!>![mynumber]
	{printn}Guess higher!
	.guess
*i
![yournumber]!<![mynumber]
	{printn}Guess lower!
	.guess
*i
![yournumber]!=![mynumber]
	{printn}Good job!
*!

Bitwise logic

Bitwise logic is used most commonly in compare statements. The syntax in Angliconian2 does not allow for placing a and/or statement with the compare so we need a way to do these earlier.

To do a bitwise and, we simply {and}[SaveToVariable], [Variable1], [Variable2]

This will store a 0 into SaveToVariable if Variable1 and Variable2 do not and, and other data if it does. For example 1 & 1 is 1, but 1 & 0 is 0.

Similarly, we can do the same for or and xor.

To use this with an if, we can use the {if} function which instead of executing certain code, places a 1 or a 0 into the first parameter (1 for would execute, 0 for wouldn't).

Here is an example using this:

:x
:a
:b
[x]5

{if}[a], [x], <, 7
{if}[b], [x], 0, 4
{and}[a], [a], [b]
![a]!=!1
	{printn}[x] is less than 7 and not equal to 4
*e
	{printn}[x] is either 4, 7, or greater than 7
*!

In this example, we check if x is less than 7 and set a to 1 if it is. We then do the same for checking if x is not 4. We and the two to make a statement such as if x is less than 7 and x is not equal to 4. Finally we actually compare a to 1. If it is 1 then our if conditions passed.

Functions

Functions are just like little subprograms. To create your own functions, you start with declaring the function, then add code just as if it was in the main program, then add a line to show we are at the end of the function.

To declare a function, we type {{ followed by the name of our function, followed by }}. After the }} we add the amount of parameters the function will use (0 for none).

To get the data of a parameter, we use the function {getarg}.

Finally, at the end of our function, we add the line *}} to show the end of the function.

Here is a quick example:

{{adder}}2
	:op1
	:op2
	:result
	{getarg}[op1], 1
	{getarg}[op2], 2

	{evals}[result], [op1]+[op2]

	{printn}[op1] + [op2] = [result]
*}}

:a
:b
[a]5
[b]7
{adder}[a], [b]

In this example, we show we have two parameters in which we store into op1 and op2. We then call the evals function to evaluate a mathematical string and store the result into result. Finally we print the answer. In the main program we run the test values 5 and 7 to result in 12.

Although this does add a lot of functionality, we may want to return data to the function we called - such as how evals stored data into result.

In order to accomplish this, before the parameter count, we place a capitol R (for return function). Then to set the data to return, we use the function setreturn. Here is adder using return values.

{{adder}}R2
	:op1
	:op2
	:result
	{getarg}[op1], 1
	{getarg}[op2], 2

	{evals}[result], [op1]+[op2]
	{setreturn}[result]
*}}

:a
:b
:result
[a]5
[b]7
{adder}[result], [a], [b]

Notice how the parameter count did not change - this is because we ignore the result variable as a paramter because the function will not access it.

On a side note, Angliconian2 does support recurssion, which is were a function calls itself. But as in every other language, make sure you place code to keep it from doing it forever!

Functions reference

Function	Description
{and}	Bitwise and. Takes a return parameter followed by 2 number parameters.
{append}	Takes 2 parameters and appends the second parameter to the first.
{appends}	{append} with a space added before the second parameter is added.
{argcount}	Takes 1 parameter. Saves the amount of arguments passed to the function and stores into parameter 1. If in the main program code, arguments are taken from the lines passed to the interpretor discluding the actual line to the interpretor. Will always return at least 1 because the function name or source name if in main program is always parameter 0.
{asize}	Takes 2 parameters. Stores the count of items in an array in the second parameter into the first parameter.
{eval}	Takes 1 parameter. Evaluates the mathematical expression in parameter 1 and stores the result into parameter 1.
{evals}	Takes 2 parameters. Evaluates the mathematical expression in parameter 2 and stores the result into parameter 1.
{getarg}	Takes 2 parameters. Stores the parameter 2th argument of the function into the first parameter. The 0th parameter is always the function name or the source name if in the main program.
{getc}	Takes 3 parameters. Gets the 3rd parameterth character in the second parameter and stores into the first parameter.
{gettext}	Takes 4 parameters. Takes the data from the 3rd parameterth character up to the 4th parameterth character (but not including) from the 2nd parameter and stores into the 1st parameter.
{if}	Takes 4 parameters. Compares the 2nd parameter and the 4th parameter with the 3rd parameter's operator (<, >, =, 0, <=, >=) and stores a 1 into the 1st parameter if a compare statement would execute code following it, and a 0 if it would not.
{input}	Takes 1 parameter. Grabs user input and stores into the first parameter.
{inputn}	{input} but only accepting numbers.
{loadfile}	Takes 2 parameters. Takes the data from the 2nd parameter's file and stores into the 1st parameter.
{makeint}	Takes 1 parameter. Truncates any decimal data making the parameter just be an interger (or nothing if no number was stored in it).
{makeintr}	{makeint} but rounds instead of truncates.
{not}	Bitwise not. Takes 2 parameters and stores the not of the 2nd to the 1st.
{or}	Bitwise or. Takes 3 parameters and stores the or of the 2nd and 3rd parameters to the 1st.
{print}	Parameterless function. Everything after the function call gets printed onto the screen.
{printn}	{print} but with a newline after the print.
{rand}	Takes 2 parameters. Places a random number, 1 to and including the 2nd parameter and stores into the 1st.
{resize}	Takes 2 parameters. With autosizing variables, this is mostly to truncate data in the 1st parameter to the size of the 2nd parameter.
{savefile}	Saves data from the 1st parameter into the file of the 2nd parameter.
{setreturn}	Takes 1 parameter. In a returning function sets the data that will be returned and stored into the 1st parameter when being called.
{size}	Takes 2 parameters. Stores the length of the 2nd parameter into the 1st.
{xor}	Bitwise xor. Takes the xor of the 2nd and 3rd parameters and places into the 1st.

The Angliconian2 Tutorial

For beginner programmers and hobbyests

An introduction to Angliconian2