venv

README

venv

A simple way to manage environment variables in Go. venv provides a virtual environment as a map[string]string, letting you read, write, diff, merge, import/export, and expand environment variables without touching the OS environment until you choose to.

Minimum Go version: 1.21

中文文档

Installation

go get github.com/YSJDG/venv

Quick Start

package main

import (
    "fmt"
    "github.com/YSJDG/venv"
)

func main() {
    // Create a new virtual environment
    v := venv.New()

    // Set variables
    v.Setenv("APP_NAME", "myapp")
    v.Setenv("APP_PORT", "8080")

    // Get a variable
    fmt.Println(v.Getenv("APP_NAME")) // "myapp"

    // Look up with existence check
    val, ok := v.LookupEnv("APP_PORT")
    if ok {
        fmt.Println("Port:", val) // "Port: 8080"
    }

    // Apply to the real environment
    v.ToEnv()
}

Core Types

type Venv map[string]string

Venv is a plain map[string]string — you can use it just like a map.

type VenvDiff struct {
    OldOnly  Venv // keys present only in the old environment
    NewOnly  Venv // keys present only in the new environment
    OldValue Venv // old values of changed keys
    NewValue Venv // new values of changed keys
}

API Reference

Creating & Merging

Function	Description
New() Venv	Create an empty virtual environment.
Merge(venvs ...Venv) Venv	Merge multiple environments. Later values overwrite earlier ones for the same key.

Comparing

Function	Description
Diff(old, new Venv) VenvDiff	Compute the difference between two environments: added, removed, and changed keys.

Import / Export

Method	Description
FromMap(m map[string]string, expand bool) Venv	Load variables from a map. If expand is true, values are expanded against the current environment.
ToMap() map[string]string	Export all variables as a new map.
FromSlice(s []string, expand bool) Venv	Load variables from a KEY=VALUE slice. A key without = unsets that variable.
ToSlice() []string	Export as a KEY=VALUE slice (alias of Environ).
FromJson(data []byte, expand bool) error	Load variables from JSON: [{"key":"K","value":"V"}, ...].
ToJson() ([]byte, error)	Export as JSON (same format).
FromEnv() Venv	Load all variables from the real OS environment.
ToEnv() error	Apply all variables to the real OS environment.

Variable Expansion

Method	Description
ExpandEnv(s string) string	Expand $VAR references using only the virtual environment.
ExpandEnvHybrid(s string) string	Expand $VAR references, checking the virtual environment first, then falling back to the real OS environment.
ExpandEnvInMap(m map[string]string) map[string]string	Apply ExpandEnvHybrid to every value in a map (modifies in place).
ExpandEnvInSlice(s []string) []string	Apply ExpandEnvHybrid to every element in a slice (modifies in place).

CRUD

Method	Description
Setenv(key, val string)	Set a variable.
Getenv(key string) string	Get a variable (returns empty string if missing).
LookupEnv(key string) (string, bool)	Get a variable with an existence boolean.
Unsetenv(key string)	Delete a variable.
Setvar(pair string)	Parse KEY=VALUE or KEY (unsets).
Clearenv() Venv	Remove all variables.
Environ() []string	Export as KEY=VALUE slice.

Notes

• Variable names are case-sensitive.
• This package is not concurrency-safe. Protect access with a mutex if using across goroutines.
• FromMap, FromSlice, FromJson, and Environ are intentionally out of order — iteration over a Go map is non-deterministic.
• FromSlice treats a key without = as a removal instruction (calls Unsetenv).

License

MIT

Documentation

Overview

A simple way to manage environment variables. (Minimal Go version: 1.21)

Note: Variable names in virtual environment are case sensitive. This package is not concurrency safe.

Index

• type Venv
  • func Merge(venvs ...Venv) Venv
  • func New() Venv
  • func (v Venv) Clearenv() Venv
  • func (v Venv) Environ() []string
  • func (v Venv) ExpandEnv(s string) string
  • func (v Venv) ExpandEnvHybrid(s string) string
  • func (v Venv) ExpandEnvInMap(m map[string]string) map[string]string
  • func (v Venv) ExpandEnvInSlice(s []string) []string
  • func (v Venv) FromEnv() Venv
  • func (v Venv) FromJson(data []byte, expand bool) error
  • func (v Venv) FromMap(newMap map[string]string, expand bool) Venv
  • func (v Venv) FromSlice(newSlice []string, expand bool) Venv
  • func (v Venv) Getenv(key string) string
  • func (v Venv) LookupEnv(key string) (string, bool)
  • func (v Venv) Setenv(key string, val string)
  • func (v Venv) Setvar(pair string)
  • func (v Venv) ToEnv() error
  • func (v Venv) ToJson() ([]byte, error)
  • func (v Venv) ToMap() map[string]string
  • func (v Venv) ToSlice() []string
  • func (v Venv) Unsetenv(key string)
• type VenvDiff
  • func Diff(oldVenv Venv, newVenv Venv) VenvDiff

Types

type Venv

type Venv map[string]string

Type of virtual environment. It is a Map, so you can manipulate virtual environments just like you would a Map.

func Merge

func Merge(venvs ...Venv) Venv

Merge virtual environment instances.

func New

func New() Venv

Create a new virtual environment instance.

func (Venv) Clearenv

func (v Venv) Clearenv() Venv

func (Venv) Environ

func (v Venv) Environ() []string

This operation is out of order.

func (Venv) ExpandEnv

func (v Venv) ExpandEnv(s string) string

func (Venv) ExpandEnvHybrid

func (v Venv) ExpandEnvHybrid(s string) string

ExpandEnv with a fallback approach. Prioritize searching in the virtual environment, and if not, using variables from the actual environment.

func (Venv) ExpandEnvInMap

func (v Venv) ExpandEnvInMap(m map[string]string) map[string]string

Apply ExpandEnvHybrid to each value in map. This method directly modifies the original Map/Slice passed in.

func (Venv) ExpandEnvInSlice

func (v Venv) ExpandEnvInSlice(s []string) []string

Apply ExpandEnvHybrid to each element in slice. This method directly modifies the original Map/Slice passed in.

func (Venv) FromEnv

func (v Venv) FromEnv() Venv

Update virtual environment from actual environment.

func (Venv) FromJson

func (v Venv) FromJson(data []byte, expand bool) error

Update virtual environment from JSON JSON Format: [{"key": "KEY", "value": "VALUE"}...]

func (Venv) FromMap

func (v Venv) FromMap(newMap map[string]string, expand bool) Venv

Update virtual environment from map. This operation is out of order.

func (Venv) FromSlice

func (v Venv) FromSlice(newSlice []string, expand bool) Venv

Update virtual environment from slice.

func (Venv) Getenv

func (v Venv) Getenv(key string) string

func (Venv) LookupEnv

func (v Venv) LookupEnv(key string) (string, bool)

func (Venv) Setenv

func (v Venv) Setenv(key string, val string)

func (Venv) Setvar

func (v Venv) Setvar(pair string)

Update virtual environment by key-value pair. If there is no "=", the variable will be unset.

func (Venv) ToEnv

func (v Venv) ToEnv() error

Apply virtual environment to actual environment. This operation terminates on error, but does not have the ability to restore environment variables.

func (Venv) ToJson

func (v Venv) ToJson() ([]byte, error)

Export virtual environment to JSON. JSON Format: [{"key": "KEY", "value": "VALUE"}...] This operation is out of order.

func (Venv) ToMap

func (v Venv) ToMap() map[string]string

Export virtual environment to map[string]string.

func (Venv) ToSlice

func (v Venv) ToSlice() []string

Export virtual environment to []string. This method is a alias of Environ. This operation is out of order.

func (Venv) Unsetenv

func (v Venv) Unsetenv(key string)

type VenvDiff

type VenvDiff struct {
	OldOnly  Venv // keys in old virtual environment only
	NewOnly  Venv // keys in new virtual environment only
	OldValue Venv // values of changed keys in old virtual environment
	NewValue Venv // values of changed keys in new virtual environment
}

Result of Diff

func Diff

func Diff(oldVenv Venv, newVenv Venv) VenvDiff

Get difference of two virtual environment instance.