rivescript-go: github.com/aichaos/rivescript-go Index | Examples | Files | Directories

package rivescript

import "github.com/aichaos/rivescript-go"

Package rivescript implements the RiveScript chatbot scripting language.

About RiveScript

RiveScript is a scripting language for authoring chatbots. It has a very simple syntax and is designed to be easy to read and fast to write.

A simple example of what RiveScript looks like:

+ hello bot
- Hello human.

This matches a user's message of "hello bot" and would reply "Hello human." Or for a slightly more complicated example:

+ my name is *
* <formal> == <bot name> => <set name=<formal>>Wow, we have the same name!
* <get name> != undefined => <set name=<formal>>Did you change your name?
- <set name=<formal>>Nice to meet you, <get name>!

The official website for RiveScript is https://www.rivescript.com/

To test drive RiveScript in your web browser, try the [RiveScript Playground](https://play.rivescript.com/).

Object Macros

A common feature in many RiveScript implementations is the object macro, which enables you to write dynamic program code (in your favorite programming language) to add extra capabilities to your bot. For example, your bot could answer a question of `what is the weather like in _____` by running some code to look up their answer via a web API.

The Go version of RiveScript has support for object macros written in Go (at compile time of your application). It also has optional support for JavaScript object macros using the Otto library.

UTF-8 Support

UTF-8 support in RiveScript is considered an experimental feature. It is disabled by default. Enable it by setting `RiveScript.SetUTF8(true)`.

By default (without UTF-8 mode on), triggers may only contain basic ASCII characters (no foreign characters), and the user's message is stripped of all characters except letters, numbers and spaces. This means that, for example, you can't capture a user's e-mail address in a RiveScript reply, because of the @ and . characters.

When UTF-8 mode is enabled, these restrictions are lifted. Triggers are only limited to not contain certain metacharacters like the backslash, and the user's message is only stripped of backslashes and HTML angled brackets (to protect from obvious XSS if you use RiveScript in a web application). Additionally, common punctuation characters are stripped out, with the default set being `/[.,!?;:]/g`. This can be overridden by providing a new regexp string literal to the `RiveScript.SetUnicodePunctuation` function. Example:

// Make a new bot with UTF-8 mode enabled.
bot := rivescript.New(config.UTF8())

// Override the punctuation characters that get stripped from the
// user's message.
bot.SetUnicodePunctuation(`[.,!?;:]`);

The `<star>` tags in RiveScript will capture the user's "raw" input, so you can write replies to get the user's e-mail address or store foreign characters in their name.

See Also

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

Code:

// Create a new RiveScript instance, which represents an individual bot
// with its own brain and memory of users.
//
// You can provide a rivescript.Config struct to configure the bot and
// provide values that differ from the defaults:
bot := rivescript.New(&rivescript.Config{
    UTF8:  true, // enable UTF-8 mode
    Debug: true, // enable debug mode
})

// Or if you want the default configuration, provide a nil config.
// See the documentation for the rivescript.Config type for information
// on what the defaults are.
bot = rivescript.New(nil)

// Load a directory full of RiveScript documents (.rive files)
bot.LoadDirectory("eg/brain")

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

// Stream in more RiveScript code dynamically from a string.
bot.Stream(`
		+ hello bot
		- Hello, human!
	`)

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

// Get a reply.
reply, _ := bot.Reply("local-user", "Hello, bot!")
fmt.Printf("The bot says: %s", reply)

Index

Examples

Package Files

astmap.go brain.go config.go debug.go deprecated.go doc.go errors.go inheritance.go loading.go parser.go regexp.go rivescript.go sorting.go tags.go utils.go

Constants

const (
    // UNDEFINED is the text "undefined", the default text for variable getters.
    UNDEFINED = "undefined"

    // UNDEFTAG is the "<undef>" tag for unsetting variables in !Definitions.
    UNDEFTAG = "<undef>"
)

Forms of undefined.

const Version = "0.3.0"

Version number for the RiveScript library.

Variables

var (
    ErrDeepRecursion    = errors.New("Deep Recursion Detected")
    ErrRepliesNotSorted = errors.New("Replies Not Sorted")
    ErrNoDefaultTopic   = errors.New("No default topic 'random' was found")
    ErrNoTriggerMatched = errors.New("No Trigger Matched")
    ErrNoReplyFound     = errors.New("The trigger matched but yielded no reply")
)

The types of errors returned by RiveScript.

type Config Uses

type Config struct {
    // Debug enables verbose logging to standard output. Default false.
    Debug bool

    // Strict enables strict syntax checking, where a syntax error in RiveScript
    // code is considered fatal at parse time. Default true.
    Strict bool

    // UTF8 enables UTF-8 mode within the bot. Default false.
    //
    // When UTF-8 mode is enabled, triggers in the RiveScript source files are
    // allowed to contain foreign characters. Additionally, the user's incoming
    // messages are left *mostly* intact, so that they send messages with
    // foreign characters to the bot.
    UTF8 bool

    // Depth controls the global limit for recursive functions within
    // RiveScript. Default 50.
    Depth uint

    // Random number seed, if you'd like to customize it. The default is for
    // RiveScript to choose its own seed, `time.Now().UnixNano()`
    Seed int64

    // SessionManager is an implementation of the same name for managing user
    // variables for the bot. The default is the in-memory session handler.
    SessionManager sessions.SessionManager
}

Config provides options to configure the RiveScript bot.

Create a pointer to this type and send it to the New() constructor to change the default settings. You only need to provide settings you want to override; the zero-values of all the options are handled appropriately by the RiveScript library.

The default values are documented below.

func WithUTF8 Uses

func WithUTF8() *Config

WithUTF8 provides a Config object that enables UTF-8 mode.

type RiveScript Uses

type RiveScript struct {
    // Parameters
    Debug              bool // Debug mode
    Strict             bool // Strictly enforce RiveScript syntax
    Depth              uint // Max depth for recursion
    UTF8               bool // Support UTF-8 RiveScript code
    Quiet              bool // Suppress all warnings from being emitted
    UnicodePunctuation *regexp.Regexp
    // contains filtered or unexported fields
}

RiveScript is the bot instance.

Code:

// Example for configuring the JavaScript object macro handler via Otto.
bot := rivescript.New(nil)

// Create the JS handler.
bot.SetHandler("javascript", javascript.New(bot))

// Now we can use object macros written in JS!
bot.Stream(`
		> object add javascript
			var a = args[0];
			var b = args[1];
			return parseInt(a) + parseInt(b);
		< object

		> object setname javascript
			// Set the user's name via JavaScript
			var uid = rs.CurrentUser();
			rs.SetUservar(uid, args[0], args[1])
		< object

		+ add # and #
		- <star1> + <star2> = <call>add <star1> <star2></call>

		+ my name is *
		- I will remember that.<call>setname <id> <formal></call>

		+ what is my name
		- You are <get name>.
	`)
bot.SortReplies()

reply, _ := bot.Reply("local-user", "Add 5 and 7")
fmt.Printf("Bot: %s\n", reply)

Code:

// Example for defining a Go function as an object macro.
bot := rivescript.New(nil)

// Define an object macro named `setname`
bot.SetSubroutine("setname", func(rs *rivescript.RiveScript, args []string) string {
    uid, _ := rs.CurrentUser()
    rs.SetUservar(uid, args[0], args[1])
    return ""
})

// Stream in some RiveScript code.
bot.Stream(`
		+ my name is *
		- I will remember that.<call>setname <id> <formal></call>

		+ what is my name
		- You are <get name>.
	`)
bot.SortReplies()

bot.Reply("local-user", "my name is bob")
reply, _ := bot.Reply("local-user", "What is my name?")
fmt.Printf("Bot: %s\n", reply)

Code:

// Examples of using UTF-8 mode in RiveScript.
bot := rivescript.New(rivescript.WithUTF8())

bot.Stream(`
		// Without UTF-8 mode enabled, this trigger would be a syntax error
		// for containing non-ASCII characters; but in UTF-8 mode you can use it.
		+ comment ça va
		- ça va bien.
	`)

// Always call SortReplies when you're done loading replies.
bot.SortReplies()

// Without UTF-8 mode enabled, the user's message "comment ça va" would
// have the ç symbol removed; but in UTF-8 mode it's preserved and can
// match the trigger we defined.
reply, _ := bot.Reply("local-user", "Comment ça va?")
fmt.Println(reply) // "ça va bien."

func New Uses

func New(cfg *Config) *RiveScript

New creates a new RiveScript instance.

A RiveScript instance represents one chat bot personality; it has its own replies and its own memory of user data. You could make multiple bots in the same program, each with its own replies loaded from different sources.

func (*RiveScript) ClearAllUservars Uses

func (rs *RiveScript) ClearAllUservars()

ClearAllUservars deletes all variables for all users.

func (*RiveScript) ClearUservars Uses

func (rs *RiveScript) ClearUservars(username string)

ClearUservars deletes all the variables that belong to a user.

func (*RiveScript) CurrentUser Uses

func (rs *RiveScript) CurrentUser() (string, error)

CurrentUser returns the current user's ID.

This is only useful from within an object macro, to get the ID of the user who invoked the macro. This value is set at the beginning of `Reply()` and unset at the end, so this function will return empty outside of a reply context.

func (*RiveScript) DeleteSubroutine Uses

func (rs *RiveScript) DeleteSubroutine(name string)

DeleteSubroutine removes a Go object macro.

Parameters

name: The name of the object macro to be deleted.

func (*RiveScript) DumpSorted Uses

func (rs *RiveScript) DumpSorted()

DumpSorted is a debug method which pretty-prints the sort tree of topics from the bot's memory.

func (*RiveScript) DumpTopics Uses

func (rs *RiveScript) DumpTopics()

DumpTopics is a debug method which pretty-prints the topic tree structure from the bot's memory.

func (*RiveScript) FreezeUservars Uses

func (rs *RiveScript) FreezeUservars(username string) error

FreezeUservars freezes 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()`.

func (*RiveScript) GetAllUservars Uses

func (rs *RiveScript) GetAllUservars() map[string]*sessions.UserData

GetAllUservars gets all the variables for all the users.

This returns a map of username (strings) to `map[string]string` of their variables.

func (*RiveScript) GetDebug Uses

func (rs *RiveScript) GetDebug() bool

GetDebug tells you the current status of the debug mode.

func (*RiveScript) GetDepth Uses

func (rs *RiveScript) GetDepth() uint

GetDepth returns the current recursion depth limit.

func (*RiveScript) GetGlobal Uses

func (rs *RiveScript) GetGlobal(name string) (string, error)

GetGlobal gets a global variable.

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

func (*RiveScript) GetStrict Uses

func (rs *RiveScript) GetStrict() bool

GetStrict returns the strict syntax check setting.

func (*RiveScript) GetUTF8 Uses

func (rs *RiveScript) GetUTF8() bool

GetUTF8 returns the current status of UTF-8 mode.

func (*RiveScript) GetUservar Uses

func (rs *RiveScript) GetUservar(username, name string) (string, error)

GetUservar gets a user variable.

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

func (*RiveScript) GetUservars Uses

func (rs *RiveScript) GetUservars(username string) (*sessions.UserData, error)

GetUservars gets all the variables for a user.

This returns a `map[string]string` containing all the user's variables.

func (*RiveScript) GetVariable Uses

func (rs *RiveScript) GetVariable(name string) (string, error)

GetVariable gets a bot variable.

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

func (*RiveScript) LastMatch Uses

func (rs *RiveScript) LastMatch(username string) (string, error)

LastMatch returns the user's last matched trigger.

func (*RiveScript) LoadDirectory Uses

func (rs *RiveScript) LoadDirectory(path string, extensions ...string) error

LoadDirectory loads multiple RiveScript documents from a folder on disk.

Parameters

path: Path to the directory on disk
extensions...: List of file extensions to filter on, default is
               '.rive' and '.rs'

func (*RiveScript) LoadFile Uses

func (rs *RiveScript) LoadFile(path string) error

LoadFile loads a single RiveScript source file from disk.

Parameters

path: Path to a RiveScript source file.

func (*RiveScript) RemoveHandler Uses

func (rs *RiveScript) RemoveHandler(lang string)

RemoveHandler removes an object macro language handler.

If the handler has already loaded object macros, they will be deleted from the bot along with the handler.

Parameters

lang: The programming language for the handler to remove.

func (*RiveScript) Reply Uses

func (rs *RiveScript) Reply(username, message string) (string, error)

Reply fetches a reply from the bot for a user's message.

Parameters

username: The name of the user requesting a reply.
message: The user's message.

func (*RiveScript) SetDebug Uses

func (rs *RiveScript) SetDebug(value bool)

SetDebug enables or disable debug mode.

func (*RiveScript) SetDepth Uses

func (rs *RiveScript) SetDepth(value uint)

SetDepth lets you override the recursion depth limit (default 50).

func (*RiveScript) SetGlobal Uses

func (rs *RiveScript) SetGlobal(name, value string)

SetGlobal sets a global variable.

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

func (*RiveScript) SetHandler Uses

func (rs *RiveScript) SetHandler(lang string, handler macro.MacroInterface)

SetHandler sets a custom language handler for RiveScript object macros.

Parameters

lang: What your programming language is called, e.g. "javascript"
handler: An implementation of macro.MacroInterface.

func (*RiveScript) SetPerson Uses

func (rs *RiveScript) SetPerson(name, value string)

SetPerson sets a person substitution pattern.

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

func (*RiveScript) SetStrict Uses

func (rs *RiveScript) SetStrict(value bool)

SetStrict enables strict syntax checking when parsing RiveScript code.

func (*RiveScript) SetSubroutine Uses

func (rs *RiveScript) SetSubroutine(name string, fn Subroutine)

SetSubroutine defines a Go object macro from your program.

Parameters

name: The name of your subroutine for the `<call>` tag in RiveScript.
fn: A function with a prototype `func(*RiveScript, []string) string`

func (*RiveScript) SetSubstitution Uses

func (rs *RiveScript) SetSubstitution(name, value string)

SetSubstitution sets a substitution pattern.

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

func (*RiveScript) SetUTF8 Uses

func (rs *RiveScript) SetUTF8(value bool)

SetUTF8 enables or disabled UTF-8 mode.

func (*RiveScript) SetUnicodePunctuation Uses

func (rs *RiveScript) SetUnicodePunctuation(value string)

SetUnicodePunctuation allows you to override the text of the unicode punctuation regexp. Provide a string literal that will validate in `regexp.MustCompile()`

func (*RiveScript) SetUservar Uses

func (rs *RiveScript) SetUservar(username, name, value string)

SetUservar sets a variable for a user.

This is equivalent to `<set>` in RiveScript. Set the value to `undefined` to delete a substitution.

func (*RiveScript) SetUservars Uses

func (rs *RiveScript) SetUservars(username string, data map[string]string)

SetUservars sets a map of variables for a user.

Set multiple user variables by providing a map[string]string of key/value pairs. Equivalent to calling `SetUservar()` for each pair in the map.

func (*RiveScript) SetVariable Uses

func (rs *RiveScript) SetVariable(name, value string)

SetVariable sets a bot variable.

This is equivalent to `! var` in RiveScript. Set the value to `undefined` to delete a bot variable.

func (*RiveScript) SortReplies Uses

func (rs *RiveScript) SortReplies() error

SortReplies sorts the reply structures in memory for optimal matching.

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!

If the bot has loaded no topics, or if it ends up with no sorted triggers at the end, it will return an error saying such. This usually means the bot didn't load any RiveScript code, for example because it looked in the wrong directory.

func (*RiveScript) Stream Uses

func (rs *RiveScript) Stream(code string) error

Stream loads RiveScript code from a text buffer.

Parameters

code: Raw source code of a RiveScript document, with line breaks after
      each line.

func (*RiveScript) ThawUservars Uses

func (rs *RiveScript) ThawUservars(username string, action sessions.ThawAction) error

ThawUservars unfreezes a user's variables.

The `action` can be one of the following: * thaw: Restore the variables and delete the frozen copy. * discard: Don't restore the variables, just delete the frozen copy. * keep: Keep the frozen copy after restoring.

type Subroutine Uses

type Subroutine func(*RiveScript, []string) string

Subroutine is a function prototype for defining custom object macros in Go.

Directories

PathSynopsis
astPackage ast defines the Abstract Syntax Tree for RiveScript.
cmd/rivescriptStand-alone RiveScript Interpreter.
lang/javascriptPackage javascript implements JavaScript object macros for RiveScript.
macroPackage macros exports types relevant to object macros.
parserPackage parser is a RiveScript language parser.
sessionsPackage sessions provides the interface and default session store for RiveScript.
sessions/memoryPackage memory provides the default in-memory session store.
sessions/nullPackage null provides a session manager that has no memory.
sessions/redisPackage redis implements a Redis backed session manager for RiveScript.

Package rivescript imports 16 packages (graph) and is imported by 4 packages. Updated 2018-10-19. Refresh now. Tools for package owners.