Add pub(restricted) example

Author: cramertj

examples/mod/visibility/visibility.rs

@@ -1,39 +1,55 @@
-// A module named `my`
-mod my {
+// A module named `my_mod`
+mod my_mod {
     // Items in modules default to private visibility.
     fn private_function() {
-        println!("called `my::private_function()`");
+        println!("called `my_mod::private_function()`");
     }
-    
+
     // Use the `pub` modifier to override default visibility.
     pub fn function() {
-        println!("called `my::function()`");
+        println!("called `my_mod::function()`");
     }
-    
+
     // Items can access other items in the same module,
     // even when private.
     pub fn indirect_access() {
-        print!("called `my::indirect_access()`, that\n> ");
+        print!("called `my_mod::indirect_access()`, that\n> ");
         private_function();
     }
 
     // Modules can also be nested
     pub mod nested {
         pub fn function() {
-            println!("called `my::nested::function()`");
+            println!("called `my_mod::nested::function()`");
         }
 
         #[allow(dead_code)]
         fn private_function() {
-            println!("called `my::nested::private_function()`");
+            println!("called `my_mod::nested::private_function()`");
         }
+
+        // Functions declared using `pub(in path)` syntax are only visible
+        // within the given path
+        pub(in my_mod) fn public_function_in_my_mod() {
+        println!("called `my_mod::nested::public_function_in_my_mod()`")
+    }
+    }
+
+    pub fn call_public_function_in_my_mod() {
+        print!("called `my_mod::call_public_funcion_in_my_mod()`, that\n> ");
+        nested::public_function_in_my_mod();
+    }
+
+    // pub(crate) makes functions visible only within the current crate
+    pub(crate) fn public_function_in_crate() {
+        println!("called `my_mod::public_function_in_crate()");
     }
-    
+
     // Nested modules follow the same rules for visibility
     mod private_nested {
         #[allow(dead_code)]
         pub fn function() {
-            println!("called `my::private_nested::function()`");
+            println!("called `my_mod::private_nested::function()`");
         }
     }
 }
@@ -45,16 +61,25 @@ fn function() {
 fn main() {
     // Modules allow disambiguation between items that have the same name.
     function();
-    my::function();
-    
+    my_mod::function();
+
     // Public items, including those inside nested modules, can be
     // accessed from outside the parent module.
-    my::indirect_access();
-    my::nested::function();
+    my_mod::indirect_access();
+    my_mod::nested::function();
+    my_mod::call_public_function_in_my_mod();
+
+    // pub(crate) items can be called from anywhere in the same crate
+    my_mod::public_function_in_crate();
+
+    // pub(in path) items can only be called from within the mode specified
+    // Error! function `public_function_in_my_mod` is private
+    // my_mod::nested::public_function_in_my_mod();
+    // TODO ^ Try uncommenting this line
 
     // Private items of a module cannot be directly accessed, even if
     // nested in a public module:
-    
+
     // Error! `private_function` is private
     //my::private_function();
     // TODO ^ Try uncommenting this line