environment

README

environment - Environment Logging

Documentation

Official godoc documentation (with examples) can be found at the Package Registry.

Usage

Add Package Dependency

go get -u github.com/x-ethr/environment

Import & Implement

main.go

package main

import (
    "fmt"

    "github.com/x-ethr/environment"
)

func main() {
    ctx, level := context.Background(), slog.LevelInfo

    // Log all environment variables
    environment.Log(ctx, level)

    // Log only specific environment variable(s)
    environment.Log(ctx, level, func(o *environment.Options) {
        o.Variables = []string{
            "PATH",
        }
    })

    // Log only specific environment variable(s), and warn if one of the specified variable(s) was set to an empty string
    environment.Log(ctx, level, func(o *environment.Options) {
        _ = os.Setenv("TEST", "") // --> for example purposes

        o.Variables = []string{
            "TEST",
        }

        o.Warnings.Empty = true
    })

    // Log only specific environment variable(s), and warn if one of the specified variable(s) wasn't found
    environment.Log(ctx, level, func(o *environment.Options) {
        _ = os.Unsetenv("TEST") // --> for example purposes

        o.Variables = []string{
            "TEST",
        }

        o.Warnings.Missing = true
    })
}

• Please refer to the code examples for additional usage and implementation details.
• See https://pkg.go.dev/github.com/x-ethr/environment for additional documentation.

Contributions

See the Contributing Guide for additional details on getting started.

Documentation

Overview

Package environment provides environment related functions, options, and logging for os-level capabilities.

Example

package main

import (
	"context"
	"log/slog"
	"os"

	"github.com/x-ethr/environment"
)

func main() {
	ctx, level := context.Background(), slog.LevelInfo

	// Log all environment variables
	environment.Log(ctx, level)

	// Log only specific environment variable(s)
	environment.Log(ctx, level, func(o *environment.Options) {
		o.Variables = []string{
			"PATH",
		}
	})

	// Log only specific environment variable(s), and warn if one of the specified variable(s) was set to an empty string
	environment.Log(ctx, level, func(o *environment.Options) {
		_ = os.Setenv("TEST", "") // --> for example purposes

		o.Variables = []string{
			"TEST",
		}

		o.Warnings.Empty = true
	})

	// Log only specific environment variable(s), and warn if one of the specified variable(s) wasn't found
	environment.Log(ctx, level, func(o *environment.Options) {
		_ = os.Unsetenv("TEST") // --> for example purposes

		o.Variables = []string{
			"TEST",
		}

		o.Warnings.Missing = true
	})
}

Index

• func Log(ctx context.Context, level slog.Level, settings ...Variadic)
• type Options
  • func Settings() *Options
• type Variadic
• type Warnings

Examples

• Package

Functions

func Log

func Log(ctx context.Context, level slog.Level, settings ...Variadic)

Log logs environment variables with the specified log level. It iterates over the environment variables, splits them into key-value pairs, and logs them using slog.Log.

Types

type Options

type Options struct {
	Variables []string  // Variables represents an array of environment variables (as returned by [os.Environ]), to selectively log.
	Warnings  *Warnings // Warnings represents logging options relating to [slog.Warn] logs. Defaults to a non-nil [Warnings] reference with all attributes set to false.
}

Options is the configuration structure optionally mutated via the Variadic constructor used throughout the package.

func Settings

func Settings() *Options

Settings represents a default constructor for Options.

type Variadic

type Variadic func(o *Options)

Variadic represents a functional constructor for the Options type. Typical callers of Variadic won't need to perform nil checks as all implementations first construct an Options reference using packaged default(s).

• However, see Settings for construction of an Options type.

type Warnings

type Warnings struct {
	Empty   bool // Empty represents a logging option to warn if a given environment variable is set to any empty string. Requires [Options.Variables]. Defaults to false.
	Missing bool // Missing represents a logging option to warn if a given environment variable isn't found. Requires [Options.Variables]. Defaults to false.
}