zig-dotenv

A simple and lightweight .env file parser for Zig applications. Parse environment configuration files with minimal overhead and zero external dependencies.

Features

Lightweight implementation in under 100 lines of pure Zig
Zero dependencies beyond the Zig standard library
Clean, straightforward API that's easy to integrate
Supports standard .env file format and conventions
Proper memory management with explicit allocation and cleanup

Installation

Add this repository as a dependency in your build.zig.zon:

.{
    .name = "your-project",
    .version = "0.1.0",
    .dependencies = .{
        .dotenv = .{
            .url = "https://github.com/BeigeHornet151/zig-dotenv/archive/main.tar.gz",
            .hash = "12200000000000000000000000000000000000000000000000000000000000000000", // Use zig fetch to get actual hash
        },
    },
}

Alternatively, you can copy src/dotenv.zig directly into your project.

Usage

Basic Example

const std = @import("std");
const dotenv = @import("dotenv");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();
    
    // Load .env file
    var env = try dotenv.DotEnv.loadFile(allocator, ".env");
    defer env.deinit();
    
    // Get values
    const db_url = env.get("DATABASE_URL") orelse "default_db_url";
    const api_key = env.get("API_KEY") orelse "no_key";
    
    std.debug.print("Database URL: {s}\n", .{db_url});
    std.debug.print("API Key: {s}\n", .{api_key});
}

Example .env file

# Database configuration
DATABASE_URL=postgres://localhost:5432/myapp
DATABASE_POOL_SIZE=10

# API settings
API_KEY=your_secret_key_here
API_TIMEOUT=30

# Feature flags
DEBUG=true
ENABLE_LOGGING=false

# Quoted values
WELCOME_MESSAGE="Hello, World!"
SINGLE_QUOTED='Also works'

Supported Format

The parser handles standard .env file format:

Key-value pairs: KEY=value
Comments: Lines starting with # are ignored
Empty lines: Blank lines are skipped
Quoted values: Both "double" and 'single' quotes are supported and stripped
Whitespace: Leading and trailing whitespace is automatically trimmed

API Reference

`DotEnv`

Main struct for loading and accessing environment variables.

Methods

loadFile(allocator: Allocator, path: []const u8) !DotEnv

Loads a .env file from the specified path
Returns DotEnvError.FileNotFound if the file doesn't exist
Allocates memory for all key-value pairs

get(key: []const u8) ?[]const u8

Retrieves a value by its key
Returns null if the key doesn't exist

deinit()

Frees all allocated memory
Must be called when finished with the DotEnv instance

Testing

Run the tests:

zig test test.zig

Contributing

Contributions are welcome. Please:

Fork the repository
Create a feature branch
Add tests for any new functionality
Ensure all existing tests pass
Submit a pull request with a clear description

README