Rename OSUsers to UsersCache

It's more descriptive to call it a cache when there are functions that do all the *actual* OS users stuff separately now.

Similarly, we may as well call its constructor 'new' instead of 'empty_cache', because it's obvious that it's a cache now.

examples/example.rs

@@ -1,8 +1,8 @@
 extern crate users;
-use users::{Users, Groups, OSUsers};
+use users::{Users, Groups, UsersCache};
 
 fn main() {
-	let cache = OSUsers::empty_cache();
+	let cache = UsersCache::new();
 
 	let current_uid = cache.get_current_uid();
 	println!("Your UID is {}", current_uid);

examples/threading.rs

@@ -1,4 +1,4 @@
-//! This example demonstrates how to use an `OSUsers` cache in a
+//! This example demonstrates how to use a `UsersCache` cache in a
 //! multi-threaded situation. The cache uses `RefCell`s internally, so it
 //! is distinctly not thread-safe. Instead, you’ll need to place it within
 //! some kind of lock in order to have threads access it one-at-a-time.
@@ -16,7 +16,7 @@
 // spew compile errors at you.
 
 extern crate users;
-use users::{Users, OSUsers, uid_t};
+use users::{Users, UsersCache, uid_t};
 
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -30,8 +30,8 @@ fn main() {
     // For thread-safely, our users cache needs to be within a Mutex, so
     // only one thread can access it once. This Mutex needs to be within an
     // Arc, so multiple threads can access the Mutex.
-    let cache = Arc::new(Mutex::new(OSUsers::empty_cache()));
-    // let cache = OSUsers::empty_cache();
+    let cache = Arc::new(Mutex::new(UsersCache::new()));
+    // let cache = UsersCache::empty_cache();
 
     // Loop over the range and query all the users in the range. Although we
     // could use the `&User` values returned, we just ignore them.

src/cache.rs

@@ -2,7 +2,7 @@
 //!
 //! ## Caching, multiple threads, and mutability
 //!
-//! The `OSUsers` type is caught between a rock and a hard place when it comes
+//! The `UsersCache` type is caught between a rock and a hard place when it comes
 //! to providing references to users and groups.
 //!
 //! Instead of returning a fresh `User` struct each time, for example, it will
@@ -25,7 +25,7 @@
 //! to be read at a time!
 //!
 //! ``norun
-//! let mut cache = OSUsers::empty_cache();
+//! let mut cache = UsersCache::empty_cache();
 //! let uid   = cache.get_current_uid();                     // OK...
 //! let user  = cache.get_user_by_uid(uid).unwrap()          // OK...
 //! let group = cache.get_group_by_gid(user.primary_group);  // No!
@@ -73,7 +73,7 @@ use traits::{Users, Groups};
 
 
 /// A producer of user and group instances that caches every result.
-pub struct OSUsers {
+pub struct UsersCache {
     users:  BiMap<uid_t, User>,
     groups: BiMap<gid_t, Group>,
 
@@ -97,9 +97,9 @@ struct BiMap<K, V> {
 // Default impl on User or Group, even though those types aren't
 // needed to produce a default instance of any HashMaps...
 
-impl Default for OSUsers {
-    fn default() -> OSUsers {
-        OSUsers {
+impl Default for UsersCache {
+    fn default() -> UsersCache {
+        UsersCache {
             users: BiMap {
                 forward:  RefCell::new(HashMap::new()),
                 backward: RefCell::new(HashMap::new()),
@@ -118,15 +118,15 @@ impl Default for OSUsers {
     }
 }
 
-impl OSUsers {
+impl UsersCache {
 
     /// Create a new empty cache.
-    pub fn empty_cache() -> OSUsers {
-        OSUsers::default()
+    pub fn new() -> UsersCache {
+        UsersCache::default()
     }
 }
 
-impl Users for OSUsers {
+impl Users for UsersCache {
     fn get_user_by_uid(&self, uid: uid_t) -> Option<Arc<User>> {
         let mut users_forward = self.users.forward.borrow_mut();
 
@@ -219,7 +219,7 @@ impl Users for OSUsers {
     }
 }
 
-impl Groups for OSUsers {
+impl Groups for UsersCache {
     fn get_group_by_gid(&self, gid: gid_t) -> Option<Arc<Group>> {
         let mut groups_forward = self.groups.forward.borrow_mut();
 

src/lib.rs

@@ -60,12 +60,12 @@
 //! which offers the same functionality while holding on to every result,
 //! caching the information so it can be re-used.
 //!
-//! To introduce a cache, create a new `OSUsers` object and call the same
+//! To introduce a cache, create a new `UsersCache` and call the same
 //! methods on it. For example:
 //!
 //! ```rust
-//! use users::{Users, Groups, 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);
@@ -74,13 +74,13 @@
 //! 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. So to accomplish this, just start using a new
-//! `OSUsers` object.
+//! `UsersCache`.
 //!
 //!
 //! ## Groups
 //!
 //! Finally, it’s possible to get groups in a similar manner.
-//! A `Group` object has the following public fields:
+//! A `Group` has the following public fields:
 //!
 //! - **gid:** The group’s ID
 //! - **name:** The group’s name
@@ -89,8 +89,8 @@
 //! And again, a complete example:
 //!
 //! ```rust
-//! use users::{Users, Groups, 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 {
@@ -114,12 +114,12 @@ pub use libc::{uid_t, gid_t};
 mod base;
 pub use base::*;
 
+pub mod cache;
+pub use cache::UsersCache;
+
 pub mod mock;
-pub mod os;
-pub use os::OSUsers;
 
 pub mod switch;
-use switch::*;
 
 mod traits;
 pub use traits::{Users, Groups};

src/mock.rs

@@ -32,12 +32,12 @@
 //!
 //! To set your program up to use either type of Users object, make your
 //! functions and structs accept a generic parameter that implements the `Users`
-//! trait. Then, you can pass in an object of either OS or Mock type.
+//! trait. Then, you can pass in a value of either Cache or Mock type.
 //!
 //! Here's a complete example:
 //!
 //! ```rust
-//! use users::{Users, OSUsers, User};
+//! use users::{Users, UsersCache, User};
 //! use users::mock::MockUsers;
 //! use std::sync::Arc;
 //!
@@ -49,7 +49,7 @@
 //! users.add_user(User { uid: 1001, name: Arc::new("fred".to_string()), primary_group: 101 , home_dir: "/home/fred".to_string(), shell: "/bin/bash".to_string()});
 //! print_current_username(&mut users);
 //!
-//! let mut actual_users = OSUsers::empty_cache();
+//! let mut actual_users = UsersCache::new();
 //! print_current_username(&mut actual_users);
 //! ```