Merge branch 'graft'

README.md

@@ -31,7 +31,7 @@ It does not (yet) offer *editing* functionality; the objects returned are read-o
 The function `get_current_uid` returns a `uid_t` value representing the user currently running the program, and the `get_user_by_uid` function scans the users database and returns a User object with the user’s information.
 This function returns `None` when there is no user for that ID.
 
-A `User` object has the following public fields:
+A `User` object has the following accessors:
 
 - **uid:** The user’s ID
 - **name:** The user’s name
@@ -42,7 +42,7 @@ Here is a complete example that prints out the current user’s name:
 ```rust
 use users::{get_user_by_uid, get_current_uid};
 let user = get_user_by_uid(get_current_uid()).unwrap();
-println!("Hello, {}!", user.name);
+println!("Hello, {}!", user.name());
 ```
 
 This code assumes (with `unwrap()`) that the user hasn’t been deleted after the program has started running.
@@ -63,11 +63,11 @@ To introduce a cache, create a new `OSUsers` object and call the same methods on
 For example:
 
 ```rust
-use users::{Users, OSUsers};
-let mut cache = OSUsers::empty_cache();
+use users::{Users, Groups, UsersCache};
+let mut cache = UsersCache::new();
 let uid = cache.get_current_uid();
 let user = cache.get_user_by_uid(uid).unwrap();
-println!("Hello again, {}!", user.name);
+println!("Hello again, {}!", user.name());
 ```
 
 This cache is **only additive**: it’s not possible to drop it, or erase selected entries, as when the database may have been modified, it’s best to start entirely afresh.
@@ -77,22 +77,18 @@ So to accomplish this, just start using a new `OSUsers` object.
 ## Groups
 
 Finally, it’s possible to get groups in a similar manner.
-A `Group` object has the following public fields:
+A `Group` object has the following accessors:
 
 - **gid:** The group’s ID
 - **name:** The group’s name
-- **members:** Vector of names of the users that belong to this group
 
 And again, a complete example:
 
 ```rust
-use users::{Users, OSUsers};
-let mut cache = OSUsers::empty_cache();
+use users::{Users, Groups, UsersCache};
+let mut cache = UsersCache::new();
 let group = cache.get_group_by_name("admin").expect("No such group 'admin'!");
-println!("The '{}' group has the ID {}", group.name, group.gid);
-for member in group.members.into_iter() {
-    println!("{} is a member of the group", member);
-}
+println!("The '{}' group has the ID {}", group.name(), group.gid());
 ```
 
 
@@ -117,19 +113,13 @@ Aside from that, you can add users and groups with `add_user` and `add_group` to
 
 ```rust
 use users::mock::{MockUsers, User, Group};
+use users::os::unix::{UserExt, GroupExt};
+use std::sync::Arc;
+
 let mut users = MockUsers::with_current_uid(1000);
-users.add_user(User {
-    uid: 1000,
-    name: "Bobbins".to_string(),
-    primary_group: 100,
-    home_dir: "/home/bobbins".to_string(),
-    shell: "/bin/bash".to_string(),
-});
-users.add_group(Group {
-    gid: 100,
-    name: "funkyppl".to_string(),
-    members: vec![ "other_person".to_string() ]
-});
+let bobbins = User::new(1000, "Bobbins", 1000).with_home_dir("/home/bobbins");
+users.add_user(bobbins);
+users.add_group(Group::new(100, "funkyppl"));
 ```
 
 The exports get re-exported into the mock module, for simpler `use` lines.
@@ -143,24 +133,19 @@ Then, you can pass in an object of either OS or Mock type.
 Here's a complete example:
 
 ```rust
-use users::{Users, OSUsers, User};
+use users::{Users, UsersCache, User};
+use users::os::unix::UserExt;
 use users::mock::MockUsers;
+use std::sync::Arc;
 
 fn print_current_username<U: Users>(users: &mut U) {
     println!("Current user: {:?}", users.get_current_username());
 }
 
 let mut users = MockUsers::with_current_uid(1001);
-users.add_user(User {
-    uid: 1001,
-    name: "fred".to_string(),
-    primary_group: 101,
-    home_dir: "/home/fred".to_string(),
-    shell: "/bin/bash".to_string(),
-});
-
+users.add_user(User::new(1001, "fred", 101));
 print_current_username(&mut users);
 
-let mut actual_users = OSUsers::empty_cache();
+let mut actual_users = UsersCache::new();
 print_current_username(&mut actual_users);
 ```

examples/example.rs

@@ -8,17 +8,8 @@ fn main() {
 	println!("Your UID is {}", current_uid);
 
 	let you = cache.get_user_by_uid(current_uid).expect("No entry for current user!");
-	println!("Your username is {}", you.name);
+	println!("Your username is {}", you.name());
 
-	let primary_group = cache.get_group_by_gid(you.primary_group).expect("No entry for your primary group!");
-	println!("Your primary group has ID {} and name {}", primary_group.gid, primary_group.name);
-
-	if primary_group.members.is_empty() {
-		println!("There are no other members of that group.");
-	}
-	else {
-		for username in primary_group.members.iter() {
-			println!("User {} is also a member of that group.", username);
-		}
-	}
+	let primary_group = cache.get_group_by_gid(you.primary_group_id()).expect("No entry for your primary group!");
+	println!("Your primary group has ID {} and name {}", primary_group.gid(), primary_group.name());
 }

examples/os.rs

@@ -0,0 +1,33 @@
+extern crate users;
+use users::{Users, Groups, UsersCache};
+use users::os::unix::{UserExt, GroupExt};
+//use users::os::bsd::UserExt as BSDUserExt;
+
+fn main() {
+	let cache = UsersCache::new();
+
+	let current_uid = cache.get_current_uid();
+	println!("Your UID is {}", current_uid);
+
+	let you = cache.get_user_by_uid(current_uid).expect("No entry for current user!");
+	println!("Your username is {}", you.name());
+	println!("Your shell is {}", you.shell().display());
+	println!("Your home directory is {}", you.home_dir().display());
+
+    // The two fields below are only available on BSD systems.
+    // Linux systems don’t have the fields in their `passwd` structs!
+    //println!("Your password change timestamp is {}", you.password_change_time());
+    //println!("Your password expiry timestamp is {}", you.password_expire_time());
+
+	let primary_group = cache.get_group_by_gid(you.primary_group_id()).expect("No entry for your primary group!");
+	println!("Your primary group has ID {} and name {}", primary_group.gid(), primary_group.name());
+
+	if primary_group.members().is_empty() {
+		println!("There are no other members of that group.");
+	}
+	else {
+		for username in primary_group.members() {
+			println!("User {} is also a member of that group.", username);
+		}
+	}
+}

examples/threading.rs

@@ -52,7 +52,7 @@ fn main() {
     for uid in LO .. HI {
         let cache = cache.lock().unwrap();             // Re-unlock the mutex
         if let Some(u) = cache.get_user_by_uid(uid) {  // Re-query our cache!
-            println!("User #{} is {}", u.uid, u.name)
+            println!("User #{} is {}", u.uid(), u.name())
         }
         else {
             println!("User #{} does not exist", uid);