| 1 | package RiveScript::WD; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use warnings; | ||
| 5 | |||
| 6 | # Version of the Perl RiveScript interpreter. This must be on a single line! | ||
| 7 | # See `perldoc version` | ||
| 8 | use version; our $VERSION = version->declare('v2.0.4'); | ||
| 9 | |||
| 10 | # This is not a real module; it's only a current copy of the RiveScript | ||
| 11 | # Working Draft. See the latest version at | ||
| 12 | # http://www.rivescript.com/wd/RiveScript.html | ||
| 13 | 1; | ||
| 14 | |||
| 15 | =head1 NAME | ||
| 16 | |||
| 17 | RiveScript::WD - RiveScript 2.00 Working Draft (2014/11/30) | ||
| 18 | |||
| 19 | =head1 DESCRIPTION | ||
| 20 | |||
| 21 | This document details the standards for the RiveScript scripting language. The | ||
| 22 | purpose of this document is that interpreters for RiveScript could be written | ||
| 23 | in various programming languages that would meet the standards for the | ||
| 24 | RiveScript language itself. | ||
| 25 | |||
| 26 | The most current version of this document is at | ||
| 27 | http://www.rivescript.com/wd/RiveScript.html | ||
| 28 | |||
| 29 | =head1 INTRODUCTION | ||
| 30 | |||
| 31 | RiveScript is an interpreted scripting language for giving responses to | ||
| 32 | chatterbots and other intelligent chatting entities in a simple trigger/reply | ||
| 33 | format. The scripting language is intended to be simplistic and easy to learn | ||
| 34 | and manage. | ||
| 35 | |||
| 36 | =head1 VOCABULARY | ||
| 37 | |||
| 38 | =over 4 | ||
| 39 | |||
| 40 | =item RiveScript | ||
| 41 | |||
| 42 | RiveScript is the name of the scripting language that this document explains. | ||
| 43 | |||
| 44 | =item Interpreter | ||
| 45 | |||
| 46 | The RiveScript interpreter is a program or library in another programming | ||
| 47 | language that loads and parses a RiveScript document. | ||
| 48 | |||
| 49 | =item RiveScript Document | ||
| 50 | |||
| 51 | A RiveScript Document is a text file containing RiveScript code. | ||
| 52 | |||
| 53 | =item Bot | ||
| 54 | |||
| 55 | A Bot (short for robot) is the artificial entity that is represented by an | ||
| 56 | instance of a RiveScript Interpreter object. That is, when you create a new | ||
| 57 | Interpreter object and load a set of RiveScript Documents, that becomes the | ||
| 58 | "brain" of the bot. | ||
| 59 | |||
| 60 | =item Bot Variable | ||
| 61 | |||
| 62 | A variable that describes the bot, such as its name, age, or other details | ||
| 63 | you want to define for the bot. | ||
| 64 | |||
| 65 | =item Client Variable | ||
| 66 | |||
| 67 | A variable that the bot keeps about a specific client, or user of the bot. | ||
| 68 | Usually as the client tells the bot information about itself, the bot could | ||
| 69 | save this information into Client Variables and recite it later. | ||
| 70 | |||
| 71 | =back | ||
| 72 | |||
| 73 | =head1 FORMAT | ||
| 74 | |||
| 75 | A RiveScript document should be parsed line by line, and preferably arranged | ||
| 76 | in the interpreter's memory in an efficient way. | ||
| 77 | |||
| 78 | The first character on each line should be the C<command>, and the rest of the | ||
| 79 | line is the command's C<arguments>. The C<command> should be a single character | ||
| 80 | that is not a number or a letter. | ||
| 81 | |||
| 82 | In its most simple form, a valid RiveScript trigger/response pair looks like | ||
| 83 | this: | ||
| 84 | |||
| 85 | + hello bot | ||
| 86 | - Hello, human. | ||
| 87 | |||
| 88 | =head1 WHITESPACE | ||
| 89 | |||
| 90 | A RiveScript interpreter should ignore leading and trailing whitespace characters | ||
| 91 | on any line. It should also ignore whitespace characters surrounding individual | ||
| 92 | arguments of a RiveScript command, where applicable. That is to say, the following | ||
| 93 | two lines should be interpreted as being exactly the same: | ||
| 94 | |||
| 95 | ! global debug = 1 | ||
| 96 | ! global debug= 1 | ||
| 97 | |||
| 98 | =head1 COMMANDS | ||
| 99 | |||
| 100 | =head2 ! DEFINITION | ||
| 101 | |||
| 102 | The C<!> command is for defining variables within RiveScript. It's used to | ||
| 103 | define information about the bot, define global arrays that can be used in | ||
| 104 | multiple triggers, or override interpreter globals such as debug mode. | ||
| 105 | |||
| 106 | The format of the C<!> command is as follows: | ||
| 107 | |||
| 108 | ! type name = value | ||
| 109 | |||
| 110 | Where C<type> is one of C<version, global, var, array, sub,> or C<person>. | ||
| 111 | The C<name> is the name of the variable being defined, and C<value> is the | ||
| 112 | value of said variable. | ||
| 113 | |||
| 114 | Whitespace surrounding the C<=> sign should be stripped out. | ||
| 115 | |||
| 116 | Setting a value to C<E<lt>undefE<gt>> will undefine the variable (deleting it | ||
| 117 | or uninitializing it, depending on the implementation). | ||
| 118 | |||
| 119 | The variable types supported are detailed as follows: | ||
| 120 | |||
| 121 | =head3 version | ||
| 122 | |||
| 123 | It's highly recommended practice that new RiveScript documents explicitly | ||
| 124 | define the version of RiveScript that they are following. RiveScript 2.00 | ||
| 125 | has some compatibility issues with the old 1.x line (see L<"REVERSE COMPATIBILITY">). | ||
| 126 | Newer RiveScript versions should encourage that RiveScript documents define their | ||
| 127 | own version numbers. | ||
| 128 | |||
| 129 | ! version = 2.00 | ||
| 130 | |||
| 131 | =head3 global | ||
| 132 | |||
| 133 | This should override a global variable at the interpreter level. The obvious | ||
| 134 | variable name might be "debug" (to enable/disable debugging within the | ||
| 135 | RiveScript interpreter). | ||
| 136 | |||
| 137 | The interpreter should take extra care not to allow reserved globals to be | ||
| 138 | overridden by this command in ways that might break the interpreter. | ||
| 139 | |||
| 140 | Examples: | ||
| 141 | |||
| 142 | ! global debug = 1 | ||
| 143 | |||
| 144 | =head3 var | ||
| 145 | |||
| 146 | This should define a "bot variable" for the bot. This should only be used in an | ||
| 147 | initialization sense; that is, as the interpreter loads the document, it should | ||
| 148 | define the bot variable as it reads in this line. If you'd want to redefine or | ||
| 149 | alter the value of a bot variable, you should do so using a tag inside of a | ||
| 150 | RiveScript document (see L<"TAGS">). | ||
| 151 | |||
| 152 | Examples: | ||
| 153 | |||
| 154 | ! var name = RiveScript Bot | ||
| 155 | ! var age = 0 | ||
| 156 | ! var gender = androgynous | ||
| 157 | ! var location = Cyberspace | ||
| 158 | ! var generator = RiveScript | ||
| 159 | |||
| 160 | =head3 array | ||
| 161 | |||
| 162 | This will create an array of strings, which can then be used later in triggers | ||
| 163 | (see L<"+ TRIGGER">). If the array contains single words, separating the words | ||
| 164 | with a space character is fine. If the array contains items with multiple words | ||
| 165 | in them, separate the entries with a pipe symbol (C<"|">). | ||
| 166 | |||
| 167 | Examples: | ||
| 168 | |||
| 169 | ! array colors = red green blue cyan magenta yellow black white orange brown | ||
| 170 | ! array be = is are was were | ||
| 171 | ! array whatis = what is|what are|what was|what were | ||
| 172 | |||
| 173 | Arrays have special treatment when spanned over multiple lines. Each extension | ||
| 174 | of the array data is treated individually. For example, to break an array of | ||
| 175 | many single-words into multiple lines of RiveScript code: | ||
| 176 | |||
| 177 | ! array colors = red green blue cyan | ||
| 178 | ^ magenta yellow black white | ||
| 179 | ^ orange brown | ||
| 180 | |||
| 181 | The data structure pulled from that code would be identical to the previous | ||
| 182 | example above for this array. | ||
| 183 | |||
| 184 | Since each extension line is processed individually, you can combine the | ||
| 185 | space-delimited and pipe-delimited formats. In this case, we can add some color | ||
| 186 | names to our list that have multiple words in them. | ||
| 187 | |||
| 188 | ! array colors = red green blue cyan magenta yellow | ||
| 189 | ^ light red|light green|light blue|light cyan|light magenta|light yellow | ||
| 190 | ^ dark red|dark green|dark blue|dark cyan|dark magenta|dark yellow | ||
| 191 | ^ white orange teal brown pink | ||
| 192 | ^ dark white|dark orange|dark teal|dark brown|dark pink | ||
| 193 | |||
| 194 | Finally, if your array consists of almost entirely single-word items, and you | ||
| 195 | want to add in just one multi-word item, but don't want to require an extra line | ||
| 196 | of RiveScript code to accomplish this, just use the C<\s> tag where you need | ||
| 197 | spaces to go. | ||
| 198 | |||
| 199 | ! array blues = azure blue aqua cyan baby\sblue sky\sblue | ||
| 200 | |||
| 201 | =head3 sub | ||
| 202 | |||
| 203 | The C<sub> variables are for defining substitutions that should be run against | ||
| 204 | the client's message before any attempts are made to match it to a reply. | ||
| 205 | |||
| 206 | The interpreter should do the minimum amount of formatting possible on the | ||
| 207 | client's message until after it has been passed through all the substitution | ||
| 208 | patterns. | ||
| 209 | |||
| 210 | B<NOTE:> Spaces are allowed in both the variable name and the value fields. | ||
| 211 | |||
| 212 | Examples: | ||
| 213 | |||
| 214 | ! sub what's = what is | ||
| 215 | ! sub what're = what are | ||
| 216 | ! sub what'd = what did | ||
| 217 | ! sub a/s/l = age sex location | ||
| 218 | ! sub brb = be right back | ||
| 219 | ! sub afk = away from keyboard | ||
| 220 | ! sub l o l = lol | ||
| 221 | |||
| 222 | =head3 person | ||
| 223 | |||
| 224 | The C<person> variables work a lot like C<sub>s do, but these are run against | ||
| 225 | the bot's response, specifically within C<E<lt>personE<gt>> tags (See L<"TAGS">). | ||
| 226 | |||
| 227 | Person substitutions should swap first- and second-person pronouns. This is so | ||
| 228 | that ex. if the client asks the bot a direct question using "you" when addressing | ||
| 229 | the bot, if the bot uses the client's message in the response it should swap | ||
| 230 | "you" for "I". | ||
| 231 | |||
| 232 | Examples: | ||
| 233 | |||
| 234 | ! person you are = I am | ||
| 235 | ! person i am = you are | ||
| 236 | ! person you = I | ||
| 237 | ! person i = you | ||
| 238 | |||
| 239 | =head2 E<gt> LABEL | ||
| 240 | |||
| 241 | The C<E<gt>> and C<E<lt>> commands are for defining a subset of your code under | ||
| 242 | a certain label. The label command takes between one and three arguments. The | ||
| 243 | first argument defines the type of the label, which is one of C<begin, topic,> | ||
| 244 | or C<object>. The various types are as follows. | ||
| 245 | |||
| 246 | =head3 begin | ||
| 247 | |||
| 248 | This is a special label used with the C<BEGIN block>. Every message the | ||
| 249 | client sends to the bot gets passed through the Begin Statement first, and the | ||
| 250 | response in there determines whether or not to get an actual reply. | ||
| 251 | |||
| 252 | Here's a full example of the Begin Statement. | ||
| 253 | |||
| 254 | > begin | ||
| 255 | |||
| 256 | + request | ||
| 257 | - {ok} | ||
| 258 | |||
| 259 | < begin | ||
| 260 | |||
| 261 | In the C<BEGIN block>, the trigger named "C<request>" is called by the | ||
| 262 | interpreter, and it should return the tag "C<{ok}>" to tell the interpreter | ||
| 263 | that it's OK to get a real reply. This way the bot could have a "maintenance | ||
| 264 | mode," or could filter the results of your trigger based on a variable. | ||
| 265 | |||
| 266 | Here's a maintenance mode example: | ||
| 267 | |||
| 268 | > begin | ||
| 269 | |||
| 270 | + request | ||
| 271 | * <id> eq <bot master> => {ok} // Always let the bot master get a reply | ||
| 272 | * <env maint> eq true => Sorry, I'm not available for chat right now! | ||
| 273 | - {ok} | ||
| 274 | |||
| 275 | < begin | ||
| 276 | |||
| 277 | // Allow the owner to change the maintenance mode | ||
| 278 | + activate maintenance mode | ||
| 279 | * <id> eq <bot master> => <env maint=true>Maintenance mode activated. | ||
| 280 | - You're not my master! You can't tell me what to do! | ||
| 281 | |||
| 282 | + deactivate maintenance mode | ||
| 283 | * <id> eq <bot master> => <env maint=false>Maintenance mode deactivated. | ||
| 284 | - Only my master can deactivate maintenance mode! | ||
| 285 | |||
| 286 | With this example, if the global variable "maint" is set to "true", the bot | ||
| 287 | will always reply "Sorry, I'm not available for chat right now!" when a user | ||
| 288 | sends it a message -- unless the user is the bot's owner. | ||
| 289 | |||
| 290 | Here is another example that will modify the response formatting based on a | ||
| 291 | bot variable called "mood," to simulate humanoid moods for the bot: | ||
| 292 | |||
| 293 | > begin | ||
| 294 | |||
| 295 | + request | ||
| 296 | * <get mood> == happy => {ok} :-) | ||
| 297 | * <get mood> == sad => {lowercase}{ok}{/lowercase} | ||
| 298 | * <get mood> == angry => {uppercase}{ok}{/uppercase} | ||
| 299 | - {ok} | ||
| 300 | |||
| 301 | < begin | ||
| 302 | |||
| 303 | In this example the bot will use smiley faces when it's happy, reply in all | ||
| 304 | lowercase when it's sad, or all uppercase when it's angry. If its mood doesn't | ||
| 305 | fall into any of those categories, it replies normally. | ||
| 306 | |||
| 307 | Here is one last example: say you want your bot to interview its users when | ||
| 308 | they first talk to it, by asking them for their name: | ||
| 309 | |||
| 310 | > begin | ||
| 311 | |||
| 312 | + request | ||
| 313 | * <get name> == undefined => {topic=newuser}{ok} | ||
| 314 | - {ok} | ||
| 315 | |||
| 316 | < begin | ||
| 317 | |||
| 318 | > topic newuser | ||
| 319 | + * | ||
| 320 | - Hello! My name is <bot name>! I'm a robot. What's your name? | ||
| 321 | |||
| 322 | + _ | ||
| 323 | % * what is your name | ||
| 324 | - <set name=<formal>>Nice to meet you, <get name>!{topic=random} | ||
| 325 | < topic | ||
| 326 | |||
| 327 | Begin blocks are B<optional!> They are not required. You only need to manually | ||
| 328 | define them if you need to do any "pre-processing" or "post-processing" on the | ||
| 329 | user's message or the bot's response. Having no begin block is the same as | ||
| 330 | having a super basic begin block, which always returns C<{ok}>. | ||
| 331 | |||
| 332 | =head3 topic | ||
| 333 | |||
| 334 | A topic is a smaller set of responses to which the client will be bound until | ||
| 335 | the topic is changed to something else. The default topic is C<random>. | ||
| 336 | |||
| 337 | The C<topic> label only requires one additional argument, which is the name of | ||
| 338 | the topic. The topic's name should be one word and lowercase. | ||
| 339 | |||
| 340 | Example: | ||
| 341 | |||
| 342 | + i hate you | ||
| 343 | - Well then, I won't talk to you until you take that back.{topic=apology} | ||
| 344 | |||
| 345 | > topic apology | ||
| 346 | |||
| 347 | + * | ||
| 348 | - I won't listen to you until you apologize for being mean to me. | ||
| 349 | - I have nothing to say until you say you're sorry. | ||
| 350 | |||
| 351 | + (sorry|i apologize) | ||
| 352 | - Okay. I guess I'll forgive you then.{topic=random} | ||
| 353 | |||
| 354 | < topic | ||
| 355 | |||
| 356 | Topics are able to C<include> and C<inherit> triggers that belong to a | ||
| 357 | different topic. When a topic C<includes> another topic, it means that the | ||
| 358 | triggers in another topic are made available in the topic that did the | ||
| 359 | inclusion (hereby called the "source topic", which includes triggers from | ||
| 360 | the "included topic"). | ||
| 361 | |||
| 362 | When a topic inherits another topic, it means that the entire collection | ||
| 363 | of triggers of the source topic I<and> any included topics, will have a | ||
| 364 | higher matching priority than the inherited topics. | ||
| 365 | |||
| 366 | See L<"Sorting +Triggers"> to see how triggers are sorted internally. The | ||
| 367 | following example shows how includes and inheritence works: | ||
| 368 | |||
| 369 | // This is in the default "random" topic and catches all non-matching | ||
| 370 | // triggers. | ||
| 371 | + * | ||
| 372 | - I'm afraid I don't know how to reply to that! | ||
| 373 | |||
| 374 | > topic alpha | ||
| 375 | + alpha trigger | ||
| 376 | - Alpha's response. | ||
| 377 | < topic | ||
| 378 | |||
| 379 | > topic beta | ||
| 380 | + beta trigger | ||
| 381 | - Beta's response. | ||
| 382 | < | ||
| 383 | |||
| 384 | > topic gamma | ||
| 385 | + gamma trigger | ||
| 386 | - Gamma's response. | ||
| 387 | < topic | ||
| 388 | |||
| 389 | > topic delta | ||
| 390 | + delta trigger | ||
| 391 | - Delta's response. | ||
| 392 | |||
| 393 | + * | ||
| 394 | - You can't access any other triggers! Haha! | ||
| 395 | < topic | ||
| 396 | |||
| 397 | These are all normal topics. Alpha, beta, and gamma all have a single | ||
| 398 | trigger corresponding to their topic names. If the user were put into | ||
| 399 | one of these topics, this is the only trigger available. Anything else | ||
| 400 | would give them a "NO REPLY" error message. They are unable to match the | ||
| 401 | C<*> trigger at the top, because that trigger belongs to the "C<random>" | ||
| 402 | topic, and they're not in that topic. | ||
| 403 | |||
| 404 | Now let's see how we can pair these topics up with includes and | ||
| 405 | inheritence. | ||
| 406 | |||
| 407 | > topic ab includes alpha | ||
| 408 | + hello bot | ||
| 409 | - Hello human! | ||
| 410 | < topic | ||
| 411 | |||
| 412 | // Matching order: | ||
| 413 | alpha trigger | ||
| 414 | hello bot | ||
| 415 | |||
| 416 | If the user were put into topic "C<ab>", they could match the trigger | ||
| 417 | C<hello bot> as well as the trigger C<alpha trigger>, as if they were | ||
| 418 | both in the same topic. | ||
| 419 | |||
| 420 | Note that in the matching order, "alpha trigger" is at the top: this | ||
| 421 | is because it is the longest trigger. If the user types "alpha trigger", | ||
| 422 | the interpreter knows that "alpha trigger" does not belong to the topic | ||
| 423 | "ab", but since "ab" includes triggers from "alpha", the interpreter | ||
| 424 | searches there and finds the trigger. Then it gives the user the | ||
| 425 | correct reply of "Alpha's response." | ||
| 426 | |||
| 427 | > topic abc includes alpha beta | ||
| 428 | + how are you | ||
| 429 | - Good, how are you? | ||
| 430 | < topic | ||
| 431 | |||
| 432 | // Matching order: | ||
| 433 | how are you | ||
| 434 | alpha trigger | ||
| 435 | beta trigger | ||
| 436 | |||
| 437 | In this case, "how are you" is on the top of the matching list because | ||
| 438 | it has three words, then "alpha trigger" and "beta trigger" -- "alpha | ||
| 439 | trigger" is first because it is longer than "beta trigger", even though | ||
| 440 | they both have 2 words. | ||
| 441 | |||
| 442 | Now consider this example: | ||
| 443 | |||
| 444 | > topic abc includes alpha beta | ||
| 445 | + how are you | ||
| 446 | - Good, how are you? | ||
| 447 | |||
| 448 | + * | ||
| 449 | - You matched my star trigger! | ||
| 450 | < topic | ||
| 451 | |||
| 452 | // Matching order: | ||
| 453 | how are you | ||
| 454 | alpha trigger | ||
| 455 | beta trigger | ||
| 456 | * | ||
| 457 | |||
| 458 | Notice what happened here: we had a trigger of simply C<*> in the "abc" | ||
| 459 | topic - C<*> is the fallback trigger which matches anything that wasn't | ||
| 460 | matched by a better trigger. But this trigger is at the end of our matching | ||
| 461 | list! This is because the triggers available in the "alpha" and "beta" topics | ||
| 462 | are included in the "abc" topic, meaning they all share the same "space" | ||
| 463 | when the triggers are sorted. Since C<*> has the lowest sort priority, | ||
| 464 | it ends up at the very end of the collective list. | ||
| 465 | |||
| 466 | What if we want C<*>, or any other short trigger, to match in our current | ||
| 467 | topic before anything in an included topic? We need to C<inherit> another | ||
| 468 | topic. Consider this: | ||
| 469 | |||
| 470 | > topic abc inherits alpha beta | ||
| 471 | + how are you | ||
| 472 | - Good, how are you? | ||
| 473 | |||
| 474 | + * | ||
| 475 | - You matched my star trigger! | ||
| 476 | < topic | ||
| 477 | |||
| 478 | // Matching order: | ||
| 479 | how are you | ||
| 480 | * | ||
| 481 | alpha trigger | ||
| 482 | beta trigger | ||
| 483 | |||
| 484 | Now the C<*> trigger is the second on the matching list. Because "abc" | ||
| 485 | I<inherits> alpha and beta, it means that the collection of triggers | ||
| 486 | inside "abc" are sorted independently, and I<then> the triggers of alpha | ||
| 487 | and beta are sorted. So this way every trigger in "abc" inherits, or | ||
| 488 | I<overrides>, all triggers in the inherited topics. | ||
| 489 | |||
| 490 | Of course, using a C<*> trigger in a topic that inherits other topics is | ||
| 491 | useless, because you could just leave the topic as it is. However it might | ||
| 492 | be helpful in the case that a trigger in your topic is very short or has | ||
| 493 | very few words, and you want to make sure that this trigger will have a | ||
| 494 | good chance of matching before anything that appears in a different topic. | ||
| 495 | |||
| 496 | You can combine inherited and included topics together, too. | ||
| 497 | |||
| 498 | > topic abc includes alpha beta delta inherits gamma | ||
| 499 | + how are you | ||
| 500 | - Good, how are you? | ||
| 501 | < topic | ||
| 502 | |||
| 503 | // Matching order: | ||
| 504 | how are you | ||
| 505 | alpha trigger | ||
| 506 | delta trigger | ||
| 507 | beta trigger | ||
| 508 | * | ||
| 509 | gamma trigger | ||
| 510 | |||
| 511 | In this example, the combined triggers from abc, alpha, beta, and delta | ||
| 512 | are all merged together in one pool and sorted amongst themselves, and | ||
| 513 | then triggers from gamma are placed after them in the sort list. | ||
| 514 | |||
| 515 | This effectively means you can combine the triggers from multiple | ||
| 516 | topics together, and have ALL of those triggers override triggers | ||
| 517 | from an inherited topic. | ||
| 518 | |||
| 519 | You can use as many "includes" and "inherits" keywords as you want, but | ||
| 520 | the order you specify them has no effect. So the following two formats | ||
| 521 | are identical: | ||
| 522 | |||
| 523 | > topic alpha includes beta inherits gamma | ||
| 524 | > topic alpha inherits gamma includes beta | ||
| 525 | |||
| 526 | In both cases, alpha and beta's triggers are pooled and have higher | ||
| 527 | priority than gamma's. If gamma wants to include beta and have alpha's | ||
| 528 | triggers be higher priority than gamma's and beta's, gamma will need | ||
| 529 | to include beta first. | ||
| 530 | |||
| 531 | > topic gamma includes beta | ||
| 532 | > topic alpha inherits gamma | ||
| 533 | |||
| 534 | In this case the triggers in "alpha" are higher priority than the | ||
| 535 | combined triggers in gamma and beta. | ||
| 536 | |||
| 537 | =head3 object | ||
| 538 | |||
| 539 | Objects are bits of program code that the interpreter should try to process. | ||
| 540 | The programming language that the interpreter was written in will determine | ||
| 541 | whether or not it will attempt to process the object. | ||
| 542 | |||
| 543 | See L<"OBJECT MACROS"> for more information on objects. | ||
| 544 | |||
| 545 | The C<object> label should have two arguments: a lowercase single-word name for | ||
| 546 | the object, and the programming language that the object should be interpreted | ||
| 547 | by, which should also be lowercase. | ||
| 548 | |||
| 549 | Example: | ||
| 550 | |||
| 551 | > object encode perl | ||
| 552 | my ($obj,$method,@args) = @_; | ||
| 553 | my $msg = join(" ",@args); | ||
| 554 | |||
| 555 | use Digest::MD5 qw(md5_hex); | ||
| 556 | use MIME::Base64 qw(encode_base64); | ||
| 557 | |||
| 558 | if ($method eq 'md5') { | ||
| 559 | return md5_hex($msg); | ||
| 560 | } | ||
| 561 | else { | ||
| 562 | return encode_base64($msg); | ||
| 563 | } | ||
| 564 | < object | ||
| 565 | |||
| 566 | =head2 + TRIGGER | ||
| 567 | |||
| 568 | The C<+> command is the basis for all things that actually do stuff within a | ||
| 569 | RiveScript document. The trigger command is what matches the user's message to | ||
| 570 | a response. | ||
| 571 | |||
| 572 | The trigger's text should be entirely lowercase and not contain any symbols | ||
| 573 | (except those used for matching complicated messages). That is, a trigger that | ||
| 574 | wants to match "C<what's your name>" shouldn't be used; you should use a | ||
| 575 | L<"sub">stitution to convert C<what's> into C<what is> ahead of time. | ||
| 576 | |||
| 577 | Example: | ||
| 578 | |||
| 579 | + are you a bot | ||
| 580 | - How did you know I'm a robot? | ||
| 581 | |||
| 582 | =head3 Atomic Trigger | ||
| 583 | |||
| 584 | An atomic trigger is a trigger that matches nothing but plain text. It doesn't | ||
| 585 | contain any wildcards (C<*>) or optionals, but it may contain alternations. | ||
| 586 | Atomic triggers should take higher priority for matching a client's message | ||
| 587 | than should triggers containing wildcards and optionals. | ||
| 588 | |||
| 589 | Examples: | ||
| 590 | |||
| 591 | + hello bot | ||
| 592 | + what is your name | ||
| 593 | + what is your (home|office) phone number | ||
| 594 | + who is george w bush | ||
| 595 | |||
| 596 | =head3 Trigger Wildcards | ||
| 597 | |||
| 598 | Using an asterisk (C<*>) in the trigger will make it act as a wildcard. Anything | ||
| 599 | the user says in place of the wildcard may still match the trigger. For example: | ||
| 600 | |||
| 601 | + my name is * | ||
| 602 | - Pleased to meet you, <star>. | ||
| 603 | |||
| 604 | An asterisk (C<*>) will match any character (numbers and letters). If you want | ||
| 605 | to only match numbers, use C<#>, and to match only letters use C<_>. Example: | ||
| 606 | |||
| 607 | // This will ONLY take a number as the wildcard. | ||
| 608 | + i am # years old | ||
| 609 | - I will remember that you are <star> years old. | ||
| 610 | |||
| 611 | // This will ONLY take letters but not numbers. | ||
| 612 | + my name is _ | ||
| 613 | - Nice to meet you, <star>. | ||
| 614 | |||
| 615 | The values matched by the wildcards can be retrieved in the responses by using | ||
| 616 | the tags C<E<lt>star1E<gt>>, C<E<lt>star2E<gt>>, C<E<lt>star3E<gt>>, etc. in the | ||
| 617 | order that the wildcard appeared. C<E<lt>starE<gt>> is an alias for C<E<lt>star1E<gt>>. | ||
| 618 | |||
| 619 | =head3 Trigger Alternations | ||
| 620 | |||
| 621 | An alternation in a trigger is a sub-set of strings, in which any one of the | ||
| 622 | strings will still match the trigger. For example, the following trigger should | ||
| 623 | match both "are you okay" and "are you alright": | ||
| 624 | |||
| 625 | + are you (okay|alright) | ||
| 626 | |||
| 627 | Alternations can contain spaces in them, too. | ||
| 628 | |||
| 629 | + (are you|you) (okay|alright) | ||
| 630 | |||
| 631 | That would match all of the following questions from the client: | ||
| 632 | |||
| 633 | are you okay | ||
| 634 | are you alright | ||
| 635 | you okay | ||
| 636 | you alright | ||
| 637 | |||
| 638 | Alternations match the same as wildcards do; they can be retrieved via the | ||
| 639 | C<E<lt>starE<gt>> tags. | ||
| 640 | |||
| 641 | =head3 Trigger Optionals | ||
| 642 | |||
| 643 | Triggers can contain optional words as well. Optionals are written similarly to | ||
| 644 | alternations, but they use square braces. The following example would match both | ||
| 645 | "what is your phone number" as well as "what is your B<home> phone number" | ||
| 646 | |||
| 647 | + what is your [home] phone number | ||
| 648 | |||
| 649 | Optionals do B<NOT> match like wildcards do. They do NOT go into the | ||
| 650 | C<E<lt>starE<gt>> tags. The reason for this is that optionals are optional, and | ||
| 651 | won't always match anything if the client didn't actually say the optional word(s). | ||
| 652 | |||
| 653 | =head3 Arrays in Triggers | ||
| 654 | |||
| 655 | Arrays defined via the L<"! DEFINITION"> L<"array"> commands can be used within | ||
| 656 | a trigger. This is the only place where arrays are used, and they're added as a | ||
| 657 | convenience feature. | ||
| 658 | |||
| 659 | For example, you can make an array of color names, and then use that array in | ||
| 660 | multiple triggers, without having to copy a whole bunch of alternation code between | ||
| 661 | triggers. | ||
| 662 | |||
| 663 | ! array colors = red green blue cyan magenta yellow black white orange brown | ||
| 664 | |||
| 665 | + i am wearing a (@colors) shirt | ||
| 666 | - I don't know if I have a shirt that's colored <star>. | ||
| 667 | |||
| 668 | + my favorite color is (@colors) | ||
| 669 | - I like <star> too. | ||
| 670 | |||
| 671 | + i have a @colors colored * | ||
| 672 | - Have you thought about getting a <star> in a different color? | ||
| 673 | |||
| 674 | When an array is called within parenthesis, it should be matched into a | ||
| 675 | C<E<lt>starE<gt>> tag. When the parenthesis are absent, however, it should not | ||
| 676 | be matched into a C<E<lt>starE<gt>> tag. | ||
| 677 | |||
| 678 | =head3 Priority Triggers | ||
| 679 | |||
| 680 | A new feature proposed for RiveScript 2.00 is to add a priority tag to triggers. | ||
| 681 | When the interpreter sorts all the loaded triggers into a search sequence, any | ||
| 682 | triggers that have a priority defined will be sorted with higher priority | ||
| 683 | triggers first. | ||
| 684 | |||
| 685 | The idea is to have "important" triggers that should always be matched before a | ||
| 686 | different trigger, which may have been a better match, can be tried. The best | ||
| 687 | example would be for commands. For example: | ||
| 688 | |||
| 689 | + google * | ||
| 690 | - Searching Google... <call>google <star></call> | ||
| 691 | |||
| 692 | + * or not | ||
| 693 | - Or yes. <@> | ||
| 694 | |||
| 695 | In that example, if the bot had a Google search function and the user wanted to | ||
| 696 | search for whether or not Perl is a superior programming language to PHP, the | ||
| 697 | user might ask "C<google is perl better than php or not>". However, without | ||
| 698 | priorities in effect, that question would actually match the "C<* or not>" | ||
| 699 | trigger, because that trigger has more words than "C<google *>" does. | ||
| 700 | |||
| 701 | Adding a priority to the "C<google *>" trigger would ensure that conflicts like | ||
| 702 | this don't happen, by always sorting the Google search trigger with higher | ||
| 703 | priority than the other. | ||
| 704 | |||
| 705 | + {weight=100}google * | ||
| 706 | - Searching Google... <call>google <star></call> | ||
| 707 | |||
| 708 | B<NOTE:> It would NOT be recommended to put a priority tag on every one of your | ||
| 709 | triggers. To the interpreter this might mean extra processing work to sort | ||
| 710 | prioritized triggers by each number group. Only add priorities to triggers that | ||
| 711 | need them. | ||
| 712 | |||
| 713 | =head2 - RESPONSE | ||
| 714 | |||
| 715 | The C<-> tag is used to indicate a response to a matched trigger. A single | ||
| 716 | response to a single trigger is called an "atomic response." When more than one | ||
| 717 | response is given to a single trigger, the collection of responses become a | ||
| 718 | "random response," where a response is chosen randomly from the list. Random | ||
| 719 | responses can also use a C<{weight}> tag to improve the likelihood of one response | ||
| 720 | being randomly chosen over another. | ||
| 721 | |||
| 722 | =head3 Atomic Response | ||
| 723 | |||
| 724 | A single response to a single trigger makes an Atomic Response. The bot will | ||
| 725 | respond pretty much the same way each time the trigger is matched. | ||
| 726 | |||
| 727 | Examples: | ||
| 728 | |||
| 729 | + hello bot | ||
| 730 | - Hello human. | ||
| 731 | |||
| 732 | + my name is * | ||
| 733 | - Nice to meet you, <star>. | ||
| 734 | |||
| 735 | + i have a (@colors) shirt | ||
| 736 | - You're not the only one that has a <star> shirt. | ||
| 737 | |||
| 738 | =head3 Random Response | ||
| 739 | |||
| 740 | Multiple responses to a single trigger will be chosen randomly. | ||
| 741 | |||
| 742 | + hello | ||
| 743 | - Hey there! | ||
| 744 | - Hello! | ||
| 745 | - Hi, how are you? | ||
| 746 | |||
| 747 | + my name is * | ||
| 748 | - Nice to meet you, <star>. | ||
| 749 | - Hi, <star>, my name is <bot name>. | ||
| 750 | - <star>, nice to meet you. | ||
| 751 | |||
| 752 | =head3 Weighted Random Response | ||
| 753 | |||
| 754 | When using random responses, it's possible to give weight to them to change the | ||
| 755 | likelihood that a response will be chosen. In this example, the response of | ||
| 756 | "Hello there" will be much more likely to be chosen than would the response of | ||
| 757 | "Hi". | ||
| 758 | |||
| 759 | + hello | ||
| 760 | - Hello there!{weight=50} | ||
| 761 | - Hi. | ||
| 762 | |||
| 763 | When the C<{weight}> tag isn't used, a default weight of 1 is implied for that | ||
| 764 | response. The C<{weight}> should always be a number greater than zero and must | ||
| 765 | be an integer (no decimal point). | ||
| 766 | |||
| 767 | =head2 % PREVIOUS | ||
| 768 | |||
| 769 | The C<%> command is for drawing the user back to finish a short discussion. Its | ||
| 770 | behavior is similar to using topics, but is implied automatically and used for | ||
| 771 | short-term things. It's also less strict than topics are; if the client replies | ||
| 772 | in a way that doesn't match, a normal reply is given anyway. For example: | ||
| 773 | |||
| 774 | + knock knock | ||
| 775 | - Who's there? | ||
| 776 | |||
| 777 | + * | ||
| 778 | % who is there | ||
| 779 | - <star> who? | ||
| 780 | |||
| 781 | + * | ||
| 782 | % * who | ||
| 783 | - lol! <star>! That's hilarious! | ||
| 784 | |||
| 785 | The text of the C<%> command looks similar to the text next to the trigger. In | ||
| 786 | essence, they work the same; the only difference is that the C<%> command matches | ||
| 787 | the last thing that the I<bot> sent to you. | ||
| 788 | |||
| 789 | Here's another example: | ||
| 790 | |||
| 791 | + i have a dog | ||
| 792 | - What color is it? | ||
| 793 | |||
| 794 | + (@colors) | ||
| 795 | % what color is it | ||
| 796 | - That's an odd color for a dog. | ||
| 797 | |||
| 798 | In that case, if the client says "I have a dog," the bot will reply asking what | ||
| 799 | color it is. Now, if I tell it the color in my next message, it will reply back | ||
| 800 | and tell me what an odd color that is. However, if I change the topic instead and | ||
| 801 | say something else to the bot, it will answer my new question anyway. This is in | ||
| 802 | contrast to using topics, where I'd be stuck inside of the topic until the bot | ||
| 803 | resets the topic to C<random>. | ||
| 804 | |||
| 805 | Similarly to the wildcards in C<+ Trigger>, the wildcards matched in the | ||
| 806 | C<% Previous> command are put into C<E<lt>botstarE<gt>>. See L<"TAGS"> for | ||
| 807 | more information. | ||
| 808 | |||
| 809 | =head2 ^ CONTINUE | ||
| 810 | |||
| 811 | The C<^> command is used to continue the text of a lengthy previous command down | ||
| 812 | to the new line. It can be used to extend any other command. Example: | ||
| 813 | |||
| 814 | + tell me a poem | ||
| 815 | - Little Miss Muffit sat on her tuffet\n | ||
| 816 | ^ in a nonchalant sort of way.\n | ||
| 817 | ^ With her forcefield around her,\n | ||
| 818 | ^ the Spider, the bounder,\n | ||
| 819 | ^ Is not in the picture today. | ||
| 820 | |||
| 821 | Note that when the C<^> command continues the previous command, no spaces or | ||
| 822 | line breaks are implied at the joining of the two lines. The C<\s> and C<\n> | ||
| 823 | tags must be explicitly defined where needed. | ||
| 824 | |||
| 825 | =head2 @ REDIRECT | ||
| 826 | |||
| 827 | The C<@> command is used to redirect an entire response to appear as though the | ||
| 828 | client asked an entirely different question. For example: | ||
| 829 | |||
| 830 | + my name is * | ||
| 831 | - Nice to meet you, <star>. | ||
| 832 | |||
| 833 | + call me * | ||
| 834 | @ my name is <star> | ||
| 835 | |||
| 836 | If the client says "call me John", the bot will redirect it as though the client | ||
| 837 | actually said "my name is John" and give the response of "Nice to meet you, | ||
| 838 | John." | ||
| 839 | |||
| 840 | =head2 * CONDITION | ||
| 841 | |||
| 842 | The C<*> command is used with conditionals when replying to a trigger. Put simply, | ||
| 843 | they compare two values, and when the comparison is true the associated response | ||
| 844 | is given. The syntax is as follows: | ||
| 845 | |||
| 846 | * value symbol value => response | ||
| 847 | |||
| 848 | The following inequality symbols may be used: | ||
| 849 | |||
| 850 | == equal to | ||
| 851 | eq equal to (alias) | ||
| 852 | != not equal to | ||
| 853 | ne not equal to (alias) | ||
| 854 | <> not equal to (alias) | ||
| 855 | < less than | ||
| 856 | <= less than or equal to | ||
| 857 | > greater than | ||
| 858 | >= greater than or equal to | ||
| 859 | |||
| 860 | In each of the value places, tags can be used to i.e. insert client or bot | ||
| 861 | variables. | ||
| 862 | |||
| 863 | Examples: | ||
| 864 | |||
| 865 | + am i a boy or a girl | ||
| 866 | * <get gender> eq male => You told me you were a boy. | ||
| 867 | * <get gender> eq female => You told me you were a girl. | ||
| 868 | - You never told me what you were. | ||
| 869 | |||
| 870 | + am i your master | ||
| 871 | * <id> eq <bot master> => Yes, you are. | ||
| 872 | - No, you're not my master. | ||
| 873 | |||
| 874 | + my name is * | ||
| 875 | * <get name> eq <star> => I know, you told me that already. | ||
| 876 | * <get name> ne undefined => Did you get a name change?<set name=<star>> | ||
| 877 | - <set name=<star>>Nice to meet you, <star>. | ||
| 878 | |||
| 879 | It's recommended practice to always include at least one response in case all | ||
| 880 | of the conditionals return false. | ||
| 881 | |||
| 882 | B<NOTE:> Conditionals are tried in the order they appear in the RiveScript | ||
| 883 | document, and the next condition is tried when the previous ones are false. | ||
| 884 | |||
| 885 | =head2 // COMMENT | ||
| 886 | |||
| 887 | The C<//> command is for putting comments into your RiveScript document. The | ||
| 888 | C-style multiline comment syntax C</* */> is also supported. | ||
| 889 | |||
| 890 | Comments on their own line should be ignored by all interpreters. For inline | ||
| 891 | comments, only the C<//> format is acceptable. If you want a literal C<//> in | ||
| 892 | your RiveScript data, escape at least one of the symbols, i.e. C<\//> or C<\/\/> | ||
| 893 | or C</\/>. | ||
| 894 | |||
| 895 | Examples: | ||
| 896 | |||
| 897 | // A single regular comment | ||
| 898 | |||
| 899 | /* | ||
| 900 | This comment can span | ||
| 901 | multiple lines | ||
| 902 | */ | ||
| 903 | |||
| 904 | > begin // The "BEGIN" block | ||
| 905 | + request // This is required | ||
| 906 | - {ok} // An {ok} means to get a real reply | ||
| 907 | < begin//End the begin block | ||
| 908 | |||
| 909 | =head1 OBJECT MACROS | ||
| 910 | |||
| 911 | An C<object macro> is a piece of program code that is processed by the interpreter | ||
| 912 | to give a little more "kick" to the RiveScript. All objects are required to define | ||
| 913 | the programming language they use. Ones that don't should result in vociferous | ||
| 914 | warnings by the interpreter. | ||
| 915 | |||
| 916 | Objects should be able to be declared inline within RiveScript code, however they | ||
| 917 | may also be defined by the program utilizing the interpreter as well. All objects | ||
| 918 | should receive, at a minimum, some kind of reference to the RiveScript interpreter | ||
| 919 | object that called them. | ||
| 920 | |||
| 921 | Here is an example of a simple Perl object that encodes a bit of text into | ||
| 922 | MD5 or Base64. | ||
| 923 | |||
| 924 | > object encode perl | ||
| 925 | my ($obj,$method,@args) = @_; | ||
| 926 | my $msg = join(" ",@args); | ||
| 927 | |||
| 928 | use Digest::MD5 qw(md5_hex); | ||
| 929 | use MIME::Base64 qw(encode_base64); | ||
| 930 | |||
| 931 | if ($method eq 'md5') { | ||
| 932 | return md5_hex($msg); | ||
| 933 | } | ||
| 934 | else { | ||
| 935 | return encode_base64($msg); | ||
| 936 | } | ||
| 937 | < object | ||
| 938 | |||
| 939 | To call an object within a response, call it in the format of: | ||
| 940 | |||
| 941 | <call>object_name arguments</call> | ||
| 942 | |||
| 943 | For example: | ||
| 944 | |||
| 945 | + encode * in md5 | ||
| 946 | - The MD5 hash of "<star>" is: <call>encode md5 <star></call> | ||
| 947 | |||
| 948 | + encode * in base64 | ||
| 949 | - The Base64 hash of "<star>" is: <call>encode base64 <star></call> | ||
| 950 | |||
| 951 | In the above examples, C<encode> calls on the object named "encode", which we | ||
| 952 | defined above; C<md5> and C<base64> calls on the method name, which is received | ||
| 953 | by the object as C<$method>. Finally, C<@args> as received by the object would | ||
| 954 | be the value of E<lt>starE<gt> in this example. | ||
| 955 | |||
| 956 | C<$obj> in this example would be a reference to the RiveScript interpreter. | ||
| 957 | |||
| 958 | =head1 TAGS | ||
| 959 | |||
| 960 | Tags are bits of text inserted within the argument space of a RiveScript command. | ||
| 961 | As a general rule of thumb, tags with E<lt>angle bracketsE<gt> are for setting | ||
| 962 | and getting a variable or for inserting text. Tags with {curly brackets} modify | ||
| 963 | the text around them, such as to change the formatting of enclosed text. | ||
| 964 | |||
| 965 | No tags can be used within C<! Definition> and C<E<gt> Label> under any | ||
| 966 | circumstances. | ||
| 967 | |||
| 968 | Unless otherwise specified, all of the tags can be used within every RiveScript | ||
| 969 | command. | ||
| 970 | |||
| 971 | =head2 E<lt>starE<gt>, E<lt>star1E<gt> - E<lt>starNE<gt> | ||
| 972 | |||
| 973 | The C<E<lt>starE<gt>> tags are used for matching responses. See | ||
| 974 | L<"+ TRIGGER"> for usage examples. | ||
| 975 | |||
| 976 | The C<E<lt>starE<gt>> tags can NOT be used within C<+ Trigger>. | ||
| 977 | |||
| 978 | =head2 E<lt>botstarE<gt>, E<lt>botstar1E<gt> - E<lt>botstarNE<gt> | ||
| 979 | |||
| 980 | If the trigger included a C<% Previous> command, C<E<lt>botstarE<gt>> will match | ||
| 981 | any wildcards that matched the bot's previous response. | ||
| 982 | |||
| 983 | + ask me a question | ||
| 984 | - What color's your {random}shirt shoes socks{/random} | ||
| 985 | |||
| 986 | + * | ||
| 987 | % what colors your * | ||
| 988 | - I wouldn't like <star> as a color for my <botstar>. | ||
| 989 | |||
| 990 | =head2 E<lt>input1E<gt> - E<lt>input9E<gt>; E<lt>reply1E<gt> - E<lt>reply9E<gt>. | ||
| 991 | |||
| 992 | The input and reply tags insert the previous 1 to 9 things the client said, and | ||
| 993 | the last 1 to 9 things the bot said, respectively. When these tags are used with | ||
| 994 | C<+ Trigger>, they should be formatted against substitutions first. This way, the | ||
| 995 | bot might be able to detect when the client is repeating themself or when they're | ||
| 996 | repeating the bot's replies. | ||
| 997 | |||
| 998 | + <reply1> | ||
| 999 | - Don't repeat what I say. | ||
| 1000 | |||
| 1001 | + <input1> | ||
| 1002 | * <input1> eq <input2> => That's the second time you've repeated yourself. | ||
| 1003 | * <input1> eq <input3> => If you repeat yourself again I'll stop talking to you. | ||
| 1004 | * <input1> eq <input4> => That's it. I'm done talking to you.{topic=blocked} | ||
| 1005 | - Please don't repeat yourself. | ||
| 1006 | |||
| 1007 | C<E<lt>inputE<gt>> and C<E<lt>replyE<gt>> are aliases for C<E<lt>input1E<gt>> and | ||
| 1008 | C<E<lt>reply1E<gt>>, respectively. | ||
| 1009 | |||
| 1010 | =head2 E<lt>idE<gt> | ||
| 1011 | |||
| 1012 | The C<E<lt>idE<gt>> tag inserts the client's ID, as told to the RiveScript | ||
| 1013 | interpreter when the client's ID and message were passed in. | ||
| 1014 | |||
| 1015 | =head2 E<lt>botE<gt> | ||
| 1016 | |||
| 1017 | Insert a bot variable, which was previously defined via the C<! Definition> | ||
| 1018 | L<"var"> commands. | ||
| 1019 | |||
| 1020 | + what is your name | ||
| 1021 | - I am <bot name>, a chatterbot created by <bot company>. | ||
| 1022 | |||
| 1023 | + my name is <bot name> | ||
| 1024 | - <set name=<bot name>>What a coincidence, that's my name too! | ||
| 1025 | |||
| 1026 | The C<E<lt>botE<gt>> tag allows assignment as well (which deprecates the old | ||
| 1027 | C<{!...}> tag. | ||
| 1028 | |||
| 1029 | + set mood to (happy|angry|sad) | ||
| 1030 | * <get master> == true => <bot mood=<star>>Updated my mood. | ||
| 1031 | - Only my botmaster can do that. | ||
| 1032 | |||
| 1033 | =head2 E<lt>envE<gt> | ||
| 1034 | |||
| 1035 | Insert a global variable, which was previously defined via C<! Definition> | ||
| 1036 | L<"global"> commands. | ||
| 1037 | |||
| 1038 | + is debug mode enabled | ||
| 1039 | * <env debug> == 1 => Yes, debug mode is active. | ||
| 1040 | - No, debug mode is set to "<env debug>" | ||
| 1041 | |||
| 1042 | The C<E<lt>envE<gt>> tag allows assignment as well (which deprecates the old | ||
| 1043 | C<{!...}> tag). | ||
| 1044 | |||
| 1045 | + turn debug mode on | ||
| 1046 | * <get master> == true => <env debug=1>Debug mode enabled. | ||
| 1047 | - You can't turn debug mode on. | ||
| 1048 | |||
| 1049 | =head2 E<lt>getE<gt>, E<lt>setE<gt> | ||
| 1050 | |||
| 1051 | Get and set a client variable. These variables are local to the user ID that is | ||
| 1052 | chatting with the bot. | ||
| 1053 | |||
| 1054 | + my name is * | ||
| 1055 | - <set name=<star>>Nice to meet you, <star>. | ||
| 1056 | |||
| 1057 | E<lt>getE<gt> can be used within C<+ Trigger>, but E<lt>setE<gt> can not. | ||
| 1058 | |||
| 1059 | =head2 E<lt>addE<gt>, E<lt>subE<gt>, E<lt>multE<gt>, E<lt>divE<gt> | ||
| 1060 | |||
| 1061 | Add, subtract, multiply, and divide a numeric client variable, respectively. | ||
| 1062 | |||
| 1063 | + give me 5 points | ||
| 1064 | - <add points=5>I've added 5 points to your account. | ||
| 1065 | |||
| 1066 | These tags can not be used within C<+ Trigger>. | ||
| 1067 | |||
| 1068 | =head2 {topic=...} | ||
| 1069 | |||
| 1070 | Change the client's topic. This tag can only be used with C<* Condition> and | ||
| 1071 | C<- Response>. | ||
| 1072 | |||
| 1073 | =head2 {weight=...} | ||
| 1074 | |||
| 1075 | When used with C<- Response>, this will weigh the response more heavily to be | ||
| 1076 | chosen when random responses are available. When used with C<+ Trigger>, this | ||
| 1077 | sets that trigger to have a higher matching priority. | ||
| 1078 | |||
| 1079 | =head2 {@...}, E<lt>@E<gt> | ||
| 1080 | |||
| 1081 | Perform an inline redirection. This should work like a regular redirection but | ||
| 1082 | is embedded within another response. This tag can only be used with | ||
| 1083 | C<- Response>, and in the response part of a C<* Condition>. | ||
| 1084 | |||
| 1085 | E<lt>@E<gt> is an alias for {@E<lt>starE<gt>} | ||
| 1086 | |||
| 1087 | + your * | ||
| 1088 | - I think you meant to say "you are" or "you're", not "your". {@you are <star>} | ||
| 1089 | |||
| 1090 | =head2 {!...} | ||
| 1091 | |||
| 1092 | Perform an inline definition. This can be used just like the normal | ||
| 1093 | C<! Definition> command from within a reply. This tag can only be used | ||
| 1094 | with C<- Response>. | ||
| 1095 | |||
| 1096 | B<This tag is deprecated>. This tag's purpose was to redefine a global or bot | ||
| 1097 | variable on the fly. Instead, the env and bot tags allow assignment. | ||
| 1098 | |||
| 1099 | + set bot mood to * | ||
| 1100 | - <bot mood=<star>>Bot mood set to <star>. | ||
| 1101 | |||
| 1102 | =head2 {random}...{/random} | ||
| 1103 | |||
| 1104 | Insert a sub-set of random text. This tag can NOT be used with C<+ Trigger>. Use | ||
| 1105 | the same array syntax as when defining arrays (separate single-word groups with | ||
| 1106 | spaces and multi-word groups with pipes). | ||
| 1107 | |||
| 1108 | + say something random | ||
| 1109 | - This {random}sentence statement{/random} has a random {random}set of words|gang of vocabulary{/random}. | ||
| 1110 | |||
| 1111 | =head2 {person}...{/person}, E<lt>personE<gt> | ||
| 1112 | |||
| 1113 | Process L<"person"> substitutions on a group of text. | ||
| 1114 | |||
| 1115 | + say * | ||
| 1116 | - Umm... "<person>" | ||
| 1117 | |||
| 1118 | In that example, if the client says "say you are a robot", the bot should reply, | ||
| 1119 | "Umm... "I am a robot."" | ||
| 1120 | |||
| 1121 | E<lt>personE<gt> is an alias for {person}E<lt>starE<gt>{/person}. | ||
| 1122 | |||
| 1123 | =head2 {formal}...{/formal}, E<lt>formalE<gt> | ||
| 1124 | |||
| 1125 | Formalize A String Of Text (Capitalize Every First Letter Of Every Word). | ||
| 1126 | |||
| 1127 | + my name is * | ||
| 1128 | - Nice to meet you, <formal>. | ||
| 1129 | |||
| 1130 | E<lt>formalE<gt> is an alias for {formal}E<lt>starE<gt>{/formal}. | ||
| 1131 | |||
| 1132 | =head2 {sentence}...{/sentence}, E<lt>sentenceE<gt> | ||
| 1133 | |||
| 1134 | Format a string of text in sentence-case (capitilizing only the first letter | ||
| 1135 | of the first word of each sentence). | ||
| 1136 | |||
| 1137 | E<lt>sentenceE<gt> is an alias for {sentence}E<lt>starE<gt>{/sentence}. | ||
| 1138 | |||
| 1139 | =head2 {uppercase}...{/uppercase}, E<lt>uppercaseE<gt> | ||
| 1140 | |||
| 1141 | FORMAT A STRING OF TEXT INTO UPPERCASE. | ||
| 1142 | |||
| 1143 | E<lt>uppercaseE<gt> is an alias for {uppercase}E<lt>starE<gt>{/uppercase}. | ||
| 1144 | |||
| 1145 | =head2 {lowercase}...{/lowercase}, E<lt>lowercaseE<gt> | ||
| 1146 | |||
| 1147 | format a string of text into lowercase. | ||
| 1148 | |||
| 1149 | E<lt>lowercaseE<gt> is an alias for {lowercase}E<lt>starE<gt>{/lowercase}. | ||
| 1150 | |||
| 1151 | =head2 {ok} | ||
| 1152 | |||
| 1153 | This is used only with the "request" trigger within the BEGIN block. It tells | ||
| 1154 | the interpreter that it's okay to go and get a real response to the client's | ||
| 1155 | message. | ||
| 1156 | |||
| 1157 | =head2 \s | ||
| 1158 | |||
| 1159 | Inserts a white space character. This is useful with the C<^ Continue> | ||
| 1160 | command. | ||
| 1161 | |||
| 1162 | =head2 \n | ||
| 1163 | |||
| 1164 | Inserts a line break character. | ||
| 1165 | |||
| 1166 | =head2 \/ | ||
| 1167 | |||
| 1168 | Inserts a forward slash. | ||
| 1169 | |||
| 1170 | =head2 \# | ||
| 1171 | |||
| 1172 | Inserts a pound symbol. | ||
| 1173 | |||
| 1174 | =head1 INTERPRETER IMPLEMENTATION | ||
| 1175 | |||
| 1176 | Interpreters of RiveScript should follow these guidelines when interpreting | ||
| 1177 | RiveScript code. This details some of the priorities for processing tags and | ||
| 1178 | sorting internal data structures. This part of the document should be | ||
| 1179 | programming-language-independent. | ||
| 1180 | |||
| 1181 | =head2 STANDARD GLOBAL VARIABLES | ||
| 1182 | |||
| 1183 | The interpreter must support the following standard global variables: | ||
| 1184 | |||
| 1185 | depth = a recursion limit before an attempt to fetch a reply will be abandoned. | ||
| 1186 | |||
| 1187 | It's recommended to also have a C<debug> variable for consistency, but it may | ||
| 1188 | not be applicable. | ||
| 1189 | |||
| 1190 | The C<depth> variable is strongly encouraged, though. It's to set a user-defineable | ||
| 1191 | recursion limit when fetching a response. For example, a pair of triggers like | ||
| 1192 | this will cause infinite recursion: | ||
| 1193 | |||
| 1194 | + one | ||
| 1195 | @ two | ||
| 1196 | |||
| 1197 | + two | ||
| 1198 | @ one | ||
| 1199 | |||
| 1200 | The interpreter should protect itself against such possibilities and provide a | ||
| 1201 | C<depth> variable to allow the user to adjust the recursion limit. | ||
| 1202 | |||
| 1203 | ! global depth = 25 | ||
| 1204 | |||
| 1205 | =head2 PARSING GUIDELINES | ||
| 1206 | |||
| 1207 | Interpreters should parse all of the RiveScript documents ahead of time and | ||
| 1208 | store them in an efficient way in which replies can be looked up quickly. | ||
| 1209 | |||
| 1210 | =head3 Sorting +Triggers | ||
| 1211 | |||
| 1212 | Triggers should be sorted in a "most specific first" order. That is: | ||
| 1213 | |||
| 1214 | 1. Atomic triggers first. Sort them so that the triggers with the most amount | ||
| 1215 | of words are on top. For multiple triggers with the same amount of words, | ||
| 1216 | sort them by length, and then alphabetically if there are still matches | ||
| 1217 | in length. | ||
| 1218 | 2. Sort triggers that contain optionals in their triggers next. Sort them in | ||
| 1219 | the same manner as the atomic triggers. | ||
| 1220 | 3. Sort triggers containing wildcards next. Sort them by the number of words | ||
| 1221 | that aren't wildcards. The order of wildcard sorting should be as follows: | ||
| 1222 | |||
| 1223 | A. Alphabetic wildcards (_) | ||
| 1224 | B. Numeric wildcards (#) | ||
| 1225 | C. Global wildcards (*) | ||
| 1226 | |||
| 1227 | 4. The very bottom of the list will be a trigger that simply matches * by | ||
| 1228 | itself, if it exists. If triggers of only _ or only # exist, sort them in | ||
| 1229 | the same order as in step 3. | ||
| 1230 | |||
| 1231 | =head3 Sorting %Previous | ||
| 1232 | |||
| 1233 | C<% Previous> triggers should be sorted in the same manner as C<+ Triggers>, and | ||
| 1234 | associated with the reply group that they belong to (creating pseudotopics for | ||
| 1235 | each C<% Previous> is a good way to go). | ||
| 1236 | |||
| 1237 | =head3 Syntax Checking | ||
| 1238 | |||
| 1239 | It will be helpful if the interpreter also offers syntax checking and will give | ||
| 1240 | verbose warnings when it tries to parse something that doesn't follow standards. | ||
| 1241 | When possible, it should try to correct the error, but should still emit a | ||
| 1242 | warning so that the author might fix it. | ||
| 1243 | |||
| 1244 | It would also be good practice to keep track of file names and line numbers of | ||
| 1245 | each parsed command, so that syntax warnings can direct the author to the exact | ||
| 1246 | location where the problem occurred. | ||
| 1247 | |||
| 1248 | =head2 REPLY FETCHING | ||
| 1249 | |||
| 1250 | When attempting to get a response to a client's message, the interpreter should | ||
| 1251 | support the sending of a "sender ID" along with the message. This would preferably | ||
| 1252 | be a screen name or handle of the client who is sending the message, and the | ||
| 1253 | interpreter should be able to keep different groups of user variables for each | ||
| 1254 | user ID. The E<lt>idE<gt> tag should substitute for the user's ID. | ||
| 1255 | |||
| 1256 | If the BEGIN block was defined in any of the loaded RiveScript documents, it should | ||
| 1257 | be tried for the "request" trigger. That is, this trigger should be matched: | ||
| 1258 | |||
| 1259 | > begin | ||
| 1260 | + request | ||
| 1261 | - {ok} | ||
| 1262 | < begin | ||
| 1263 | |||
| 1264 | The interpreter should make the request for that trigger in the context of the | ||
| 1265 | calling user, and allow it to change the user's topic or set a user variable | ||
| 1266 | immediately. Do not process any other tags that are present in the response (see | ||
| 1267 | L<"TAG PRIORITY">). | ||
| 1268 | |||
| 1269 | If the response contains the C<{ok}> tag, then make a second request to try to | ||
| 1270 | match the client's actual message. When a response was found, substitute the | ||
| 1271 | C<{ok}> tag from the BEGIN response with the text of the actual response the | ||
| 1272 | client wanted, and then process any remaining tags in the BEGIN response. | ||
| 1273 | Finally, return the reply to the client. | ||
| 1274 | |||
| 1275 | When fetching responses, the following order of events should happen. | ||
| 1276 | |||
| 1277 | 1. Build in a system of recursion prevention. Since replies can redirect to | ||
| 1278 | other replies, there's the possibility of deep recursion. The first thing | ||
| 1279 | that the reply fetching routine should do is prevent this from getting out | ||
| 1280 | of control. | ||
| 1281 | 2. Dig through the triggers under the client's current topic. Check to see if | ||
| 1282 | there are any %Previous commands on any of these topics and see if they | ||
| 1283 | match the bot's last message to the client. If so, make sure the client's | ||
| 1284 | current message matches the trigger in question. If so, we have a response | ||
| 1285 | set; skip to step 4. | ||
| 1286 | 3. Find a trigger that matches the client's message. If one is found, we have | ||
| 1287 | a response set; continue to step 4. | ||
| 1288 | |||
| 1289 | 4. If we found a reply set, process the reply. First check if this reply set | ||
| 1290 | has a "solid redirection" (an @ command). If so, recurse the response | ||
| 1291 | routine with the redirection trigger and resume from step 1. Break when an | ||
| 1292 | eventual response was returned. | ||
| 1293 | 5. Process conditionals if they exist in order. As soon as one of them returns | ||
| 1294 | true, we have a response and break. If none are true, continue to step 6. | ||
| 1295 | 6. See if there is more than one response to this trigger. If any of the random | ||
| 1296 | responses has a {weight}, take that into account as a random response is | ||
| 1297 | chosen. If we have a reply now, break. | ||
| 1298 | 7. If there is still no reply, insert a generic "no reply" error message. | ||
| 1299 | |||
| 1300 | When a reply was obtained, then tags should be executed on them in the order | ||
| 1301 | defined under L<"TAG PRIORITY">. | ||
| 1302 | |||
| 1303 | =head2 TAG PRIORITY | ||
| 1304 | |||
| 1305 | =head3 Within BEGIN/Request | ||
| 1306 | |||
| 1307 | Within the "request" response of the BEGIN block, the following tags can be | ||
| 1308 | executed prior to getting a real response for the client's message: | ||
| 1309 | |||
| 1310 | {topic} | ||
| 1311 | <set> | ||
| 1312 | |||
| 1313 | All other tags, especially modifier tags, must be held off until the final | ||
| 1314 | response has been given. Substitute C<{ok}> for the final response, and then | ||
| 1315 | process the other tags. | ||
| 1316 | |||
| 1317 | Things like this should be able to work: | ||
| 1318 | |||
| 1319 | > begin | ||
| 1320 | |||
| 1321 | + request | ||
| 1322 | * <get name> eq undefined => {topic=new_user}{ok} | ||
| 1323 | * <bot mood> eq happy => {ok} | ||
| 1324 | * <bot mood> eq angry => {uppercase}{ok}{/uppercase} | ||
| 1325 | * <bot mood> eq sad => {lowercase}{ok}{/lowercase} | ||
| 1326 | - {ok} | ||
| 1327 | |||
| 1328 | < begin | ||
| 1329 | |||
| 1330 | =head3 Within +Trigger | ||
| 1331 | |||
| 1332 | All tags that appear within the context of C<+ Trigger> must be processed prior | ||
| 1333 | to any attempts to match on the trigger. | ||
| 1334 | |||
| 1335 | =head3 Within Replies | ||
| 1336 | |||
| 1337 | The order that the tags should be processed within a response or anywhere else | ||
| 1338 | that a tag is allowed is as follows: | ||
| 1339 | |||
| 1340 | <star> # Static text macros | ||
| 1341 | <input> # | ||
| 1342 | <reply> # | ||
| 1343 | <id> # | ||
| 1344 | \s # | ||
| 1345 | \n # | ||
| 1346 | \\ # | ||
| 1347 | \# # | ||
| 1348 | {random} # Random text insertion (which may contain other tags) | ||
| 1349 | <person> # String modifiers | ||
| 1350 | <formal> # | ||
| 1351 | <sentence> # | ||
| 1352 | <uppercase> # | ||
| 1353 | <lowercase> # | ||
| 1354 | <bot>* # Insert bot variables | ||
| 1355 | <env>* # Insert environment variables | ||
| 1356 | <set>* # User variable modifiers | ||
| 1357 | <add>* # | ||
| 1358 | <sub>* # | ||
| 1359 | <mult>* # | ||
| 1360 | <div>* # | ||
| 1361 | <get>* # Get user variables | ||
| 1362 | {topic} # Set user topic | ||
| 1363 | <@> # Inline redirection | ||
| 1364 | <call> # Object macros. | ||
| 1365 | |||
| 1366 | * The variable manipulation tags should all be processed "at the same time", | ||
| 1367 | not in any particular order. This will allow, for example, the following sort | ||
| 1368 | of trigger to work: | ||
| 1369 | |||
| 1370 | + my name is * | ||
| 1371 | * <get name> != undefined => | ||
| 1372 | ^ <set oldname=<get name>>I thought your name was <get oldname>? | ||
| 1373 | ^ <set name=<formal>> | ||
| 1374 | - <set name=<formal>>Nice to meet you. | ||
| 1375 | |||
| 1376 | In older implementations of RiveScript, `set` tags were processed earlier than | ||
| 1377 | `get` making it impossible to copy variables. Implementations should process | ||
| 1378 | this group of tags from the most-embedded outward. | ||
| 1379 | |||
| 1380 | An easy way to do this is with a regular expression that matches a tag that | ||
| 1381 | contains no other tag, and make multiple passes until no tags remain that match | ||
| 1382 | the regexp: | ||
| 1383 | |||
| 1384 | /<([^<]+?)>/ | ||
| 1385 | |||
| 1386 | =head1 REVERSE COMPATIBILITY | ||
| 1387 | |||
| 1388 | RiveScript 2.00 will have limited backwards compatibility with RiveScript 1.x | ||
| 1389 | documents. Here is a full breakdown of the differences: | ||
| 1390 | |||
| 1391 | RiveScript Changes from 1.02 to 2.00 | ||
| 1392 | ------------------------------------ | ||
| 1393 | |||
| 1394 | REMOVED: | ||
| 1395 | |||
| 1396 | - Variants of !DEFINITION | ||
| 1397 | - ! addpath | ||
| 1398 | - ! include | ||
| 1399 | - ! syslib | ||
| 1400 | - RiveScript Libraries (RSL files) | ||
| 1401 | - RiveScript Packages (RSP files) | ||
| 1402 | - These made code management messy. Keep your own | ||
| 1403 | brain's files together! | ||
| 1404 | |||
| 1405 | COMPATIBLE CHANGES: | ||
| 1406 | |||
| 1407 | - Object macros now require the programming language to be defined. | ||
| 1408 | - Old way: > object encode | ||
| 1409 | - New way: > object encode perl | ||
| 1410 | - The ^CONTINUE command can extend every command. | ||
| 1411 | - Most tags can be used with almost every command. | ||
| 1412 | - Topics can inherit triggers from other topics now. | ||
| 1413 | |||
| 1414 | INCOMPATIBLE CHANGES: | ||
| 1415 | |||
| 1416 | - Conditionals work differently now. Instead of comparing variables to values, | ||
| 1417 | they compare values to values, and each value can <get> variables to compare. | ||
| 1418 | - Old way: * name = Bob => Hello Bob! | ||
| 1419 | - New way: * <get name> eq Bob => Hello Bob! | ||
| 1420 | - Conditionals no longer use a single = for "equal to" comparison. Replace it | ||
| 1421 | with either == or "eq". | ||
| 1422 | - Object macros will receive a reference to the RiveScript object as their first | ||
| 1423 | argument. | ||
| 1424 | - Objects are called in a new <call> syntax instead of the old &object one. | ||
| 1425 | |||
| 1426 | NEW THINGS: | ||
| 1427 | |||
| 1428 | - {weight} is a valid tag in triggers now to increase matching priority. | ||
| 1429 | - <env> has been added for calling global variables. | ||
| 1430 | - <botstar> has been added for wildcard matching on %previous. | ||
| 1431 | - Conditionals have more inequality comparisons now: | ||
| 1432 | "==" and "eq" : equal to | ||
| 1433 | "!=", "ne", and "<>" : not equal to | ||
| 1434 | |||
| 1435 | Nice interpreters might be able to fix some old RiveScript code to make them work. | ||
| 1436 | For example, if a condition is found that has one equals sign instead of two, it | ||
| 1437 | could print a warning that it's detected RiveScript 1.x code in action and | ||
| 1438 | automatically adjust it to 2.x standards, and perhaps reparse the entire file or | ||
| 1439 | group of files, assuming that they are RiveScript 1.x code and fix these | ||
| 1440 | inconsistencies altogether. | ||
| 1441 | |||
| 1442 | Or perhaps there will just be a converter tool created that would go through code | ||
| 1443 | that it already assumes will be RiveScript 1.x and update it to 2.x standards. | ||
| 1444 | |||
| 1445 | =head1 REVISIONS | ||
| 1446 | |||
| 1447 | Rev 12 - Nov 30, 2014 | ||
| 1448 | - Added implementation guidelines for dealing with variable-setting tags. | ||
| 1449 | |||
| 1450 | Rev 11 - Jun 13, 2013 | ||
| 1451 | - Clarify the ability for the <bot> and <env> tags to be used for assignment. | ||
| 1452 | |||
| 1453 | Rev 10 - May 15, 2012 | ||
| 1454 | - Deprecated the {!...} tag. It was intended for reassigning global or bot | ||
| 1455 | variables. Instead use <env name=value>, <bot name=value>. | ||
| 1456 | |||
| 1457 | Rev 9 - Jul 31, 2009 | ||
| 1458 | - Added more explicit details on the usage of the BEGIN block, under the | ||
| 1459 | section on >Labels / "begin" | ||
| 1460 | - Revised the WD, fixing some typos. | ||
| 1461 | |||
| 1462 | Rev 8 - Jul 30, 2009 | ||
| 1463 | - The proper format for the `! version` line is to be `! version = 2.00`, | ||
| 1464 | and not `! version 2.00` | ||
| 1465 | - Included the "includes" option for triggers and changed how "inherits" | ||
| 1466 | works. | ||
| 1467 | |||
| 1468 | Rev 7 - Dec 4, 2008 | ||
| 1469 | - Topics are able to inherit additional triggers that belong to different | ||
| 1470 | topics, in the "> topic alpha inherits beta" syntax. | ||
| 1471 | - Added more documentation to the "! array" section of the document. Also | ||
| 1472 | check that section for some changes to the way arrays should be processed by | ||
| 1473 | the interpreter. | ||
| 1474 | - Deprecated the # command for inline comments. Use only // and /* */. | ||
| 1475 | |||
| 1476 | Rev 6 - Sep 15, 2008 | ||
| 1477 | - Updated the section about # for inline comments: when used next to a | ||
| 1478 | +Trigger, there should be at least 2 spaces before the # symbol and 1 space | ||
| 1479 | after, to avoid confusion with # as a wildcard character. | ||
| 1480 | |||
| 1481 | Rev 5 - Jul 22, 2008 | ||
| 1482 | - Added two new variants of the wildcard: # will match only numbers and _ will | ||
| 1483 | match only letters. * will still match anything at all. | ||
| 1484 | |||
| 1485 | Rev 4 - Jun 19, 2008 | ||
| 1486 | - Rearranged tag priorities: | ||
| 1487 | - <bot> and <env> moved higher up. | ||
| 1488 | |||
| 1489 | Rev 3 - Apr 2, 2008 | ||
| 1490 | - Typo fix: under the !person section, the examples were using !sub | ||
| 1491 | - Inconsistency fix: under %Previous it was saying the wildcards were | ||
| 1492 | unmatchable, but this isn't the case (they go into <botstar>). | ||
| 1493 | - Typo fix: under OBJECT MACROS, fixed the explanation of the code to match | ||
| 1494 | the new object syntax. | ||
| 1495 | - Inconsistency fix: <@> can be used in the response portion of conditionals. | ||
| 1496 | - Rearranged the tag priorities: | ||
| 1497 | - String modifiers (person - lowercase) come in higher priority than | ||
| 1498 | {random} | ||
| 1499 | - <env> comes in after <bot> | ||
| 1500 | - Typo fix: updated the object syntax (<call>) in the priority list. | ||
| 1501 | |||
| 1502 | Rev 2 - Feb 18, 2008 | ||
| 1503 | - Moved {random} to higher tag priority. | ||
| 1504 | - Change the &object syntax to <call> | ||
| 1505 | - Added the <env> variable. | ||
| 1506 | - Added the <botstar> variable. | ||
| 1507 | |||
| 1508 | Rev 1 - Jan 15, 2008 | ||
| 1509 | - Added the {priority} tag to triggers, to increase a trigger's matching | ||
| 1510 | priority over others, even when another trigger might be a better match | ||
| 1511 | to the client's message. | ||
| 1512 | |||
| 1513 | =head1 DISCLAIMER | ||
| 1514 | |||
| 1515 | Note that this document is only a working draft of the RiveScript 2.00 | ||
| 1516 | specification and may undergo numerous changes before a final standard is | ||
| 1517 | agreed on. Changes to this document after the creation date on January 14, 2008 | ||
| 1518 | will be noted in a change log. | ||
| 1519 | |||
| 1520 | http://www.rivescript.com/ | ||
| 1521 | |||
| 1522 | =cut |