/ 
Chatbot-Alpha-2.00
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->loadFolder ("./replies");

# Load an additional response file.
$alpha->loadFile ("./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.

loadFolder (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.

loadFile (FILE_PATH[, STREAM])

Loads a single file. The "loadFolder" 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.

sortReplies

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.

Update with v 7.1 - Reply sorting method reprogrammed: items are sorted with solid triggers first, then those with wildcards and 16 whole words, then 15 whole words, 14, etc. and then unknown triggers, followed lastly by those that contain NO full words.

setVariable (VARIABLE, VALUE)

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

removeVariable (VARIABLE)

Removes an internal variable.

clearVariables

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.

% (Percent)

This is used as a "that" -- that is, an emulation of the <that> tag in AIML. The value of this would be Alpha's last reply, lowercase and without any punctuation. There's an example of this in the example reply code below.

- (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++).

ALPHA TAGS

These tags can be used within Alpha -REPLIES, some of which may be used also in @REDIRECTS.

{topic=...}

Sets a topic. Set topic to random to return to the default topic.

{@trigger}

Include a redirection within another response. Example:

+ * or something
- Or something. {@<star1>}

"Your stupid or something?"
"Or something. At least I know the difference between "your" and "you're.""

<msg>

This can only be used in &HOLDERS, it inserts the user's message (for example a knock-knock joke convo).

EXAMPLE ALPHA CODE

// Test Replies

// Chatbot-Alpha 2.0 - Mid-sentence redirections.
+ redirect test
- If you said hello I would've said: {@hello} But if you said whats up I'd say: {@whats up}

// Redirect test with <star1>.
+ i say *
- Indeed you do say. {@<star1>}

// 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 "that" test.
+ i hate you
- You're really mean... =(

+ sorry
% youre really mean
- Don't worry--it's okay. :-)

// A test of having two of the same trigger in different topics.
+ sorry
- Why are you sorry?

// A simple one-reply response to "what's up"
+ whats 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

// Wildcard Tests
+ my name is *
- Nice to meet you <star1>.
+ i am * years old
- Many people are <star1>.

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

+ is my name bob
* name=bob::Yes, that's your name.
- No your name is not Bob.

// 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}

// 1.71 Test - Single wildcards should sort LAST, so this could be
// used as a "I can't reply to that" reply.
+ *
- Hm, I'm going to have to think about that one for a minute.
- I'm sorry, but I can't answer that!
- I really don't know what to say to that one...

> 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

CHATBOT-ALPHA 2.X

The following changes have been made from Chatbot-Alpha 1.x to 2.x

- Methods have been renamed:
  load_folder     => loadFolder
  load_file       => loadFile
  sort_replies    => sortReplies
  set_variable    => setVariable
  remove_variable => removeVariable
  clear_variables => clearVariables

- Methods that have been REMOVED:
  default_reply*

- Alpha commands added:
  %THAT

- Alpha commands changed:
  *CONDITION
  New format:
    *VAR=VALUE::REPLY

* Set a trigger of just an asterisk to set up a fallback for when no better
  response is found. Example:

  + *
  - I don't know how to reply to your message!

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 2.00
- Added some AIML emulation:
  - In-reply redirections (like <srai>):
       + * or something
       - Or something. {@<star1>}
  - "That" kind of support.
       + i hate you
       - You're really mean... =(

       + sorry
       % youre really mean
       - Don't worry--it's okay. :-)
- Renamed all methods to be alternatingCaps instead of with underscores.
- Chatbot::Alpha::Syntax supports the newly-added commands.
- Fixed conditionals, should work more efficiently now:
  - Format changed to *VARIABLE=VALUE::HAPPENS
  - Does numeric == for numbers, or eq for strings... = better matching.

Version 1.71
- Redid sorting method. Sometimes triggers such as I AM * would match
  before I AM * YEARS OLD.

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
- "sortReplies" 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.

SEE ALSO

Chatbot::Alpha::Tutorial

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