Documentation ¶
Overview ¶
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/
Index ¶
- Constants
- type RiveScript
- func (self *RiveScript) ClearAllUservars()
- func (self *RiveScript) ClearUservars(username string)
- func (self *RiveScript) CurrentUser() string
- func (self *RiveScript) DeleteSubroutine(name string)
- func (self *RiveScript) DumpSorted()
- func (self *RiveScript) DumpTopics()
- func (self *RiveScript) FreezeUservars(username string) error
- func (self *RiveScript) GetAllUservars() map[string]*sessions.UserData
- func (self *RiveScript) GetDebug() bool
- func (self *RiveScript) GetDepth() uint
- func (self *RiveScript) GetGlobal(name string) (string, error)
- func (self *RiveScript) GetStrict() bool
- func (self *RiveScript) GetUTF8() bool
- func (self *RiveScript) GetUservar(username, name string) (string, error)
- func (self *RiveScript) GetUservars(username string) (*sessions.UserData, error)
- func (self *RiveScript) GetVariable(name string) (string, error)
- func (self *RiveScript) LastMatch(username string) (string, error)
- func (self *RiveScript) LoadDirectory(path string, extensions ...string) error
- func (self *RiveScript) LoadFile(path string) error
- func (self *RiveScript) RemoveHandler(lang string)
- func (self *RiveScript) Reply(username, message string) string
- func (self *RiveScript) SetDebug(value bool)
- func (self *RiveScript) SetDepth(value uint)
- func (self *RiveScript) SetGlobal(name, value string)
- func (self *RiveScript) SetHandler(name string, handler macro.MacroInterface)
- func (self *RiveScript) SetPerson(name, value string)
- func (self *RiveScript) SetStrict(value bool)
- func (self *RiveScript) SetSubroutine(name string, fn rivescript.Subroutine)
- func (self *RiveScript) SetSubstitution(name, value string)
- func (self *RiveScript) SetUTF8(value bool)
- func (self *RiveScript) SetUnicodePunctuation(value string)
- func (self *RiveScript) SetUservar(username, name, value string)
- func (self *RiveScript) SetUservars(username string, data map[string]string)
- func (self *RiveScript) SetVariable(name, value string)
- func (self *RiveScript) SortReplies()
- func (self *RiveScript) Stream(code string) error
- func (self *RiveScript) ThawUservars(username string, action sessions.ThawAction) error
- func (self *RiveScript) Version() string
Examples ¶
Constants ¶
const VERSION string = "0.1.0"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type RiveScript ¶
type RiveScript struct {
// contains filtered or unexported fields
}
Example ¶
bot := rivescript.New(config.Basic()) // Load a directory full of RiveScript documents (.rive files) bot.LoadDirectory("eg/brain") // Load an individual file. bot.LoadFile("testsuite.rive") // 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)
Output:
Example (Javascript) ¶
// Example for configuring the JavaScript object macro handler via Otto. bot := rivescript.New(config.Basic()) // 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)
Output:
Example (Subroutine) ¶
// Example for defining a Go function as an object macro. // import rss "github.com/aichaos/rivescript-go/src" bot := rivescript.New(config.Basic()) // Define an object macro named `setname` bot.SetSubroutine("setname", func(rs *rss.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)
Output:
func New ¶
func New(config *config.Config) *RiveScript
func (*RiveScript) ClearAllUservars ¶
func (self *RiveScript) ClearAllUservars()
ClearAllUservars clears all variables for all users.
func (*RiveScript) ClearUservars ¶
func (self *RiveScript) ClearUservars(username string)
ClearUservars clears all a user's variables.
func (*RiveScript) CurrentUser ¶
func (self *RiveScript) CurrentUser() string
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 ¶
func (self *RiveScript) DeleteSubroutine(name string)
DeleteSubroutine removes a Go object macro.
Parameters
name: The name of the object macro to be deleted.
func (*RiveScript) DumpSorted ¶
func (self *RiveScript) DumpSorted()
DumpSorted is a debug method which dumps the sort tree from the bot's memory.
func (*RiveScript) DumpTopics ¶
func (self *RiveScript) DumpTopics()
DumpTopics is a debug method which dumps the topic structure from the bot's memory.
func (*RiveScript) FreezeUservars ¶
func (self *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 ¶
func (self *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 ¶ added in v0.0.3
func (self *RiveScript) GetDebug() bool
GetDebug tells you the current status of the debug mode.
func (*RiveScript) GetDepth ¶ added in v0.0.3
func (self *RiveScript) GetDepth() uint
GetDepth returns the current recursion depth limit.
func (*RiveScript) GetGlobal ¶ added in v0.0.3
func (self *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 ¶ added in v0.0.3
func (self *RiveScript) GetStrict() bool
GetStrict returns the strict syntax check setting.
func (*RiveScript) GetUTF8 ¶ added in v0.0.3
func (self *RiveScript) GetUTF8() bool
GetUTF8 returns the current status of UTF-8 mode.
func (*RiveScript) GetUservar ¶
func (self *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 ¶
func (self *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 ¶
func (self *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 ¶
func (self *RiveScript) LastMatch(username string) (string, error)
LastMatch returns the user's last matched trigger.
func (*RiveScript) LoadDirectory ¶
func (self *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 ¶
func (self *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 ¶
func (self *RiveScript) RemoveHandler(lang string)
RemoveHandler removes an object macro language handler.
Parameters
lang: The programming language for the handler to remove.
func (*RiveScript) Reply ¶
func (self *RiveScript) Reply(username, message string) string
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 ¶
func (self *RiveScript) SetDebug(value bool)
SetDebug enables or disable debug mode.
func (*RiveScript) SetDepth ¶
func (self *RiveScript) SetDepth(value uint)
SetDepth lets you override the recursion depth limit (default 50).
func (*RiveScript) SetGlobal ¶
func (self *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 ¶
func (self *RiveScript) SetHandler(name 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 ¶
func (self *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 ¶
func (self *RiveScript) SetStrict(value bool)
SetStrict enables strict syntax checking when parsing RiveScript code.
func (*RiveScript) SetSubroutine ¶
func (self *RiveScript) SetSubroutine(name string, fn rivescript.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 ¶
func (self *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 ¶
func (self *RiveScript) SetUTF8(value bool)
SetUTF8 enables or disabled UTF-8 mode.
func (*RiveScript) SetUnicodePunctuation ¶
func (self *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 ¶
func (self *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 ¶
func (self *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 ¶
func (self *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 ¶
func (self *RiveScript) SortReplies()
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!
func (*RiveScript) Stream ¶
func (self *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 ¶
func (self *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.
func (*RiveScript) Version ¶
func (self *RiveScript) Version() string
Version returns the RiveScript library version.
Directories ¶
Path | Synopsis |
---|---|
Package ast defines the Abstract Syntax Tree for RiveScript.
|
Package ast defines the Abstract Syntax Tree for RiveScript. |
cmd
|
|
rivescript
Stand-alone RiveScript Interpreter.
|
Stand-alone RiveScript Interpreter. |
Package config provides the RiveScript configuration type.
|
Package config provides the RiveScript configuration type. |
lang
|
|
javascript
Package javascript implements JavaScript object macros for RiveScript.
|
Package javascript implements JavaScript object macros for RiveScript. |
Package macros exports types relevant to object macros.
|
Package macros exports types relevant to object macros. |
Package parser is a RiveScript language parser.
|
Package parser is a RiveScript language parser. |
Package sessions provides the interface and default session store for RiveScript.
|
Package sessions provides the interface and default session store for RiveScript. |
memory
Package memory provides the default in-memory session store.
|
Package memory provides the default in-memory session store. |
null
Package null provides a session manager that has no memory.
|
Package null provides a session manager that has no memory. |
Package rivescript contains all of the private use functions of RiveScript.
|
Package rivescript contains all of the private use functions of RiveScript. |