Examples
The env library ships 11 runnable examples in the examples/ directory of the source repository. Each example is a self-contained main program, covering everything from global-mode basics to security features and advanced capabilities. All examples are included in normal builds (go build ./...).
Running the Examples
Clone the repository at github.com/cybergodev/env, then run go run from the project root:
git clone https://github.com/cybergodev/env.git
cd env
go run ./examples/01_quickstart/Examples reference shared configuration files under examples/data/ using relative paths, so they must be run from the project root for those paths to resolve.
Shared Data Files
| File | Format | Purpose |
|---|---|---|
config.env | dotenv | Flat KEY=value pairs, variable expansion demo |
config.json | JSON | Nested structure (app/db/cache/features) |
config.yaml | YAML | Same structure as JSON, for struct mapping demos |
Example Index
| # | Directory | What It Demonstrates | Related Docs |
|---|---|---|---|
| 01 | 01_quickstart/ | Global-mode basics: Load initialization, typed access via GetString/GetInt/GetBool/GetDuration, Lookup existence checks, runtime Set | Quick Start |
| 02 | 02_loader_config/ | Instance mode with four config presets (Default/Development/Production/Testing), custom configs, and explicit lifecycle control | Config, Loader |
| 03 | 03_type_access/ | Every typed getter: string, int, bool, duration, float, uint, and slice, plus Lookup, including dot-notation paths | Quick Start |
| 04 | 04_struct_mapping/ | Struct mapping with env tags: nested structs, envDefault defaults, and marshaling | Struct Mapping |
| 05 | 05_secure_values/ | SecureValue lifecycle: Close vs Release, memory zeroing, and mlock memory locking | Memory Locking, SecureValue |
| 06 | 06_audit_logging/ | JSON, Channel, and Log audit handlers, automatically capturing read, write, and delete events | Audit Logging |
| 07 | 07_marshal_unmarshal/ | Format conversion: map ↔ string, struct ↔ map, multi-format output, and round trips | Serialization |
| 08 | 08_utilities/ | Utility functions: introspection (Len/Keys/All), key deletion, masking, and format detection | Multi-format Config |
| 09 | 09_error_handling/ | Sentinel errors (errors.Is) and typed errors (errors.As), including missing-file and closed-loader cases | Error Handling |
| 10 | 10_concurrency/ | Concurrent reads, writes, and mixed access, demonstrating shard-lock concurrency safety | Concurrency |
| 11 | 11_advanced/ | Variable expansion ($VAR and ${VAR}), multiple file loading with override, and prefix filtering | Variable Expansion |
Reading Order
We recommend reading the examples in numeric order: 01–03 cover the global and instance modes plus typed access, 04–07 introduce production features such as struct mapping, secure values, and auditing, and 08–11 move on to utilities, error handling, and advanced features. Every example can be verified directly with go run and pairs well with its linked documentation page.