Now that we have an understanding of XML, and a general idea of how Entity itself works, we'll show you how to create and run simple program.
Running entity Programs
Entity works like a scripting languages in how it loads up its applications. The command:
$ entity file.e
will load up file.e (which contains an application marked up in XML), and begin interpreting it.
Alternatively you can use what is called the 'shebang' method, in which you make the first line of the file:
#!/path/to/entity
or
#!/usr/bin/env entity
and set the file's permissions to include execution. This allows you to run it as an interpreted file directly, without having to call entity on it each time. The second method is preferred because it will work as long as you have /usr/bin/env, and Entity is in your path. Entity's XML parser knows to ignore shebang lines if they are present.
A first Entity program
Our sample file looks like this:
<object name="foo">
<window title="This app rules">
<button label="DO NOT CLICK ME"/>
</window>
<?perl
### This is where the code will go, when we write it later
?>
</object>
When entity parses this, it builds a tree of ENodes that can be represented like this:
/object.foo
/window._123
/button._254
/perl._343
The names "_123", "_254" and "_343" are just unique identifiers made up by entity; they may be different from run to run.
This should be familiar to anyone who has seen a graphical directory tree browser. We can see that we have a root, "/", which has a single child, an object node called "foo". "foo" in turn has two children: a window node with an arbitrary (but unique) name, and a perl node with another arbitrary name. The window has one child: a button node with an arbitrary name.
At parse time entity will construct the implementations of these tags and keep them synchronized with your tree. In our example, a window is made with title "This app rules", containing just a button labelled "DO NOT CLICK ME". Also, the perl code is compiled and placed in its own perl namespace.
As a consequence of these at-startup actions, syntax errors or compilation errors in code elements will be flagged at startup. The tree will still continue being built and the program will be run, but the offending node will not be added to the tree.
Once entity has finished parsing the XML file and building the in-memory objects, entity waits for events to happen - events being anything the application listens to, from user actions to network activity.
If the user clicks the button, entity looks to see if that button wants to report the event to anyone. Since our example has no code, nothing happens. Let's change that now.
Change your file to look like this:
<object name="foo">
<window title="This app rules">
<button label="DO NOT CLICK ME" onclick="perl:clicked"/>
</window>
<?perl
sub clicked
{
$the_button = shift;
PRInt "button $the_button was clicked\n";
}
?>
</object>
So what's changed? We've added an attribute called "onclick" to our button tag, with the value "perl:clicked". This means that when a click event happens, entity looks in any perl nodes within the parent object tag (this is one of the main roles of the object tag) for a procedure called "clicked" and executes that.
We've also added some code in the perl node, a sub called "clicked" that we've told the button to call on click events. This sub takes one parameter: the node that was clicked. This is so you can use a single handler for a number of events, which can often be a very elegant way of doing things.
You will find that in many applications programmers will set the "default-lang" attribute in the object node to specify what language should be called when no language identifier is given. For example:
<object default-lang="javascript">
<button onclick="some_javascript_function"/>
...
</object>
Because of the 'default-lang="javascript"' attribute of this object, when the button is clicked, entity assumes the onclick callback "some_javascript_function" is in fact a javascript function. Entity will search for this function in any javascript nodes within this object and execute this function.