RiveScript
Methods
RiveScript (hash options)
Create a new RiveScript interpreter. options is a hash:
bool debug: Debug mode (default false)
int depth: Recursion depth limit (default 50)
bool strict: Strict mode (default true)
str debug_div: ID of an element to write debug lines to (optional)
float version ()
Return the version number of the RiveScript.js library.
private void runtime ()
Detect the runtime environment of this module, to determine if we're
running in a web browser or from NodeJS for example.
private void say (string message)
This is the debug function. If debug mode is enabled, the 'message' will be
sent to the console via console.log (if available), or to your debug div if
you defined one.
@param message: A message to add to the debug log.
private void warn (string message)
Print a warning or error message. This is like debug, except it's GOING to be
given to the user one way or another. If the debug div is defined, this is
written to it. If console is defined, the error will be sent there. In a
worst case scenario, an alert box is shown.
int loadFile (string path || array path[, on_success[, on_error]])
Load a RiveScript document from a file. The path can either be a string
that contains the path to a single file, or an array of paths to load
multiple files. on_success is a function to be called when the file(s)
have been successfully loaded. on_error is for catching any errors, such
as syntax errors.
This loading method is asyncronous. You should define an on_success
handler to be called when the file(s) have been successfully loaded.
This method returns the "batch number" for this load attempt. The first
call to this function will have a batch number of 0 and that will go
up from there. This batch number is passed to your on_success handler
as its only argument, in case you want to correlate it with your call
to loadFile.
on_success receives: int batch_count
on_error receives: string error_message
void loadDirectory (string path[, func on_success[, func on_error]])
Load RiveScript documents from a directory.
This function is not supported in a web environment. Only for
NodeJS.
bool stream (string code[, func on_error])
Stream in RiveScript code dynamically. 'code' should be the raw
RiveScript source code as a string (with line breaks after each line).
This function is synchronous, meaning there is no success handler
needed. It will return false on parsing error, true otherwise.
on_error receives: string error_message
private bool parse (string name, string code[, func on_error])
Parse RiveScript code and load it into memory. 'name' is a file name in
case syntax errors need to be pointed out. 'code' is the source code,
and 'on_error' is a function to call when a syntax error occurs.
string checkSyntax (char command, string line)
Check the syntax of a RiveScript command. 'command' is the single
character command symbol, and 'line' is the rest of the line after
the command.
Returns an empty string on success, or a description of the error
on error.
void sortReplies ()
After you have finished loading your RiveScript code, call this method to
populate the various sort buffers. This is absolutely necessary for
reply matching to work efficiently!
void setHandler (string lang, object)
Set a custom language handler for RiveScript objects. See the source for
the built-in JavaScript handler as an example.
@param lang: The lowercased name of the programming language, e.g. perl, python
@param obj: A JavaScript object that has functions named "load" and "call".
Use the undefined value to delete a language handler.
void setSubroutine (string name, function)
Define a JavaScript object from your program.
This is equivalent to having a JS object defined in the RiveScript code, except
your JavaScript code is defining it instead.
void setGlobal (string name, string value)
Set a global variable. This is equivalent to '! global' in RiveScript.
Set the value to undefined to delete a global.
void setVariable (string name, string value)
Set a bot variable. This is equivalent to '! var' in RiveScript.
Set the value to undefined to delete a variable.
void setSubstitution (string name, string value)
Set a substitution. This is equivalent to '! sub' in RiveScript.
Set the value to undefined to delete a substitution.
void setPerson (string name, string value)
Set a person substitution. This is equivalent to '! person' in RiveScript.
Set the value to undefined to delete a substitution.
void setUservar (string user, string name, string value)
Set a user variable for a user.
string getUservar (string user, string name)
Get a variable from a user. Returns the string "undefined" if it isn't
defined.
data getUservars ([string user])
Get all variables about a user. If no user is provided, returns all
data about all users.
void clearUservars ([string user])
Clear all a user's variables. If no user is provided, clears all variables
for all users.
void freezeUservars (string user)
Freeze the variable state of a user. This will clone and preserve the user's
entire variable state, so that it can be restored later with thawUservars().
void thawUservars (string user[, string action])
Thaws a user's frozen variables. The action can be one of the following:
- discard: Don't restore the variables, just delete the frozen copy.
- keep: Keep the frozen copy after restoring.
- thaw: Restore the variables and delete the frozen copy (default)
void lastMatch (string user)
Retrieve the trigger that the user matched most recently.
string reply (string username, string message)
Fetch a reply from the RiveScript brain. The message doesn't require any
special pre-processing to be done to it, i.e. it's allowed to contain
punctuation and weird symbols. The username is arbitrary and is used to
uniquely identify the user, in the case that you may have multiple
distinct users chatting with your bot.