From ff7ce95000e308d639641949bd4821425cae75d5 Mon Sep 17 00:00:00 2001
From: darwincereska <accfordarwin@gmail.com>
Date: Mon, 8 Jun 2026 01:17:44 -0400
Subject: [PATCH] feat: added examples

---
 README.md            | 79 ++++++++++++++++++++++++++++++++++++++++++++
 examples/basic.rs    | 15 +++++++++
 examples/prefixed.rs | 16 +++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 README.md
 create mode 100644 examples/basic.rs
 create mode 100644 examples/prefixed.rs

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..433307f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# envkit
+
+`envkit` is a small Rust crate for reading environment variables and converting them into typed values.
+
+It keeps the API minimal:
+
+- `EnvLoader::get` reads a required variable.
+- `EnvLoader::get_or` reads a variable with a fallback.
+- `EnvLoader::get_opt` returns `Option<T>`.
+- `with_prefix` lets you build loaders for namespaced variables like `APP_PORT` or `DB_HOST`.
+
+## Supported types
+
+`envkit` currently supports:
+
+- `String`
+- `bool`
+- numeric types: `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `f32`, `f64`
+
+Boolean parsing accepts:
+
+- `true` / `false`
+- `1` / `0`
+- `t` / `f`
+
+## Quick start
+
+```rust
+use envkit::EnvLoader;
+
+fn main() -> Result<(), envkit::error::EnvError> {
+    let loader = EnvLoader;
+
+    let port: u16 = loader.get("PORT")?;
+    let debug: bool = loader.get_or("DEBUG", false);
+    let app_name: String = loader.get_opt("APP_NAME").unwrap_or_else(|| "envkit".to_string());
+
+    println!("port={port}, debug={debug}, app_name={app_name}");
+    Ok(())
+}
+```
+
+## Prefixed variables
+
+```rust
+use envkit::EnvLoader;
+
+fn main() -> Result<(), envkit::error::EnvError> {
+    let loader = EnvLoader;
+    let app = loader.with_prefix("APP_");
+
+    let host: String = app.get("HOST")?;
+    let port: u16 = app.get_or("PORT", 8080);
+
+    println!("host={host}, port={port}");
+    Ok(())
+}
+```
+
+If you use the prefixed loader above, it reads `APP_HOST` and `APP_PORT`.
+
+## Errors
+
+`envkit` returns `EnvError` for two cases:
+
+- `MissingVar` when the environment variable is not present
+- `Invalid` when parsing fails
+
+## Examples
+
+See the `examples/` folder for runnable usage samples.
+
+## Development
+
+Run the test suite with:
+
+```bash
+cargo test
+```
diff --git a/examples/basic.rs b/examples/basic.rs
new file mode 100644
index 0000000..f322f19
--- /dev/null
+++ b/examples/basic.rs
@@ -0,0 +1,15 @@
+use envkit::EnvLoader;
+
+fn main() -> Result<(), envkit::error::EnvError> {
+    let loader = EnvLoader;
+
+    let port: u16 = loader.get("PORT")?;
+    let debug: bool = loader.get_or("DEBUG", false);
+    let app_name: String = loader.get_opt("APP_NAME").unwrap_or_else(|| "envkit".to_string());
+
+    println!("port={port}");
+    println!("debug={debug}");
+    println!("app_name={app_name}");
+
+    Ok(())
+}
diff --git a/examples/prefixed.rs b/examples/prefixed.rs
new file mode 100644
index 0000000..3c671dc
--- /dev/null
+++ b/examples/prefixed.rs
@@ -0,0 +1,16 @@
+use envkit::EnvLoader;
+
+fn main() -> Result<(), envkit::error::EnvError> {
+    let loader = EnvLoader;
+    let app = loader.with_prefix("APP_");
+
+    let host: String = app.get("HOST")?;
+    let port: u16 = app.get_or("PORT", 8080);
+    let enabled: bool = app.get_or("ENABLED", false);
+
+    println!("host={host}");
+    println!("port={port}");
+    println!("enabled={enabled}");
+
+    Ok(())
+}