AttributeAlter: update documentation to include new features.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@3354 44740490-163a-0410-bde0-09ae8108e29a

modules/core/docs/authproc_attributealter.txt

 `core:AttributeAlter`
 ==========
 
-This filter can be used to substitute and replace different parts of the attribute value based on regular expressions.
+This filter can be used to substitute and replace different parts of the attribute values based on regular expressions.
+It can also be used to create new attributes based on existing values, or even to remove blacklisted values from
+attributes.
 
 Parameters
 ----------
@@ -11,32 +13,36 @@ Parameters
     It must be `'core:AttributeAlter'`.
 
 `subject`
-:   The attribute in which the search is preformed.
-    This parameter is REQUIRED and the filter will throw an exception if this parameter is not set.
+:   The attribute in which the search is performed.
+    This parameter is REQUIRED and the filter will throw an exception if it is not set. The filter will
+    stop quietly if the attribute specified here is empty or not found.
     
 `pattern`
-:   The regular expression used.
-    This parameter is REQUIRED and the filter will throw an exception if this parameter is not set.
-    It is not possible to use backreference.
+:   The pattern to look for inside the subject. Supports full Perl Compatible Regular Expressions (PCRE).
+    This parameter is REQUIRED and the filter will throw an exception if it is not set.
     
 `replacement`
-:   The value used to replace the searched value.
-    This parameter is REQUIRED if `%replace` is not used.
-    If `%replace` is used and `replacement` is not set, then the matched text is used instead.
+:   The value used to replace the match. Back references are not supported.
+    This parameter is REQUIRED, except when using the `%replace` or `%remove` options. If `%replace` is used and
+    `replacement` is not set, then the match is used as a replacement.
     
 `target`
-:   The target attribute where the replaced attribute value is put.
-    This parameter is OPTIONAL.
-    If this parameter is not set `subject` is used as `target`.
+:   The attribute where the replaced value will be placed.
+    This parameter is OPTIONAL, and if not set, `subject` is used as `target`.
 
 `%replace`
-:   Indicate whether the searched part should be replaced or the whole value.
-    this parameter is OPTIONAL.
+:   Indicates that the whole value of the attribute should be replaced, instead of just the match.
+    This parameter is OPTIONAL.
+
+`%remove`
+:   Indicates that the whole value of the attribute should be removed completely. If no other values exist, the
+    attribute will be removed completely.
+    This parameter is OPTIONAL.
     
 Examples
 --------
 
-Change the domain on the `mail` attribute (when both the new and old domain is known):
+Change the domain on the `mail` attribute (when both the new and old domain are known):
 
     10 => array(
         'class' => 'core:AttributeAlter',
@@ -64,7 +70,7 @@ Set the eduPersonPrimaryAffiliation based on users distinguishedName:
         'target' => 'eduPersonPrimaryAffiliation',
     ),
     
-Change the eduPersonPrimaryAffiliation:
+Normalize the eduPersonPrimaryAffiliation:
 
     10 => array(
         'class' => 'core:AttributeAlter',
@@ -74,7 +80,7 @@ Change the eduPersonPrimaryAffiliation:
         '%replace',
     ),
     
-Get the domain of the email and put it in a seperat attribute:
+Get the domain of the email and put it in a separate attribute:
 
     10 => array(
         'class' => 'core:AttributeAlter',
@@ -82,4 +88,33 @@ Get the domain of the email and put it in a seperat attribute:
         'pattern' => '/(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,6}$/',
         'target' => 'domain',
         '%replace',
+    ),
+
+Remove internal, private values from eduPersonEntitlement:
+
+    10 => array(
+        'class' => 'core:AttributeAlter',
+        'subject' => 'eduPersonEntitlement',
+        'pattern' => '/ldap-admin/',
+        '%remove',
+    ),
+
+Set a value to be blank (which will be sent as an empty string):
+
+    10 => array(
+        'class' => 'core:AttributeAlter',
+        'subject' => 'cn',
+        'pattern' => '/No name/',
+        'replacement' => '',
+        '%replace',
+    ),
+
+Set a value to be NULL (which will be sent as a NULL value):
+
+    10 => array(
+        'class' => 'core:AttributeAlter',
+        'subject' => 'telephone',
+        'pattern' => '/NULL/',
+        'replacement' => null,
+        '%replace',
     ),
\ No newline at end of file