=head1 INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install


=head1 Package Name

AUBBC

=head1 Description

 AUBBC - (Advanced Universal Bulletin Board Code)
 Tags used to create formatting effects in HTML & XHTML.

=head1 Abstract

 The advantage of using this Bulletin Board Code tags is to restrict the usage of HTML/XHTML elements and
 to make formating of posts easy to people that have no HTML/XHTML skill. Most sites that use these tags show a list of them and/or easy way to insert the tags to the form field by the user.

 This module addresses many security issues the UBBC tags may have mainly cross site script also known as XSS.
 Each message is sanitized/escaped before it gets returned if script_escape is Enabled and checked for many types of security problems before that tag converts to HTML/XHTML.

 Allows easy conversion to HTML and XHTML, existing tags will convert to the HTML type set.

 If there isn't a popular tag available this module provides a method to "Build your own tags" custom tags can help link to parts of the current web page, other web pages and add other HTML elements.

=head1 Settings

=head2 $aubbc->settings();

This is a list of Default settings and the method to change them when needed.

     $aubbc->settings(
        aubbc => 1,
        utf => 1,
        smileys => 1,
        highlight => 1,
        no_bypass => 0,
        for_links => 0,
        aubbc_escape => 1,
        icon_image => 1,
        image_hight => 60,
        image_width => 90,
        image_border => 0,
        image_wrap => 1,
        href_target => 0,
        images_url => '',
        html_type => 'html',
        code_class => '',
        code_extra => '',
        href_class => '',
        quote_class => '',
        quote_extra => '',
        bad_pattern => 'view\-source:|script:|mocha:|mailto:|about:|shell:|\.js',
        script_escape => 1,
        protect_email => 1,
      );

=head2 aubbc

Enable or Disable Main AUBBC Tags Default 1 is Enabled, 0 is Disable.

=head2 utf

Enable or Disable UFT Tags Default 1 is Enabled, 0 is Disable.

=head2 smileys

Enable or Disable Smiley Tags Default 1 is Enabled, 0 is Disable.

=head2 highlight

Enable or Disable Code Highlight Default 1 is Enabled, 0 is Disable.

=head2 no_bypass

Enable or Disable User Tags for Bypassing Tags Default 0 is Disable, 1 is Enabled.

 Tags must at the very beginning of the message.
  Bypass Tags:
  #none
  #noaubbc
  #nobuild
  #noutf
  #nosmileys

=head2 for_links

 Enable or Disable Use Tags for Links Default 0 is Disable, 1 is Enabled.

 Some AUBBC Tags are not good to use in a link like other links.

 If Enabled will only use the UTF and Smiley tags.

=head2 aubbc_escape

Enable or Disable AUBBC Tag Escape Default 1 is Enabled, 0 is Disable.

 Escaping a Tag:
  [b]Stuff[/b] # Normal Tag Bold
  [b]]Stuff[/b]] # Escaped Tag Bold
  [[b]Stuff[[/b] # Escaped Tag Bold
  [[b]]Stuff[[/b]] # Escaped Tag Bold
  [b}}Stuff[/b}} # Escaped Tag Bold
  {{b]Stuff{{/b] # Escaped Tag Bold
  {{b}}Stuff{{/b}} # Escaped Tag Bold

 Bugs if Enabled:

 Any use of }} will equal ] and any {{ will equal [

 Any use of ]] will equal ] and any [[ will equal [

=head2 icon_image

 Enable or Disable Custom Image Size Default 1 is Enabled, 0 is Disable.

 If enabled will use the values from image_hight and image_width

 in all Image Tags [img]/images/large_pic.gif[/img]

=head2 image_hight

 The Default Image hight is 60px.

 Only used when icon_image is Enabled.

=head2 image_width

 The Default Image width is 90px.

 Only used when icon_image is Enabled.

=head2 image_border

Enable or Disable Image Border Default 0 is Disable, 1 is Enabled.

=head2 image_wrap

 Enable or Disable Image wrap Default 1 is Enabled, 0 is Disable.

 Enabled will add a space after each image & smiley's.

=head2 href_target

 Enable or Disable href target Default 0 is Disable, 1 is Enabled.

 Enabled will add target="_blank" to all href's.

=head2 images_url

 Default is blank.

 This is the link to your images folder and is only used for Smilies.

 For the smileis to work you must provide a URL.

 example:

 smilies must be in /smilies folder

 the images_url link must have the /smilies folder in it and not point directly to /smilies.

=head2 html_type

Default is 'html' and the only other support is 'xhtml'

=head2 code_class

 Default is '' and this allows a custom class, style and/or javascript to be used in any of the [code] [c] tags.

 must have a space before the text.

 example:

 code_class => ' class="quote"',

 code_class => ' class="quote" onclick="....."',

=head2 code_extra

Default is '' and this is for a custom message, code, image, est.. to be used after the [code] [c] tags.

 example:

 code_extra => 'Codes may not reflect what is in the current version.',

 code_extra => '<div style="clear: left"> </div>',

=head2 href_class

Default is '' and this allows a custom class, style and/or javascript to be used in the [url] tags.

 must have a space before the text.

 example:

 href_class => ' class="url"',
 href_class => ' class="url" onclick="....."',

=head2 quote_class

Default is '' and this allows a custom class, style and/or javascript to be used in the [quote] tags.

 must have a space before the text.

 example:

  quote_class => ' class="quote"',
  quote_class => ' class="quote" onclick="....."',

=head2 quote_extra

Default is '' and this is for a custom message, code, image, est.. to be used after a [quote] tags.

example:

  quote_extra => 'QUOTES AND SAYINGS DISPLAYED ON THIS BLOG ARE NOT WRITTEN BY THE AUTHOR OF THE BLOG.',
  quote_extra => '<div style="clear: left"> </div>',

=head2 bad_pattern

Default is 'view\-source:|script:|mocha:|mailto:|about:|shell:|\.js' and this restricts the use of characters used in all [img] tags.

=head2 script_escape

This will turn on or off the sanitizer/escape security for the hole message.

Default is 1 on and 0 for Disable.

Notes: 1)The code highlighter works best with an escaped character format like the
script_escape => 1 setting can provide.

2) If this setting is disabled and a character escaping method or security filter is not used
can result is a security compromise of the AUBBC tags.

3) if Disabled the method "$message = $aubbc->script_escape($message);" can be used on the message as needed before do_all_ubbc() is called.


=head2 protect_email

  Default is 1 and other possible values are (0, 2, 3, 4).

  Can add a protection to hide emails in the [email] tag from email harvesters.


  Not 100% fool proof.

        0 - has no type of protection.


        1 - uses unicode type protection.


        2 - uses javascript and unicode type protection.


        3 - Javascript, random function and var names and unicode type protection.


        4 - Javascript encryption with random function and var names



=head1 Smilies Settings

These are the settings for using custom smilies.

Note: There are no Built-in smilies.

=head2 $aubbc->smiley_hash();

This is one of the two ways to import your custom smilies hash.

example:

  use AUBBC;
  my $aubbc = new AUBBC;
  my %smiley = (lol => 'lol.gif');
  $aubbc->smiley_hash(%smiley);

The way you use this smiley is [lol]

Must have the images_url set to the proper location.

images_url/smilies/lol.gif

=head2 %AUBBC::SMILEYS

This is one of the two ways to import your custom smiley hash.

example:

  my %smiley = (lol => 'lol.gif');
  use AUBBC;
  %AUBBC::SMILEYS = %smiley;
  my $aubbc = new AUBBC;

The way you use this smiley is [lol]

Must have the images_url set to the proper location.

images_url/smileis/lol.gif

=head1 Build your own tags

These are the settings and methods for using custom tags.

=head2 $aubbc->add_build_tag(name=>'stuff', pattern=>'stuff' , type=>'stuff', function=>'stuff');

name - will be the tags name

pattern - limited to 'all' or 'l,n,-,:,_,s'

    'all' = 'a-z\d\:\-\s\_\/\.\;\&\=\?\-\+\#\%\~\,\|'
    'l' = 'a-z'
    'n' = '0-9'
    's' = ' '
    '-' = '-'
    ':' = ':'
    '_' = '_'

type - 1 is style [name://pattern], 2 is style [name]pattern[/name] and 3 is style [name]

function - a pre-defined subroutine that receives the matched pattern, tag name and returns what you want,

   Note: if the function returns undefined, '' or 0 the tag will not be changed.

Usage:

  package My_Message;

  use AUBBC;
  my $aubbc = new AUBBC;

  $aubbc->add_build_tag(
        name     => 'ok',
        pattern  => 'l,s',
        type     => 1,
        function => 'My_Message::check_ok_tag',
        );
  $aubbc->add_build_tag(
        name     => 'ip',
        pattern  => '',
        type     => 3,
        function => 'My_Message::get_some_tag',
        );
  $aubbc->add_build_tag(
        name     => 'agent',
        pattern  => '',
        type     => 3,
        function => 'My_Message::get_some_tag',
        );

  my @other_sites =
        ('cpan','google','wikisource','ws','wikiquote','wq','wikibooks','wb','wikipedia','wp');
  foreach my $tag (@other_sites) {
  $aubbc->add_build_tag(
        name     => $tag,
        pattern  => 'all',
        type     => 1,
        function => 'My_Message::other_sites',
        );
  }

  $aubbc->add_build_tag(
        name     => 'time',
        pattern  => '',
        type     => 3,
        function => 'My_Message::other_sites',
        );

  my $message = <<TEXT;
  [ok://test me] [ok://test other] [ok://n0 w00rk] [ip] [agent]
  [google://Google] Google Search
  [wp://Wikipedia:About] or  [wikipedia://Wikipedia:About] Wikipedia
  [wb://Wikibooks:About] or [wikibooks://Wikibooks:About] Wikibooks
  [wq://Wikiquote:About] or [wikiquote://Wikiquote:About] Wikiquote
  [ws://Wikisource:About_Wikisource] or [wikisource://Wikisource:About_Wikisource] Wikisource
  [cpan://Cpan] Cpan Module Search
  [time] Time
  TEXT

  $message = $aubbc->do_all_ubbc($message);

  print $message;

  sub check_ok_tag {
  my ($tag_name, $text_from_AUBBC) = @_;

   if ($text_from_AUBBC eq 'test me') {
        return 'Works Good 1';
        }
         else {
               return 'Works Good 2';
               }
  }

  sub get_some_tag {
  my ($tag_name, $text_from_AUBBC) = @_;
  lc($tag_name);
  $text_from_AUBBC = $ENV{'REMOTE_ADDR'} if ($tag_name eq 'ip');
  $text_from_AUBBC = $ENV{'HTTP_USER_AGENT'} if ($tag_name eq 'agent');
  return $text_from_AUBBC;
  }

  sub other_sites {
  my ($tag_name, $text_from_AUBBC) = @_;

  # cpan modules
  # http://search.cpan.org/search?mode=module&query=Net%3A%3ASyslog
  $text_from_AUBBC = "<a href=\"http://search.cpan.org/search?mode=module&query=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if $tag_name eq 'cpan';

  # wikipedia Wiki
  # http://wikipedia.org/wiki/Special:Search?search=search%20terms
  $text_from_AUBBC = "<a href=\"http://wikipedia.org/wiki/Special:Search?search=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if ($tag_name eq 'wikipedia' || $tag_name eq 'wp');

  # wikibooks Wiki Books
  # http://wikibooks.org/wiki/Special:Search?search=search%20terms
  $text_from_AUBBC = "<a href=\"http://wikibooks.org/wiki/Special:Search?search=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if ($tag_name eq 'wikibooks' || $tag_name eq 'wb');

  # wikiquote Wiki Quote
  # http://wikiquote.org/wiki/Special:Search?search=here&go=Go
  $text_from_AUBBC = "<a href=\"http://wikiquote.org/wiki/Special:Search?search=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if ($tag_name eq 'wikiquote' || $tag_name eq 'wq');

  # wikisource Wiki Source
  # http://wikisource.org/wiki/Special:Search?search=
  $text_from_AUBBC = "<a href=\"http://wikisource.org/wiki/Special:Search?search=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if ($tag_name eq 'wikisource' || $tag_name eq 'ws');

  # google search
  # http://www.google.com/search?q=search%20terms
  $text_from_AUBBC = "<a href=\"http://www.google.com/search?q=$text_from_AUBBC\" target=\"_blank\">$text_from_AUBBC</a>" if $tag_name eq 'google';

  # localtime()
  if ($tag_name eq 'time') {
        my $time = scalar(localtime);
        $text_from_AUBBC = "<b>[$time]</b>";
        }
        return $text_from_AUBBC;
  }
  1;

=head2 $aubbc->remove_build_tag($name, $option);

There are two ways to use this.

1) Remove a single built tag: $aubbc->remove_build_tag($name);

2) Remove all built tags: $aubbc->remove_build_tag('', 1);

=head1 Error Message

=head2 $AUBBC::BAD_MESSAGE

Default message is 'Error', this message is used when the code finds bad characters in [email] or [img] tags.

 Usage of this setting:

  use AUBBC;
  $AUBBC::BAD_MESSAGE = 'Unauthorized use of characters or pattern in this tag.';
  # est...

=head1 Debug

The Debug setting will send a lot of messages to warn and is not recommended to leave on all the time.

=head2 $AUBBC::DEBUG_AUBBC

 Default is '' off, and Enabled is 1.

 Usage of this setting:

  use AUBBC;
  $AUBBC::DEBUG_AUBBC = 1;
  # est...

=head1 Version

Returns the current version of the module.

=head2 $aubbc->version();


 Usage:

  use AUBBC;
  my $aubbc = new AUBBC;

  my $Current_Version = $aubbc->version();

  print $Current_Version;

=head1 History

v1.10 - 09/02/2008 09:49:46

Added two more tags [big]..[/big] and [small]..[/small].

Removed utf tag style [ux23] and [u://0931] to make more tag names available.

Changed add_build_tag() to use hash variable, see "Build your own tags" for the new style.

Changed the way functions should work for built tags, the custom function for built tags will receive the tag name and data of the tag. This is so one function can handle many tags.

Removed other site tags and setting other_sites_pattern, an example of them are in "Build your own tags"

Removed [time] tag, example in "Build your own tags".

Email now allows names with & sign

Now every message that is passed to do_all_ubbc() gets escaped before being returned if script_escape is Enabled.

All tags in %AUBBC_TAGS will only convert if lowercase.

"new" now uses the most standard referenced object method.

Removed DOS_prevent() method, since the script has been tested more and was causing a timing problem.

Removed [cd]#code[/cd] code tag, which had no code_class or code_extra.

Commented bad_pattern check for [email] tags, this security check is not needed because the next line will take care of all email tag security.

Added missing $AUBBC{image_border}, $AUBBC{html_type} and $AUBBC{image_wrap} to the none icon image.

Changed names of left and right align images to [left_img]..[/img] and [right_img]..[/img], also updated examples to show tags.


v1.0 01/20/2008 08:46:08

Released.

=head1 COPYLEFT

 AUBBC.pm, v1.10 09/02/2008 09:49:46 By: N.K.A

 Advanced Universal Bulletin Board Code Tags.

 Note: This code has a lot of settings and works good
 with most default settings.

=cut
