view release on metacpan or  search on metacpan

lib/Chatbot/Alpha.pm  view on Meta::CPAN

  
  # 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");

=head1 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.

B<Note: This module is obsolete!> Alpha was superceded by a more powerful language, rewritten from scratch,
called L<RiveScript>. Chatbot::Alpha was allowed (and will be allowed) to remain here only because there are
a few incompatibilities in the reply files. If you haven't used Alpha yet, I urge you to use RiveScript instead.
If you've already invested time in writing reply files for Alpha, know that this module isn't going anywhere.
However, this module is no longer actively maintained (and hasn't been in a number of years).

See L<RiveScript>.

=head1 METHODS

=head2 new (ARGUMENTS)

Creates a new Chatbot::Alpha object. Pass in any default arguments (in hash form). Default arguments are
B<debug> (debug mode; defaults to 0) and B<verify> (to run syntax checking, defaults to 1).

Returns a Chatbot::Alpha instance.

=head2 version

Returns the version number of the module.

=head2 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.

=head2 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.

=head2 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.

=head2 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.

B<Update with v 1.7> - 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.

=head2 setVariable (VARIABLE, VALUE)

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

=head2 removeVariable (VARIABLE)

Removes an internal variable.

=head2 clearVariables

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

=head2 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.

=head2 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.

=head2 stringUtil (TYPE, STRING)

Called on internally for the string modification tags. TYPE would be uppercase, lowercase, formal, or sentence. String
would be the string to modify. Returns the modified string.

=head1 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:

=head2 + (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.

=head2 ~ (Tilde)

The ~ command is another version of the trigger, added in version 2.03. The contents of this command would be a regexp
pattern. Any parts that would normally be put into $1 to $9 can be obtained in <star1> to <star9>.

Example:

  ~ i (would have|would\'ve) done it
  - Do you really think you <star1> done it?