RiveScript - Rendering Intelligence Very Easily

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- GENERAL
- LOADING AND PARSING
- CONFIGURATION
- INTERACTION
- INTERNAL

- RIVESCRIPT
- ERROR MESSAGES

- ERR: Deep Recursion Detected!
- ERR: No Reply Matched
- ERR: No Reply Found
- [ERR: Can't Modify Non-Numeric Variable $var]
- [ERR: Math Can't "add" Non-Numeric Value $value]
- [ERR: Can't Divide By Zero]
- [ERR: Object Not Found]

- SEE ALSO
- CHANGES
- AUTHOR
- KEYWORDS
- COPYRIGHT AND LICENSE

# NAME

RiveScript - Rendering Intelligence Very Easily

# SYNOPSIS

      use RiveScript;

      # Create a new RiveScript interpreter.
      my $rs = new RiveScript;

      # Load a directory of replies.
      $rs->loadDirectory ("./replies");

      # Load another file.
      $rs->loadFile ("./more_replies.rs");

      # Stream in some RiveScript code.
      $rs->stream (q~
        + hello bot
        - Hello, human.
      ~);

      # Sort all the loaded replies.
      $rs->sortReplies;

      # Chat with the bot.
      while (1) {
        print "You> ";
        chomp (my $msg = <STDIN>);
        my $reply = $rs->reply ('localuser',$msg);
        print "Bot> $reply\n";
      }

# DESCRIPTION

RiveScript is a simple trigger/response language primarily used for the creation of chatting robots. It's designed to have an easy-to-learn syntax but provide a lot of power and flexibility. For more information, visit http://www.rivescript.com/

# METHODS

## GENERAL

new (ARGS)

  Create a new instance of a RiveScript interpreter. The instance will become its own "chatterbot," with its own set of responses and user variables. You can pass in any global variables here. The two standard variables are:

        debug - Turns on debug mode (a LOT of information will be printed to the
                terminal!). Default is 0 (disabled).
        depth - Determines the recursion depth limit when following a trail of replies
                that point to other replies. Default is 50.

  It's recommended that if you set any other global variables that you do so by calling `setGlobal` or defining it within the RiveScript code. This will avoid the possibility of overriding reserved globals. Currently, these variable names are reserved:

        topics  sorted   sortsthat  thats
        arrays  subs     person     client
        bot     objects  reserved

## LOADING AND PARSING

loadDirectory ($PATH[,@EXTS])

  Load a directory full of RiveScript documents. `$PATH` must be a path to a directory. `@EXTS` is optionally an array containing file extensions, including the dot. By default `@EXTS` is `('.rs')`.

  Returns true on success, false on failure.

loadFile ($PATH)

  Load a single RiveScript document. `$PATH` should be the path to a valid RiveScript file. Returns true on success; false otherwise.

stream ($CODE)

  Stream RiveScript code directly into the module. This is for providing RS code from within the Perl script instead of from an external file. Returns true on success.

sortReplies

  Call this method after loading replies to create an internal sort buffer. This is necessary for trigger matching purposes. If you fail to call this method yourself, RiveScript will call it once when you request a reply. However, it will complain loudly about it.

## CONFIGURATION

setSubroutine ($NAME, $CODEREF)

  Manually create a RiveScript object (a dynamic bit of Perl code that can be provoked in a RiveScript response). `$NAME` should be a single-word, alphanumeric string. `$CODEREF` should be a pointer to a subroutine or an anonymous sub.

setGlobal (%DATA)

  Set one or more global variables, in hash form, where the keys are the variable names and the values are their value. This subroutine will make sure that you don't override any reserved global variables, and warn if that happens.

  This is equivalent to `! global` in RiveScript code.

setVariable (%DATA)

  Set one or more bot variables (things that describe your bot's personality).

  This is equivalent to `! var` in RiveScript code.

setSubstitution (%DATA)

  Set one or more substitution patterns. The keys should be the original word, and the value should be the word to substitute with it.

        $rs->setSubstitution (
          q{what's}  => 'what is',
          q{what're} => 'what are',
        );

  This is equivalent to `! sub` in RiveScript code.

setPerson (%DATA)

  Set a person substitution. This is equivalent to `! person` in RiveScript code.

setUservar ($USER,%DATA)

  Set a variable for a user. `$USER` should be their User ID, and `%DATA` is a hash containing variable/value pairs.

  This is like `<set>` for a specific user.

getUservars ([$USER])

  Get all the variables about a user. If a username is provided, returns a hash reference containing that user's information. Else, a hash reference of all the users and their information is returned.

  This is like `<get>` for a specific user or for all users.

clearUservars ([$USER])

  Clears all variables about `$USER`. If no `$USER` is provided, clears all variables about all users.

## INTERACTION

reply ($USER,$MESSAGE)

  Fetch a response to `$MESSAGE` from user `$USER`. RiveScript will take care of lowercasing, running substitutions, and removing punctuation from the message.

  Returns a response from the RiveScript brain.

## INTERNAL

debug ($MESSAGE) *Internal

  Prints a debug message to the terminal. Called from within in debug mode.

issue ($MESSAGE) *Internal

  Called internally to report an issue (similar to a warning). If debug mode is active, it will print the issue to STDOUT with a # sign prepended. Otherwise, the issue is sent to STDERR via `warn`.

parse ($FILENAME, $CODE) *Internal

  This method is called internally to parse a file or streamed RiveScript code. `$FILENAME` is only there so it can keep internal track of files and line numbers, in case syntax errors appear.

_getreply ($USER,$MSG,%TAGS) *Internal

  Do NOT call this method yourself. This method assumes a few things about the user's input that is taken care of by `reply()`. There is no reason to call this method manually.

_reply_regexp ($USER,$TRIGGER) *Internal

  This method takes a raw trigger `$TRIGGER` and formats it for a matching attempt in a regular expression. It removes `{weight}` tags, processes arrays, processes bot variables and other tags, and returns something ready for the regular expression engine.

processTags ($USER,$MSG,$REPLY,$STARS,$BOTSTARS) *Internal

  Process tags in the bot's response. `$USER` and `$MSG` are the values originally passed to the reply engine. `$REPLY` is the bot's raw response. `$STARS` and `$BOTSTARS` are array references containing any wildcards matched in a trigger or `%Previous` command, respectively. Returns a reply with all the tags processed.

_formatMessage ($STRING) *Internal

  Formats a message to prepare it for reply matching. Lowercases the string, runs substitutions, and sanitizes what's left.

_stringUtil ($TYPE,$STRING) *Internal

  Runs string modifiers on `$STRING` (uppercase, lowercase, sentence, formal).

_personSub ($STRING) *Internal

  Runs person substitutions on `$STRING`.

# RIVESCRIPT

This interpreter tries its best to follow RiveScript standards. Currently it supports RiveScript 2.0 documents. A current copy of the RiveScript working draft is included with this package: see the RiveScript::WD manpage.

# ERROR MESSAGES

Most of the Perl warnings that the module will emit are self-explanatory, and when parsing RiveScript files, file names and line numbers will be given. This section of the manpage instead outlines error strings that may turn up in responses to the bot's queries.

## ERR: Deep Recursion Detected!

The deep recursion depth limit has been reached (a response redirected to a different trigger, which redirected somewhere else, etc.).

How to fix: override the global variable `depth`. This can be done via `setGlobal` or in the RiveScript code:

      ! global depth = 100

## ERR: No Reply Matched

No match was found for the client's message.

How to fix: create a catch-all trigger of just `*`.

      + *
      - I don't know how to reply to that.

## ERR: No Reply Found

A match to the client's message was found, but no response to it was found. This might mean you had a set of conditionals after it, and no `-Reply` to fall back on, and every conditional returned false.

How to fix: make sure you have at least one `-Reply` to every `+Trigger`, even if you don't expect that the `-Reply` will ever be used.

## [ERR: Can't Modify Non-Numeric Variable $var]

You called a math tag on a variable, and the current value of the variable contains something that isn't a number.

How to fix: verify that the variable you're working with is a number. If necessary, reset the variable via `<set>`.

## [ERR: Math Can't "add" Non-Numeric Value $value]

("add" may also be sub, mult, or div). You tried to run a math function on a variable, but the value you used wasn't a number.

How to fix: verify that you're adding, subtracting, multiplying, or dividing using numbers.

## [ERR: Can't Divide By Zero]

A `<div>` tag was found that attempted to divide a variable by zero.

How to fix: make sure your division isn't dividing by zero. If you're using a variable to provide the divisor, validate that the variable isn't zero by using a conditional.

      * <get divisor> == 0 => The divisor is zero so I can't do that.
      - <div myvar=<get divisor>>I divided the variable by <get divisor>.

## [ERR: Object Not Found]

RiveScript attempted to call an object that doesn't exist. This may be because a syntax error in the object prevented Perl from evaluating it, or the object was written in a different programming language.

How to fix: verify that the called object was loaded properly. You will receive notifications on the terminal if the object failed to load for any reason.

# SEE ALSO

the RiveScript::WD manpage - A current snapshot of the Working Draft that defines the standards of RiveScript.

http://www.rivescript.com/ - The official homepage of RiveScript.

# CHANGES

      Version 1.12
      - Initial beta release for a RiveScript 2.00 parser.

# AUTHOR

      Casey Kirsle, http://www.cuvou.com/

# KEYWORDS

bot, chatbot, chatterbot, chatter bot, reply, replies, script, aiml, alpha

# COPYRIGHT AND LICENSE

      RiveScript - Rendering Intelligence Very Easily
      Copyright (C) 2008  Casey Kirsle

      This program is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published by
      the Free Software Foundation; either version 2 of the License, or
      (at your option) any later version.

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      GNU General Public License for more details.

      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA