sema-dotenv

Parse .env files and load environment variables.

Install

sema pkg add sema-dotenv

Quick start

(import "sema-dotenv")

;; Load .env into the environment (existing vars are not overridden)
(dotenv/load-if-exists ".env")

;; Get with a default
(define db-host (dotenv/get "DATABASE_HOST" "localhost"))

;; Error early if critical vars are missing
(dotenv/require "API_KEY" "SECRET_KEY")

API

dotenv/parse

(dotenv/parse "HOST=localhost\nPORT=5432")
; => {"HOST" "localhost" "PORT" "5432"}

Returns a map of string keys to string values. Blank lines, # comment lines, and malformed lines (no =, empty key) are skipped; when a key repeats, the last value wins. See Supported syntax for the full line format.

dotenv/read

(dotenv/read ".env")   ; => {"KEY" "value" ...}

Reads a file and parses it. Errors if the file does not exist — use dotenv/load-if-exists when the file is optional.

dotenv/load

(dotenv/load ".env")                  ; set vars, keep existing ones
(dotenv/load ".env" {:override #t})   ; set vars, replacing existing ones

Reads the file and sets each variable in the process environment. Like standard dotenv tooling, already-set environment variables win by default — pass {:override #t} to have the file win instead. Returns the full parsed map (including entries that were not applied because the variable was already set).

dotenv/load-if-exists

(dotenv/load-if-exists ".env.local")                  ; => {} if missing
(dotenv/load-if-exists ".env.local" {:override #t})

Same as dotenv/load, but a missing file returns {} instead of erroring.

dotenv/get

(dotenv/get "PORT" "5432")   ; => value of PORT, or "5432" if unset
(dotenv/get "PORT")          ; => value of PORT, or nil if unset

Reads from the process environment (use after dotenv/load).

dotenv/require

(dotenv/require "API_KEY" "SECRET_KEY")
; errors: "dotenv/require: missing required environment variables: ..."

Checks the process environment and raises an error naming every missing variable. Returns nil when all are present.

Supported .env syntax

# Full-line comments are ignored
KEY=value
export KEY=value          # "export " prefix is allowed
KEY = value               # spaces around = are trimmed

KEY="quoted value"        # double quotes: contents kept verbatim
KEY='single quoted'       # single quotes too
KEY="value" # comment     # after the closing quote: ignored
KEY=value # comment       # unquoted: " #..." strips the comment
COLOR=#ff0000             # but # right after = is the value
PASS=abc#def              # ...and # without a space before it is too

EMPTY=                    # empty value → ""
URL=postgres://u:p@h/db   # value may contain = (split on the first =)

Also handled: CRLF (\r\n) line endings, a leading UTF-8 BOM (stripped), # and spaces inside quotes. Not supported: multi-line values, escape sequences inside quotes (\n stays literal), and variable expansion ($OTHER stays literal).

Testing

sema pkg add sema-test   # once
sema tests.sema

License

MIT