haXe 2 Beginner’s Guide

Develop exciting applications with this multi-platform programming language

What is cross-platform in the library

The standard library includes a lot of classes and methods, which you will need most of the time in a web application. So, let’s have a look at the different features. What we call standard library is simply a set of objects, which is available when you install haXe.

Object storage

The standard library offers several structures in which you can store objects. In haXe, you will see that, compared to many other languages, there are not many structures to store objects. This choice has been made because developers should be able to do what they need to do with their objects instead of dealing with a lot of structures, which they have to cast all the time.

The basic structures are array, list, and hash. All of these have a different utility:

• Objects stored in an array can be directly accessed by using their index
• Objects in a list are linked together in an ordered way
• Objects in an hash are tied to what are called “keys”, but instead of being an Int, keys are a String

There is also the IntHash structure that is a hash-table using Int values as keys.

These structures can be used seamlessly in all targets. This is also, why the hash only supports String as indexes: some platforms would require a complex class that would impair performances to support any kind of object as indexes.

The Std class

The Std class is a class that contains methods allowing you to do some basic tasks, such as parsing a Float or an Int from a String, transforming a Float to an Int, or obtaining a randomly generated number.

This class can be used on all targets without any problems.

The haxe package

The haxe package (notice the lower-case x) contains a lot of class-specific to haXe such as the haxe.Serializer class that allows one to serialize any object to the haXe serialization format or its twin class haxe.Unserializer that allows one to unserialize objects (that is “reconstruct” them).

This is basically a package offering extended cross-platform functionalities.

The classes in the haxe package can be used on all platforms most of the time.

The haxe.remoting package

This package also contains a remoting package that contains several classes allowing us to use the haXe remoting protocol. This protocol allows several programs supporting it to communicate easily. Some classes in this package are only available for certain targets because of their limitations. For example, a browser environment won’t allow one to open a TCP socket, or Flash won’t allow one to create a server.

Remoting will be discussed later, as it is a very interesting feature of haXe.

The haxe.rtti package

There’s also the rtti package. RTTI means Run Time Type Information. A class can hold information about itself, such as what fields it contains and their declared types. This can be really interesting in some cases, such as, if you want to create automatically generated editors for some objects.

The haxe.Http class

The haxe.Http class is one you are certainly going to use quite often. It allows you to make HTTP requests and retrieve the answer pretty easily without having to deal with the HTTP protocol by yourself. If you don’t know what HTTP is, then you should just know that it is the protocol used between web browsers and servers.

On a side-note, the ability to make HTTPS requests depends on the platform. For example, at the moment, Neko doesn’t provide any way to make one, whereas it’s not a problem at all on JS because this functionality is provided by the browser.

Also, some methods in this class are only available on some platforms. That’s why, if you are writing a cross-platform library or program, you should pay attention to what methods you can use on all the platforms you want to target.

You should note that on JS, the haxe.Http class uses HttpRequest objects and as such, they suffer from security restrictions, the most important one being the same-domain policy. This is something that you should keep in mind, when thinking about your solution’s architecture.

You can make a simple synchronous request by writing the following:

var answer = Http.requestUrl(“http://www.benjamindasnois.com”);

It is also possible to make some asynchronous requests as follows:

var myRequest = new Http(“http://www.benjamindasnois.com”);
myRequest.onData = function (d : String)
{
Lib.println(d);
}
myRequest.request(false);

This method also allows you to get more information about the answer, such as the headers and the return code.

The following is an example displaying the answer’s headers:

import haxe.Http;
#if neko
import neko.Lib;
#elseif php
import php.Lib;
#end

class Main
{

static function main()
{
var myRequest = new Http(“http://www.benjamindasnois.com”);
myRequest.onData = function (d : String)
{
for (k in myRequest.responseHeaders.keys())
{
Lib.println(k + ” : ” + myRequest.responseHeaders.get(k));
}
};
myRequest.request(false);
}

}

The following is what it displays:

X-Cache : MISS from rack1.tumblr.com
X-Cache-Lookup : MISS from rack1.tumblr.com:80
Via : 1.0 rack1.tumblr.com:80 (squid/2.6.STABLE6)
P3P : CP=”ALL ADM DEV PSAi COM OUR OTRo STP IND ONL”
Set-Cookie : tmgioct=h6NSbuBBgVV2IH3qzPEPPQLg; expires=Thu,
02-Jul-2020
23:30:11
GMT; path=/; httponly
ETag : f85901c583a154f897ba718048d779ef
Link : <http://assets.tumblr.com/images/default_avatar_16.gif>;
rel=icon
Vary : Accept-Encoding
Content-Type : text/html; charset=UTF-8
Content-Length : 30091
Server : Apache/2.2.3 (Red Hat)
Date : Mon, 05 Jul 2010 23:31:10 GMT
X-Tumblr-Usec : D=78076
X-Tumblr-User : pignoufou
X-Cache-Auto : hit
Connection : close

Regular expressions and XML handling

haXe offers a cross-platform API for regular expressions and XML that can be used on most targets’ target.

Regular expressions

The regular expression API is implemented as the EReg class. You can use this class on any platform to match a RegExp, split a string according to a RegExp, or do some replacement.

This class is available on all targets, but on Flash, it only starts from Flash 9.

The following is an example of a simple function that returns true or false depending on if a RegExp matches a string given as parameter:

public static function matchesHello(str : String) : Bool
{
var helloRegExp = ~/.*hello.*/;
return helloRegExp.match(str);
}

One can also replace what is matched by the RegExp and return this value. This one simply replaces the word “hello” with “bye”, so it’s a bit of an overkill to use a RegExp to do that, and you will find some more useful ways to use this possibility when making some real programs. Now, at least you will know how to do it:

public static function replaceHello(str : String) : String
{
var helloRegExp = ~/hello/;
helloRegExp.match(str);
return helloRegExp.replace(str, “bye”);
}

XML handling

The XML class is available on all platforms. It allows you to parse and emit XML the same way on many targets. Unfortunately, it is implemented using RegExp on most platforms, and therefore can become quite slow on big files. Such problems have already been raised on the JS targets, particularly on some browsers, but you should keep in mind that different browsers perform completely differently.

For example, on the Flash platform, this API is now using the internal Flash XML libraries, which results in some incompatibilities.

The following is an example of how to create a simple XML document:

<pages>
<page id=”page1″/>
<page id=”page2″/>
</pages>

Now, the haXe code to generate it:

var xmlDoc : Xml;
var xmlRoot : Xml;
xmlDoc = Xml.createDocument(); //Create the document
xmlRoot = Xml.createElement(“pages”); //Create the root node
xmlDoc.addChild(xmlRoot); //Add the root node to the document

var page1 : Xml;
page1 = Xml.createElement(“page”); //create the first page node
page1.set(“id”, “page1”);
xmlRoot.addChild(page1); //Add it to the root node

var page2 : Xml;
page2 = Xml.createElement(“page”);
page2.set(“id”, “page2”);
xmlRoot.addChild(page2);

trace(xmlDoc.toString()); //Print the generated XML

Input and output

Input and output are certainly the most important parts of an application; indeed, without them, an application is almost useless.

If you think about how the different targets supported by haXe work and how the user may interact with them, you will quickly come to the conclusion that they use different ways of interacting with the user, which are as follows:

• JavaScript in the browser uses the DOM
• Flash has its own API to draw on screen and handle events
• Neko uses the classic input/output streams (stdin, stdout, stderr) and so do PHP and C++

So, we have three different main interfaces: DOM, Flash, and classic streams.

The DOM interface

The implementation of the DOM interface is available in the js package. This interface is implemented through typedefs. Unfortunately, the API doesn’t provide any way to abstract the differences between browsers and you will have to deal with them in most cases by yourself.

This API is simply telling the compiler what objects exist in the DOM environment; so, if you know how to manipulate the DOM in JavaScript, you will be able to manipulate it in haXe. The thing that you should know is that the document object can be accessed through js.Lib.document.

The js package is accessible only when compiling to JS.

The Flash interface

In a way that is similar to how the Flash is implemented in the flash and flash9 packages, the js package implements the DOM interface. When reading this sentence, you may wonder why there are two packages. The reason is pretty simple, the Flash APIs pre and post Flash 9 are different.

You also have to pay attention to the fact that, when compiling to Flash 9, the flash9 package is accessible through the flashpath and not through flash9.

Also, at the time of writing, the documentation for flash and flash9 packages on haxe. org is almost non-existent; but, if you need some documentation, you can refer to the official documentation.

The standard input/output interface

The standard input/output interface refers to the three basic streams that exist on most systems, which are as follows:

1. stdin (most of the time the keyboard).
2. stdout (the standard output which is most of the time the console, or, when running as a web-application, the stream sent to the client).
3. stderr (the standard error output which is most of the time directed to the console or the log file).

Neko, PHP and C++ all make use of this kind of interface. Now, there are two pieces news for you: one good and one bad.

The bad one is that the API for each platform is located in a platform-specific package. So, for example, when targeting Neko, you will have to use the neko package, which is not available in PHP or C++.

The good news is that there is a workaround. Well, indeed, there are three. You just have to continue reading through this article and I’ll tell you how to handle that.