GraphBuilder Class Reference

This is the interface from which all AIML action operations will take place. More...

#include <GraphBuilder.h>

Inheritance diagram for GraphBuilder:

GraphBuilderFramework List of all members.

Public Member Functions

virtual void addCustomTagLibrary (const char *const library)=0 throw (FileNotFoundException &, Exception &)
 Adds a custom AIML tag library which should be a seperate compiled .dll (Windows) or .so (Linux).
virtual void addDirectory (const char *const directory, const char *const regularExpression=".*\\.aiml")=0 throw (IllegalArgumentException &, DirectoryNotFoundException &, Exception &)
 Add entire directory of AIML files to the internal queue for latter processing by GraphBuilder::createGraph().
virtual void addFile (const char *const file)=0 throw (FileNotFoundException &, Exception &)
 Add one AIML file to the internal queue for latter processing by GraphBuilder::createGraph().
virtual void addString (const char *const stringContainingAIML)=0 throw (Exception &)
 Add a string containing AIML to the internal queue for latter processing by GraphBuilder::createGraph().
virtual void createGraph ()=0 throw (XMLErrorException &, Exception &)
 Creates the internal data structures needed to be able to query AIML through GraphBuilder::getResponse().
virtual StringPimpl getBotPredicate (const char *const name) const =0 throw (Exception &)
 Gets a bot predicate inside of the AIML data structure in the same way that a AIML "Bot" tag does.
virtual StringPimpl getId () const =0 throw (Exception &)
 Gets the id the same way the AIML tag "Id" does.
virtual StringPimpl getPredicate (const char *const name) const =0 throw (Exception &)
 Gets a predicate inside of the AIML data structure in the same way that a AIML "Get" tag does.
virtual StringPimpl getPreviousBotResponse (const unsigned int &previousBotResponse, const unsigned int &sentence) const =0 throw (IllegalArgumentException &, Exception &)
 Returns a previous RebeccaAIML response.
virtual StringPimpl getPreviousUserInput (const unsigned int &previousUserInput, const unsigned int &sentence) const =0 throw (IllegalArgumentException &, Exception &)
 Returns a previous RebeccaAIML user input.
virtual StringPimpl getResponse (const char *const input)=0 throw (Exception &)
 Queries the AIML internal in-memory data structures with conversational input and returns the AIML response.
virtual int getSize () const =0 throw (Exception &)
 Returns the number of AIML categories loaded.
virtual StringPimpl getThat () const =0 throw (Exception &)
 This returns the AIML data structure's current that.
virtual StringPimpl getTopic () const =0 throw (Exception &)
 This returns the AIML data structure's current topic.
virtual StringPimpl getVersion () const =0 throw (Exception &)
 Returns the version of rebeccaAIML.
virtual void parsePropertiesFile (const char *const fileName)=0 throw (XMLErrorException &, FileNotFoundException &, Exception &)
 Parses a properties file and calls GraphBuilder::setBotPredicate() for each property encountered.
virtual void parseSentenceSplitterFile (const char *const fileName)=0 throw (XMLErrorException &, FileNotFoundException &, Exception &)
 Parses a sentence splitter file and calls GraphBuilder::setSentenceSplitter() for sentence splitters during run time.
virtual void parseSubstitutionFile (const char *const fileName)=0 throw (XMLErrorException &, FileNotFoundException &, Exception &)
 Parses a substitution file and calls setXXXXSubstitution methods for substitutions during runtime.
virtual bool predicateMatch (const char *const predicateName, const char *const aimlPattern) const =0 throw (Exception &)
 Checks if the predicateName matches the aimlPattern and returns true or false accordingly.
virtual void removeCustomTagLibrary (const char *const library)=0 throw (FileNotFoundException &, Exception &)
 Removes a custom AIML tag library which should be a seprate compiled .dll (Windows) or .so (Linux).
virtual void setAddStringAIMLFooter (const char *const aimlFooter)=0 throw (Exception &)
 Sets the string that is automatically attached to the the end of the string sent to GraphBuilder::addString() to help form a correct XML document in memory.
virtual void setAddStringAIMLHeader (const char *const aimlHeader)=0 throw (Exception &)
 Sets the string that is automatically attached to the the begining of the string sent to GraphBuilder::addString() to help form a correct XML document in memory.
virtual void setAIMLSchema (const char *const schema)=0 throw (Exception &)
 Sets the xsd schema for validating AIML tag files.
virtual void setAIMLValidation (bool trueOrFalse=true)=0 throw (Exception &)
 Sets whether to use AIML validation from the xsd given at GraphBuilder::setAIMLSchema() or not.
virtual void setBotConfigurationSchema (const char *const schema)=0 throw (Exception &)
 Sets the bot configuration schema to be used with parsing a RebeccaAIML configuration file.
virtual void setBotConfigurationValidation (const bool trueOrFalse=true)=0 throw (Exception &)
 Sets XML Validation with the xml schema files from GraphBuilder::setBotConfigurationSchema() and GraphBuilder::setCommonTypesSchema().
virtual void setBotPredicate (const char *const name, const char *const value)=0 throw (Exception &)
 Sets a bot predicate inside of the AIML data structure.
virtual void setCallBacks (CallBacks *callBacks)=0 throw (Exception &)
 Sets the subclass of CallBacks to use for RebeccaAIML callbacks.
virtual void setCommonTypesSchema (const char *const schema)=0 throw (Exception &)
 Sets the common types schema for validating RebeccaAIML configuration files.
virtual void setGenderSubstitution (const char *const find, const char *const replace)=0 throw (IllegalArgumentException &, Exception &)
 Sets a gender substitution for AIML tag "Gender".
virtual void setId (const char *const id)=0 throw (Exception &)
 Sets the id to be returned by the AIML tag "Id".
virtual void setInputSubstitution (const char *const find, const char *const replace)=0 throw (IllegalArgumentException &, Exception &)
 Sets a input substitution for the input that goes into GraphBuilder::getResponse().
virtual void setPerson2Substitution (const char *const find, const char *const replace)=0 throw (IllegalArgumentException &, Exception &)
 Sets a person2 substitution for AIML tag "Person2".
virtual void setPersonSubstitution (const char *const find, const char *const replace)=0 throw (IllegalArgumentException &, Exception &)
 Sets a person substitution for AIML tag "Person".
virtual void setPredicate (const char *const name, const char *const value)=0 throw (Exception &)
 Sets a predicate inside of the AIML data structure in the same way that a AIML "Set" tag does.
virtual void setSentenceSplitter (const char *const splitter)=0 throw (Exception &)
 Adds a sentence splitter to distinguish the end of a sentence.
virtual void setThat (const char *const that)=0 throw (Exception &)
 This allows you to hand set the AIML data structure's current that.
virtual void setTopic (const char *const topic)=0 throw (Exception &)
 This allows you to hand set the AIML data structure's current topic.
virtual void storeGossip (const char *const gossip)=0 throw (Exception &)
 Stores gossip the same way the AIML tag "Gossip" does.
virtual ~GraphBuilder ()
 Empty virtual destructor.

Detailed Description

This is the interface from which all AIML action operations will take place.

This class provides all the operations from loading the AIML tag data from files into memory to querying the AIML data in memory with user input to get back the response.

Use AimlFacade to create the concrete representation of this interface and AimlFacade for getting a handle to this interface. ALWAYS let AimlFacade manage the memory to this interface. Never try to delete this interface directly.

How to use this interface:

Instantiate a AimlFacade object. Call AimlFacade::getGraphBuilder() to get a reference to this interface.

Now, using that reference to this interface:

Create an instance of your CallBacks subclass and call GraphBuilder::setCallBacks() with the address of your subclass. GraphBuilder WILL NOT manage the memory of your CallBacks subclass. You are responsible for managing the memory of your subclass. You can ommit this step if you do not wish to log the AIML gossip tags and if you do not want informative or error handling routines during the load and runtime of RebeccaAIML.

Setup any xsd's for validation of AIML tags through GraphBuilder::setAIMLSchema(). Activate validation by calling GraphBuilder::setAIMLValidation(). Optionally if you are sure that your AIML files are AIML XML compliant/correct you can ommit this step. However, if you do ommit this step and have illegal AIML tags in your files, then the illegal AIML XML tags will cause RebeccaAIML to abort through an exception or crash altogether. Or in C++ terms, the behaviour of RebeccaAIML is undefined.

Bug:
At this time the xsd provided for validation (AIML.xsd) does not validate the AIML tag "Set" properly. Therefore calling GraphBuilder::setAIMLValidation() does nothing other than call CallBacks::XMLParseWarning() with the warning "aiml schema disabled for this version due to incorrect AIML.xsd" and does not allow validation. This should be fixed in the next release, sorry. You will have to make sure your AIML files are correct altogether for the time being.
Setup any xsd's for validation of configuration files for Substitution, Sentence Splitters, and Bot properites. Those methods would be GraphBuilder::setCommonTypesSchema() and GraphBuilder::setBotConfigurationSchema(). The provided xsd's that should be used are bot-configuration.xsd and common-types.xsd. At this time if you use your own custom version, it will result in undefined behavior (a.k.a crashing or exception throwing by Rebecca AIML). Activate both schema's through GraphBuilder::setBotConfigurationValidation().

Parse RebeccaAIML configuration files through the methods GraphBuilder::parseSubstitutionFile(), GraphBuilder::parsePropertiesFile(), and GraphBuilder::parseSentenceSplitterFile() with their respective XML files. Provided sample configuration files are bots.xml, properties.xml, sentence-splitters.xml, and substitutions.xml. Optionally, you can ommit this step or augment it by directly calling GraphBuilder::setSentenceSplitter(), GraphBuilder::setPersonSubstitution(), GraphBuilder::setPerson2Substitution(), GraphBuilder::setGenderSubstitution(), GraphBuilder::setBotPredicate() with the appropriate values.

Call GraphBuilder::setId() to setup the Id to be returned by the AIML tag "Id". If you ommit this step, an empty string for the AIML tag "Id" will always be returned.

Call GraphBuilder::addFile() to add one file at a time or call GraphBuilder::addDirectory() to add an entire directory with AIML tag files.

Call GraphBuilder::createGraph() to begin the parsing of the AIML files which creates the internal data structures.

Call GraphBuilder::getResponse() to query the AIML data structures with input to get RebeccaAIML's bot response back.


Constructor & Destructor Documentation

virtual ~GraphBuilder  )  [inline, virtual]
 

Empty virtual destructor.


Member Function Documentation

virtual void addCustomTagLibrary const char *const   library  )  throw (FileNotFoundException &, Exception &) [pure virtual]
 

Adds a custom AIML tag library which should be a seperate compiled .dll (Windows) or .so (Linux).

The .dll or .so that has the custom AIML tags must conform to the proper format. The proper format is that the .dll/.so should have a class that inherits from CustomTags in it. Also the two global C functions of CustomTags *rebeccaAIMLLoadCustomTags() and rebeccaAIMLRemoveCustomTags(CustomTagsImpl *customTags) must be present. rebeccaAIMLLoadCustomTags returns a new instance of the class that inherits from CustomTags and rebeccaAIMLRemoveCustomTags takes a CustomTags argument and deletes the object. If both of these C functions cannot be found, an exception will be thrown.

Parameters:
library The name of the library without the extension of .dll or .so on the end.
Exceptions:
This will throw a FileNotFoundException if the .dll or .so does not exist on the file system and it will throw a generic Exception if it cannot load the .dll or .so

virtual void addDirectory const char *const   directory,
const char *const   regularExpression = ".*\\.aiml"
throw (IllegalArgumentException &, DirectoryNotFoundException &, Exception &) [pure virtual]
 

Add entire directory of AIML files to the internal queue for latter processing by GraphBuilder::createGraph().

Once all the the files you want to be parsed have been added to the internal queue by GraphBuilder::addFile() and/or GraphBuilder::addDirectory() and/or GraphBuilder::addString(), call GraphBuilder::createGraph() to parse and build the RebeccaAIML in-memory data structures.

Since parsing and building the in-memory data structures is expensive, it's best to keep the functionality for queueing files and the functionality for actually creating the internal data structures seperate for convience.

Both relative and absolute paths are allowed. Although you can use Windows paths it's recommended to only use unix paths to be cross plaform. Windows paths will only work on Windows. Unix paths will work both on unix's and under Windows.

Examples that work under both Unix and Windows:

		   builder.addDirectory("/someDir");
		   builder.addDirectory("../../someDir");
		   

Some examples that only work under Windows.

		   builder.addDirectory("C:\\someDir");
		   builder.addDirectory("C:/someDir");
		   builder.addDirectory("..\\..\\someDir");
		   

Parameters:
directory The AIML directory to add to the internal queue.
regularExpression The regular expression which defines what a AIML file is within the directory. The default is all files which end in ".aiml".
Exceptions:
If the directory is not found, this method will throw a DirectoryNotFoundException. If an underlying method throws an exception, it will be wrapped and thrown as a Exception. If the regular expression is an invalid regular expression, IllegalArgumentException will be thrown.

virtual void addFile const char *const   file  )  throw (FileNotFoundException &, Exception &) [pure virtual]
 

Add one AIML file to the internal queue for latter processing by GraphBuilder::createGraph().

Once all the the files you want to be parsed have been added to the internal queue by GraphBuilder::addFile() and/or GraphBuilder::addDirectory() and/or GraphBuilder::addString(), call GraphBuilder::createGraph() to parse and build the RebeccaAIML in-memory data structures.

Since parsing and building the in-memory data structures is expensive, it's best to keep the functionality for queueing files and the functionality for actually creating the internal data structures seperate for convience.

Both relative and absolute paths are allowed. Although you can use Windows paths it's recommended to only use unix paths to be cross plaform. Windows paths will only work on Windows. Unix paths will work both on unix's and under Windows.

Examples that work under both Unix and Windows:

		   builder.addFile("/someDir/someFile.aiml");
		   builder.addFile("../../someDir/someFile.aiml");
		   

Some examples that only work under Windows.

		   builder.addFile("C:\\someDir\\someFile.aiml");
		   builder.addFile("C:/someDir/someFile.aiml");
		   builder.addFile("..\\..\\someDir\\someFile.aiml");
		   

Parameters:
file The AIML file to add to the internal queue.
Exceptions:
If the file is not found, this method will throw a FileNotFoundException. If an underlying method throws an exception, it will be wrapped and thrown as a Exception.

virtual void addString const char *const   stringContainingAIML  )  throw (Exception &) [pure virtual]
 

Add a string containing AIML to the internal queue for latter processing by GraphBuilder::createGraph().

Once all the the files you want to be parsed have been added to the internal queue by GraphBuilder::addFile() and/or GraphBuilder::addDirectory() and/or GraphBuilder::addString(), call GraphBuilder::createGraph() to parse and build the RebeccaAIML in-memory data structures.

Since parsing and building the in-memory data structures is expensive, it's best to keep the functionality for queueing files and the functionality for actually creating the internal data structures seperate for convience.

A quick example would be:

           builder.addString
           (
             "<category>"
             "<pattern>test aiml string</pattern>"
             "<template>it simply works!</template>"
             "</category>"
           );
		 

By default a AIML Header attached to the begining of your string is:

         <?xml version="1.0" encoding="ISO-8859-1"?>
         <aiml version="1.0.1" xmlns="http://alicebot.org/2001/AIML-1.0.1"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://alicebot.org/2001/AIML-1.0.1 http://aitools.org/aiml/schema/AIML.xsd">
	     

and a AIML Footer attached to the end of your string is:

		 </aiml>
		 

These are automatically attached to the begining and end of your string for you to form a correct XML document in memory. If you want to change either of these two values use GraphBuilder::setAddStringAIMLHeader() and GraphBuilder::setAddStringAIMLFooter()

Parameters:
stringContainingAIML The string that contains the AIML to add to the internal queue.
Exceptions:
If an underlying method throws an exception, it will be wrapped and thrown as a Exception.

virtual void createGraph  )  throw (XMLErrorException &, Exception &) [pure virtual]
 

Creates the internal data structures needed to be able to query AIML through GraphBuilder::getResponse().

After files from GraphBuilder::addFile() and/or GraphBuilder::addDirectory() are queued and other RebeccaAIML setups have taken place this method should be called to create the internal data structures needed to perform an AIML query.

Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception. Also, a possible XMLErrorException can occur through either illegal AIML tags or through a bad initialization of the internal XML engine.

virtual StringPimpl getBotPredicate const char *const   name  )  const throw (Exception &) [pure virtual]
 

Gets a bot predicate inside of the AIML data structure in the same way that a AIML "Bot" tag does.

This method is called usually whenever the AIML tag "Bot" is encountered to retrieve a predicate name's value, but it is exposed here so that the user of RebeccaAIML api may also get predicates the same way.

Parameters:
name The name of the predicate to get the value of from the AIML data structure.
Returns:
Returns the value of the predicate's name or empty string if the predicate name does not exist in the AIML data structure.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getId  )  const throw (Exception &) [pure virtual]
 

Gets the id the same way the AIML tag "Id" does.

This will return the Id set by GraphBuilder::setId(). If GraphBuilder::setId has not been called, then this will return an empty string.

Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getPredicate const char *const   name  )  const throw (Exception &) [pure virtual]
 

Gets a predicate inside of the AIML data structure in the same way that a AIML "Get" tag does.

This method is called usually whenever the AIML tag "Get" is encountered to retrieve a predicate name's value, but it is exposed here so that the user of RebeccaAIML api may also get predicates the same way.

Parameters:
name The name of the predicate to get the value of from the AIML data structure.
Returns:
Returns the value of the predicate's name or empty string if the predicate name does not exist in the AIML data structure.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getPreviousBotResponse const unsigned int &  previousBotResponse,
const unsigned int &  sentence
const throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Returns a previous RebeccaAIML response.

Retrives a previous RebeccaAIML bot response returned from GraphBuilder::getResponse(). Useful for debugging or informative purposes, or to put other AI logic besides just using AIML tags.

Parameters:
previousBotResponse The index of the previous Bot Response to retrieve.
sentence Which sentence of the previous bot response to retrieve.
Returns:
Returns the pervious Bot Response.
Exceptions:
Throws a IllegalArgumentException if the previousBotResponse or sentence is out of range. If an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getPreviousUserInput const unsigned int &  previousUserInput,
const unsigned int &  sentence
const throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Returns a previous RebeccaAIML user input.

Retrives a previous RebeccaAIML user input fed as an argument into GraphBuilder::getResponse(). Useful for debugging or informative purposes, or to put other AI logic besides just using AIML tags.

Parameters:
previousUserInput The index of the previous user input to retrieve.
sentence Which sentence of the previous user input to retrieve.
Returns:
Returns the pervious user input.
Exceptions:
Throws a IllegalArgumentException if the previous user input or sentence is out of range. If an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getResponse const char *const   input  )  throw (Exception &) [pure virtual]
 

Queries the AIML internal in-memory data structures with conversational input and returns the AIML response.

This is the method which ultimatly you want to call after setup to query the AIML brain/data structure and get back a response.

Parameters:
input The human conversational input seperated by the sentence splitters you setup from either from configuration file or GraphBuilder::setSentenceSplitter().
Returns:
Returns the AIML response to the human conversation.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual int getSize  )  const throw (Exception &) [pure virtual]
 

Returns the number of AIML categories loaded.

Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getThat  )  const throw (Exception &) [pure virtual]
 

This returns the AIML data structure's current that.

This is a more advanced feature that not a lot of people will find useful. It returns the AIML data structure's current internal that. However, this is provided in case you want to do testing or get the internal that yourself for debugging purposes.

Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getTopic  )  const throw (Exception &) [pure virtual]
 

This returns the AIML data structure's current topic.

This is a more advanced feature that not a lot of people will find useful. returns the AIML data structure's current internal topic. However, this is provided in case you want to do testing or get the internal that yourself for debugging purposes.

Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual StringPimpl getVersion  )  const throw (Exception &) [pure virtual]
 

Returns the version of rebeccaAIML.

Returns:
The version of rebeccaAIML.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void parsePropertiesFile const char *const   fileName  )  throw (XMLErrorException &, FileNotFoundException &, Exception &) [pure virtual]
 

Parses a properties file and calls GraphBuilder::setBotPredicate() for each property encountered.

Look at the sample xml file properties.xml and the xsd bot-configuration.xsd for an idea of how to write bot properties configuration files. More than likely you'll want to just use the sample xml file provided. Feel free to add to it for your own custom bot properties to it.

Under the covers, as the xml engine parses the bot properties xml file, it calls GraphBuilder::setBotPredicate() for each property it finds.

Parameters:
fileName The name of the bot property file.
Exceptions:
This will throw an XMLErrorException if an XML error is encountered. It will throw a FileNotFoundException if the fileName given is incorrect, and it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void parseSentenceSplitterFile const char *const   fileName  )  throw (XMLErrorException &, FileNotFoundException &, Exception &) [pure virtual]
 

Parses a sentence splitter file and calls GraphBuilder::setSentenceSplitter() for sentence splitters during run time.

Look at the sample xml file sentence-splitters.xml and the xsd bot-configuration.xsd for an idea of how to write sentence splitter configuration files. More than likely you'll want to just use the sample xml file provided. Feel free to add to it for your own custom sentence splitters to it.

Under the covers, as the xml engine parses the sentence splitter xml file, it calls GraphBuilder::setSentenceSplitter() for each sentence splitter it finds.

Parameters:
fileName The name of the sentence splitter file.
Exceptions:
This will throw an XMLErrorException if an XML error is encountered. It will throw a FileNotFoundException if the fileName given is incorrect, and it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void parseSubstitutionFile const char *const   fileName  )  throw (XMLErrorException &, FileNotFoundException &, Exception &) [pure virtual]
 

Parses a substitution file and calls setXXXXSubstitution methods for substitutions during runtime.

Look at the sample xml file substitutions.xml and the xsd bot-configuration.xsd for an idea of how to write substitution files. More than likely you'll want to just use the sample xml file provided. Feel free to add to it for your own custom substitutions.

Under the covers, as the xml engine parses the substitution xml file and calls GraphBuilder::setInputSubstitution(), GraphBuilder::setGenderSubstitution(), GraphBuilder::setPersonSubstitution(), and GraphBuilder::setPerson2Substitution() based upon the start tags inside of the xml file.

Parameters:
fileName The name of the substitution file.
Exceptions:
This will throw an XMLErrorException if an XML error is encountered. It will throw a FileNotFoundException if the fileName given is incorrect, and it will throw an Exception for any underlying exceptions from other methods it might call.

virtual bool predicateMatch const char *const   predicateName,
const char *const   aimlPattern
const throw (Exception &) [pure virtual]
 

Checks if the predicateName matches the aimlPattern and returns true or false accordingly.

This is mostly for just debugging purposes for the user to check against condition AIML tags since, internally, the condition AIML tags use this same method when encountered at runtime during a GraphBuilder::getResponse().

Parameters:
predicateName The variable name to check a AIML pattern against.
aimlPattern The AIML pattern to check against variable name to see if the two match.
Returns:
Returns true if the AIML pattern matches the predicateName otherwise returns false.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void removeCustomTagLibrary const char *const   library  )  throw (FileNotFoundException &, Exception &) [pure virtual]
 

Removes a custom AIML tag library which should be a seprate compiled .dll (Windows) or .so (Linux).

The .dll or .so that has the custom AIML tags must conform to the proper format. The proper format is that the .dll/.so should have a class that inherits from CustomTags in it. Also the two global C functions of CustomTags *rebeccaAIMLLoadCustomTags() and rebeccaAIMLRemoveCustomTags(CustomTagsImpl *customTags) must be present. rebeccaAIMLLoadCustomTags returns a new instance of the class that inherits from CustomTags and rebeccaAIMLRemoveCustomTags takes a CustomTags argument and deletes the object. If both of these C functions cannot be found, an exception will be thrown.

Parameters:
library The name of the library without the extension of .dll or .so on the end.
Exceptions:
This will throw a FileNotFoundException if the .dll or .so was never loaded in the first place. It will throw a generic Exception if it cannot unload the .dll or .so

virtual void setAddStringAIMLFooter const char *const   aimlFooter  )  throw (Exception &) [pure virtual]
 

Sets the string that is automatically attached to the the end of the string sent to GraphBuilder::addString() to help form a correct XML document in memory.

The default string set when Rebecca starts is:

		 </aiml>
		 
Parameters:
aimlFooter The string to change which is automatically attached to the end of the string sent to GraphBuilder::addString()
Exceptions:
If an underlying method throws an exception, it will be wrapped and thrown as a Exception.

virtual void setAddStringAIMLHeader const char *const   aimlHeader  )  throw (Exception &) [pure virtual]
 

Sets the string that is automatically attached to the the begining of the string sent to GraphBuilder::addString() to help form a correct XML document in memory.

The default string set when Rebecca starts is:

         <?xml version="1.0" encoding="ISO-8859-1"?>
         <aiml version="1.0.1" xmlns="http://alicebot.org/2001/AIML-1.0.1"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://alicebot.org/2001/AIML-1.0.1 http://aitools.org/aiml/schema/AIML.xsd">
	     

Parameters:
aimlHeader The string to change which is automatically attached to the begining of the string sent to GraphBuilder::addString()
Exceptions:
If an underlying method throws an exception, it will be wrapped and thrown as a Exception.

virtual void setAIMLSchema const char *const   schema  )  throw (Exception &) [pure virtual]
 

Sets the xsd schema for validating AIML tag files.

Parameters:
schema The xsd schema for validating AIML tag files. The schema path has to be relative to where the files you are going to parse are going to be located at. Use the unix "/" as the path seperator and not "\".
Exceptions:
Will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setAIMLValidation bool  trueOrFalse = true  )  throw (Exception &) [pure virtual]
 

Sets whether to use AIML validation from the xsd given at GraphBuilder::setAIMLSchema() or not.

By default if this is not called, then the AIML validation will not be used even if GraphBuilder::setAIMLSchema() has been called with a valid xsd.

Parameters:
trueOrFalse By default true. Set this to true to use validation and false to not use validation.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setBotConfigurationSchema const char *const   schema  )  throw (Exception &) [pure virtual]
 

Sets the bot configuration schema to be used with parsing a RebeccaAIML configuration file.

This should be used in conjunction with GraphBuilder::setCommonTypesSchema() and one of the parseConfiguration methods of: GraphBuilder::parseSubstitutionFile(), GraphBuilder::parsePropertiesFile(), and GraphBuilder::parseSentenceSplitterFile() with their respective XML files. Provided sample configuration files are bots.xml, properties.xml, sentence-splitters.xml, and substitutions.xml.

Parameters:
schema The schema for validating RebeccaAIML configuration files. The schema path has to be relative to where the files you are going to parse are going to be located at. Use unix "/" as the path seperator and not "\".
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setBotConfigurationValidation const bool  trueOrFalse = true  )  throw (Exception &) [pure virtual]
 

Sets XML Validation with the xml schema files from GraphBuilder::setBotConfigurationSchema() and GraphBuilder::setCommonTypesSchema().

By default if this is not called, then the validation will not be used even if GraphBuilder::setBotConfigurationSchema() and GraphBuilder::setCommonTypesSchema() has been called with a valid xsd.

Parameters:
trueOrFalse True to turn on validation and false to turn off validation.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setBotPredicate const char *const   name,
const char *const   value
throw (Exception &) [pure virtual]
 

Sets a bot predicate inside of the AIML data structure.

This is the only means to set a bot Predicate so that during a GraphBuilder::getResponse() the "Bot" AIML tag returns the predicate set here. After this method is called setting up a new predicate with a value, any AIML "Bot" tags latter encountered querying the predicate name will return the value which was set here.

Parameters:
name The name of the predicate to put into the AIML data structure.
value The value of the predicate name to put into the AIML data structure.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setCallBacks CallBacks callBacks  )  throw (Exception &) [pure virtual]
 

Sets the subclass of CallBacks to use for RebeccaAIML callbacks.

SubClass CallBacks with your own custom subclass and then instantiate it. Call this method with the address of your instantiated class. This method *WILL NOT* try to deallocate the memory of your instantiated subcalss. You are responsbile for the memory management of it.

Parameters:
callBacks The adress of the instantiation of your subclass.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setCommonTypesSchema const char *const   schema  )  throw (Exception &) [pure virtual]
 

Sets the common types schema for validating RebeccaAIML configuration files.

This has to be set in conjuction with GraphBuilder::setBotConfigurationSchema.

Parameters:
schema The schema for validating RebeccaAIML configuration files. The schema path has to be relative to where the files you are going to parse are going to be located at. Use unix "/" as the path seperator and not "\".
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setGenderSubstitution const char *const   find,
const char *const   replace
throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Sets a gender substitution for AIML tag "Gender".

Gender AIML tag is to replace all occurances of one gender with that of another. So, this provided method allows the gender substiutions to be set. None are hardcoded internally for the "Gender" AIML tag. A simple example to use this would be:

setGenderSubstitution("he", "she");

Now, when the gender tag is encountered it will replace all occurances of "he" with "she".

Take note that the first argument to this method accepts regular expressions which make this method more robust. For example, it is more robust to use the word boundary "\b" as in:

setGenderSubstitution("\bhe\b", "she");

Now, "he" will only be substituted for "she" when there is a white space character on each side.

Parameters:
find A regular expression to search for inside of the "Gender" AIML tag.
replace The text to replace with. This is NOT a regular expression.
Exceptions:
IllegalArgumentException will be thrown if the first argument is a illegal regular expression. it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void setId const char *const   id  )  throw (Exception &) [pure virtual]
 

Sets the id to be returned by the AIML tag "Id".

Set this to what you want the AIML tag "Id" to return. If you do not se this, the AIML tag "Id" will just return an empty string.

Parameters:
id The id to set for the AIML tag "Id"
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setInputSubstitution const char *const   find,
const char *const   replace
throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Sets a input substitution for the input that goes into GraphBuilder::getResponse().

Substitutions are good so as to not write duplicate AIML. A simple example would be:

setInputSubstitution("it's", "it is");

Now, if the input is:

GraphBuilder::getResponse("It's a great day");

The input will be substituted internally for "It is a great day". Take note that the first argument to this method accepts regular expressions which make this method more robust. For example, it is more robust to use the word boundary "\b" as in:

setInputSubstitution("\bit's\b", "it is");

Now, "it's" will only be substituted for "it is" when there is a white space character on each side.

See GraphBuilder::parseSubstitutionFile(), a convience method for parsing a provided substitution file.

Parameters:
find A regular expression to search for in the input of GraphBuilder::getResponse().
replace The text to replace with. This is NOT a regular expression.
Exceptions:
IllegalArgumentException will be thrown if the first argument is a illegal regular expression. it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void setPerson2Substitution const char *const   find,
const char *const   replace
throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Sets a person2 substitution for AIML tag "Person2".

From the AIML specification:

The "Person2" AIML tag is to replace words with first-person aspect in the result of processing the contents of the person2 element with words with the grammatically-corresponding second-person aspect; and replace words with second-person aspect in the result of processing the contents of the person2 element with words with the grammatically-corresponding first-person aspect.

A simple example to use this would be:

setPersonSubstitution("with you ", "with me");

Now when the "Person2" tag is encountered it will replace all occurances of "with you" with "with me".

Take note that the first argument to this method accepts regular expressions which make this method more robust. For example, it is more robust to use the word boundary "\b" as in:

setGenderSubstitution("\bwith you\b", "with me");

Now, "with you" will only be substituted for "with me" when there is a white space character on each side.

Parameters:
find A regular expression to search for inside of the "Person2" AIML tag.
replace The text to replace with. This is NOT a regular expression.
Exceptions:
IllegalArgumentException will be thrown if the first argument is a illegal regular expression. it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void setPersonSubstitution const char *const   find,
const char *const   replace
throw (IllegalArgumentException &, Exception &) [pure virtual]
 

Sets a person substitution for AIML tag "Person".

From the AIML specification:

The "Person" AIML tag is to replace words with first-person aspect in the result of processing the contents of the person element with words with the grammatically-corresponding third-person aspect; and replace words with third-person aspect in the result of processing the contents of the person element with words with the grammatically-corresponding first-person aspect.

A simple example to use this would be:

setPersonSubstitution("he was ", "I was");

Now when the "Person" tag is encountered it will replace all occurances of "he was" with "I was".

Take note that the first argument to this method accepts regular expressions which make this method more robust. For example, it is more robust to use the word boundary "\b" as in:

setGenderSubstitution("\bhe was\b", "I was");

Now, "he was" will only be substituted for "I was" when there is a white space character on each side.

Parameters:
find A regular expression to search for inside of the "Person" AIML tag.
replace The text to replace with. This is NOT a regular expression.
Exceptions:
IllegalArgumentException will be thrown if the first argument is a illegal regular expression. it will throw an Exception for any underlying exceptions from other methods it might call.

virtual void setPredicate const char *const   name,
const char *const   value
throw (Exception &) [pure virtual]
 

Sets a predicate inside of the AIML data structure in the same way that a AIML "Set" tag does.

This method is called usually whenever the AIML tag "Set" is encountered to set a predicate to a value, but it is exposed here so that the user of RebeccaAIML api may also set predicates the same way. After this method is called setting up a new predicate with a value, any AIML "Get" tags latter encountered querying the predicate name will return the value which was set here.

Parameters:
name The name of the predicate to put into the AIML data structure.
value The value of the predicate name to put into the AIML data structure.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setSentenceSplitter const char *const   splitter  )  throw (Exception &) [pure virtual]
 

Adds a sentence splitter to distinguish the end of a sentence.

Each time this is called with a character or string, that character or string is added as a sentence splitter. Sentence splitters are used internally to distinguish the end of a sentence. See GraphBuilder::parseSentenceSplitterFile() for a convience method for parsing an example sentence splitter file provided.

Parameters:
splitter The character or string to be added as a splitter.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setThat const char *const   that  )  throw (Exception &) [pure virtual]
 

This allows you to hand set the AIML data structure's current that.

This is a more advanced feature that not a lot of people will find useful. It sets the internal that which is done automatically by RebeccaAiml. However, this is provided in case you want to do testing or set the internal that yourself.

Parameters:
that The internal AIML that in which you can set yourself if you really want to.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void setTopic const char *const   topic  )  throw (Exception &) [pure virtual]
 

This allows you to hand set the AIML data structure's current topic.

This is a more advanced feature that not a lot of people will find useful. It sets the internal topic which is done automatically by RebeccaAiml. However, this is provided in case you want to do testing or set the internal topic yourself.

Parameters:
topic The internal AIML topic in which you can set yourself if you really want to.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.

virtual void storeGossip const char *const   gossip  )  throw (Exception &) [pure virtual]
 

Stores gossip the same way the AIML tag "Gossip" does.

This under the covers will just call the callback CallBacks::storeGossip(). If no callback is set through GraphBuilder::setCallBacks() this does nothing.

Parameters:
gossip The textual gossip to store.
Exceptions:
This will not directly throw an exception but if an underlying method throws an exception, it will be wrapped and thrown as an Exception.


The documentation for this class was generated from the following file:
Generated on Mon Apr 10 00:39:45 2006 for RebeccaAIML by  doxygen 1.4.5