Add documentation related to attributes

Author: pitbulk

README.md

@@ -127,8 +127,7 @@ class SamlController < ApplicationController
 end
 ```
 
-If are using saml:AttributeStatement to transfer metadata, like the user name, you can access all the attributes through response.attributes. It
-contains all the saml:AttributeStatement with its 'Name' as a indifferent key and the one saml:AttributeValue as value.
+If are using saml:AttributeStatement to transfer metadata, like the user name, you can access all the attributes through response.attributes. It contains all the saml:AttributeStatement with its 'Name' as a indifferent key and the one saml:AttributeValue as value.
 
 ```ruby
 response          = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
@@ -137,6 +136,106 @@ response.settings = saml_settings
 response.attributes[:username]
 ```
 
+Imagine this saml:AttributeStatement
+
+```xml
+  <saml:AttributeStatement>
+    <saml:Attribute Name="uid">
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">demo</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="another_value">
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value1</saml:AttributeValue>
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">value2</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="role">
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">role1</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="role">
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">role2</saml:AttributeValue>
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">role3</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="attribute_with_nil_value">
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
+    </saml:Attribute>
+    <saml:Attribute Name="attribute_with_nils_and_empty_strings">
+      <saml:AttributeValue/>
+      <saml:AttributeValue>valuePresent</saml:AttributeValue>
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
+      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
+    </saml:Attribute>
+  </saml:AttributeStatement>
+```
+
+```ruby
+pp(response.attributes)   # is an OneLogin::RubySaml::Attributes object
+# => @attributes=
+  {"uid"=>["demo"],
+   "another_value"=>["value1", "value2"],
+   "role"=>["role1", "role2", "role3"],
+   "attribute_with_nil_value"=>[nil],
+   "attribute_with_nils_and_empty_strings"=>["", "valuePresent", nil, nil]}>
+
+# Active single_value_compatibility
+OneLogin::RubySaml::Attributes.single_value_compatibility = true
+
+pp(response.attributes[:uid])
+# => "demo"
+
+pp(response.attributes[:role])
+# => "role1"
+
+pp(response.attributes.single(:role))
+# => "role1"
+
+pp(response.attributes.multi(:role))
+# => ["role1", "role2", "role3"]
+
+pp(response.attributes[:attribute_with_nil_value])
+# => nil
+
+pp(response.attributes[:attribute_with_nils_and_empty_strings])
+# => ""
+
+pp(response.attributes[:not_exists])
+# => nil
+
+pp(response.attributes.single(:not_exists))
+# => nil
+
+pp(response.attributes.multi(:not_exists))
+# => nil
+
+# Deactive single_value_compatibility
+OneLogin::RubySaml::Attributes.single_value_compatibility = false
+
+pp(response.attributes[:uid])
+# => ["demo"]
+
+pp(response.attributes[:role])
+# => ["role1", "role2", "role3"]
+
+pp(response.attributes.single(:role))
+# => "role1"
+
+pp(response.attributes.multi(:role))
+# => ["role1", "role2", "role3"]
+
+pp(response.attributes[:attribute_with_nil_value])
+# => [nil]
+
+pp(response.attributes[:attribute_with_nils_and_empty_strings])
+# => ["", "valuePresent", nil, nil]
+
+pp(response.attributes[:not_exists])
+# => nil
+
+pp(response.attributes.single(:not_exists))
+# => nil
+
+pp(response.attributes.multi(:not_exists))
+# => nil
+```
+
 ## Service Provider Metadata
 
 To form a trusted pair relationship with the IdP, the SP (you) need to provide metadata XML