Chapter 1. Introduction and Tutorial

This chapter will introduce you to the Hassium programming language. Topics included are installing Hassium, Hello, World!, and basic global functions.

1.1 - Getting Started

The first step to programming in Hassium is to download and install the Hassium interpreter. This is the program that takes the source code (the code that the programmer writes) compiles it, then executes it. Anytime we execute Hassium source code we must invoke it in the interpreter.

Hassium can be downloaded from it’s GitHub (https://github.com/HassiumTeam/Hassium) page. There are two ways to install Hassium, and the way that you choose is affected by which operating system you are on.

1.1.1 Install Guide - Unix, Linux, OS X Users

The recommended way to install Hassium is by cloning the main repository from GitHub. If you do not have the git program installed on your computer, install it either from the git website (https://git-scm.com), or on the command line as shown below.

Debian, Ubuntu, Elementary OS:

# apt-get install git

RPM, Fedora, Red Hat:

# yum install git

The next step is to get the source code from the main repository using the git tool. Open your terminal and enter the following commands.

$ cd ~

$ git clone https://github.com/HassiumTeam/Hassium

The first command changes directory to the home directory. Most terminals will open to this by default, but it is good to make sure just in case. The second command tells git to download all of the source code for the Hassium interpreter.

Now it is time to install Hassium. The source code repository we just downloaded contains several scripts for managing installations of Hassium. The script that we need to install Hassium is called install.sh. This script will compile the code for the interpreter using xbuild and move the interpreter binary and execution script to /usr/bin/, where it becomes part of the $PATH and can be invoked from any directory in the terminal.

Before we install Hassium we need to first verify that the necessary prerequisites are installed on your system. In order to compile, Hassium needs the xbuild command to build the .NET solution file and mono to execute the Hassium interpreter. Some package managers will have access to a package called mono-complete, which includes both of these requirements. Try to install mono-complete as shown below.

Debian, Ubuntu, Elementary OS:

# apt-get install mono-complete

RPM, Fedora, Red Hat:

# yum install mono-complete

If the command failed saying that there was no such package that exists, you must then install the packages mono-core and mono-devel.

Debian, Ubuntu, Elementary OS:

# apt-get install mono-core

# apt-get install mono-devel

RPM, Fedora, Red Hat:

# yum install mono-core

# yum install mono-devel

In the event that the packages are still not being found by your package manager, lookup instructions for installing mono and xbuild on your system.

Now that the relevant prerequisites have been installed we can finish by installing Hassium. Start by changing into the freshly cloned Hassium directory, build the binary using make, and install using make install, both using sudo (superuser permissions).

$ cd Hassium

$ sudo make

$ sudo make install

If the command works, you should see the output from xbuild as it compiles the Hassium interpreter and moves the necessary files.

1.1.2 Install Guide - Windows Users

Clone from GitHub:

The recommended way to install Hassium is by cloning the main repository from GitHub. In order to install using this method however, you must have a C# compiler installed on your system. This is usually either Microsoft Visual Studio or Xamarin Studio. If you do not have either of these programs or another C# compiler, you must then download a release of Hassium from GitHub as covered in the next mini-section.

If you do not have the git program installed on your computer, install from the git website (https://git-scm.com). Make sure to download the git bash program when doing so, as that is the environment in which we will be downloading Hassium as well as running Hassium from.

Start by opening the git bash program from the Start Menu. A black window should pop up showing a command line interface on the ~ or home directory. From there we can clone the source code repository from GitHub by running the following command.

$ git clone https://github.com/HassiumTeam/Hassium

This will download the source tree into the home directory at C:\Users\<YourName>\Hassium\. From there we can open the Hassium.sln file in order to compile the project.

Open either Microsoft Visual Studio or Xamarin studio and click “Open Solution” or “Open”. In the file explorer, navigate to C:\Users\<YourName>\Hassium\src\Hassium.sln and select it. Your IDE will open up the solution and you should see all of the C# files that make up the Hassium interpreter. Click the “Run”, “Compile”, or “Play” button at the top of the IDE and let the solution compile out. Once this task is done the IDE can be closed and the interpreter will have been built.

When the IDE builds the solution, it will send the resulting executable to C:\Users\<YourName>\Hassium\src\Hassium\bin\Debug\Hassium.exe. In git bash, change to this directory using the following command.

$ cd /c/Users/<YourName>/Hassium/src/Hassium/bin/Debug/

In order to be able to invoke the interpreter it has to be moved to the executable $PATH. To do this we can use the mv command in bash to move the file to /usr/bin/.

$ mv Hassium.exe /usr/bin/hassium

Download a Release:

If you do not have a C# compiler or IDE on your system, you can download a pre-compiled release from the GitHub Releases Tab (https://github.com/HacssiumTeam/Hassium/releases). Find the most recent release and download Hassium.exe.

The environment that we will be invoking and installing the Hassium interpreter in is git bash. If you do not have the git program installed on your computer, install from the git website (https://git-scm.com). Open the git bash program from the Start Menu. A black window should pop up showing a command line interface on the ~ or home directory.

In order to be able to invoke the interpreter it has to be moved to the executable $PATH. To do this we can use the mv command in bash to move the file to /usr/bin/. When you downloaded Hassium.exe from GitHub, it downloaded the file to your default downloads folder. For some users this is C:\Users\<YourName>\Downloads\, and for others it is C:\Users\<YourName>\Documents\Downloads\. Find out which one is yours and change to that directory in git bash using one of the following commands.

$ cd /c/Users/<YourName>/Downloads/

$ cd /c/Users/<YourName>/Documents/Downloads/

Once you are in the Downloads directory, you can move the executable file to /usr/bin/ using the mv command.

$ mv Hassium.exe /usr/bin/hassium

1.2 - Hello, World!

The first program most people write is called the Hello, World! Program. The single function of the program is to display Hello, World! to the terminal. This serves as an introductory program due to the simple nature of the program and what it can teach about how the language works.

Since this book is written for both those who are on Unix-based terminals and those on git bash, the text editor we will cover will be vi, which is included in almost all Unix-based distributions and in the git bash package. We will go over briefly on how to use vi, but a more adequate guide can be found here (http://heather.cs.ucdavis.edu/~matloff/UnixAndC/Editors/ViIntro.html). It is also recommended that you maximize your terminal whenever editing files for ease of use.

The first step to creating a program in Hassium is to create the file where the source code (Hassium code) will be saved. It is standard practice to postfix Hassium file names with the file extension .has. To start off writing our first program open up a new file in vi.

$ vi hello.has

This will open up the editor window for the vi text editor. In order to add text to the file we must enter insert mode by tapping the i key on the keyboard. Once in insert mode we can write the Hassium source code that will constitute our program.

func main () {
    println ("Hello, World!");
}

To save the file, hit the escape key, then w followed by q, followed by the enter key. If done correctly, this will return back to the command prompt and save your file.

To properly execute the Hassium code, invoke the interpreter and give the command line argument helloworld.has.

$ hassium hello.has

The program should emit the following output:

Hello, World!

Congratulations! You just wrote and executed your first program in Hassium. Now we can go over the source code and review what each part does.

The very first word, which is actually a keyword (special identifier in a programming language), is func. If you haven't guessed it, func is short for function (a block of code that can be invoked). When we write func main, we are denoting a function named main. main, of course, is a special function in most programming languages. It signifies the "main" entry point of the application. The code that is inside of main is the very first code to execute when your program runs.

Next to the identifier main is an opening parentheses followed by a closing parentheses. This is what is called an argument list (list of variables the function takes as parameters), and it is something all functions are required to declare. In this case, main requires no arguments, so an empty argument list is declared.

After the argument list declaration, there is a code block (sequence of statements enclosed in { }). This is also called the function body, or the code block that is run when a function is invoked.

Inside the function body of main is a single statement, a function call (invoking of a function) of the println function. println is a global function (function that exists in the global scope and can be called from anywhere), which takes in string parameters and displays them to the terminal, followed by a newline. To preform this function call, the identifier println must be followed by an argument list, which starts with ( and ends with ). Inside of the argument list is a single string (series of characters between " and "), "Hello, World".

Once the argument list is terminated with ), the statement is followed by a semicolon. Many languages such as C, C++, C#, and Java all require statements to send with a semicolon. In Hassium however, this is an optional feature. All of the code examples written in this book will still adhere to this standard since it is good practice to do so.

1.3 - Global Functions

The code example we have written so far invoked a global function called println, which displays a string to the terminal followed by a newline. Hassium comes built in with several global functions, all of which are documented in Appendix A. For the purposes of learning about function calls, we will just focus on the the print and printf functions.

1.3.1 Function - `print`

The print function simply displays the argument given to the screen. Unlike println there is not following newline character. To see this in action, run the following program.

func main () {
    print ("Hello! ");
    print ("I am on the same line! ");
    println ("I am still on the same line, but this will be followed by a newline!");
    print ("I am on a new line!");
}

When run, the program should output:

Hello! I am on the same line! I am still on the same line, but this will be followed by a newline!
I am on a new line!

1.3.2 Function - `printf`

The term printf is short for "print format". This means that the function will take firstly a format string (string containing special format codes in the C# format), followed by data to insert into that string.

Here is an example of a C#-style format string:
"Hello, there. My name is {0}, nice to meet you {1}."

The string looks fairly normal except for the {0} in the middle. This signifies that the first argument given to printf after the format string will be inserted into that spot. The {1} means that the second argument after the format string will be inserted to that location.

To test this, let's invoke printf using this format string and some different data as arguments.

func main () {
    printf ("Hello, there. My name is {0}, nice to meet you {1}.\n", "Jacob", "Andrei");
    printf ("Hello, there. My name is {0}, nice to meet you {1}.\n", "Sloan", "Avril");
}

This code should display the following:

Hello, there. My name is Jacob, nice to meet you Andrei.
Hello, there. My name is Sloan, nice to meet you Avril.

You may notice in the example that the format string had the character \n at the end. \n is an example of an escape sequence (special character in a string starting with \) for a newline. Since printf does not display a newline by default in the same way println does, we must manually add in an escape sequence for a newline at the end to make our output look cleaner.

For the experienced programmer, the Hassium escape sequences are the standard C-style escape sequences. A table of escape sequences can be found in Appendix B.

Chapter 1 - Exercises

For each exercise, create a program in Hassium that displays the given output to the terminal.

Exercise 1.1

Hello,
World!

Exercise 1.2

This should be displayed from two statements

Exercise 1.3

this

is

one

statement

Chapter 1. Introduction and Tutorial