RiveScript/WD.pm untested

filter: Statementstmt 0.0% 0 / 10 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 3 Podpod n/a totaltotal 0.0% 0 / 13 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
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