activeldap.rb in ruby-activeldap-0.5.0

- old
+ new

@@ -210,11 +210,12 @@
 # the minimum requirement is when creating a new object. LDAP uses objectClasses
 # to define what attributes a LDAP object may have. Ruby/ActiveLDAP needs to know
 # what classes are required when creating a new object.  Of course, you can leave
 # that field out to default to ['top'] only.  Then you can let each application
 # choose what objectClasses their objects should have by calling the method e.g.
-# Group#objectClass=(value).
+# Group#objectClass=(value) or by modifying the value returned by the accessor, 
+# e.g. Group#objectClass.
 #
 # Note that is can be very important to define the default :classes value. Due to
 # implementation choices with most LDAP servers, once an object is created, its
 # structural objectclasses may not be removed (or replaced).  Setting a sane default
 # may help avoid programmer error later.
@@ -257,32 +258,30 @@
 # 
 # Now, class User will have a method called 'groups' which will retrieve all
 # Group objects that a user is in.
 # 
 #   irb> me = User.new('drewry')
-#   => ...
 #   irb> me.groups
-#   => ["cdrom", "audio", "develop"]
-# 
-# Methods created with belongs_to also take an optional argument: objects. This
-# argument specifies whether it will return the value of the 'dnattr' of the
-# objects, or whether it will return Group objects.
-# 
-#   irb> me.groups(true)
 #   => [#<Group:0x000001 ...>, #<Group:0x000002 ...>, ...]
 #   irb> me.groups(true).each { |group| p group.cn };nil
 #   "cdrom"
 #   "audio"
 #   "develop"
 #   => nil
-# 
 #   (Note: nil is just there to make the output cleaner...)
 # 
+# Methods created with belongs_to also take an optional argument: objects. This
+# argument specifies whether it will return the value of the 'dnattr' of the
+# objects, or whether it will return Group objects. 
+# 
+#   irb> me.groups(false)
+#   => ["cdrom", "audio", "develop"]
+# 
 # TIP: If you weren't sure what the distinguished name attribute was for Group,
 # you could also do the following:
 # 
-#   irb> me.groups(true).each { |group| p group.dnattr };nil
+#   irb> me.groups.each { |group| p group.dnattr };nil
 #   "cdrom"
 #   "audio"
 #   "develop"
 #   => nil
 # 
@@ -326,13 +325,13 @@
 # even return all responses in object form just like belongs_to methods.
 # 
 #   irb> develop = Group.new('develop')
 #   => ...
 #   irb> develop.members
-#   => ["drewry", "builder"]
-#   irb> develop.members(true)
 #   => [#<User:0x000001 ...>, #<User:...>]
+#   irb> develop.members(false)
+#   => ["drewry", "builder"]
 # 
 # 
 # The arguments for has_many follow the exact same idea that belongs_to's
 # arguments followed. :local_key's contents are used to search for matching
 # :foreign_key content.  If :foreign_key is not specified, it defaults to the
@@ -390,15 +389,17 @@
 # You can specify the :filter, :base, :scope, and :attrs, but they all have defaults --
 #  * :filter defaults to objectClass=* - usually this isn't what you want
 #  * :base defaults to the base of the class this is executed from (as set in ldap_mapping)
 #  * :scope defaults to LDAP::LDAP_SCOPE_SUBTREE. Usually you won't need to change it
 #  * :attrs defaults to [] and is the list of attrs you want back. Empty means all of them.
-# 
+#
 # ==== #validate
 # 
 # validate is a method that verifies that all attributes that are required by the
-# objects current objectClasses are populated. This is called by #write prior to
+# objects current objectClasses are populated. This also will call the
+# private "#enforce_types" method. This will make sure that all values defined are
+# valid to be written to LDAP.  #validate is called by #write prior to
 # performing any action. Its explicit use in an application is unnecessary, and
 # it may become a private method in the future.
 # 
 # ==== #write
 # 
@@ -534,10 +535,15 @@
 # 
 # This exception is raised during Base.connect if no valid connection to the
 # LDAP server could be created. Check you configuration.rb, Base.connect
 # arguments, and network connectivity! Also check your LDAP server logs to see
 # if it ever saw the request.
+#
+# ==== ObjectClassError
+#
+# This exception is raised when an object class is used that is not defined
+# in the schema.
 # 
 # === Others
 # 
 # Other exceptions may be raised by the Ruby/LDAP module, or by other subsystems.
 # If you get one of these exceptions and thing it should be wrapped, write me an
@@ -750,30 +756,30 @@
 #   ...
 # 
 # and everything should work well.
 # 
 #
-# ==== Array results for everything
+# ==== Non-array results for single values
 #
-# Even though Ruby/ActiveLDAP tries to be convenient by returning Arrays only
-# when an LDAP object attribute has multiple values, sometimes this can be a
-# programmatic nightmare. If you would like to force all returned values to
-# come in Array form, just query like so:
+# Even though Ruby/ActiveLDAP attempts to maintain programmatic ease by 
+# returning Array values only. By specifying 'false' as an argument to 
+# any attribute method you will get back a String if it is single value.
+# This is useful when you are just dumping values for human reading.
+# Here's an example:
 #
 #   irb> user = User.new('drewry')
 #   => ...
-#   irb> user.cn(true)
-#   => ["Will Drewry"]
+#   irb> user.cn(false)
+#   => "Will Drewry"
 #
-# That's it. Now you can ALWAYS get Arrays back without having to write your own
-# wrappers.
+# That's it. Now you can make human-readable output faster.
 # 
 # ==== Dynamic attribute crawling
 # 
-# If you use tab completion in irb, you'll notice that you can't tab complete the
-# dynamic attributes available for each object. You can still see what's available with the method call
-# #attributes.
+# If you use tab completion in irb, you'll notice that you /can/ tab complete the dynamic 
+# attribute methods. You can still see which methods are for attributes using 
+# Base#attributes:
 # 
 #   irb> d = Group.new('develop')
 #   => ...
 #   irb> d.attributes
 #   => ["gidNumber", "cn", "memberUid", "commonName", "description", "userPassword", "objectClass"]
@@ -890,10 +896,10 @@
 require 'activeldap/associations'
 require 'activeldap/configuration'
 require 'activeldap/schema2'
 
 module ActiveLDAP
-  VERSION = "0.4.4"
+  VERSION = "0.5.0"
 end
 
 ActiveLDAP::Base.class_eval do
   include ActiveLDAP::Configuration
   include ActiveLDAP::Associations