Merge pull request #10 from delan/delan/examples

fix and improve macros and README.md examples

Cargo.toml

@@ -10,7 +10,7 @@ keywords = ["openbsd", "binding", "security"]
 license = "MIT"
 
 [workspace]
-members = ["variants"]
+members = ["variants", "example-2015", "example-2018"]
 
 [dependencies]
 libc = "0.2"

README.md

@@ -7,77 +7,71 @@ A Rust binding to OpenBSD's pledge(2) interface.
 
 ## Usage
 
-    #[macro_use] extern crate pledge;
-    use pledge::{pledge, Promise, ToPromiseString};
+    /* Rust 2015 only */ #[macro_use] extern crate pledge;
+    /* Rust 2018 only */ use pledge::{pledge, pledge_promises, pledge_execpromises};
 
     fn foo() {
         // make both promises and execpromises
-        match pledge![Stdio Proc Exec, Stdio Tty] {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge![Stdio Proc Exec, Stdio Tty].unwrap();
 
         // make promises only
-        match pledge_promises[Stdio Exec] {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge_promises![Stdio Exec].unwrap();
 
         // make execpromises only
-        match pledge_execpromises[Stdio] {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge_execpromises![Stdio].unwrap();
     }
 
-This is equivalent to:
+This is roughly equivalent to:
 
-    extern crate pledge;
+    /* Rust 2015 only */ extern crate pledge;
     use pledge::{pledge, Promise, ToPromiseString};
 
     fn foo() {
         // make both promises and execpromises
         let promises = vec![Promise::Stdio, Promise::Proc, Promise::Exec];
         let execpromises = vec![Promise::Stdio, Promise::Tty];
-        match pledge(&*promises.to_promise_string(), &*execpromises.to_promise_string()) {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge(&*promises.to_promise_string(), &*execpromises.to_promise_string()).unwrap();
 
         // make promises only
         let promises = vec![Promise::Stdio, Promise::Exec];
-        match pledge(&*promises.to_promise_string(), None) {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge(&*promises.to_promise_string(), None).unwrap();
 
         // make execpromises only
         let execpromises = vec![Promise::Stdio];
-        match pledge(None, &*execpromises.to_promise_string()) {
-            Err(_) => println!("Failed to pledge"),
-            _ => ()
-        }
+        pledge(None, &*execpromises.to_promise_string()).unwrap();
     }
 
 You may also provide promises directly as a string:
 
+    /* Rust 2015 only */ extern crate pledge;
     use pledge::pledge;
 
     fn foo() {
         // make both promises and execpromises
-        if pledge("stdio proc exec", "stdio tty").is_err() {
-            panic!("Failed to pledge");
-        }
+        pledge("stdio proc exec", "stdio tty").unwrap();
 
         // make promises only
-        if pledge("stdio exec", None).is_err() {
-            panic!("Failed to pledge");
-        }
+        pledge("stdio exec", None).unwrap();
 
         // make execpromises only
-        if pledge(None, "stdio").is_err() {
-            panic!("Failed to pledge");
-        }
+        pledge(None, "stdio").unwrap();
+    }
+
+All of these will yield `pledge::Error::UnsupportedPlatform` on platforms that
+don’t support pledge(2). You can use `pledge::Error::ignore_platform` to ignore
+that variant and make your program portable to those platforms:
+
+    /* Rust 2015 only */ extern crate pledge;
+    /* Rust 2018 only */ use pledge::pledge_promises;
+
+    fn foo() {
+        ...
+
+        pledge_promises![Stdio Exec]
+            .or_else(pledge::Error::ignore_platform)
+            .unwrap();
+
+        ...
     }
 
 ## Compatibility
@@ -91,7 +85,7 @@ where the second parameter sets a whitelist of permitted paths.
 
 To migrate your code from older versions:
 
-* change `pledge![P, Q, R]` call sites to `pledge_promises![P, Q, R]`
+* change `pledge![P, Q, R]` call sites to `pledge_promises![P Q R]`
 * change `pledge("p q r")` call sites to `pledge("p q r", None)`
 * change `pledge_with_paths(promises, paths)` to `pledge(promises)`
 * update usage of renamed `Promise` variants (e.g. `MCast` → `Mcast`)

example-2015/.gitignore

@@ -0,0 +1 @@
+/target/

example-2015/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "pledge-example-2015"
+version = "0.0.0"
+authors = ["Andrew Aldridge <[email protected]>", "Delan Azabani <[email protected]>"]
+edition = "2015"
+publish = false
+
+[dependencies.pledge]
+path = ".."

example-2015/src/main.rs

@@ -0,0 +1,9 @@
+#[macro_use]
+extern crate pledge;
+
+fn main() {
+    pledge_promises![Stdio]
+        .or_else(pledge::Error::ignore_platform)
+        .unwrap();
+    println!("Hello, world!");
+}

example-2018/.gitignore

@@ -0,0 +1 @@
+/target/

example-2018/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "pledge-example-2018"
+version = "0.0.0"
+authors = ["Andrew Aldridge <[email protected]>", "Delan Azabani <[email protected]>"]
+edition = "2018"
+publish = false
+
+[dependencies.pledge]
+path = ".."

example-2018/src/main.rs

@@ -0,0 +1,8 @@
+use pledge::pledge_promises;
+
+fn main() {
+    pledge_promises![Stdio]
+        .or_else(pledge::Error::ignore_platform)
+        .unwrap();
+    println!("Hello, world!");
+}

src/lib.rs

@@ -12,6 +12,15 @@ pub enum Error {
     Other(c_int),
 }
 
+impl Error {
+    pub fn ignore_platform(self) -> Result<(), Self> {
+        match self {
+            Error::UnsupportedPlatform => Ok(()),
+            x => Err(x),
+        }
+    }
+}
+
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match *self {
@@ -68,14 +77,14 @@ macro_rules! pledge {
             let mut promises = Vec::new();
             let mut execpromises = Vec::new();
             $(
-                promises.push(Promise::$promises);
+                promises.push($crate::Promise::$promises);
             )*
             $(
-                execpromises.push(Promise::$execpromises);
+                execpromises.push($crate::Promise::$execpromises);
             )*
-            let promises = promises.to_promise_string();
-            let execpromises = execpromises.to_promise_string();
-            pledge(&*promises, &*execpromises)
+            let promises = $crate::ToPromiseString::to_promise_string(&*promises);
+            let execpromises = $crate::ToPromiseString::to_promise_string(&*execpromises);
+            $crate::pledge(&*promises, &*execpromises)
         }
     };
 }
@@ -86,10 +95,10 @@ macro_rules! pledge_promises {
         {
             let mut promises = Vec::new();
             $(
-                promises.push(Promise::$promises);
+                promises.push($crate::Promise::$promises);
             )*
-            let promises = promises.to_promise_string();
-            pledge(&*promises, None)
+            let promises = $crate::ToPromiseString::to_promise_string(&*promises);
+            $crate::pledge(&*promises, None)
         }
     };
 }
@@ -100,10 +109,10 @@ macro_rules! pledge_execpromises {
         {
             let mut execpromises = Vec::new();
             $(
-                execpromises.push(Promise::$execpromises);
+                execpromises.push($crate::Promise::$execpromises);
             )*
-            let execpromises = execpromises.to_promise_string();
-            pledge(None, &*execpromises)
+            let execpromises = $crate::ToPromiseString::to_promise_string(&*execpromises);
+            $crate::pledge(None, &*execpromises)
         }
     };
 }