NAML language introduction

NAML is an HTML-like macro language designed to be easy to read and tweak.  A tweak is a small change, like a text change or removing unwanted features, that can be made without fully understanding everything about NAML.  But larger changes require understanding NAML, and in this document we will try to give you a basic understanding of the NAML language.

Here is an example of a NAML macro:

<macro name="hello_world">
	Hello <b>world</b>.
</macro>

So now whenever the macro "hello_world" is used, the text "Hello world." is placed there.  Note that we used regular HTML in this macro.  Now let's expand this:

<macro name="hello_world">
	<n.hello>
		<who>world</who>
	</n.hello>
</macro>

<macro name="hello" parameters="who">
	Hello <b><n.who/></b>.
</macro>

Here we have one macro calling another.  When we want to call a macro, we start the name of the tag with "n.".  This lets NAML know that this isn't just regular HTML, but must be processed.  Our "hello" macro has a parameter called "who".  Within the "hello" macro, "who" can be referenced like we would reference a macro.  In effect "who" is a macro containing whatever is passed to "hello".  In "hello_world", we call "hello" and pass in "world" as the "who" argument.  We could also do this in another way:

<macro name="hello_world">
	<n.hello who="world" />
</macro>

<macro name="hello" parameters="who">
	Hello <b><n.who/></b>.
</macro>

NAML treats XML attributes and child entities the same.

Now let's make a new macro:

<macro name="hello_president">
	<n.hello>
		<who><n.president/></who>
	</n.hello>
</macro>

<macro name="president">
	Mr. Obama
</macro>

<macro name="hello" parameters="who">
	Hello <b><n.who/></b>.
</macro>

Here we pass another macro, "president", as the "who" argument.  We could also do:

<macro name="hello_president">
	<n.hello who="[n.president/]" >
</macro>

<macro name="president">
	Mr. Obama
</macro>

<macro name="hello" parameters="who">
	Hello <b><n.who/></b>.
</macro>

In this case, we use the attribute approach.  In an attribute that uses double-quotes, NAML will replace "[" with "<" and "]" with ">" and then evaluate the result.  Single-quoted attributes are not processed.

Here is another way to do this:

<macro name="hello_president">
	<n.hello.president />
</macro>

<macro name="president">
	Mr. Obama
</macro>

<macro name="hello" dot_parameter="who">
	Hello <b><n.who/></b>.
</macro>

The dot_parameter is a special parameter that allows you to string macros together connected by dots (".").  So here the "hello" macro is passed the "president" macro because it follows the dot (line 2 above).

Here is yet another way to do this:

<macro name="hello_president">
	<n.hello.>
		<n.president />
	</n.hello.>
</macro>

<macro name="president">
	Mr. Obama
</macro>

<macro name="hello" dot_parameter="who">
	Hello <b><n.who/></b>.
</macro>

In this case, the tag that calls "hello" in the "hello_president" macro ends with a dot (lines 2 and 4 above).  This tells NAML that rather than looking for arguments inside the inner block, it should treat the whole block as the dot_parameter.  This isn't very useful in this case, but this is a nice way to handle a big block of NAML being passed to a macro.

Finally, here is one more way:

<macro name="hello_president">
	<n.hello>
		<who.president />
	</n.hello>
</macro>

<macro name="president">
	Mr. Obama
</macro>

<macro name="hello" dot_parameter="who">
	Hello <b><n.who/></b>.
</macro>

This is very ugly in this case and not recommended for a situation like this, but we provide this for completeness and will show where it is useful later.  Here the "who" argument takes its content after a dot instead of taking it as an inner block (line 3 above).

NAML macros are similar to subroutines, but as macros, they are expanded in place instead of being called as a separate block of code.  NAML code can call both macros and binary commands defined in Java.  There is no difference between the syntax to call a macro or a Java command.  Here is some NAML that uses a Java command:

<macro name="my_plans">
	<n.if.I_am_hungry>
		<then>
			I will eat.
		</then>
		<else>
			I will work.
		</else>
	</n.if.I_am_hungry>
</macro>

<macro name="I_am_hungry">
	false
</macro>

Here we have one Java command, "if", which takes three arguments, a dot_parameter of "condition", and regular parameters "then" and "else".  Let's expand this:

<macro name="my_plans">
	<n.if.I_am_tired>
		<then>
			I will sleep.
		</then>
		<else>
			<n.if.I_am_hungry>
				<then>
					I will eat.
				</then>
				<else>
					I will work.
				</else>
			</n.if.I_am_hungry>
		</else>
	</n.if.I_am_tired>
</macro>

<macro name="I_am_tried">
	false
</macro>

<macro name="I_am_hungry">
	false
</macro>

This is somewhat ugly.  We can clean it up by using the dot form of the "else" argument (line 6 below):

<macro name="my_plans">
	<n.if.I_am_tired>
		<then>
			I will sleep.
		</then>
		<else.if.I_am_hungry>
			<then>
				I will eat.
			</then>
			<else>
				I will work.
			</else>
		</else.if.I_am_hungry>
	</n.if.I_am_tired>
</macro>

<macro name="I_am_tired">
	false
</macro>

<macro name="I_am_hungry">
	false
</macro>

This completes the basic syntax of NAML.