Golang Kommandozeilenargumente: os.Args, flag und Umgebungsvariablen

os.Args

os.Args ist ein Slice von Strings. os.Args[0] ist der Name des Programms, der Rest sind die Argumente genau so, wie die Shell sie übergeben hat.

package main

import (
	"fmt"
	"os"
)

func main() {
	fmt.Println("argument count:", len(os.Args)-1)
	for i, arg := range os.Args[1:] {
		fmt.Printf("arg %d: %q\n", i+1, arg)
	}
	if len(os.Args) < 2 {
		fmt.Println("no arguments: type some in the Args panel and run again")
	}
}

Im Args-Panel des Editors ist jedes Feld ein Argument und wird unverändert übergeben. Trag hello, two words und -v in drei Felder ein: Das Programm sieht drei Argumente, und two words bleibt ein Argument mit einem Leerzeichen darin. Im Terminal übernimmt die Shell das Aufteilen, dort schreibst du dasselbe als go run . hello "two words" -v.

Prüf immer len(os.Args), bevor du indizierst. os.Args[1] ohne Argumente löst eine Panic mit index out of range [1] with length 1 aus.

Argumente sind Strings. Konvertiere Zahlen mit strconv.Atoi oder strconv.ParseFloat und behandle den Fehler, denn Nutzer tippen alles Mögliche.

Das Paket flag

Für Optionen wie -port 8080 -verbose nimmst du flag. Es parst, konvertiert Typen, meldet Fehler und erzeugt eine Hilfemeldung.

package main

import (
	"flag"
	"fmt"
	"strings"
	"time"
)

func main() {
	name := flag.String("name", "world", "who to greet")
	count := flag.Int("count", 1, "how many times")
	loud := flag.Bool("loud", false, "shout the greeting")
	delay := flag.Duration("delay", 0, "pause between greetings, e.g. 10ms")

	flag.Parse()

	msg := "hello, " + *name
	if *loud {
		msg = strings.ToUpper(msg) + "!"
	}
	for i := range *count {
		if i > 0 {
			time.Sleep(*delay)
		}
		fmt.Println(msg)
	}
	fmt.Println("remaining args:", flag.Args())
}

Ohne Argumente gibt das einmal hello, world aus. Trag im Args-Panel -name und Gopher in zwei Felder ein, dann -count=3, -loud und extra in drei weitere. Das Programm gibt dreimal HELLO, GOPHER! aus und remaining args: [extra].

So funktionieren Flags:

• Jede Definitionsfunktion (flag.String, flag.Int, flag.Bool, flag.Float64, flag.Duration, flag.Uint64...) nimmt einen Namen, einen Standardwert und einen Hilfetext und gibt einen Pointer zurück. Den Wert liest du nach flag.Parse() mit *name.
• Die Var-Formen binden an eine Variable, die du schon hast: flag.IntVar(&cfg.Port, "port", 8080, "port"). Für ein Config-Struct ist das aufgeräumter.
• Nutzer können -name value, -name=value, --name value oder --name=value schreiben. Go unterscheidet nicht zwischen einem und zwei Bindestrichen.
• Booleans brauchen =, um einen Wert zu nehmen. -loud setzt true, -loud=false setzt false, aber -loud false setzt true und lässt false als Positionsargument übrig.
• Das Parsen stoppt beim ersten Argument, das kein Flag ist (oder bei --). prog file.txt -v behandelt -v als Positionsargument. Setz Flags an den Anfang.
• flag.Args() gibt die verbleibenden Positionsargumente zurück, flag.NArg() ihre Anzahl und flag.Arg(i) eines davon.

Ein unbekanntes Flag oder ein falscher Wert gibt einen Fehler plus die Hilfe aus und beendet das Programm mit Status 2. -h oder -help gibt die Hilfe aus und beendet mit Status 0 (seit Go 1.15). Der Hilfetext wird aus deinen Definitionen erzeugt:

Usage of greet:
  -count int
    	how many times (default 1)
  -delay duration
    	pause between greetings, e.g. 10ms
  -loud
    	shout the greeting
  -name string
    	who to greet (default "world")

Setz flag.Usage auf eine Funktion, um deinen eigenen Kopf auszugeben, bevor du flag.PrintDefaults() aufrufst.

Unterbefehle mit FlagSet

Tools wie git commit -m msg haben Unterbefehle mit eigenen Flags. Leg pro Unterbefehl ein flag.FlagSet an und wähl eins mit einem switch auf das erste Argument:

package main

import (
	"flag"
	"fmt"
	"os"
)

func run(args []string) error {
	if len(args) < 1 {
		return fmt.Errorf("usage: todo <add|list> [flags]")
	}

	switch args[0] {
	case "add":
		fs := flag.NewFlagSet("add", flag.ContinueOnError)
		priority := fs.Int("p", 3, "priority 1 to 5")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		if fs.NArg() == 0 {
			return fmt.Errorf("add: missing task text")
		}
		fmt.Printf("added %q with priority %d\n", fs.Arg(0), *priority)
	case "list":
		fs := flag.NewFlagSet("list", flag.ContinueOnError)
		all := fs.Bool("all", false, "include finished tasks")
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		fmt.Println("listing tasks, all =", *all)
	default:
		return fmt.Errorf("unknown command %q", args[0])
	}
	return nil
}

func main() {
	args := os.Args[1:]
	if len(args) == 0 {
		args = []string{"add", "-p", "1", "buy milk"} // demo input when the Args panel is empty
	}
	if err := run(args); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

flag.ContinueOnError lässt Parse einen Fehler zurückgeben, statt das Programm zu beenden, und hält die Funktion so testbar. run nimmt die Argumente als Parameter, statt os.Args zu lesen, also kann ein Test direkt run([]string{"list", "-all"}) aufrufen. Probier list und -all im Args-Panel aus, oder delete, um den Fehlerpfad zu sehen.

Für große CLIs mit verschachtelten Befehlen, Shell-Vervollständigung und generierter Doku nutzen die meisten Projekte das Drittanbieterpaket github.com/spf13/cobra. Kleine Tools deckt das Standardpaket flag gut ab.

Umgebungsvariablen

package main

import (
	"fmt"
	"os"
	"strconv"
)

func envInt(key string, fallback int) (int, error) {
	v, ok := os.LookupEnv(key)
	if !ok {
		return fallback, nil
	}
	n, err := strconv.Atoi(v)
	if err != nil {
		return 0, fmt.Errorf("%s must be a number, got %q", key, v)
	}
	return n, nil
}

func main() {
	os.Setenv("APP_WORKERS", "8") // for the demo; normally set by the shell
	os.Setenv("APP_MODE", "")     // set, but empty
	os.Unsetenv("APP_MISSING")    // make sure it is unset

	fmt.Printf("Getenv APP_MODE:    %q\n", os.Getenv("APP_MODE"))
	fmt.Printf("Getenv APP_MISSING: %q\n", os.Getenv("APP_MISSING"))

	_, modeSet := os.LookupEnv("APP_MODE")
	_, missingSet := os.LookupEnv("APP_MISSING")
	fmt.Println("APP_MODE set:", modeSet, "| APP_MISSING set:", missingSet)

	workers, err := envInt("APP_WORKERS", 4)
	fmt.Println("workers:", workers, err)

	timeout, err := envInt("APP_TIMEOUT", 30)
	fmt.Println("timeout:", timeout, err)

	fmt.Println(os.ExpandEnv("running with $APP_WORKERS workers"))
}

• os.Getenv gibt "" zurück, sowohl wenn die Variable fehlt als auch wenn sie auf einen leeren String gesetzt ist. os.LookupEnv unterscheidet die beiden Fälle.
• Werte sind immer Strings. Konvertiere und validiere sie beim Start und brich mit einer klaren Meldung ab, statt mitten in einem Request zu scheitern.
• os.Setenv wirkt auf den aktuellen Prozess und auf später gestartete Kindprozesse. Die Umgebung der Shell, die dich gestartet hat, kann es nicht ändern.
• os.Environ() gibt alle Variablen als Strings der Form "KEY=value" zurück.

Eine verbreitete Aufteilung für Konfiguration: Flags für alles, was ein Mensch eintippt, Umgebungsvariablen für Deployment-Einstellungen (Container-Plattformen setzen sie), wobei Flags die Umgebung überschreiben und die Umgebung die Standardwerte.

Exit-Codes und os.Exit

Ein Go-Programm beendet sich mit Status 0, wenn main zurückkehrt. os.Exit(code) beendet den Prozess sofort mit diesem Status. Per Konvention bedeutet 0 Erfolg, 1 einen allgemeinen Fehler und 2 einen Bedienungsfehler (das Paket flag verwendet 2).

os.Exit führt keine defer-Funktionen aus. Dateien werden nicht geschrieben, und das Aufräumen per defer entfällt. log.Fatal ruft os.Exit(1) auf und hat dieselbe Wirkung. Halte os.Exit an einer Stelle, am Ende von main, und steck das eigentliche Programm in eine Funktion run, die einen Fehler zurückgibt, so wie im Beispiel mit den Unterbefehlen:

func main() {
	if err := run(os.Args[1:]); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

Schreib Fehlermeldungen nach os.Stderr, nicht nach os.Stdout, damit sie sichtbar bleiben, wenn die Ausgabe in eine Datei umgeleitet oder an einen anderen Befehl weitergereicht wird. Eine nicht abgefangene Panic beendet das Programm mit Status 2.

Häufige Fehler

• os.Args indizieren, ohne die Länge zu prüfen. Fehlende Argumente lösen eine Panic aus.
• Flags vor flag.Parse() lesen. Du bekommst die Standardwerte.
• Das * vergessen. fmt.Println(port) gibt eine Adresse wie 0xc000012345 aus, nicht den Wert.
• Flags hinter Positionsargumente setzen. prog input.txt -v parst -v nicht.
• -verbose false bei einem bool-Flag. Schreib -verbose=false.
• os.Exit oder log.Fatal tief im Programm aufrufen. Das Aufräumen per defer läuft nie, und der Code lässt sich nicht testen. Gib Fehler bis zu main zurück.