Package rivescript :: Module rivescript :: Class RiveScript
[hide private]
[frames] | no frames]

Class RiveScript

source code

A RiveScript interpreter for Python 2 and 3.

Instance Methods [hide private]
 
__init__(self, debug=False, strict=True, depth=50, log='', utf8=False)
Initialize a new RiveScript interpreter.
source code
 
_say(self, message) source code
 
_warn(self, message, fname='', lineno=0) source code
 
load_directory(self, directory, ext=None)
Load RiveScript documents from a directory.
source code
 
load_file(self, filename)
Load and parse a RiveScript document.
source code
 
stream(self, code)
Stream in RiveScript source code dynamically.
source code
 
_parse(self, fname, code)
Parse RiveScript code into memory.
source code
 
check_syntax(self, cmd, line)
Syntax check a RiveScript command and line.
source code
 
deparse(self)
Return the in-memory RiveScript document as a Python data structure.
source code
 
write(self, fh, deparsed=None)
Write the currently parsed RiveScript data into a file.
source code
 
_copy_trigger(self, trig, data, previous=None)
Make copies of all data below a trigger.
source code
 
_write_triggers(self, fh, triggers, indent='')
Write triggers to a file handle.
source code
 
_write_wrapped(self, line, sep=' ', indent='', width=78)
Word-wrap a line of RiveScript code for being written to a file.
source code
 
_initTT(self, toplevel, topic, trigger, what='')
Initialize a Topic Tree data structure.
source code
 
sort_replies(self, thats=False)
Sort the loaded triggers.
source code
 
_sort_that_triggers(self)
Make a sorted list of triggers that correspond to %Previous groups.
source code
 
_sort_trigger_set(self, triggers)
Sort a group of triggers in optimal sorting order.
source code
 
_sort_list(self, name, items)
Sort a simple list by number of words and length.
source code
 
_init_sort_track(self)
Returns a new dict for keeping track of triggers for sorting.
source code
 
set_handler(self, language, obj)
Define a custom language handler for RiveScript objects.
source code
 
set_subroutine(self, name, code)
Define a Python object from your program.
source code
 
set_global(self, name, value)
Set a global variable.
source code
 
set_variable(self, name, value)
Set a bot variable.
source code
 
set_substitution(self, what, rep)
Set a substitution.
source code
 
set_person(self, what, rep)
Set a person substitution.
source code
 
set_uservar(self, user, name, value)
Set a variable for a user.
source code
 
get_uservar(self, user, name)
Get a variable about a user.
source code
 
get_uservars(self, user=None)
Get all variables about a user (or all users).
source code
 
clear_uservars(self, user=None)
Delete all variables about a user (or all users).
source code
 
freeze_uservars(self, user)
Freeze the variable state for a user.
source code
 
thaw_uservars(self, user, action='thaw')
Thaw a user's frozen variables.
source code
 
last_match(self, user)
Get the last trigger matched for the user.
source code
 
trigger_info(self, trigger=None, dump=False)
Get information about a trigger.
source code
 
current_user(self)
Retrieve the user ID of the current user talking to your bot.
source code
 
reply(self, user, msg)
Fetch a reply from the RiveScript brain.
source code
 
_format_message(self, msg, botreply=False)
Format a user's message for safe processing.
source code
 
_getreply(self, user, msg, context='normal', step=0) source code
 
_substitute(self, msg, list)
Run a kind of substitution on a message.
source code
 
_reply_regexp(self, user, regexp)
Prepares a trigger for the regular expression engine.
source code
 
_process_tags(self, user, msg, reply, st=[], bst=[], depth=0)
Post process tags in a message.
source code
 
_string_format(self, msg, method)
Format a string (upper, lower, formal, sentence).
source code
 
_topic_triggers(self, topic, triglvl, depth=0, inheritence=0, inherited=False)
Recursively scan a topic and return a list of all triggers.
source code
 
_find_trigger_by_inheritence(self, topic, trig, depth=0)
Locate the replies for a trigger in an inherited/included topic.
source code
 
_get_topic_tree(self, topic, depth=0)
Given one topic, get the list of all included/inherited topics.
source code
 
_is_atomic(self, trigger)
Determine if a trigger is atomic or not.
source code
 
_word_count(self, trigger, all=False)
Count the words that aren't wildcards in a trigger.
source code
 
_strip_nasties(self, s)
Formats a string for ASCII regex matching.
source code
 
_dump(self)
For debugging, dump the entire data structure.
source code
Class Methods [hide private]
 
VERSION(self=None)
Return the version number of the RiveScript library.
source code
Method Details [hide private]

__init__(self, debug=False, strict=True, depth=50, log='', utf8=False)
(Constructor)

source code 

Initialize a new RiveScript interpreter.

bool debug: Specify a debug mode. bool strict: Strict mode (RS syntax errors are fatal) str log: Specify a log file for debug output to go to (instead of STDOUT). int depth: Specify the recursion depth limit. bool utf8: Enable UTF-8 support.

VERSION(self=None)
Class Method

source code 

Return the version number of the RiveScript library.

This may be called as either a class method of a method of a RiveScript object.

load_directory(self, directory, ext=None)

source code 

Load RiveScript documents from a directory.

Provide `ext` as a list of extensions to search for. The default list is `.rive`, `.rs`

stream(self, code)

source code 

Stream in RiveScript source code dynamically.

`code` should be an array of lines of RiveScript code.

check_syntax(self, cmd, line)

source code 

Syntax check a RiveScript command and line.

Returns a syntax error string on error; None otherwise.

deparse(self)

source code 

Return the in-memory RiveScript document as a Python data structure.

This would be useful for developing a user interface for editing RiveScript replies without having to edit the RiveScript code manually.

write(self, fh, deparsed=None)

source code 

Write the currently parsed RiveScript data into a file.

Pass either a file name (string) or a file handle object.

This uses `deparse()` to dump a representation of the loaded data and writes it to the destination file. If you provide your own data as the `deparsed` argument, it will use that data instead of calling `deparse()` itself. This way you can use `deparse()`, edit the data, and use that to write the RiveScript document (for example, to be used by a user interface for editing RiveScript without writing the code directly).

set_handler(self, language, obj)

source code 
Define a custom language handler for RiveScript objects.

language: The lowercased name of the programming language,
          e.g. python, javascript, perl
obj:      An instance of a class object that provides the following interface:

    class MyObjectHandler:
        def __init__(self):
            pass
        def load(self, name, code):
            # name = the name of the object from the RiveScript code
            # code = the source code of the object
        def call(self, rs, name, fields):
            # rs     = the current RiveScript interpreter object
            # name   = the name of the object being called
            # fields = array of arguments passed to the object
            return reply

Pass in a None value for the object to delete an existing handler (for example,
to prevent Python code from being able to be run by default).

Look in the `eg` folder of the rivescript-python distribution for an example
script that sets up a JavaScript language handler.

set_subroutine(self, name, code)

source code 

Define a Python object from your program.

This is equivalent to having an object defined in the RiveScript code, except your Python code is defining it instead. `name` is the name of the object, and `code` is a Python function (a `def`) that accepts rs,args as its parameters.

This method is only available if there is a Python handler set up (which there is by default, unless you've called set_handler("python", None)).

set_global(self, name, value)

source code 

Set a global variable.

Equivalent to `! global` in RiveScript code. Set to None to delete.

set_variable(self, name, value)

source code 

Set a bot variable.

Equivalent to `! var` in RiveScript code. Set to None to delete.

set_substitution(self, what, rep)

source code 

Set a substitution.

Equivalent to `! sub` in RiveScript code. Set to None to delete.

set_person(self, what, rep)

source code 

Set a person substitution.

Equivalent to `! person` in RiveScript code. Set to None to delete.

get_uservar(self, user, name)

source code 

Get a variable about a user.

If the user has no data at all, returns None. If the user doesn't have a value set for the variable you want, returns the string 'undefined'.

get_uservars(self, user=None)

source code 

Get all variables about a user (or all users).

If no username is passed, returns the entire user database structure. Otherwise, only returns the variables for the given user, or None if none exist.

clear_uservars(self, user=None)

source code 

Delete all variables about a user (or all users).

If no username is passed, deletes all variables about all users. Otherwise, only deletes all variables for the given user.

freeze_uservars(self, user)

source code 

Freeze the variable state for a user.

This will clone and preserve a user's entire variable state, so that it can be restored later with `thaw_uservars`.

thaw_uservars(self, user, action='thaw')

source code 
Thaw a user's frozen variables.

The `action` can be one of the following options:

    discard: Don't restore the user's variables, just delete the frozen copy.
    keep:    Keep the frozen copy after restoring the variables.
    thaw:    Restore the variables, then delete the frozen copy (default).

last_match(self, user)

source code 

Get the last trigger matched for the user.

This will return the raw trigger text that the user's last message matched. If there was no match, this will return None.

trigger_info(self, trigger=None, dump=False)

source code 

Get information about a trigger.

Pass in a raw trigger to find out what file name and line number it appeared at. This is useful for e.g. tracking down the location of the trigger last matched by the user via last_match(). Returns a list of matching triggers, containing their topics, filenames and line numbers. Returns None if there weren't any matches found.

The keys in the trigger info is as follows:

* category: Either 'topic' (for normal) or 'thats' (for %Previous triggers) * topic: The topic name * trigger: The raw trigger text * filename: The filename the trigger was found in. * lineno: The line number the trigger was found on.

Pass in a true value for `dump`, and the entire syntax tracking tree is returned.

current_user(self)

source code 

Retrieve the user ID of the current user talking to your bot.

This is mostly useful inside of a Python object macro to get the user ID of the person who caused the object macro to be invoked (i.e. to set a variable for that user from within the object).

This will return None if used outside of the context of getting a reply (i.e. the value is unset at the end of the `reply()` method).