=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 This module addresses many security issues the UBBC tags may have. Each message is sanitized/escaped and checked for many types of security problems befor that tag converts to HTML/XHTML. To some it may have very strict security methods, but it allows you to change some of the security patterns. =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 => '', other_sites_pattern => 'a-zA-Z\d\:\-\s\_\/\.', bad_pattern => 'view\-source:|script:|mocha:|mailto:|about:|shell:|\.js', 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 & smileys. =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 Smileis. 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. Tag [cd] is the only tag that does not support this feature. must have a space befor 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 => '
', =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 befor 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 befor 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 => '
', =head2 other_sites_pattern Default is 'a-zA-Z\d\:\-\s\_\/\.' and this restricts the use of characters used in tags to other sites, not used in [url] tags. other site tags: [cpan://....] [google://....] [wikipedia://....] [wp://....] [wikibooks://....] [wb://....] [wikiquote://....] [wq://....] [wikisource://....] [ws://....] =head2 bad_pattern Default is 'view\-source:|script:|mocha:|mailto:|about:|shell:|\.js' and this restricts the use of characters used in [email] and 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 befor 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/smilies/lol.gif =head1 Build your own tags These are the settings and methods for using custom tags. =head2 $aubbc->add_build_tag($name,$pattern,$type,$function); 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 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('ok','l,s',1,'My_Message::check_ok_tag'); $aubbc->add_build_tag('ip','',3,'My_Message::get_some_tag'); $aubbc->add_build_tag('agent','',3,'My_Message::get_some_tag'); my $message = '[ok://test me] [ok://test other] [ok://n0 w00rk] [ip] [agent]'; $message = $aubbc->do_all_ubbc($message); print $message; sub check_ok_tag { my $text_from_AUBBC = shift; if ($text_from_AUBBC eq 'test me') { return 'Works Good 1'; } else { return 'Works Good 2'; } } sub get_some_tag { my $text_from_AUBBC = shift; lc($text_from_AUBBC); $text_from_AUBBC = $ENV{'REMOTE_ADDR'} if ($text_from_AUBBC eq 'ip'); $text_from_AUBBC = $ENV{'HTTP_USER_AGENT'} if ($text_from_AUBBC eq 'agent'); 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 AUBBC Methods List of Methods =head2 $aubbc->do_all_ubbc($message); This is the method to convert the tags. $message = $aubbc->do_all_ubbc($message); =head2 $aubbc->get_setting($setting_name); A method for getting a setting from the module. Usage: my $utf_active = $aubbc->get_setting('utf'); # if $utf_active = '' or 0 its not active =head2 $aubbc->script_escape($message); Escapes characters. $message = $aubbc->script_escape($message); =head2 $aubbc->html_to_text($message); A reverse for script_escape() $message = $aubbc->html_to_text($message); =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 COPYLEFT AUBBC.pm, v1.0 01/20/2008 08:46:08 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