Chapter 9. Standard Library

Chapter 8 went over the nuances of importing modules. This chapter will cover some features of the builtin modules included with Hassium. This chapter only scratches the surface of what the standard library can do. For a generic coverage of the builtin modules in Hassium, visit Appendix D. For a complete documentation of the Hassium standard library, visit the Hassium Github (https://github.com/HassiumTeam/Hassium/tree/master/docs).

9.1 - Random

Although there is no such thing as true entropy, most languages come equipped with a Pseudo Random Number Generator (software that generates seemingly random numbers based on a seed). The seed (integer that initializes the PRNG) is derived from the system clock or given in the constructor. The Hassium Random class is included in the Math module.

Let's write a code example which generates 20 random numbers between 0 and 50.

from Math use Random;

func main () {
    Random prng = new Random ();
    foreach (i in range (0, 20)) {
        println (prng.randint (0, 50));
    }
    println ("All done.");
}

9.2 - UI

Up until now, the Hassium programs we have been writing were on a black background with white text. The UI class allows us to change certain aspects of the Text User Interface (input-output console), or TUI. The Hassium UI class is located in the Util module. It is important to note that a lot of these modifications are system dependent, and Linux users may notice some variations.

9.2.1 TUI - Changing the Background Color

To get or set the background color of the terminal, use the UI.backcolor property. This program will display the default background color, then change it and print sample text.

from Util use UI;

func main () {
    printf ("The default background color is {0}.", UI.backcolor);
    UI.backcolor = "blue";
    printf ("The new background color is {0}.", UI.backcolor);
}

9.2.2 TUI - Changing the Foreground Color

To get or set the foreground color of the terminal, use the UI.forecolor property. This program will display the default foreground color, then change it and print sample text.

use Util;

func main () {
    printf ("The default foreground color is {0}.", UI.forecolor);
    UI.forecolor = "blue";
    printf ("The new foreground color is {0}.", UI.forecolor);
}

9.3 - File IO

File IO refers to the process of reading and writing to files on the File System (FS). This section will use the Hassium FS class in the IO module.

9.3.1 IO - Reading from a File

If you wish to read the entire contents of a file, you can use FS.readbytes, FS.readlines, and FS.readstring.

Create a text file in the directory with your Hassium programs called file.txt with the following text.

File.txt:

Hello, World!
This is the second line.
Goodday.

We'll start by reading this text file into a string in Hassium.

use IO;

func main () {
    string text = FS.readstring ("file.txt");

    println ("Begin contents of file: ");
    println (text);
    println ("End contents of file.");
}

Output:

Begin contents of file:
Hello, World!
This is the second line.
Goodday.
End contents of file.

You can also read the individual lines of a file into a list of strings.

from IO use FS;

func main () {
    list lines = FS.readlines ("file.txt");

    foreach (line in lines) {
        printf ("Line: {0}", line);
    }
}

Output:

Line: Hello, World!
Line: This is the second line.
Line: Goodday.

9.3.2 IO - Writing to a File

To write a chunk of text to a file, you can use the FS.writebytes, FS.writelines, FS.writestring.

from IO use FS;

func main () {
    string text = "Heyo!\nI am a new line!";
    FS.writetext ("text.txt", text);
    list lines = [ "One", "Two", "Three" ];
    FS.writelines ("lines.txt", lines);
    list bytes = [ 97, 98, 99 ];
    FS.writebytes ("bytes.txt", bytes);
}

text.txt:

Heyo!
I am a new line!

lines.txt:

One
Two
Three

bytes.txt

abc

9.3.3 Stream Reading from a File

9.3.1 covers reading functions that read all the data from a file at once. This can be problematic for large files, or times when you want to read from a certain position in the file. To accomplish this, we can read from a stream (sequence of data elements that can be read at a time). This way, all of the data isn't read into RAM at once.

To accomplish this, we can open a new File object using the function FS.open that will allow us to read this file as a stream.

from IO use FS;

func main () {
    File file = FS.open ("file.txt");

    while (file.position < file.length) {
        println (file.readLine ());
    }
}

Output:

Hello, World!
This is the second line.
Goodday.

9.3.4 Stream Writing to a File

9.3.2 covers reading functions that write all the data to a file at once. This can be problematic for large files, or times when you want to write to a certain position in the file. To accomplish this, we can write to a stream. This way, all of the data isn't stored in RAM at once.

To accomplish this, we can open a new File object using the function FS.open that will allow us to write to this file as a stream.

use IO;

func main () {
    File file = FS.open ("out.txt");
    file.writeline ("One.");
    file.writeline ("Two.");
    file.writeline ("Three.");
}

out.txt:

One.
Two.
Three.

9.4 - Networking

Hassium includes a module dedicated to networking (the system of sharing data with other computers). This is the Net module.

9.4.1 Networking - Downloading a Webpage

You can interact with webpages using theWeb class from the Net module. Let's download the data from a webpage as a list of bytes and save it to a file using the FS class from the IO module.

from IO use FS;
from Net use Web;

func main () {
    list data = new Web ().downloadData ("http://google.com/index.html");   
    FS.writebytes ("google.html", data);
}

The file google.html will contain the downloaded HTML from index.html.

The Web class has a function for automatically saving a page to a file. The previous example can be written as the following.

from Net use Web;

func main () {
    new Web ().downloadfile ("google.html", "http://google.com/index.html");
}

The Web class can also download a page as a string. A common way to retrieve the external IP Address (unique identifier for your network) is to download the string at icanhazip (http://icanhazip.com/).

from Net use Web;

func main () {
    string ip = new Web ().downloadstring ("http://icanhazip.com");
    printf ("Your IP is {0}", ip);
}

9.4.2 Networking - Dns

Domain Name System (or DNS) is a protocol most commonly used for resolving the actual IP address from a domain name. To use this feature in Hassium, we can use the static Dns class from the Net module.

from Net use Dns;

func main () {
    string ip = Dns.getip ("www.google.com");
    printf ("The IP Address for www.google.com is {0}", ip);
}

Chapter 9 - Exercises

Exercise 9.1

Create a program that downloads the HTML for http://yahoo.com/index.html and stream writes it to a file.

Exercise 9.2

Create a program that stream reads a file, then stream writes it backwards to the disc.

results matching ""

    No results matching ""