com.rivescript

Class RiveScript

java.lang.Object

com.rivescript.RiveScript

public class RiveScript
extends java.lang.Object

A RiveScript interpreter written in Java.

Usage:

 
 import com.rivescript.Config;
 import com.rivescript.RiveScript;

 // Create a new bot with the default settings.
 RiveScript bot = new RiveScript();

 // To enable UTF-8 mode, you'd have initialized the bot like:
 RiveScript bot = new RiveScript(Config.utf8());

 // Load a directory full of RiveScript documents (.rive files)
 bot.loadDirectory("./replies");

 // Load an individual file.
 bot.LoadFile("./testsuite.rive");

 // Sort the replies after loading them!
 bot.sortReplies();

 // Get a reply.
 String reply = bot.reply("user", "Hello bot!");
 
 

Author:

Noah Petherbridge, Marcel Overdijk

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CANNOT_DIVIDE_BY_ZERO_KEY
static java.lang.String	CANNOT_MATH_VALUE_KEY
static java.lang.String	CANNOT_MATH_VARIABLE_KEY
static java.lang.String	DEEP_RECURSION_KEY
static java.lang.String	DEFAULT_CANNOT_DIVIDE_BY_ZERO_MESSAGE
static java.lang.String	DEFAULT_CANNOT_MATH_VALUE_MESSAGE
static java.lang.String	DEFAULT_CANNOT_MATH_VARIABLE_MESSAGE
static java.lang.String	DEFAULT_DEEP_RECURSION_MESSAGE
static java.lang.String	DEFAULT_DEFAULT_TOPIC_NOT_FOUND_MESSAGE
static java.lang.String[]	DEFAULT_FILE_EXTENSIONS
static java.lang.String	DEFAULT_OBJECT_NOT_FOUND_MESSAGE
static java.lang.String	DEFAULT_REPLIES_NOT_SORTED_MESSAGE
static java.lang.String	DEFAULT_REPLY_NOT_FOUND_MESSAGE
static java.lang.String	DEFAULT_REPLY_NOT_MATCHED_MESSAGE
static java.lang.String	DEFAULT_TOPIC_NOT_FOUND_KEY
static java.lang.String	OBJECT_NOT_FOUND_KEY
static java.lang.String	REPLIES_NOT_SORTED_KEY
static java.lang.String	REPLY_NOT_FOUND_KEY
static java.lang.String	REPLY_NOT_MATCHED_KEY
static java.lang.String	UNDEFINED

Constructor Summary

Constructors

Constructor and Description
RiveScript() Creates a new RiveScript interpreter.
RiveScript(Config config) Creates a new RiveScript interpreter with the given Config.

Method Summary

Modifier and Type	Method and Description
void	clearAllUservars() Clears all variables for all users.
void	clearUservars(java.lang.String username) Clears a user's variables.
java.lang.String	currentUser() Returns the current user's ID.
void	dumpSorted() Dumps the trigger sort buffers to the standard output stream.
void	dumpTopics() Dumps the entire topic/trigger/reply structure to the standard output stream.
void	freezeUservars(java.lang.String username) Makes a snapshot of a user's variables.
int	getDepth() Returns the recursion depth limit.
java.util.Map<java.lang.String,java.lang.String>	getErrorMessages() Returns the error messages (unmodifiable).
java.lang.String	getGlobal(java.lang.String name) Returns a global variable.
java.util.Map<java.lang.String,ObjectHandler>	getHandlers() Returns the object macro language handlers (unmodifiable).
java.lang.String	getPerson(java.lang.String name) Returns a person substitution pattern.
java.util.Map<java.lang.String,Subroutine>	getSubroutines() Returns the Java object macros (unmodifiable).
java.lang.String	getSubstitution(java.lang.String name) Returns a substitution pattern.
java.lang.String	getUnicodePunctuation() Returns the unicode punctuation pattern.
java.lang.String	getUservar(java.lang.String username, java.lang.String name) Returns a user variable.
UserData	getUservars(java.lang.String username) Returns all variables for a user.
java.lang.String	getVariable(java.lang.String name) Returns a bot variable.
static java.lang.String	getVersion() Returns the RiveScript library version, or null if it cannot be determined.
boolean	isForceCase() Returns whether forcing triggers to lowercase is enabled.
boolean	isStrict() Returns whether strict syntax checking is enabled.
boolean	isThrowExceptions() Returns whether exception throwing is enabled.
boolean	isUtf8() Returns whether UTF-8 mode is enabled for user messages and triggers.
java.lang.String	lastMatch(java.lang.String username) Returns a user's last matched trigger.
void	loadDirectory(java.io.File directory, java.lang.String... extensions) Loads multiple RiveScript documents from a directory on disk.
void	loadDirectory(java.lang.String path, java.lang.String... extensions) Loads multiple RiveScript documents from a directory on disk.
void	loadFile(java.io.File file) Loads a single RiveScript document from disk.
void	loadFile(java.lang.String path) Loads a single RiveScript document from disk.
void	removeHandler(java.lang.String name) Removes an object macro language handler.
void	removeSubroutine(java.lang.String name) Removes a Java object macro.
java.lang.String	reply(java.lang.String username, java.lang.String message) Returns a reply from the bot for a user's message.
void	setGlobal(java.lang.String name, java.lang.String value) Sets a global variable.
void	setHandler(java.lang.String name, ObjectHandler handler) Sets a custom language handler for RiveScript object macros.
void	setPerson(java.lang.String name, java.lang.String value) Sets a person substitution pattern.
void	setSubroutine(java.lang.String name, Subroutine subroutine) Defines a Java object macro.
void	setSubstitution(java.lang.String name, java.lang.String value) Sets a substitution pattern.
void	setUservar(java.lang.String username, java.lang.String name, java.lang.String value) Sets a user variable.
void	setUservars(java.lang.String username, java.util.Map<java.lang.String,java.lang.String> vars) Set a user's variables.
void	setVariable(java.lang.String name, java.lang.String value) Sets a bot variable.
void	sortReplies() Sorts the reply structures in memory for optimal matching.
void	stream(java.lang.String code) Loads RiveScript source code from a text buffer, with line breaks after each line.
void	stream(java.lang.String[] code) Loads RiveScript source code from a String array, one line per item.
void	thawUservars(java.lang.String username, ThawAction action) Unfreezes a user's variables.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEEP_RECURSION_KEY

public static final java.lang.String DEEP_RECURSION_KEY

See Also:

Constant Field Values

REPLIES_NOT_SORTED_KEY

public static final java.lang.String REPLIES_NOT_SORTED_KEY

See Also:

Constant Field Values

DEFAULT_TOPIC_NOT_FOUND_KEY

public static final java.lang.String DEFAULT_TOPIC_NOT_FOUND_KEY

See Also:

Constant Field Values

REPLY_NOT_MATCHED_KEY

public static final java.lang.String REPLY_NOT_MATCHED_KEY

See Also:

Constant Field Values

REPLY_NOT_FOUND_KEY

public static final java.lang.String REPLY_NOT_FOUND_KEY

See Also:

Constant Field Values

OBJECT_NOT_FOUND_KEY

public static final java.lang.String OBJECT_NOT_FOUND_KEY

See Also:

Constant Field Values

CANNOT_DIVIDE_BY_ZERO_KEY

public static final java.lang.String CANNOT_DIVIDE_BY_ZERO_KEY

See Also:

Constant Field Values

CANNOT_MATH_VARIABLE_KEY

public static final java.lang.String CANNOT_MATH_VARIABLE_KEY

See Also:

Constant Field Values

CANNOT_MATH_VALUE_KEY

public static final java.lang.String CANNOT_MATH_VALUE_KEY

See Also:

Constant Field Values

DEFAULT_DEEP_RECURSION_MESSAGE

public static final java.lang.String DEFAULT_DEEP_RECURSION_MESSAGE

See Also:

Constant Field Values

DEFAULT_REPLIES_NOT_SORTED_MESSAGE

public static final java.lang.String DEFAULT_REPLIES_NOT_SORTED_MESSAGE

See Also:

Constant Field Values

DEFAULT_DEFAULT_TOPIC_NOT_FOUND_MESSAGE

public static final java.lang.String DEFAULT_DEFAULT_TOPIC_NOT_FOUND_MESSAGE

See Also:

Constant Field Values

DEFAULT_REPLY_NOT_MATCHED_MESSAGE

public static final java.lang.String DEFAULT_REPLY_NOT_MATCHED_MESSAGE

See Also:

Constant Field Values

DEFAULT_REPLY_NOT_FOUND_MESSAGE

public static final java.lang.String DEFAULT_REPLY_NOT_FOUND_MESSAGE

See Also:

Constant Field Values

DEFAULT_OBJECT_NOT_FOUND_MESSAGE

public static final java.lang.String DEFAULT_OBJECT_NOT_FOUND_MESSAGE

See Also:

Constant Field Values

DEFAULT_CANNOT_DIVIDE_BY_ZERO_MESSAGE

public static final java.lang.String DEFAULT_CANNOT_DIVIDE_BY_ZERO_MESSAGE

See Also:

Constant Field Values

DEFAULT_CANNOT_MATH_VARIABLE_MESSAGE

public static final java.lang.String DEFAULT_CANNOT_MATH_VARIABLE_MESSAGE

See Also:

Constant Field Values

DEFAULT_CANNOT_MATH_VALUE_MESSAGE

public static final java.lang.String DEFAULT_CANNOT_MATH_VALUE_MESSAGE

See Also:

Constant Field Values

UNDEFINED

public static final java.lang.String UNDEFINED

See Also:

Constant Field Values

DEFAULT_FILE_EXTENSIONS

public static final java.lang.String[] DEFAULT_FILE_EXTENSIONS

Constructor Detail

RiveScript

public RiveScript()

Creates a new RiveScript interpreter.

RiveScript

public RiveScript(Config config)

Creates a new RiveScript interpreter with the given Config.

Parameters:

config - the config

Method Detail

getVersion

public static java.lang.String getVersion()

Returns the RiveScript library version, or null if it cannot be determined.

Returns:

the version

See Also:

Package.getImplementationVersion()

isThrowExceptions

public boolean isThrowExceptions()

Returns whether exception throwing is enabled.

Returns:

whether exception throwing is enabled

isStrict

public boolean isStrict()

Returns whether strict syntax checking is enabled.

Returns:

whether strict syntax checking is enabled

isUtf8

public boolean isUtf8()

Returns whether UTF-8 mode is enabled for user messages and triggers.

Returns:

whether UTF-8 mode is enabled for user messages and triggers

isForceCase

public boolean isForceCase()

Returns whether forcing triggers to lowercase is enabled.

Returns:

whether forcing triggers to lowercase is enabled

getDepth

public int getDepth()

Returns the recursion depth limit.

Returns:

the recursion depth limit

getUnicodePunctuation

public java.lang.String getUnicodePunctuation()

Returns the unicode punctuation pattern.

Returns:

the unicode punctuation pattern

getErrorMessages

public java.util.Map<java.lang.String,java.lang.String> getErrorMessages()

Returns the error messages (unmodifiable).

Returns:

the error messages

setHandler

public void setHandler(java.lang.String name,
                       ObjectHandler handler)

Sets a custom language handler for RiveScript object macros.

Parameters:

name - the name of the programming language

handler - the implementation

removeHandler

public void removeHandler(java.lang.String name)

Removes an object macro language handler.

Parameters:

name - the name of the programming language

getHandlers

public java.util.Map<java.lang.String,ObjectHandler> getHandlers()

Returns the object macro language handlers (unmodifiable). .

Returns:

the object macro language handlers

setSubroutine

public void setSubroutine(java.lang.String name,
                          Subroutine subroutine)

Defines a Java object macro.

Because Java is a compiled language, this method must be used to create an object macro written in Java.

Parameters:

name - the name of the object macro for the `` tag

subroutine - the subroutine

removeSubroutine

public void removeSubroutine(java.lang.String name)

Removes a Java object macro.

Parameters:

name - the name of the object macro

getSubroutines

public java.util.Map<java.lang.String,Subroutine> getSubroutines()

Returns the Java object macros (unmodifiable).

Returns:

the Java object macros

setGlobal

public void setGlobal(java.lang.String name,
                      java.lang.String value)

Sets a global variable.

This is equivalent to ! global in RiveScript. Set the value to null to delete a global.

Parameters:

name - the variable name

value - the variable value or null

getGlobal

public java.lang.String getGlobal(java.lang.String name)

Returns a global variable.

This is equivalent to <env> in RiveScript. Returns null if the variable isn't defined.

Parameters:

name - the variable name

Returns:

the variable value or null

setVariable

public void setVariable(java.lang.String name,
                        java.lang.String value)

Sets a bot variable.

This is equivalent to ! vars in RiveScript. Set the value to null to delete a bot variable.

Parameters:

name - the variable name

value - the variable value or null

getVariable

public java.lang.String getVariable(java.lang.String name)

Returns a bot variable.

This is equivalent to <bot> in RiveScript. Returns null if the variable isn't defined.

Parameters:

name - the variable name

Returns:

the variable value or null

setSubstitution

public void setSubstitution(java.lang.String name,
                            java.lang.String value)

Sets a substitution pattern.

This is equivalent to ! sub in RiveScript. Set the value to null to delete a substitution.

Parameters:

name - the substitution name

value - the substitution pattern or null

getSubstitution

public java.lang.String getSubstitution(java.lang.String name)

Returns a substitution pattern.

Returns null if the substitution isn't defined.

Parameters:

name - the substitution name

Returns:

the substitution pattern or null

setPerson

public void setPerson(java.lang.String name,
                      java.lang.String value)

Sets a person substitution pattern.

This is equivalent to ! person in RiveScript. Set the value to null to delete a person substitution.

Parameters:

name - the person substitution name

value - the person substitution pattern or null

getPerson

public java.lang.String getPerson(java.lang.String name)

Returns a person substitution pattern.

This is equivalent to <person> in RiveScript. Returns null if the person substitution isn't defined.

Parameters:

name - the person substitution name

Returns:

the person substitution pattern or null

loadFile

public void loadFile(java.io.File file)
              throws RiveScriptException,
                     ParserException

Loads a single RiveScript document from disk.

Parameters:

file - the RiveScript file

Throws:

RiveScriptException - in case of a loading error

ParserException - in case of a parsing error

loadFile

public void loadFile(java.lang.String path)
              throws RiveScriptException,
                     ParserException

Loads a single RiveScript document from disk.

Parameters:

path - the path to the RiveScript document

Throws:

RiveScriptException - in case of a loading error

ParserException - in case of a parsing error

loadDirectory

public void loadDirectory(java.io.File directory,
                          java.lang.String... extensions)
                   throws RiveScriptException,
                          ParserException

Loads multiple RiveScript documents from a directory on disk.

Parameters:

directory - the directory containing the RiveScript documents

Throws:

RiveScriptException - in case of a loading error

ParserException - in case of a parsing error

loadDirectory

public void loadDirectory(java.lang.String path,
                          java.lang.String... extensions)
                   throws RiveScriptException,
                          ParserException

Loads multiple RiveScript documents from a directory on disk.

Parameters:

path - The path to the directory containing the RiveScript documents

Throws:

RiveScriptException - in case of a loading error

ParserException - in case of a parsing error

stream

public void stream(java.lang.String code)
            throws ParserException

Loads RiveScript source code from a text buffer, with line breaks after each line.

Parameters:

code - the RiveScript source code

Throws:

ParserException - in case of a parsing error

stream

public void stream(java.lang.String[] code)
            throws ParserException

Loads RiveScript source code from a String array, one line per item.

Parameters:

code - the lines of RiveScript source code

Throws:

ParserException - in case of a parsing error

sortReplies

public void sortReplies()

Sorts the reply structures in memory for optimal matching.

After finishing loading the RiveScript code, this method needs to be called to populate the various sort buffers. This is absolutely necessary for reply matching to work efficiently!

reply

public java.lang.String reply(java.lang.String username,
                              java.lang.String message)
                       throws RiveScriptException

Returns a reply from the bot for a user's message.

In case of an exception and exception throwing is enabled a RiveScriptException is thrown. Check the subclasses to see which types exceptions can be thrown.

Parameters:

username - the username

message - the user's message

Returns:

the reply

Throws:

RiveScriptException - in case of an exception and exception throwing is enabled

setUservar

public void setUservar(java.lang.String username,
                       java.lang.String name,
                       java.lang.String value)

Sets a user variable.

This is equivalent to <set> in RiveScript. Set the value to null to delete a user variable.

Parameters:

username - the username

name - the variable name

value - the variable value

setUservars

public void setUservars(java.lang.String username,
                        java.util.Map<java.lang.String,java.lang.String> vars)

Set a user's variables.

Set multiple user variables by providing a Map of key/value pairs. Equivalent to calling setUservar(String, String, String) for each pair in the map.

Parameters:

username - the name

vars - the user variables

getUservar

public java.lang.String getUservar(java.lang.String username,
                                   java.lang.String name)

Returns a user variable.

This is equivalent to <get name> in RiveScript. Returns null if the variable isn't defined.

Parameters:

username - the username

name - the variable name

Returns:

the variable value

getUservars

public UserData getUservars(java.lang.String username)

Returns all variables for a user.

Parameters:

username - the username

Returns:

the variables

clearAllUservars

public void clearAllUservars()

Clears all variables for all users.

clearUservars

public void clearUservars(java.lang.String username)

Clears a user's variables.

Parameters:

username - the username

freezeUservars

public void freezeUservars(java.lang.String username)

Makes a snapshot of a user's variables.

Parameters:

username - the username

thawUservars

public void thawUservars(java.lang.String username,
                         ThawAction action)

Unfreezes a user's variables.

Parameters:

username - the username

action - the thaw action

See Also:

ThawAction

lastMatch

public java.lang.String lastMatch(java.lang.String username)

Returns a user's last matched trigger.

Parameters:

username - the username

Returns:

the last matched trigger

currentUser

public java.lang.String currentUser()

Returns the current user's ID.

This is only useful from within a (Java) object macro, to get the ID of the user who invoked the macro. This value is set at the beginning of reply(String, String) and unset at the end, so this method will return null outside of a reply context.

Returns:

the user's ID or null

dumpSorted

public void dumpSorted()

Dumps the trigger sort buffers to the standard output stream.

dumpTopics

public void dumpTopics()

Dumps the entire topic/trigger/reply structure to the standard output stream.