/ 
Chatbot-Alpha-1.70
River stage zero No dependents
/ Chatbot::Alpha

NAME

Chatbot::Alpha - A simple chatterbot brain.

SYNOPSIS

use Chatbot::Alpha;

# Create a new Alpha instance.
my $alpha = new Chatbot::Alpha();

# Load replies from a directory.
$alpha->load_folder ("./replies");

# Load an additional response file.
$alpha->load_file ("./more_replies.txt");

# Input even more replies directly from Perl.
$alpha->stream ("+ what is alpha\n"
              . "- Alpha, aka Chatbot::Alpha, is a chatterbot brain created by AiChaos Inc.\n\n"
              . "+ who created alpha\n"
              . "- Chatbot::Alpha was created by Cerone Kirsle.");

# Get a response.
my $reply = $alpha->reply ("user", "hello alpha");

DESCRIPTION

The Alpha brain was developed by AiChaos, Inc. for our chatterbots. The Alpha brain's language is line-by-line, command-driven. Alpha is a simplistic brain yet is very powerful for making impressive response systems.

METHODS

new (ARGUMENTS)

Creates a new Chatbot::Alpha object. Pass in any default arguments (in hash form). Avoid arguments with underscores and the "stream" key. These are reserved.

Returns a Chatbot::Alpha instance.

version

Returns the version number of the module.

load_folder (DIRECTORY[, TYPES])

Loads a directory of response files. The directory name is required. TYPES is the file extension of your response files. If TYPES is omitted, every file is considered a response file.

Just as a side note, the extension agreed upon for Alpha files is .CBA, but the extension is not important.

load_file (FILE_PATH[, STREAM])

Loads a single file. The "load_folder" method calls this for each valid file. If STREAM is 1, the current contents of the stream cache will be loaded (assuming FILE_PATH is omitted). You shouldn't need to worry about using STREAM, see the "stream" method below.

stream (ALPHA_CODE)

Inputs a set of Alpha code directly into the module ("streaming") rather than loading it from an external document. See synopsis for an example.

default_reply (RANDOM|RANDOM|RANDOM)

Sets up a default response in case there is no trigger for the message in your reply code. Separate random replies using pipes. See "Tips and Tricks" below for some clever ways to handle default_reply.

sort_replies

Sorts the replies already loaded: solid triggers go first, followed by triggers containing wildcards. If you fail to call this method yourself, it will be called automatically when "reply" is called.

set_variable (VARIABLE, VALUE)

Sets an internal variable. These are used primarily in conditionals in your Alpha responses.

remove_variable (VARIABLE)

Removes an internal variable.

clear_variables

Clears all internal variables (only those set with set_variable).

reply (ID, MESSAGE)

Scans the loaded replies to find a response to MESSAGE. ID is a unique ID for the particular person requesting a response. The ID is used for things such as topics and conversation holders. Returns a reply, or one of default_reply if a better response wasn't found.

search (MESSAGE)

Scans the loaded replies to find any triggers that match MESSAGE. Will return an array containing every trigger that matched the message, including their filenames and line numbers.

ALPHA LANGUAGE TUTORIAL

The Alpha response language is a line-by-line command-driven language. The first character on each line is the command (prepent white spaces are ignored). Everything following the command are the command's arguments. The commands are as follows:

+ (Plus)

The + symbol indicates a trigger. Every Alpha reply begins with this command. The arguments are what the trigger is (i.e. "hello chatbot"). If the message matches this trigger, then the rest of the response code is considered. Else, the triggers are skipped over until a good match is found for the message.

- (Minus)

The - symbol indicates a response to a trigger. This and all other commands (except for > and <) always go below the + command. A single + and a single - will be a one-way question/answer scenario. If more than one - is used, they will become random replies to the trigger. If conditionals are used, the -'s will be considered if each conditional is false. If a conversation holder is used, the - will be the first reply sent in the conversation. See the example code below for examples.

^ (Carat)

The ^ symbol indicates a continuation of your last - reply. This command can only be used after a - command, and adds its arguments to the end of the arguments of the last - command. See the example code for an example.

@ (At)

The @ symbol indicates a redirection. Alpha triggers are "dead-on" triggers, meaning pipes can't be used to make multiple matchibles for one reply. In the case you would want more than one trigger (i.e. "hello" and "hey"), you use the @ command to redirect them to eachother. See the example code below.

* (Asterisk)

The * command is for conditionals. At this time conditionals are very primative:

* if variable = value::this reply is sent back

More/better support for conditionals may or may not be added in the future.

& (Amperstand)

The & command is for conversation holders. Each & will be called in succession once the trigger has been matched. Each message, no matter what it is, will call the next one down the line. This is also the rare case in which a "<msg>" tag can be included in the response, for capturing the user's message. See the example code.

# (Pound)

The # command is for executing actual Perl codes within your Alpha responses. The # commands are executed last, after all the other reply handling mechanisms are completed. So in this sense, it's always a good idea to include at least one reply (-) to fall back on in case the Perl code fails.

> (Greater Than)

The > starts a labeled piece of code. At this time, the only label supported is "topic" -- see "TOPICS" below.

< (Less Than)

This command closes a label.

/ (Forward Slash)

The / command is used for comments (actually two /'s is the standard, as in Java and C++).

EXAMPLE ALPHA CODE

// Test Replies

// Chatbot-Alpha 1.7 - A reply with continuation...
+ tell me a poem
- Little Miss Muffet,\n
  ^ sat on her tuffet,\n
  ^ in a nonchalant sort of way.\n\n
  ^ With her forcefield around her,\n
  ^ the spider, the bounder\n
  ^ is not in the picture today.

// Chatbot-Alpha 1.7 - Check syntax errors on deep recursion.
+ one
@ two

+ two
@ one

// A standard reply to "hello", with multiple responses.
+ hello
- Hello there!
- What's up?
- This is random, eh?

// A simple one-reply response to "what's up"
+ what's up
- Not much, you?

// A test using <star1>
+ say *
- Um.... "<star1>"

// This reply is referred to below.
+ identify yourself
- I am Alpha.

// Refers the asker back to the reply above.
+ who are you
@ identify yourself

// Conditionals Test
+ am i your master
* if master = 1::Yes, you are my master.
- No, you are not my master.

// Perl Evaluation Test
+ what is 2 plus 2
# $reply = "2 + 2 = 4";

// A Conversation Holder: Knock Knock!
+ knock knock
- Who's there?
& <msg> who?
& Ha! <msg>! That's a good one!

// A Conversation Holder: Rambling!
+ are you crazy
- I was crazy once.
& They locked me away...
& In a room with padded walls.
& There were rats there...
& Did I mention I was crazy once?

// Topic Test
+ you suck
- And you're very rude. Apologize now!{topic=apology}

> topic apology

   + *
   - No, apologize for being so rude to me.

   // Set {topic=random} to return to the default topic.
   + sorry
   - See, that wasn't too hard. I'll forgive you.{topic=random}

< topic

TOPICS

As seen in the example code, Chatbot::Alpha has support for topics.

Setting a Topic

To set a topic, use the {topic} tag in a response:

+ play hangman
- Alright, let's play hangman.{topic=hangman}

Use the > and < commands (labels) to specify a section of code for the topic to exist in.

> topic hangman
  + *
  - 500 Internal Error. Type "quit" to quit.
  # $reply = &main::hangman ($msg);

  + quit
  - Done playing hangman.{topic=random}
< topic

The default topic is "random" -- setting the topic to random breaks out of code-defined topics. When in a topic, any triggers that aren't in that topic are not available for reply matching. In this way, you can have the same trigger many times but under different topics without them interfering with one another.

ERROR CATCHING

With Chatbot::Alpha 1.7, the module keeps filenames and line numbers with each command it finds (kept in $alpha->{_syntax} in the same order as $alpha->{_replies}). In this way, internal errors such as deep recursion can return filenames and line numbers. See the example code for a way to provoke this error.

ERR: Deep Recursion (15+ loops in reply set) at ./testreplies.txt line 17

TIPS AND TRICKS

Things to do with default_reply

One trick you can do with default_reply is set it to something totally random like "alpha no reply matched". When you're getting a reply, if the reply turns out to be "alpha no reply matched" you can go back into Alpha with another reply call, but call something like "wildcard" as the trigger. In your response code, you could then add a trigger that would be called when nothing else could be found.

KNOWN BUGS

- Conversation holders aren't always perfect. If a different trigger
  was matched 100% dead-on, the conversation may become broken.
- If a bogus topic is started (a topic with no responses) there is
  no handler for repairing the topic.

CHANGES

Version 1.7
- Chatbot::Alpha::Syntax added.
- ^ command added.
- Module keeps filenames and line numbers internally, so on internal
  errors such as 'Deep Recursion' and 'Infinite Loop' it can point you
  to the source of the problem.
- $alpha->search() method added.

Version 1.61
- Chatbot::Alpha::Sort completed.

Version 1.6
- Created Chatbot::Alpha::Sort for sorting your Alpha documents.

Version 1.5
- Added "stream" method, revised POD.

Version 1.4
- Fixed bug with wildcard subsitutitons.

Version 1.3
- Added the ">" and "<" commands, now used for topics.

Version 1.2
- "sort_replies" method added

Version 1.1
- Fixed a bug in reply matching with wildcards.
- Added a "#" command for executing System Commands.

Version 1.0
- Initial release.

FUTURE PLANS

- Add a command for long responses so that they can continue on multiple
  lines. For example:

     + hello bot
     - Hello there human. This reply is_
       ^ very very long and needs to span_
       ^ across multiple lines.

- Create a Chatbot::Alpha::Sort module for taking your already existing external
  Alpha documents and sorting the triggers, i.e. to make them alphabetic, like
  standard AIML is.

SEE ALSO

Chatbot::Alpha::Sort

AUTHOR

Cerone J. Kirsle, cjkirsle "@" aichaos.com

COPYRIGHT AND LICENSE

Chatbot::Alpha - A simple chatterbot brain.
Copyright (C) 2005  Cerone J. Kirsle

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA