Skip to content

Commit c6f8be5

Browse files
author
Marcel Overdijk
committed
Refactorings for 0.8.0 release; Separate parser, AST model, session manager, unicode support, bugfixes, revamped README and more.
1 parent 6483456 commit c6f8be5

70 files changed

Lines changed: 6658 additions & 3401 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Changes.md‎

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,63 @@
1-
# Revision History for RiveScript-Java
1+
# Change History
22

3-
* 0.7.2 January 17 2017
3+
This documents the history of significant changes to `rivescript-java`.
4+
5+
## v0.8.0 - February 14, 2017
6+
7+
This update focuses on new features and huge code refactoring / reorganization.
8+
The `rivescript-java` implementations has been aligned with the `rivescript-go`
9+
implementation.
10+
11+
* **API Breaking Changes:**
12+
* Removed `RiveScript(boolean debug)` constructor in favour of
13+
`RiveScript(Config config)` constructor .
14+
* The `RiveScript` instance has no notion of `debug` mode anymore.
15+
Debug logging is now based on the SLF4J configuration.
16+
* Refactored `com.rivescript.ObjectMacro` to `com.rivescript.macro.Subroutine`.
17+
* Renamed `ObjectHandler` methods from `onLoad`, `onCall` to respectively
18+
`load` and `call`. Also the `setClass` method has been removed.
19+
* The `org.json` dependency is now a optional dependency.
20+
Developers using Perl object macros must include this `org.json` dependency
21+
manually to their projects.
22+
23+
* **Changes:**
24+
* Replace `System.out` logging by using the SLF4J API.
25+
* Add Unicode support (#30, #31).
26+
* Add new forceCase config option, which will force-lowercase your triggers
27+
during parse time, enabling authors to use uppercase letters in triggers
28+
without it being a syntax error. Do note however that Unicode case folding
29+
can become an issue with certain symbols.
30+
* Add customizable error messages config option.
31+
* Add throw exceptions config option, which will make the bot throw (runtime)
32+
exceptions (e.g. `DeepRecursionException`, `ReplyNotFoundException`)
33+
in case of an error instead of just replying with an error message.
34+
When enabled, developers should catch these exceptions and take the
35+
appropriate actions.
36+
* The `RiveScript` constructor now accepts a `Config` object to configure
37+
the RiveScript instance. Also a developer `Config.Builder` is available.
38+
* Add support for pluggable session stores for user variables. The default
39+
one still keeps user variables in memory, but you can specify your own
40+
implementation instead (#33).
41+
* Add RiveScript shell to quickly demo and test a RiveScript bot.
42+
See `com.rivescript.cmd.Shell`.
43+
* Separated the `Parser` which can now be used independently.
44+
The parser returns a Abstract Syntax Tree (AST) identical to the
45+
`rivescript-go` parser. It enables third party developers to write
46+
applications that simply parse RiveScript code and getting an AST from it.
47+
* Add option to load RiveScript source code from a `java.io.File` or
48+
`java.nio.file.Path`.
49+
* Fix for sorting %Previous triggers (#9).
50+
51+
## v0.7.2 - January 17, 2017
52+
53+
* **Changes:**
454
* Fix to make the `RiveScript` thread safe using a a `ThreadLocal` to store
555
the current user. (#18).
656
* Add support for escaping `_` (underscores) in triggers.
757

8-
* 0.7.1 January 9 2017
58+
## v0.7.1 - January 9, 2017
59+
60+
* **Changes:**
961
* Fix for arrays in replies (e.g. `(@greek)`) not being converted to
1062
randomized sets (bug #26).
1163
* Fix trigger regexp processing so that if a `{weight}` tag contains a
@@ -19,11 +71,15 @@
1971
* Fix for moving the no-{inherits} triggers to the bottom of the stack
2072
when sorting the triggers (#8).
2173

22-
* 0.7.0 December 22 2016
74+
## v0.7.0 - December 22, 2016
75+
76+
* **Changes:**
2377
* Refactored project setup to allow separate module.
2478
* Switched to Gradle as build tool.
2579

26-
* 0.6.0 June 28 2016
80+
## v0.6.0 - June 28, 2016
81+
82+
* **Changes:**
2783
* Switched to semantic versioning; `com.rivescript.RiveScript.VERSION` is now
2884
a string `"0.6.0"` instead of a floating point number.
2985
* Add support for Java object macros (compile-time) via the new API
@@ -52,5 +108,6 @@
52108
topic inherited other topics, but didn't include other topics. The code
53109
was checking for inheritance but looping over includes.
54110

55-
* 0.03 Nov 26 2014
56-
* Initial official beta release.
111+
## v0.03-beta - Nov 26, 2014
112+
113+
* Initial official beta release.

‎README.md‎

Lines changed: 156 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,173 @@
1-
# Java RiveScript Interpreter
1+
# RiveScript-Java
22

33
[![Gitter](https://badges.gitter.im/aichaos/rivescript-java.svg)](https://gitter.im/aichaos/rivescript-java?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
44
[![Build Status](https://travis-ci.org/aichaos/rivescript-java.svg?branch=master)](https://travis-ci.org/aichaos/rivescript-java)
55
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.rivescript/rivescript-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.rivescript/rivescript-core)
66
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
77

8-
This is a Java implementation of a RiveScript interpreter, per the Working Draft
9-
at http://www.rivescript.com/wd/RiveScript.html
8+
## Introduction
109

11-
This is *BETA QUALITY SOFTWARE* and hasn't been field tested as much as some of
12-
the other RiveScript libraries in other languages.
10+
This is a RiveScript interpreter library written for the Java programming
11+
language. RiveScript is a scripting language for chatterbots, making it easy
12+
to write trigger/response pairs for building up a bot's intelligence.
1313

14-
It is feature complete syntax-wise: it supports all of the RiveScript directives
15-
and tags, but it doesn't natively support any dynamic language for object macros.
16-
You can define object macros in Java at compile-time, and there's an example
17-
that bridges Perl code; long-term plans include building in native support for
18-
JavaScript.
14+
**This project is currently in Beta status.** The API should be mostly stable
15+
but things might move around on you.
1916

20-
This repository is a little bit light on examples; most of the examples for how
21-
to do things are found in the source of `RSBot.java` and the RiveScript files
22-
in the `Aiden/` directory. These demonstrate things like Java object macros,
23-
using the Perl macro bridge, etc.
17+
## About RiveScript
2418

25-
If you find a way to crash this library, please tell me how you did it so I can
26-
improve this library!
19+
RiveScript is a scripting language for authoring chatbots. It has a very
20+
simple syntax and is designed to be easy to read and fast to write.
2721

28-
Contributions are welcome. See `CONTRIBUTING.md` for more information.
22+
A simple example of what RiveScript looks like:
23+
24+
```
25+
+ hello bot
26+
- Hello human.
27+
```
28+
29+
This matches a user's message of "hello bot" and would reply "Hello human."
30+
Or for a slightly more complicated example:
31+
32+
```
33+
+ my name is *
34+
* <formal> == <bot name> => <set name=<formal>>Wow, we have the same name!
35+
* <get name> != undefined => <set name=<formal>>Did you change your name?
36+
- <set name=<formal>>Nice to meet you, <get name>!
37+
```
38+
39+
The official website for RiveScript is https://www.rivescript.com/
40+
41+
To test drive RiveScript in your web browser, try the
42+
[RiveScript Playground](https://play.rivescript.com/).
2943

3044
## Documentation
3145

32-
Documentation is available at <https://www.rivescript.com/docs/java/>
46+
API Documentation is available at <http://www.javadoc.io/doc/com.rivescript/rivescript-core/>
3347

3448
Also check out the [**RiveScript Community Wiki**](https://github.com/aichaos/rivescript/wiki)
3549
for common design patterns and tips & tricks for RiveScript.
3650

37-
## Building from Source
51+
## Installation
52+
53+
Add the `rivescript-core` dependency to your project:
54+
55+
_Maven_:
56+
57+
```xml
58+
<dependency>
59+
<groupId>com.rivescript.</groupId>
60+
<artifactId>rivescript-core</artifactId>
61+
<version>0.8.0</version>
62+
</dependency>
63+
```
64+
65+
_Gradle_:
66+
67+
```groovy
68+
dependencies {
69+
compile "com.rivescript:rivescript-core:0.8.0"
70+
}
71+
```
72+
73+
## Usage
74+
75+
When used as a library for writing your own chatbot, the synopsis is as follows:
76+
77+
```java
78+
import com.rivescript.Config;
79+
import com.rivescript.RiveScript;
80+
81+
// Create a new bot with the default settings.
82+
RiveScript bot = new RiveScript();
83+
84+
// To enable UTF-8 mode, you'd have initialized the bot like:
85+
RiveScript bot = new RiveScript(Config.utf8());
86+
87+
// Load a directory full of RiveScript documents (.rive files)
88+
bot.loadDirectory("./replies");
89+
90+
// Load an individual file.
91+
bot.LoadFile("./testsuite.rive");
92+
93+
// Sort the replies after loading them!
94+
bot.sortReplies();
95+
96+
// Get a reply.
97+
String reply = bot.reply("user", "Hello bot!");
98+
```
99+
100+
The `rivescript-core` distribution also includes an interactive shell for testing your
101+
RiveScript bot. Run it with the path to a folder on disk that contains your
102+
RiveScript documents. Example:
103+
104+
java com.rivescript.cmd.Shell [options] </path/to/documents>
105+
106+
## Configuration
107+
108+
The `com.rivescript.RiveScript` constructor takes an optional `Config` instance.
109+
Here is a full example with all the supported options. You only need to provide
110+
values for configuration options that are different to the defaults.
111+
112+
```java
113+
RiveScript bot = new RiveScript(Config.newBuilder()
114+
.throwExceptions(false) // Whether exception throwing is enabled
115+
.strict(true) // Whether strict syntax checking is enabled
116+
.utf8(false) // Whether UTF-8 mode is enabled
117+
.unicodePunctuation("[.,!?;:]") // The unicode punctuation pattern
118+
.forceCase(false) // Whether forcing triggers to lowercase is enabled
119+
.depth(50) // The recursion depth limit
120+
.sessionManager(sessionManager) // The session manager for user variables
121+
.errorMessages(errors) // Map of custom error messages
122+
.build());
123+
```
124+
125+
For convenience, you can use shortcuts:
126+
127+
```java
128+
// The default constructor uses a basic configuration.
129+
RiveScript bot = new RiveScript();
130+
131+
// This is similar as:
132+
RiveScript bot = new RiveScript(Config.basic());
133+
134+
// To use the basic configuration with UTF-8 mode enabled use:
135+
RiveScript bot = new RiveScript(Config.utf8());
136+
```
137+
138+
## UTF-8 Support
139+
140+
UTF-8 support in RiveScript is considered an experimental feature. It is
141+
disabled by default.
142+
143+
By default (without UTF-8 mode on), triggers may only contain basic ASCII
144+
characters (no foreign characters), and the user's message is stripped of all
145+
characters except letters, numbers and spaces. This means that, for example,
146+
you can't capture a user's e-mail address in a RiveScript reply, because of
147+
the @ and . characters.
148+
149+
When UTF-8 mode is enabled, these restrictions are lifted. Triggers are only
150+
limited to not contain certain metacharacters like the backslash, and the
151+
user's message is only stripped of backslashes and HTML angled brackets
152+
(to protect from obvious XSS if you use RiveScript in a web application).
153+
Additionally, common punctuation characters are stripped out, with the default
154+
set being `[.,!?;:]`. This can be overridden by providing a new regexp
155+
string to the `Config.Builder#unicodePunctuation()` method. Example:
156+
157+
```java
158+
// Make a new bot with UTF-8 mode enabled and override the punctuation
159+
characters that get stripped from the user's message.
160+
RiveScript bot = new RiveScript(Config.Builder
161+
.utf8()
162+
.unicodePunctuation("[.,!?;:]")
163+
.build());
164+
```
165+
166+
The `<star>` tags in RiveScript will capture the user's "raw" input, so you can
167+
write replies to get the user's e-mail address or store foreign characters in
168+
their name.
169+
170+
## Building
38171
39172
To compile, test, build all jars and docs run:
40173
@@ -56,18 +189,15 @@ These commands may be used at your input prompt in RSBot:
56189
/dump sorted - Dump the internal trigger sort buffers (debugging)
57190
/last - Print the last trigger you matched.
58191
59-
## Quickstart
60-
61192
To execute `RSBot` to begin chatting with the demo Eliza-based bot that
62193
tends to ship with RiveScript libraries run:
63194
64-
./gradlew :rivescript-samples-rsbot:runApp --console plain
65-
66-
## Unit Testing
195+
./gradlew :rivescript-samples-rsbot:runBot --console plain
67196
68-
This library is tested using [JUnit](http://junit.org/). To execute the test suite run:
197+
## Authors
69198
70-
./gradlew clean test
199+
* Noah Petherbridge, https://www.kirsle.net/
200+
* Marcel Overdijk, https://twitter.com/marceloverdijk
71201
72202
## License
73203
@@ -94,7 +224,3 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
94224
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
95225
SOFTWARE.
96226
```
97-
98-
## AUTHOR
99-
100-
Noah Petherbridge, https://www.kirsle.net/

‎TODO‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎build.gradle‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,11 @@ buildscript {
77
}
88

99
ext {
10-
junitVersion = "4.12"
11-
jsonVersion = "20160810"
12-
mockitoVersion = "1.10.19"
10+
hamcrestVersion = "1.3"
11+
junitVersion = "4.12"
12+
jsonVersion = "20160810"
13+
mockitoVersion = "1.10.19"
14+
slf4jVersion = "1.7.22"
1315
ext.javadocLinks = [
1416
"http://docs.oracle.com/javase/7/docs/api/",
1517
"http://docs.oracle.com/javaee/7/api/"
@@ -49,8 +51,12 @@ configure(allprojects) { project ->
4951
}
5052

5153
dependencies {
54+
compile "org.slf4j:slf4j-api:${slf4jVersion}"
5255
testCompile "junit:junit:${junitVersion}"
56+
testCompile "org.hamcrest:hamcrest-core:${hamcrestVersion}"
57+
testCompile "org.hamcrest:hamcrest-library:${hamcrestVersion}"
5358
testCompile "org.mockito:mockito-core:${mockitoVersion}"
59+
testCompile "org.slf4j:slf4j-simple:${slf4jVersion}"
5460
}
5561

5662
idea {
@@ -59,6 +65,13 @@ configure(allprojects) { project ->
5965
downloadSources = true
6066
}
6167
}
68+
69+
test {
70+
outputs.upToDateWhen { false }
71+
testLogging {
72+
events "passed", "skipped", "failed"
73+
}
74+
}
6275
}
6376

6477
configure(subprojects - sampleprojects) { subproject ->
@@ -154,7 +167,7 @@ project("rivescript-core") {
154167
description = "RiveScript Core"
155168

156169
dependencies {
157-
compile "org.json:json:${jsonVersion}"
170+
compileOnly "org.json:json:${jsonVersion}"
158171
}
159172
}
160173

0 commit comments

Comments
 (0)