From 4d4423ec25fdb26c73fabe1a8689064eb68ab084 Mon Sep 17 00:00:00 2001
From: blackhedd <blackhedd@005445c4-6811-0410-8301-cae4f0071d1d>
Date: Mon, 1 May 2006 07:19:12 +0000
Subject: [PATCH] Deprecated #modify. Added #add_attribute, #replace_attribute
 and #delete_attribute.

---
 lib/net/ldap.rb | 61 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/lib/net/ldap.rb b/lib/net/ldap.rb
index 105e8ca..b090c2a 100644
--- a/lib/net/ldap.rb
+++ b/lib/net/ldap.rb
@@ -181,6 +181,8 @@ module Net
   # the attribute values stored in the directory for a particular entity.
   # #modify may add or delete attributes (which are lists of values) or it change attributes by
   # adding to or deleting from their values.
+  # There are three easier methods to modify an entry's attribute values:
+  # #add_attribute, #replace_attribute, and #delete_attribute.
   #
   # ==== Delete
   # #delete operation specifies an entity DN. If it succeeds, the entity and all its attributes
@@ -600,7 +602,9 @@ module Net
     end
 
 
-    # Modify the attribute values of a particular entry on the LDAP directory.
+    # _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute.
+    #
+    # Modifies the attribute values of a particular entry on the LDAP directory.
     # Takes a hash with arguments. Supported arguments are:
     # :dn :: (the full DN of the entry whose attributes are to be modified)
     # :operations :: (the modifications to be performed, detailed next)
@@ -681,6 +685,61 @@ module Net
       @result == 0
     end
 
+
+    # Add a value to an attribute.
+    # Takes the full DN of the entry to modify,
+    # the name (Symbol or String) of the attribute, and the value (String or
+    # Array). If the attribute does not exist (and there are no schema violations),
+    # #add_attribute will create it with the caller-specified values.
+    # If the attribute already exists (and there are no schema violations), the
+    # caller-specified values will be _added_ to the values already present.
+    #
+    # Returns True or False to indicate whether the operation
+    # succeeded or failed, with extended information available by calling
+    # #get_operation_result. See also #replace_attribute and #delete_attribute.
+    #
+    #  dn = "cn=modifyme,dc=example,dc=com"
+    #  ldap.add_attribute dn, :mail, "newmailaddress@example.com"
+    #
+    def add_attribute dn, attribute, value
+      modify :dn => dn, :operations => [[:add, attribute, value]]
+    end
+
+    # Replace the value of an attribute.
+    # #replace_attribute can be thought of as equivalent to calling #delete_attribute
+    # followed by #add_attribute. It takes the full DN of the entry to modify,
+    # the name (Symbol or String) of the attribute, and the value (String or
+    # Array). If the attribute does not exist, it will be created with the
+    # caller-specified value(s). If the attribute does exist, its values will be
+    # _discarded_ and replaced with the caller-specified values.
+    #
+    # Returns True or False to indicate whether the operation
+    # succeeded or failed, with extended information available by calling
+    # #get_operation_result. See also #add_attribute and #delete_attribute.
+    #
+    #  dn = "cn=modifyme,dc=example,dc=com"
+    #  ldap.replace_attribute dn, :mail, "newmailaddress@example.com"
+    #
+    def replace_attribute dn, attribute, value
+      modify :dn => dn, :operations => [[:replace, attribute, value]]
+    end
+
+    # Delete an attribute and all its values.
+    # Takes the full DN of the entry to modify, and the
+    # name (Symbol or String) of the attribute to delete.
+    #
+    # Returns True or False to indicate whether the operation
+    # succeeded or failed, with extended information available by calling
+    # #get_operation_result. See also #add_attribute and #replace_attribute.
+    #
+    #  dn = "cn=modifyme,dc=example,dc=com"
+    #  ldap.delete_attribute dn, :mail
+    #
+    def delete_attribute dn, attribute
+      modify :dn => dn, :operations => [[:delete, attribute, nil]]
+    end
+
+
     # Rename an entry on the remote DIS by changing the last RDN of its DN.
     # _Documentation_ _stub_
     #