Index: libabac/abac.hh
===================================================================
--- libabac/abac.hh	(revision 0b3ac6598a8169fa335621f049ae698baffbf633)
+++ libabac/abac.hh	(revision ed3dc05f96a0b311f3fe5dcfcedf789b79c0df5f)
@@ -21,9 +21,9 @@
 /***
    Constraint()
-      default constructure, do not use, for swig only 
+     default constructor, do not use, for swig only 
    Constraint(const Constraint &)
-      copy constructor, used for cloning a constraint
+     copy constructor, used for cloning a constraint
    ~Constraint()
-      default destructor
+     default destructor
 ***/
             Constraint() : m_constraint(NULL) { }
@@ -36,23 +36,23 @@
 /***
    Constraint(Role &)
-      constructor that takes a constraining role
-        [role:?R[{role-constraint}]
+     constructor that takes a constraining role
+       [role:?R[{role-constraint}]
    Constraint(Oset &)
-      constructor that takes a constraining  oset
-        [oset:?O[{oset-constraint}]
-        [urn:?F[keyid:$alpha_keyid].oset:documents([string:?P])]
+     constructor that takes a constraining oset
+       [oset:?O[{oset-constraint}]
+       [urn:?F[keyid:$alpha_keyid].oset:documents([string:?P])]
    Constraint(abac_condition_t *)
-      constructor that takes a abac_condition_t structure
+     constructor that takes an abac_condition_t structure
    Constraint(char *)
-      constructor that takes one of following string
-      as its vartype to set up a range constraint:
-          "integer"
-          "urn"
-          "float"
-          "boolean"
-          "time"
-          "string"
-      It should be followed with one or many of following utility
-      calls.
+     constructor that takes one of following string
+     as its vartype to set up a range constraint:
+       "integer"
+       "urn"
+       "float"
+       "boolean"
+       "time"
+       "string"
+     it should be followed with one or many of following utility
+     calls.
 ***/
             Constraint(Role& role);
@@ -65,11 +65,11 @@
             }
 /***
-    void add_constraint_integer_max(int)
-    void add_constraint_integer_min(int)
-       utility routines to setup a integer range constraint 
-           [integer:?I[10 .. 20]]
-    void add_constraint_integer_target(int)
-       utility routine to setup a integer list constraint 
-           [integer:?I[10,20]]
+   void add_constraint_integer_max(int)
+   void add_constraint_integer_min(int)
+     utility routines to setup a integer range constraint 
+       [integer:?I[10 .. 20]]
+   void add_constraint_integer_target(int)
+     utility routine to setup a integer list constraint 
+       [integer:?I[10,20]]
 ***/
             void add_constraint_integer_max(int val) {
@@ -83,11 +83,11 @@
             }
 /***
-    void add_constraint_float_max(float)
-    void add_constraint_float_min(float)
-       utility routines to setup a float range constraint 
-           [float:?F[1.0 .. 2.5]]
-    void add_constraint_float_target(float)
-       utility routine to setup a float list constraint 
-            [float:?F[0.5, 2.5]]
+   void add_constraint_float_max(float)
+   void add_constraint_float_min(float)
+     utility routines to setup a float range constraint 
+       [float:?F[1.0 .. 2.5]]
+   void add_constraint_float_target(float)
+     utility routine to setup a float list constraint 
+       [float:?F[0.5, 2.5]]
 ***/
             void add_constraint_float_max(float val) {
@@ -101,13 +101,13 @@
             }
 /***
-    void add_constraint_time_max(char*)
-    void add_constraint_time_min(char*)
-       utility routines to setup a time range constraint, 
-       takes quoted string values, beyond T is optional 
-           [time:?M["20201101T182930"]] 
-           [time:?M["20201101T"]] 
-    void add_constraint_time_target(char*)
-       utility routine to setup a time list constraint 
-            [time:?F["20120228T080000" .. "20120228T090000"]]
+   void add_constraint_time_max(char*)
+   void add_constraint_time_min(char*)
+     utility routines to setup a time range constraint, 
+     takes quoted string values, beyond T is optional 
+       [time:?M["20201101T182930"]] 
+       [time:?M["20201101T"]] 
+   void add_constraint_time_target(char*)
+     utility routine to setup a time list constraint 
+       [time:?F["20120228T080000" .. "20120228T090000"]]
 ***/
             void add_constraint_time_max(char* val) {
@@ -121,13 +121,13 @@
             }
 /***
-    void add_constraint_urn_target(char*)
-       utility routine to setup a an urn list constraint
-           [urn:?U["fileA","http://fileB"]] 
-    void add_constraint_string_target(char*)
-       utility routine to setup a a string list constraint
-           [string:?S["abc",'efg',"hij"]]
-    void add_constraint_boolean_target(char*)
-       utility routine to setup a a boolean list constraint
-            [boolean:?B['true']]
+   void add_constraint_urn_target(char*)
+     utility routine to setup a an urn list constraint
+       [urn:?U["fileA","http://fileB"]] 
+   void add_constraint_string_target(char*)
+     utility routine to setup a a string list constraint
+       [string:?S["abc",'efg',"hij"]]
+   void add_constraint_boolean_target(char*)
+     utility routine to setup a a boolean list constraint
+       [boolean:?B['true']]
 ***/
             void add_constraint_urn_target(char* val) 
@@ -138,8 +138,8 @@
             { abac_condition_add_range_boolean_item(m_constraint,val); }
 /***
-    char *string() const
-       returns literal string of the constraint
-    char *typed_string() const
-       returns typed literal string of the constraint
+   char *string() const
+     returns literal string of the constraint
+   char *typed_string() const
+     returns typed literal string of the constraint
 ***/
             char *string() const 
@@ -148,6 +148,6 @@
             { return abac_condition_typed_string(m_constraint); }
 /***
-    abac_condition_t *constraint()
-       returns internal constraint structure
+   abac_condition_t *constraint()
+     returns internal constraint structure
 ***/
             abac_condition_t *constraint()
@@ -159,6 +159,6 @@
 /*** 
 ABAC::DataTerm
-   A data term is associated with Role and Oset as a parameter that 
-   maybe be instantiated or uninstantiated but being constrained,
+   A data term is associated with Role or Oset as a parameter that 
+   maybe be instantiated, or uninstantiated but being constrained,
    or as a principal oset term (standalone right handside of an oset
    policy rule).  It holds a pointer to a abac_term_t structure and 
@@ -170,9 +170,9 @@
 /***
    DataTerm()
-      default constructure, do not use, for swig only 
+     default constructor, do not use, for swig only 
    DataTerm(const DataTerm &)
-      copy constructor, used for cloning a data term
+     copy constructor, used for cloning a data term
    ~DataTerm()
-      default destructor
+     default destructor
 ***/
             DataTerm() : m_term(NULL) { } // do not use: here for swig
@@ -188,6 +188,6 @@
             }
 /*** ???
-    DataTerm(abac_term_t *)
-       constructor to make data term from abac_term_t structure
+   DataTerm(abac_term_t *)
+     constructor to make data term from abac_term_t structure
 ***/
             DataTerm(abac_term_t *term) { 
@@ -198,9 +198,9 @@
             }
 /***
-    DataTerm(char*)
-       constructor to make named principal data term for the oset RHS 
-    DataTerm(char*, char*, Constraint*)
-       constructor for making a variable data term or an instantiated
-       data term
+   DataTerm(char*)
+     constructor to make named principal data term for the oset RHS 
+   DataTerm(char*, char*, Constraint*)
+     constructor for making a variable data term or an instantiated
+     data term
 ***/
             DataTerm(char *sha) {
@@ -224,8 +224,8 @@
             }
 /***
-    char *string() const
-       returns literal string of the data term
-    char *typed_string() const
-       returns typed literal string of the data term
+   char *string() const
+     returns literal string of the data term
+   char *typed_string() const
+     returns typed literal string of the data term
 ***/
             char *string() const
@@ -234,9 +234,9 @@
             { return abac_term_typed_string(m_term); }
 /***
-    bool is_time() const
-    bool is_string() const
-    bool is_urn() const
-    bool is_integer() const 
-       returns true if data term is of certain type
+   bool is_time() const
+   bool is_string() const
+   bool is_urn() const
+   bool is_integer() const 
+     returns true if data term is of certain type
 ***/
             bool is_time() const 
@@ -249,6 +249,6 @@
             { return abac_term_is_integer_type(m_term); }
 /***
-    int add_constraint(const Contraint&)
-       Utiltiy routine to add a constraint to this data term
+   int add_constraint(const Contraint&)
+     utiltiy routine to add a constraint to this data term
 ***/
             int add_constraint(const Constraint& cond) {
@@ -257,8 +257,8 @@
             }
 /***
-    int type() const
-        returns subtype of the data term
-    char *name() const
-        returns the name of the data term 
+   int type() const
+     returns subtype of the data term
+   char *name() const
+     returns the name of the data term 
 ***/
             int type() const 
@@ -268,12 +268,12 @@
 /*** ??? value 
    char *value() const
-      Not implemented
+     Not implemented
 ***/
             char *value() const { }
 /***
-    abac_term_t *term()
-        returns internal data term structure
-    Constraint *constraint()
-        returns internal constraint structure to the data term
+   abac_term_t *term()
+     returns internal data term structure
+   Constraint *constraint()
+     returns internal constraint structure to the data term
 ***/
             abac_term_t *term() 
@@ -287,78 +287,136 @@
 
 
+/***
+ABAC::Role
+   A Role is role specification of a set of entitities for a principal.
+***/
     class Role {
         public:
+/***
+   Role()
+     default constructor, do not use, for swig only 
+   Role(const Role &)
+     copy constructor, used for cloning a role
+   ~Role()
+     default destructor
+***/
             Role() : m_role(NULL) { } // do not use: here for swig
+            Role(const Role &role) { 
+              m_role = abac_aspect_dup(role.m_role);
+            }
+            ~Role() { 
+              if (m_role) abac_aspect_free(m_role);
+            }
+/***
+   Role(abac_aspect_t*)
+     constructor that takes an abac_aspect_t structure
+   Role(char*) 
+     constructor that builds a bare bone role with just principal's name
+   Role(char*, char*) 
+     constructor that builds a bare bone role with just principal's name
+     and a role name
+***/
             Role(abac_aspect_t *role): m_role(abac_aspect_dup(role))
-              { }
+            { }
             Role(char *principal_name) : 
                m_role(abac_aspect_role_principal_create(principal_name)) 
-              { }
+            { }
             Role(char *principal_name, char *role_name) : 
                m_role(abac_aspect_role_create(principal_name, role_name)) 
-              { }
-            Role(const Role &role) { 
-                m_role = abac_aspect_dup(role.m_role);
-              }
-            ~Role() { 
-                if (m_role) abac_aspect_free(m_role);
-              }
-            bool is_principal() const { 
-                return abac_aspect_is_principal(m_role); 
-              }
-            bool is_linking() const { 
-                return abac_aspect_is_linking(m_role); 
-              }
-            char *string() const { 
-                return abac_aspect_string(m_role);
-              }
-            char *typed_string() {
-                char* string=abac_aspect_typed_string(m_role);
-                return string;
-              }
-            char *linked_role() const { 
-                return abac_aspect_linked_role_name(m_role);
-              }
-            char *role_name() const { 
-                return abac_aspect_aspect_name(m_role);
-              }
-            char *principal() const { 
-                return abac_aspect_principal_name(m_role);
-              }
-/* Add a data term to this name. */
+            { }
+/***
+   bool is_principal() const
+     return true if the role is a principal object(made from
+     a data term), the right hand side of, 
+       [keyid:A].role:r <- [keyid:B]
+***/
+            bool is_principal() const
+            { return abac_aspect_is_principal(m_role); }
+/***
+   bool is_linking() const
+     returns true if the role is a linking role like
+     the right hand side of,
+       [keyid:A].role:r1 <- [keyid:B].role:r2.role:r3
+***/
+            bool is_linking() const
+            { return abac_aspect_is_linking(m_role); }
+/***
+   char *string() const
+     returns literal string of the role
+   char *typed_string() const
+     returns typed literal string of the role
+***/
+            char *string() const
+            { return abac_aspect_string(m_role); }
+            char *typed_string()
+            { return abac_aspect_typed_string(m_role); }
+/***
+   char *linked_role() const 
+     returns linked part of a linking role, for
+     [keyid:A].role:r1.role:r2, it returns r1
+***/
+            char *linked_role() const 
+            { return abac_aspect_linked_role_name(m_role); }
+/***
+   char *role_name() const 
+     returns the role name of any role (the part after the last dot)
+     [keyid:A].role.r1.role:r2, it returns r2
+     [keyid:A].role.r1, it returns r1
+***/
+            char *role_name() const
+            { return abac_aspect_aspect_name(m_role); }
+            char *principal() const
+            { return abac_aspect_principal_name(m_role); }
+
+/***
+   int add_data_term(DataTerm&)
+     add a data term to the role
+***/
             int add_data_term(DataTerm& d) {
-                abac_aspect_add_param(m_role, d.term());
-                return 1;
-              }
-/* Return the DataTerms bound to this name.  If the name is returned
-   in a proof, these will all have values. */
+              abac_aspect_add_param(m_role, d.term());
+              return 1;
+            }
+/***
+   std::vector<DataTerm> get_data_terms(bool &)
+     return the data terms bound to this role.
+     ??? If the role is returned in a proof, these will all have values.
+***/
             std::vector<DataTerm> get_data_terms(bool &success) {
-                abac_term_t **terms, **end;
-                int i;
-                terms = abac_param_list_vectorize(abac_aspect_aspect_params(m_role));
-                for (i = 0; terms[i] != NULL; ++i)
-                    ;
-                end = &terms[i];
-                std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
-                abac_terms_free(terms);
-                success=1;
-                return dataterms;
-              }
+              abac_term_t **terms, **end;
+              int i;
+              terms = abac_param_list_vectorize(abac_aspect_aspect_params(m_role));
+              for (i = 0; terms[i] != NULL; ++i)
+                  ;
+              end = &terms[i];
+              std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
+              abac_terms_free(terms);
+              success=1;
+              return dataterms;
+            }
             int add_linking_data_term(DataTerm& d) {
-                abac_aspect_add_linked_param(m_role, d.term());
-                return 1;
-              }
+              abac_aspect_add_linked_param(m_role, d.term());
+              return 1;
+            }
+/***
+   std::vector<DataTerm> get_linked_data_terms(bool &)
+     return the data terms bound to this role's linking role.
+     ??? If the role is returned in a proof, these will all have values.
+***/
             std::vector<DataTerm> get_linked_data_terms(bool &success) {
-                abac_term_t **terms, **end;
-                int i;
-                terms = abac_param_list_vectorize(abac_aspect_linked_role_params(m_role));
-                for (i = 0; terms[i] != NULL; ++i)
-                    ;
-                end = &terms[i];
-                std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
-                abac_terms_free(terms);
-                success=1;
-                return dataterms;
-              }
+              abac_term_t **terms, **end;
+              int i;
+              terms = abac_param_list_vectorize(abac_aspect_linked_role_params(m_role));
+              for (i = 0; terms[i] != NULL; ++i)
+                  ;
+              end = &terms[i];
+              std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
+              abac_terms_free(terms);
+              success=1;
+              return dataterms;
+            }
+/***
+   abac_aspect_t *role()
+     returns the interal libabac representation of this role
+***/
             abac_aspect_t *role() {return m_role;}
         private:
@@ -366,86 +424,161 @@
     };
 
+/***
+ABAC::Oset
+   An Oset is oset specification of a set of entitities for a principal.
+***/
     class Oset {
         public:
+/***
+   Oset()
+     default constructor, do not use, for swig only
+   Oset(const Oset &)
+     copy constructor, used for cloning an oset
+   ~Oset()
+     default destructor
+***/
             Oset() : m_oset(NULL) { } // do not use: here for swig
+            Oset(const Oset &oset)
+            { m_oset =abac_aspect_dup(oset.m_oset); }
+            ~Oset()
+            { if(m_oset) abac_aspect_free(m_oset); }
+/***
+   Oset(abac_aspect_t *)
+     constructor that takes abac_aspect_t structure
+   Oset(char *)
+     constructor that makes a principal oset, ie [keyid:B]
+   Oset(char *, char *)
+     constructor that makes a regular oset, ie. [keyid:B].oset:o
+   Oset(DataTerm&)
+     constructor that makes an object oset, ie. [urn:'file/fileA']
+***/
             Oset(abac_aspect_t *oset): m_oset(abac_aspect_dup(oset)) 
-              { }
+            { }
             Oset(char *oset_name) : m_oset(abac_aspect_oset_principal_create(oset_name)) 
-              { }
+            { }
             Oset(char *principal_name, char *oset_name) : 
                m_oset(abac_aspect_oset_create(principal_name, oset_name)) 
-              { }
+            { }
             Oset(DataTerm& d) :
                m_oset(abac_aspect_oset_object_create(d.term())) 
-              { }
-            Oset(const Oset &oset) { 
-                m_oset =abac_aspect_dup(oset.m_oset);
-              }
-            ~Oset() { 
-                if(m_oset) abac_aspect_free(m_oset);
-              }
-            bool is_object() const { 
-                return abac_aspect_is_object(m_oset); 
-              }
-            bool is_principal() const { 
-                return abac_aspect_is_principal(m_oset); 
-              }
-            bool is_linking() const { 
-                return abac_aspect_is_linking(m_oset); 
-              }
-            char *string() const { 
-                return abac_aspect_string(m_oset);
-              }
-            char *typed_string() {
-                char* string=abac_aspect_typed_string(m_oset);
-                return string;
-              }
-            char *linked_role() const { 
-                return abac_aspect_linked_role_name(m_oset);
-              }
-            char *oset_name() const { 
-                return abac_aspect_aspect_name(m_oset);
-              }
-            char *principal() const { 
-                return abac_aspect_principal_name(m_oset);
-              }
-            char *object() const { 
-                return abac_aspect_object_name(m_oset);
-              }
-/* Add a data term to this name. */
+            { }
+
+/***
+   bool is_object(), ie <- [integer:10]
+     return ture if this oset is an object oset
+***/
+            bool is_object() const
+            { return abac_aspect_is_object(m_oset); }
+/***
+   bool is_principal() const
+     return true if the oset is a principal object(made from
+     a data term), the right hand side of, 
+       [keyid:A].oset:o <- [keyid:B]
+***/
+            bool is_principal() const 
+            { return abac_aspect_is_principal(m_oset); }
+/***
+   bool is_linking() const
+     returns true if the oset is a linking oset like
+     the right hand side of,
+       [keyid:A].oset:o1 <- [keyid:B].role:r1.oset:o2
+***/
+            bool is_linking() const 
+            { return abac_aspect_is_linking(m_oset); }
+/***
+   char *string() const
+     returns literal string of the oset
+   char *typed_string() const
+     returns typed literal string of the oset
+***/
+            char *string() const
+            { return abac_aspect_string(m_oset); }
+            char *typed_string()
+            { return abac_aspect_typed_string(m_oset); }
+/***
+   char *linked_role() const 
+     returns linked part of a linking oset, for
+     [keyid:A].role:r1.oset:o1, it returns r1
+***/
+            char *linked_role() const 
+            { return abac_aspect_linked_role_name(m_oset); }
+/***
+   char *oset_name() const 
+     returns oset name,
+     [keyid:A].role:r1.oset:o1, it returns o1
+     [keyid:A].oset:o1, it returns o1
+***/
+            char *oset_name() const
+            { return abac_aspect_aspect_name(m_oset); }
+/***
+   char *principal() const 
+     returns principal name,
+     [keyid:A].role:r1.oset:o1, it returns A 
+***/
+            char *principal() const
+            { return abac_aspect_principal_name(m_oset); }
+/***
+   char *object() const 
+     returns object's name when the oset is a principal object
+     [keyid:A].oset:values <- [integer:10], it returns 10
+***/
+            char *object() const 
+            { return abac_aspect_object_name(m_oset); }
+/***
+   int add_data_term(DataTerm&)
+     add a data term to this oset's parameter set
+     always returns 1
+***/
             int add_data_term(DataTerm& d) {
-                abac_aspect_add_param(m_oset, d.term()); 
-                return 1;
-              }
-/* Return the DataTerms bound to this name.  If the name is returned
-   in a proof, these will all have values. */
+              abac_aspect_add_param(m_oset, d.term()); 
+              return 1;
+            }
+/***
+   std::vector<DataTerm> get_data_terms(bool &)
+     returns the data terms bound to this oset.  
+     ??? If the oset is returned in a proof, these will all have values.
+***/
             std::vector<DataTerm> get_data_terms(bool &success) {
-                abac_term_t **terms, **end;
-                int i;
-                terms = abac_param_list_vectorize(abac_aspect_aspect_params(m_oset));
-                for (i = 0; terms[i] != NULL; ++i)
-                    ;
-                end = &terms[i];
-                std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
-                abac_terms_free(terms);
-                success=1;
-                return dataterms;
-              }
+              abac_term_t **terms, **end;
+              int i;
+              terms = abac_param_list_vectorize(abac_aspect_aspect_params(m_oset));
+              for (i = 0; terms[i] != NULL; ++i)
+                  ;
+              end = &terms[i];
+              std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
+              abac_terms_free(terms);
+              success=1;
+              return dataterms;
+            }
+/***
+   int add_linking_data_term(DataTerm&)
+     add a data term to this oset's linking role's parameter set.
+     always returns 1
+***/
             int add_linking_data_term(DataTerm& d) {
-                abac_aspect_add_linked_param(m_oset, d.term());
-                return 1;
-              }
+              abac_aspect_add_linked_param(m_oset, d.term());
+              return 1;
+            }
+/***
+   std::vector<DataTerm> get_linked_data_terms(bool &)
+     returns the data terms bound to this oset's linking role.  
+     ??? If the oset is returned in a proof, these will all have values.
+***/
             std::vector<DataTerm> get_linked_data_terms(bool &success) {
-                abac_term_t **terms, **end;
-                int i;
-                terms = abac_param_list_vectorize(abac_aspect_linked_role_params(m_oset));
-                for (i = 0; terms[i] != NULL; ++i)
-                    ;
-                end = &terms[i];
-                std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
-                abac_terms_free(terms);
-                success=1;
-                return dataterms;
-              }
+              abac_term_t **terms, **end;
+              int i;
+              terms = abac_param_list_vectorize(abac_aspect_linked_role_params(m_oset));
+              for (i = 0; terms[i] != NULL; ++i)
+                  ;
+              end = &terms[i];
+              std::vector<DataTerm> dataterms = std::vector<DataTerm>(terms, end);
+              abac_terms_free(terms);
+              success=1;
+              return dataterms;
+            }
+/***
+   abac_aspect_t *oset()
+     returns the internal libabac representation of the oset
+***/
             abac_aspect_t *oset() {return m_oset;}
         private:
Index: libabac/abac_aspect.c
===================================================================
--- libabac/abac_aspect.c	(revision 0b3ac6598a8169fa335621f049ae698baffbf633)
+++ libabac/abac_aspect.c	(revision ed3dc05f96a0b311f3fe5dcfcedf789b79c0df5f)
@@ -465,4 +465,7 @@
         return NULL;
 
+    /* XXX currently, it might be good if the principal_name is used o
+       lookup the hashed id table and somehow link to the ID that it belongs
+       too, currently, we check it later.. */
     abac_aspect_t *ptr = _abac_aspect_init();
     ptr->aspect_type=type;
