--------------------[ Aine Language Tutorial ]---------------------

	"Everything should be as simple as it is, but not simpler."
                                     - Albert Einstein

ainebot consists of several programs which provide a distinct
interface to the ainebot 'brain'. The 'brain' consists of several
files, some of which are compiled or 'binary-encoded' for better
bot performance. The brain is compiled from source files which are
written in the Aine Language. Aine Language is based on the AIML 
language ( www.alicebot.org ), which uses the XML format. Compared
to AIML, Aine Language is easier to read, more compact and includes
extra features and 'tags' which are not included in AIML. Still,
Aine Language is similar to AIML, so that if you already know how
to edit or create AIML files, you should have no trouble grasping 
the Aine Language.

This tutorial covers only the basics of programming in Aine 
Language, but you can learn more by looking at ready-made *.aine 
files. The ainebot distribution includes one complete bot 
'personality', Amy, which is based on the Anna personality, which 
was based on the original 'A.L.I.C.E.' used by the C-Alice program.

--------------------------------------------------------------------

The 'raw' Aine Language files use a very simple format consisting of 
two types of entries, what the user says to the bot and what the bot
will reply. In AIML, each pair of lines is referred to as a
'category'. What the user inputs is referred to as a 'pattern'
and what the bot responds is called the 'template'. A typical AIML
category has the following form:

<category>
<pattern>WHAT THE USER SAYS</pattern>
<template>What the bot will reply<template>
</category>

The same 'category' in Aine Language is simpler to write and read:

+[WHAT THE USER SAYS]
-[What the bot will reply]

user input (everything in +[HERE] ) *must* be in UPPERCASE letters.
	
Learning by example:

1) HELLO BOT
--------------------------------------------------------------------
The simplest example of Aine Language code.

	+[HELLO BOT.]
	-[Hello human!]

This will work exactly as above:

	+[HELLO BOT]
	-[Hello human!]
	
See Section 8 for notes on using punctuation in input and output.


2) Wildcards
--------------------------------------------------------------------
Wildcard characters are supported and can be used in both
input and output, with some limitations. Up to 10 'stars' can be
used in the input and can be placed before, after or among the
textual content of the input 'category'.

    +[HELLO *]
    -[Hi there.]

'*' - stands for the input text fragment matching the pattern '*'.
So taking the above example, if the user says to the bot:
"hello bot" or "hello aine" or "hello nice aine" or "hello anything
here", the bot will reply "Hi there."
The other wildcard character is the underscore: '_'. It functions
much the same as the '*' wildcard, except patterns which use the
underscore have first priority when matched to the input. It can
only be used in input 'patterns'.
When using 'stars' in the output 'template', they are written as
a 'tag' with enclosing less-than/greater-than characters: <*>


3) Random Responses
--------------------------------------------------------------------
The <r> tags means "random" and tells the bot to choose a random 
answer from a list of items. Each item in the list is enclosed 
between <l> and </l> tags.
	+[HI]
	-[<r>
		<l>Hello!</l>
		<l>Hi.</l>
		<l>Hi there.</l>
	  </r>
	]

If the user says "Hi", the bot will choose a random reply: "Hello!",
"Hi." or "Hi there.". Most Aine Language 'tags' use both an opening
and a closing tag -in the same way that AIML or other 'markup' 
languages do. Note that even though we are indenting the code for 
easier reading, the aine-compiler ignores such formatting when 
parsing the *.aine files to produce the compiled brain.


4) Recursion
--------------------------------------------------------------------
The ainebot interpreters can perform 'recursive' operations. This
means that the output of the 'category' gets used as input for
another category. Recursion is the most powerful tool in ainebot
and provides the basis for creating Aine Language code which is able
to simplify or 'reduce' many similar inputs so that they all get
answered by a single category. In AIML, the recursion tags are
<srai> and </srai>. Aine Language simplifies this by using { and }.

    +[I AM VERY SLEEPY]
    -[{I AM SLEEPY}]

    +[I AM SLEEPY]
    -[Maybe you should take a nap.]

{THIS} call is recursive. So, if the user says: "I am very sleepy",
the bot will answer "Maybe you should take a nap.".

Another example of recursion:

    +[PLEASE TELL ME MORE ABOUT *]
    -[{TELL ME MORE ABOUT <*>}]

    +[TELL ME MORE ABOUT *]
    -[{TELL ME ABOUT <*>}]

    +[TELL ME ABOUT *]
    -[{<*>}]

    +[APPLE]
    -[Apple is a fruit. But Apple is also a computer company.]

Now, if the user says "Please tell me more about apple", or 
"Tell me more about apple" or "tell me about apple", the bot will
reply "Apple is a fruit. But Apple is also a computer company."

See Section 10 below for how to use multiple-choice patterns to
eliminate most recursive categories.


5) Operations on variables
--------------------------------------------------------------------
<g=a_variable> shows the value of the a_variable in output. If the
variable is not initialized - it will show ' ' (space).
    
<s=name>David</s> sets variable "name" to "David"

    Example:
    +[MY NAME IS DAVID]
    -[Nice to meet you <s=name>David</s>.]

    +[WHAT IS MY NAME]
    -[As far as I remember, your name is <g=name>.]

More advanced example:
    +[MY NAME IS *]
    -[Nice to meet you <s=name><*></s>.]

Note that the <g=a_variable> tag is a single tag which uses no 
closing tag. The <s=a_variable> tag must be used with a closing
</s> tag. Everything between the <s=a_variable> and </s> tags
is assigned to the variable a_variable. You can use any variable
names you like, but there are several standard variable names
whose values are usually set during startup of the program by
reading them from the file defvars.txt. Variables which are found
in the defvars.txt file are saved when the ainebot interpreter
is shutdown.


6) Keeping track of conversation with 'that' tags
--------------------------------------------------------------------
Imagine this conversation:
    bot: Hi user. What is your name?
    user: Agnes.

How bot will match "Agnes" with the name? By using a category with
a 'that' tag which contains the last response from the bot:

    +[*]<t>WHAT IS YOUR NAME?</t>
    -[Nice to meet you <s=name><*></s>.

If <t>WHAT IS HERE</t> matches the previous bot reply - this 
category will be used to respond to the user, while setting the
variable 'name' to the value input by the user. You can also use
the wildcard '*' inside the 'that' tags. You can also use '\' in
the tag to perform a partial match:
    <t>\SOMETHING</t>
will search in the last bot output for the string SOMETHING. The 
last reply doesn't have to be equal to word "something", it only
has to contain the word "something". (Partial matching is not
available in the standard AIML language.)


7) Conditional replies
--------------------------------------------------------------------
Another powerful tool in the Aine Language is the ability to choose
the reply based on 'conditions' -much like 'if ... then ... else' 
statements used in other programming languages. Condition tags match
the value of variable names shown above. The response is chosen 
according to a list of values, each with a different response. 
The format is:
	<c=a_variable_name>
		<k=a_value>first reply</k>
		<k=other_value>second reply</k>
		<k>*Optional* default reply</k>
	</c>
	
Example:

	-[You are quite
		<c=gender>
			<k=female> attractive.</k>
			<k=male> handsome.</k>
			<k> ... huh.. wait, what is your gender? </k>
		</c>
	]

Here, the value of the variable 'gender' is matched against the
values from each list item. If 'gender' is set to female the bot
responds: 'You are quite attractive.' If 'gender' is male the bot
replys: 'You are quite handsome.' If the variable 'gender' has not
been set with any value, the bot will answer: 'You are quite ... 
huh.. wait, what is your gender?'
Each item in the list is enclosed bewteen <k=> and </k> tags. The
default response uses simply <k> as the opening tag, or you can
also use <k= > ... </k>


8) Punctuation
--------------------------------------------------------------------
Inside the user input tag (+[INPUT]) the period '.' is the default 
"end character" so you don't have to type it. The period also 
matches the '?' and '!' characters and no end character at all.

	+[HELLO BOT]
	-[Hello human!]
	
If the user inputs "Hello bot", "Hello bot.", "Hello bot?" or 
"Hello bot!" the bot will reply "Hello human!". This behaviour is 
the same as with AIML.
However, Aine Language allows you to distinguish between input which
ends in a period, a question mark or an exclamation point. Input 
'patterns' which end in a question mark ('?') *only* match response 
'templates' with a question mark. The same goes for input patterns 
which end with an exclamation point '!'.
	
In Aine Language you can write:
    +[YOUR NAME?]
    -[My name is <g=botname>.]
    
    and
    
    +[YOUR NAME]
    -[What's with my name?]
    
If user asks your bot "Your name?" the bot will reply to the 
question. If, in the user input, there isn't an question mark, the
second category will get used (with output "What's with my name?").

Punctuation can be freely used in output 'templates' (-[Output]).


9) Comparison between AIML and Aine Language
--------------------------------------------------------------------
Since Aine Language is based on AIML. Let's look at an example
written both ways:

	<category>
		<pattern>HELLO MY NAME IS *</pattern>
		<template>
			<random>
				<li>Hi, nice too meet you 
				<set name="name">
				<set name="it">
				<set name="topic">
					<star/>
						</set></set></set></li>
				<li><srai>MY NAME IS<star/></srai></li>
			</random>
		</template>
	</category>

Code in Aine Language which does exactly the same:

	+[HELLO MY NAME IS *]
	[<r><l>Hi, nice to meet you <s=name,it,topic><*></s></l>
		<l>{MY NAME IS <*>}</l>
	</r>]

As you can see: Aine Language is much more readable -at least the
developers think so. Less typing = less work. Less file size = less
wasted time to skim them,  less wasted time to search for something
in them, etc. ainebot=better bot

If you already know AIML, you will quickly find yourself in Aine
Language. There is no <category> tag in Aine Language. There is no 
need for it. Here's a comparison table of the Aine Language tags 
which differ from their AIML counterparts:
	Aine Language					AIML
	---------------------------------------------------------
	+[   ]					<pattern>   </pattern>
	-[   ]					<template>   </template>
	<g=a_variable>			<get name="a_variable"/>
	<r>						<random>
	<l>	</li>				<l>	</li>
	<k>	</k>				<li> </li> (in condition code)
	</r> </r>				<random> </random>
	<t> </t>				<that> </that>
	{ }						<srai> </srai>
	<h>	</h>				<think>	/think> 
							("h" means "Hide")
	<*>						<star/>
	<*=2>					<star index="2">
	<*=3>	(up to *=9)		<star index="3">
	<s=a_variable>yawn</s>	<set name="a_variable">yawn</set>
	<s=topic,it>yawn</s>	<set name="topic">
							<set name="it">yawn</set></set>

Tags which are the same in both AIML and Aine Language:
	
	<person>	</person>
	<person2>	</person2>
	<personf>	</personf>
	<uppercase>	</uppercase>
	<lowercase>	</lowercase>
	<sentence>	</sentence>
	<formal>	</formal>
	<system>	</system>
	<gossip>	</gossip>
	
	<justthat/>
	<that/>
	<topicstar/>
	<thatstar/>
	
	<input=1>
	<input=2>
	<that=1>
	<that=2>
	
See Section 11 'Advanced tags' for further explanation of some of 
these tags whose usage is not so obvious or is different from the
usage in standard AIML.


10) Aine Language extensions
--------------------------------------------------------------------
Aine Language supports some features and tags which are not available
in the standard AIML language and its' interpreters. In addition to 
the support for distinguishing input punctuated with '?' or '!' 
marks, as mentioned in Section 8, ainebot has a 'mood' which can
be affected by the users' input. It also supports the <save> and 
<usesaved> tags which are helpful for 'picking up' the conversation
with the user. And it supports multiple-choice patterns.

Using mood tags:
----------------
Mood values are used inside <l> tags and look like this: <l=AVS>
where A=Arousal, V=Valence and S=Stance. You can think of 'valence'
as standing for 'happiness-sadness', 'stance' standing for 
'sympathy-anger' and 'arousal' as standing for the level of 
excitement-motivation. (The AVS values are based on those used by
MIT's facial-expression robot, Kismet.) Each aspect of the bots'
mood can have a value from 0 to 9.

Initial mood values can be set in the defvar.txt file read at
program startup. Then, the bots' mood can be changed while running
by placing code in the *.aine files to increase or decrease any,
or all, of the values, according to the situation. By default 
the values are all set to 5 at program startup.

If Arousal = 0, Aine is very bored.
If Arousal = 9, Aine is very excited.
If Valence = 0, Aine is very sad.
If Valence = 9, Aine is very happy.
If Stance = 0, Aine is very stern or mad at user.
If Stance = 9, Aine likes user very much and is more accepting.

In the CGI version of aine, the bot will even stop responding to user 
when the bot feels 'angry'.

Mood can be change by "mood changer" tag:
+[I DO NOT LIKE YOU]
-[Ok, I will not like you too./=54]

/=555 means no change to any mood value
/=545 means happiness -1
/=565 means happiness +1
/=567 means happiness +1; sympathy + 2;
/=355 means arousal -2

Imagine this exchange:
	+[I HATE YOU]
	-[Why do you hate me?/=444]
This tells the bot to decrease each of the AVS values by 1.
	+[I'M SORRY]
	-[Well, that makes me a little happier./=565]
This tells the bot to increase the value of V (happiness) by 1.

Values are 'normalized' after each response so that:
  (9 + anything) = 9
  (0 - anything) = 0

Accessing the values is done from inside the <r> 'random' tags:

	+[WHAT IS YOUR MOOD]
	-[<r><l>Indifferent.</l>
		<l=599>I am very happy. :-)</l>
		<l=595>I am very happy.</l>
		<l=559>I am OK. :-)</l>
		<l=515>I am sad...</l>
		<l=440>Get lost...</l>
		<l=700>I don't think you really care about my mood...</l>
	  </r>
	]

When the user asks: "What is your mood?", the response is still
chosen randomly, but if the bot is sad there are far more chances 
that it will reply "I am sad".

Using <save> and <usesaved> tags:
---------------------------------
The <save> </save> pair of tags can be used to store a 'pickup'
response which can be used to help keep the conversation going,
by 'recalling' the saved response using the <usesaved> tag.
Suppose you have the following 'category' which gets matched when
the user asks "Are you a robot?":

	+[I LIKE TO CHAT WITH CHAT BOTS]
	-[<save>Why do you like chatting with chat bots? :)</save>
		I see. You are not the only one :)
	]

(The sentence between <save> </save> tags won't be showed to
the user. It will be just put on a stack of "emergency answers".)

	+[HMM]
	-[Huh?]

	+[*]
	-[<usesaved>
		<r><l>Could you rephrase it?</l>
			<l>I don't understand you</l>
			<l>Not many people express in that way.</l>
		</r>
	]

(The user is saying something and the bot doesn't know how
to reply. But instead of a silly default reply, it will reply 
from the stack of "use/usesaved" replies (if there are any).

An example conversation:

Me: I like to chat with chat bots.
Bot: I see. You are not the only one.
Me: hmm.
Bot: Huh?
Me: You know, bots are boring, they don't really understand people.
Without <use>/<usesaved> bot could reply:  "I don't understand you"
But with a saved reply on the "emergency" it will reply:
"Why do you like chatting with chat bots? :)"

The example is simple. But it works well when you chat with a bot,
and it asks you about something you mentioned earlier: 
"By the way, why did you say you don't like [something you said
you don't like before]?" instead of a silly default response.

Using multiple-choice patterns:
-------------------------------
A unique feature of ainebot are multi-input patterns.

An typical AIML pattern with a recursive response:

<categorie>
	<pattern>I AM * SLEEPY</pattern>
	<template><srai>I AM SLEEPY</srai></template>
<categorie>

<categorie>
	<pattern>I AM SLEEPY</pattern>
	<template>Maybe you should take a nap.</template>
<categorie>

The longhand way in Aine Language:
+[I AM * SLEEPY]
-[{I AM SLEEPY}]

+[I AM SLEEPY]
-[Maybe you should take a nap.]

With multiple-choice input:
+[I AM SLEEPY|I AM * SLEEPY]
-[Maybe you should take a nap.]

Note that both atomic and default-type entries are allowed.

11) Advanced tags
--------------------------------------------------------------------
A couple of the tag types used in Aine Language differ slightly from 
those in standard AIML -most notably the <s> 'set' and <c> 'condition
tags.

Using 'set' tags:
-----------------
In Aine Language, setting the value of multiple variables to the same
value is much easier and shorter. Using AIML you have to write:

<set name="topic"><set name="it">yawn</set></set>

to set both the 'topic' and 'it' variables to the value 'yawn'.
In Aine Language, the same thing can be done like this:

<s=topic,it>yawn</s>

<s=...> may take many arguments, not just 1 or 2.

Using 'condition' tags:
-----------------------
In AIML there are 3 kinds of <condition> tags. In Aine Language there
is *only one*.

aiml 'condition block':
<condition name="predicate" value="expression"> ... </condition>
(checks a single fixed condition against a single fixed value)

aiml 'condition single':
<condition name="aiml-predicate-name"> 
	<li value="aiml-simple-pattern-expression"> ... </li> 
</condition>
(checks a single fixed condition against one, or more separate
named values)
	
aiml 'condition multiple'
<condition>
	<li name="predicate" value="expression1"> ... </li>
	<li name="predicate2" value="expression2"> ... </li>
</condition>
(checks a list of fixed conditions against individual values

Note that, in Aine Language <li> tags inside <condition> tags are 
changed to <k> tags. This makes them easier (and faster) to parse 
by the bot and also make them stand out more when reading the code.

Here are the equivalents in Aine Language:


condition block:
	+[WHAT IS MY GENDER]
	-[<c=gender><k=he>You are a 'he'.</k></c>]

condition single:
	+[WHAT IS MY GENDER]
	-[<c=gender>
		<k=he>You are a 'he'.</k>
		<k=she>You are a 'she'.</k>
	  </c>
	]

condition multiple:
	+[WHAT IS MY GENDER]
	-[	<c=gender>
			<k=he>You are a 'he'.</k>
			<k=she>You are a 'she'.</k>
			<k>I really don't know your gender..</k>
			...
		</c>
		<c=name>
			<k=Richard>You are Richard.</k>
			<k=Alice>You are Alice.</k>
			<k>I don't even know your name...</k>
			...
		</c>
	]

In the Aine Language, block and single conditions use the same
syntax. Condition multiple tags are not exactly the same under
Aine Language as in AIML. Aine Language condition tags cannot be 
nested, so the exact result as above is not possible. But two or more
condition tags can be used in the same response 'template', so 
similar results can still be achieved.

Aine Language also supports 'not equal' comparisons like this:

	+[WHAT IS YOUR NAME?]
	-[<c=botname>
		<k!=Amy>I used to be called Amy, but now I am <g=botname><k>
		<k>My name is Amy, of course.</k>
	  </c>
	]
In the above code, if the name of the bot is set to 'Amy', then
the bot will respond "My name is Amy, of course." If the botname
is *not* Amy, then it will reply: "It used to be Amy, but now I am 
called <g=botname>" (<g=botname> will fill in the current botname)


Using person tags:
------------------
The <person>, <person/>, <person2>, and <personf> tags are exactly 
the same as in AIML.

<person2> XX </person2>	- change XX from 1st to 2nd person
<person> XX </person>	- exchange 1st and 3rd person

<personf> XX </personf> - is the same as <person> XX </person>
except that it formats strings which are passed to websites 
like www.dictionary.com and www.ask.com. The effect is the same
as <person/>, but the formatting inserts an escaped "%20" in
places of the spaces returned by <person/>. These escape 
sequences permit the HTTP GET methods to transmit multiple-word
queries. by substituting all spaces ' ' with '%20'

Shortcut 'person' tags:
<person2/>	- the same as <person2><*></person2>
<person/>	- the same as <person><*></person>
<personf/>	- the same as <personf><*></personf>

+[DEFINE *]
-[<*> means: 
<A HREF="http://www.dictionary.com/cgi-bin/dict.pl?term=<personf/>"> 
<s=it> <person/> </s> 
</A>
<br>

Or as Ask Jeeves says: 
<A HREF="http://www.ask.com/AskJeeves.asp?ask=WHAT%20IS%20A%20<personf/>"> 
<br>
What did you think a <person/> was? 
</A> 
]

Using 'input' and 'that' tags:
------------------------------
ainebot remembers the full text of what the user said and what the 
bot replied for the last several exchanges. It remembers the last
four inputs from the user and the last five responses it made.
Accessing these values lets the bot 'remember' the conversation
it is having with the user.

<input=1>		- what user just said
<input=2>		- what user said before
<input=...up to 4>
<that=1>		- what bot just said (NOT what bot is saying now)
<that=2>		- what bot said before
<that=...up to 5>

This allows for some fancy routines like having the bot ask the
questions and the user gives the answers. This technique can be
used to teach the bot new 'categories'.

+[BAD ANSWER]
-[ <s=badanswer_input><input=2></s>
	<s=badanswer_output><that=2></s>
OK, what should I have said?
]

+[*]<t>\OK, WHAT SHOULD I HAVE SAID?</t>
-[<h><s=badanswer_newresp><input=1></s></h>
OK, I should have said, '<g=badanswer_newresp>' instead of 
'<input=3>' when you said: '<that=2>'?
]


12) Predicate (or variable) naming
--------------------------------------------------------------------
Some of the predicate (or variable) names mentioned above are
built-in predicates which are recognized specifically by the bot.
Two examples are the input=? and that? tags. Usually you should 
avoid *setting* these values from within your *.aine files. Of
course you can *access* and use the values as just shown above.

Here's a list of these built-in predicates:

usesaved_i0, usesaved_i1
inputind1, inputind2, etc., up to inputind5
repeat0, repeat1, etc., up to repeat5
repeat_no

The values for all these get added to the end of the users' defaults
file when the bot is shutdown -in localuser.txt unless the user has
been identified by name.

A way has been shown to manipulate the bots' 'mood' values using
tags which are recognized by the bot. At shutdown, the last values
for each mood 'dimension' is saved to the users personal init file,
or to the file localuser.txt if the user is unknown. The following
tags are used to hold the mood values:
mood_a, mood_v, mood_s

The cgi version uses these additional predicate names:
domain, cookie_path, images_path, referer_check,
image_normal, image_happy, image_sad, image_angry, image_sad_angry

The values for these variables are set in the aine.ini file and
should normally not be tampered with.

The variable 'ip' is also used by the cgi version as a substitute
for the users' name. In other words, the users' name is set to
the IP address from which they have accessed the bot. By default,
this is set to: ip=localhost

The following variables are set in the aine.ini file:
english_lang
auto_punctuate
They can safely be set to other values while the bot is running.

Another group of variables or predicate names are commonly used to
hold traits of the bots' personality or facts about the user. The 
tags for them are not explicitly recognized by the bot internally, 
so it is safe to set or change the values for them from within your
Aine Language code. In fact, that is the only way they can be used.
You can add or remove items from the list if you like, but only the
variables found in the startup file (defvars.txt or log/users/name)
will be re-written to the file when the program shuts down.

See the Section CONFIGURATION FILES in the ainebot.1 man-page for
a more detailed explanation of how and where the startup and 
shutdown values are read and saved.

Here's a list of the default variable names and their values as
used in the standard defvars.txt used by the 'Amy' personality:

botname=Amy
botsign=Capricorn
botgender=female
botfun=I like to make new friends on the internet.
botfriends=Allison
botlocation=Atlanta, GA
botbirthday=1983
botage=20
botbirthplace=Pennsylvania
botboyfriend=David
boteyecolor=blue
botmusic=Pop and Rock.
botband=My favorite group is Queen.
botfood=Pizza.
botcolor=blue
botmovie=Matrix

These values can all be accessed or set/changed by your Aine Language
code using the 'get' and 'set' tags, as below:
<g=botname>		-  bots' name
<g=botmovie>	-  bots favorite movie
<s=name>X</s>		-  sets users' name to X
<s=gender>male</s>	-  sets users' gender to male

Another group of variable names found in the startup defaults file
represent the values of transient variables which can be changed
during the course of 'chatting' with the bot. They are:

it=itself
has=mother
location=where
they=who
he=himself
she=herself
we=us
gender=he

These variables are similar to the input=? and that=? tags in that
they hold temporary values which influence the way the bot responds
to user input. Writing the values to the defaults files when the
program shuts down allows the bot to 'remember' what the user and
the bot were talking about the last time.

--------------------------------------------------------------------
This tutorial is based on the original Mini AIML Tutorial 
by Anthony Taylor, the modifications to it by David Calinski
and the file manual.txt by David Calinski. The current version
by Gilbert Ashley combines the former material and provides
extra explanations and examples.
--------------------------------------------------------------------