Add examples to the pinger library. Closes #428

2 files changed, 54 insertions, 0 deletions

diff --git a/pinger/README.md b/pinger/README.md
new file mode 100644
index 0000000..ae1c96d
--- /dev/null
+++ b/pinger/README.md
@@ -0,0 +1,35 @@
+# pinger
+
+> A small cross-platform library to execute the ping command and parse the output.
+
+This crate is primarily built for use with `gping`, but it can also be used as a 
+standalone library.
+
+This allows you to reliably ping hosts without having to worry about process permissions, 
+in a cross-platform manner on Windows, Linux and macOS.
+
+## Usage
+
+A full example of using the library can be found in the `examples/` directory, but the 
+interface is quite simple:
+
+```rust
+use pinger::ping;
+
+fn ping_google() {
+    let stream = ping("google.com", None).expect("Error pinging");
+    for message in stream {
+        match message {
+            pinger::PingResult::Pong(duration, _) => {
+                println!("Duration: {:?}", duration)
+            }
+            _ => {} // Handle errors, log ping timeouts, etc.
+        }
+    }
+}           
+```
+
+## Adding pinger to your project.
+
+`cargo add pinger`
+
diff --git a/pinger/examples/simple-ping.rs b/pinger/examples/simple-ping.rs
new file mode 100644
index 0000000..9afe064
--- /dev/null
+++ b/pinger/examples/simple-ping.rs
@@ -0,0 +1,19 @@
+use pinger::ping_with_interval;
+
+pub fn main() {
+    let target = "tomforb.es".to_string();
+    let interval = std::time::Duration::from_secs(1);
+    let stream = ping_with_interval(target, interval, None).expect("Error pinging");
+    for message in stream {
+        match message {
+            pinger::PingResult::Pong(duration, line) => {
+                println!("Duration: {:?}\t\t(raw: {:?})", duration, line)
+            }
+            pinger::PingResult::Timeout(line) => println!("Timeout! (raw: {line:?})"),
+            pinger::PingResult::Unknown(line) => println!("Unknown line: {:?}", line),
+            pinger::PingResult::PingExited(code, stderr) => {
+                println!("Ping exited! Code: {:?}. Stderr: {:?}", code, stderr)
+            }
+        }
+    }
+}