README.rdoc in iq-acl-1.0.5 vs README.rdoc in iq-acl-1.1.1

@@ -16,31 +16,43 @@
   })
   
   # You could alternatively read rights from a YAML file
   auth = IQ::ACL::Basic.new(YAML.load_file('rights.yml'))
 
-  auth.authorize! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'jonny', 'projects'         #=> 'rw'
-  auth.authorize! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'terry', 'projects'         #=> 'r'
-  auth.authorize! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'jonny', 'projects/private' #=> 'rw'
-  auth.authorize! 'billy', 'projects/private' #=> 'rw'
-  auth.authorize! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
-  auth.authorize! 'guest', 'projects/public'  #=> 'r'
-  auth.authorize! 'jonny', 'projects/public'  #=> 'r'
-  auth.authorize! 'billy', 'projects/public'  #=> 'r'
-  auth.authorize! 'terry', 'projects/public'  #=> 'rw
+  auth.authenticate! 'guest', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'jonny', 'projects'         #=> 'rw'
+  auth.authenticate! 'billy', 'projects'         #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'terry', 'projects'         #=> 'r'
+  auth.authenticate! 'guest', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'jonny', 'projects/private' #=> 'rw'
+  auth.authenticate! 'billy', 'projects/private' #=> 'rw'
+  auth.authenticate! 'terry', 'projects/private' #=> raises IQ::ACL::AccessDeniedError
+  auth.authenticate! 'guest', 'projects/public'  #=> 'r'
+  auth.authenticate! 'jonny', 'projects/public'  #=> 'r'
+  auth.authenticate! 'billy', 'projects/public'  #=> 'r'
+  auth.authenticate! 'terry', 'projects/public'  #=> 'rw
 
-A block may be given to <tt>authorize!</tt> that should return true if
+A block may be given to <tt>authenticate!</tt> that should return true if
 the yielded rights are adequate for the user, for example the following
 will raise an IQ::ACL::AccessDeniedError as 'terry' does not have write access
 to the 'projects' path. If 'terry' had write access to the 'projects'
 path, the exception would not be thrown.
 
-  auth.authorize! 'terry', 'projects' do |rights|
+  auth.authenticate! 'terry', 'projects' do |rights|
     rights.include?('w')
   end
+  
+In the previous examples, strings are used to identify the user, however
+user may be any object. This becomes quite powerful as you could use the
+objects returned from an ORM such as ActiveRecord. Also the rights in the
+previous examples were strings, however these may be of any type also,
+again allowing powerful solutions to be built e.g.
+ 
+ user = User.find_by_email('[e-mail]')
+ auth = IQ::ACL::Basic.new('projects/*' => { user => user.roles })
+ auth.authenticate!(user, 'projects/some-project') do |roles|
+   roles.find_by_name('project_editor')
+ end
 
 == Note on Patches/Pull Requests
  
 * Fork the project.
 * Make your feature addition or bug fix.