File: README.txt

IntelligentCensor
(c) Copyright 2006-2008 sk89q <http://sk89q.therisenrealm.com>
Released under GPLv2

Introduction
------------

While most word filters work by replacing fuzzy matches with a static 
replacement, this library does it differently. In many occasions, 
visitors to a site may try to express anger and, without any ill 
intention, spew out some vulgar language. Because most word filter 
libraries use static replacements, the original message and its tone are 
lost. However, IntelligentCensor uses dynamic replacements that adapt to 
each replaced word. If a particular filtered word is written in all-caps 
to express a heavy tone, its resulting replacement will be in all-caps 
as well. In addition, if a filtered word has any prefixes or suffixes 
applied to it ([sic] damn vs. damnit), this library can handle those 
too, and even change the ending of the replacement word according to 
(some) basic rules of English. 

The library is written in PHP and is released GNU General Public License
(GPL) version two.

Usage
-----

Construct an instance of IntelligentCensor with the list of censors 
(associative array) and list of exclusions (associative array) for the 
constructor's parameters. Then, just call the censor method on he text. 

For filter definitions, you can use * as a wildcard character. To use
the dynamic prefix and suffix handling abilities of this library, place
% at the beginning or end of the filter definition (it won't work in
any other place).

Also, filters should not use special symbols, because the regular 
expression that is in use won't support them.

See the example code below (it's also in example.php). 

<?php
require_once "IntelligentCensor.php";

// * are not expanded
// % are expanded, and but they will only work when placed at either the
// beginning or ending of the word
$censors = array(
    '*damn%' => 'darn',
    'whore%' => 'people',
    'bastard*' => 'happyperson',
    '*ho' => 'person',
);

// Can use * wildcards
$censors_exclusion = array(
    'echo*',
);

$icensor = new IntelligentCensor($censors, $censors_exclusion);

echo $icensor->censor("you're all DIETYDAMNING bastardly wHOres!
    you echo ho!");
// Result: you're all DARNING happyperson pEOples! you echo person! 
?>