Add more documentation, fix up version info

README.md

@@ -8,7 +8,35 @@ This is a RiveScript interpreter library written for the Go programming
 language. RiveScript is a scripting language for chatterbots, making it easy
 to write trigger/response pairs for building up a bot's intelligence.
 
-**This project is currently in Beta status.**
+**This project is currently in Beta status.** The API should be mostly stable
+but things might move around on you.
+
+## 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/).
 
 ## Documentation
 
@@ -75,10 +103,22 @@ func main() {
 }
 ```
 
+## 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.UTF8 = true`.
+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
@@ -91,17 +131,17 @@ 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`
-object as the `RiveScript.UnicodePunctuation` attribute. Example:
+set being `/[.,!?;:]/g`. This can be overridden by providing a new regexp
+string literal to the `RiveScript.SetUnicodePunctuation` function. Example:
 
 ```go
 // Make a new bot with UTF-8 mode enabled.
 bot := rivescript.New()
-bot.UTF8 = true
+bot.SetUTF8(true)
 
 // Override the punctuation characters that get stripped from the
 // user's message.
-bot.UnicodePunctuation = regexp.MustCompile(`[.,!?;:]`)
+bot.SetUnicodePunctuation(`[.,!?;:]`);
 ```
 
 The `<star>` tags in RiveScript will capture the user's "raw" input, so you can

doc.go

@@ -1,10 +1,45 @@
 /*
 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.UTF8 = true`.
+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
@@ -17,16 +52,16 @@ 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`
-object as the `RiveScript.UnicodePunctuation` attribute. Example:
+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()
-	bot.UTF8 = true
+	bot.SetUTF8(true)
 
 	// Override the punctuation characters that get stripped from the
 	// user's message.
-	bot.UnicodePunctuation = regexp.MustCompile(`[.,!?;:]`);
+	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

doc_test.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	rivescript "github.com/aichaos/rivescript-go"
 	js "github.com/aichaos/rivescript-go/lang/javascript"
-	"github.com/aichaos/rivescript-go/src"
+	rss "github.com/aichaos/rivescript-go/src"
 )
 
 func ExampleRiveScript() {
@@ -64,11 +64,12 @@ func ExampleRiveScript_javascript() {
 
 func ExampleRiveScript_subroutine() {
 	// Example for defining a Go function as an object macro.
+	// import rss "github.com/aichaos/rivescript-go/src"
 
 	bot := rivescript.New()
 
 	// Define an object macro named `setname`
-	bot.SetSubroutine("setname", func(rs *src.RiveScript, args []string) string {
+	bot.SetSubroutine("setname", func(rs *rss.RiveScript, args []string) string {
 		uid := rs.CurrentUser()
 		rs.SetUservar(uid, args[0], args[1])
 		return ""

rivescript.go

@@ -17,7 +17,7 @@ import (
 	"github.com/aichaos/rivescript-go/src"
 )
 
-const VERSION = src.VERSION
+const VERSION string = "0.0.3"
 
 type RiveScript struct {
 	rs *src.RiveScript
@@ -29,6 +29,11 @@ func New() *RiveScript {
 	return bot
 }
 
+// Version returns the RiveScript library version.
+func (self *RiveScript) Version() string {
+	return VERSION
+}
+
 // SetDebug enables or disable debug mode.
 func (self *RiveScript) SetDebug(value bool) {
 	self.rs.Debug = value
@@ -350,10 +355,6 @@ func (self *RiveScript) Reply(username, message string) string {
 	return self.rs.Reply(username, message)
 }
 
-func (self *RiveScript) Version() string {
-	return self.rs.Version()
-}
-
 ////////////////////////////////////////////////////////////////////////////////
 ////// Debugging Functions /////////////////////////////////////////////////////
 ////////////////////////////////////////////////////////////////////////////////

src/rivescript.go

@@ -24,10 +24,6 @@ import (
 	"regexp"
 )
 
-const (
-	VERSION string = "0.0.3"
-)
-
 type RiveScript struct {
 	// Parameters
 	Debug              bool // Debug mode
@@ -102,10 +98,6 @@ func New() *RiveScript {
 	return rs
 }
 
-func (rs *RiveScript) Version() string {
-	return VERSION
-}
-
 func (rs *RiveScript) SetDebug(value bool) {
 	rs.Debug = value
 }