AIML 2 RiveScript Converter -- BETA
-----------------------------------

This is a quick 'n' dirty app for converting Alice AIML to RiveScript.
It is intended only for converting "Dr. Wallace's ALICE". It does this
with a high degree (I'd say 90%+) of success, but there's still some
small errors with it.

Tweaks Needed for the AIML:

	Since some of the AIML docs fail validation by XML::Simple, a couple
	of them need to be modded. The cases are when hyperlinks were embedded
	in the template, via CDATA, like this:

		<![CDATA[<a href="something.com">]]>
		...
		<![CDATA[</a>]]>
	
	I fixed this by getting rid of the CDATA blocks, and having the hyperlinks
	be directly in the template. This won't please AIML interpreters, but we
	don't care, we need XML compliency to parse the AIML.

How This Roughly Works:

	To avoid the high complexity of canonicalism, the AIML is first
	translated by Perl so that the contents inside of <pattern>, <template>,
	and <that> are hidden inside of CDATA blocks (this is why the hyperlinks
	above break the XML parsing). Then the data is loaded with XML::Simple.
	The contents of these 3 tags are therefore raw unadultered XML code.

	That code is then run through Perl regular expressions like there's no
	tomorrow, and written to disk as RiveScript files.

	A static begin.rs is also created.

How To Use This:

	Place all your source AIML files into the "aiml" folder, and clear out
	everything in the "rs" folder. Then run the script.

Syntax Checking:

	In some places the regular expressions fail. The result of this is some
	somewhat broken RiveScript code in certain places. For example a reply
	might look like this:

		<set it=<get color>>Tell me more about your favorite color.>
	
	This reply would show up to the user as "Tell me more about your
	favorite color.>" with an extra bracket on the end there.

	I've tried hacking up some regular expressions to cover every edge case
	like this, but I've reached a certain point where introducing extra
	regexps will start causing new problems that weren't there before.

	So, I've created a simple "syntax-check" script, which goes through your
	RS code and counts brackets, and prints line numbers and contents of every
	line that has mismatched brackets. Compared to the over 20,000 triggers
	that AIML has and the countless, countless lines of code, the results that
	"syntax-check" returns is very manageable. You can hand-correct these
	errors on your own.

	To run the script AND do syntax double-checking at the same time, issue
	this handy lil command (in a bash terminal or similar):

		./aiml2rs; ./syntax-check rs/

Syntax Error Correcting:

	I've added the script `syntaxcorrect` which acts just like `syntaxcheck`,
	but it also gives you a prompt to allow you to correct each line it finds
	errors with. You can hit <Return> to accept the line as it is, or retype
	the line. *NOTE* that when you retype the line, you need to retype the
	RiveScript command too. For example if the line with the error is:

		^ <set it=<star>>favorite color>
	
	You need to type literally

		^ <set it=<star> favorite color>
	
	with the ^ at the start of the line.

	After a successful completion of the syntaxcorrect script, the results of
	your answers are saved to "syntaxcorrect.last" -- if you invoke the script
	with the --autofix option, every line with a syntax error that it finds a
	fault with, it will see if this line has been answered in the past by
	looking in syntaxcorrect.last.

	This way if you run aiml2rs and do syntaxcorrect to correct syntax errors,
	your choices are saved to disk. Then if you need to rebuild the RS by
	running aiml2rs again, you can re-run syntaxcorrect with the --autofix
	option and it will automatically fix the errors the same way you did
	before, thus saving lots of time!

	Initial syntax checking:
		./syntaxcorrect rs
	
	Syntax checking with autofix:
		./syntaxcorrect rs --autofix
	
	The file "syntaxcorrect.alice-aiml" is the result of me running
	syntaxcorrect to fix Alice's AIML brain. So if you're just playing with
	aiml2rs for the first time and want to quickly build Alice for RiveScript,
	run these commands:

	./aiml2rs
	cp syntaxcorrect.alice-aiml syntaxcorrect.last
	./syntaxcorrect rs --autofix

	Then the rs/*.rs files should be all ready for loading into a RiveScript
	bot.

	If you are running this on a new AIML set, delete syntaxcorrect.last if
	it exists, and do:

	./aiml2rs
	./syntaxcorrect rs

	answer the prompts, and then (preferably) copy the syntaxcorrect.last file
	to another name (e.g. syntaxcorrect.my-aiml-brain) so you don't need to
	spend time answering prompts in the future; just copy your syntax
	correction file back to "syntaxcorrect.last" and run the script with the
	--autofix option.

Disclaimer:

	This script's purpose in life and intention is only to clone Richard
	Wallace's ALICE brain for RiveScript. Thus all the regular expressions
	that try to cover as many edge cases as possible were programmed with
	ALICE in mind. ALICE is by far the most prominent AIML chatterbot in
	existence next to Amy. I make no guarantees that this script will work
	on Amy's brain or any other AIML set.

	If you write AIML and you wrote your code very cleanly (i.e. not with as
	many errors as ALICE's brain was written), this script should be quite
	successful at reliably converting your code.

	No warranty!

~Casey Kirsle
www.rivescript.com