ארגומנטים משורת הפקודה ב-Golang: os.Args, flag ומשתני סביבה

os.Args

os.Args הוא slice של מחרוזות. os.Args[0] הוא שם התוכנית, והשאר הם הארגומנטים בדיוק כפי שה-shell העביר אותם.

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")
	}
}

בחלונית Args של העורך, כל שדה הוא ארגומנט אחד שמועבר כמו שהוא. נסו hello, two words ו--v בשלושה שדות: התוכנית רואה שלושה ארגומנטים, ו-two words נשאר ארגומנט אחד עם רווח בתוכו. בטרמינל ה-shell הוא שמפצל, כך שאותו דבר נכתב go run . hello "two words" -v.

בדקו תמיד את len(os.Args) לפני גישה לאינדקס. os.Args[1] בלי ארגומנטים גורם ל-panic עם index out of range [1] with length 1.

ארגומנטים הם מחרוזות. המירו מספרים עם strconv.Atoi או strconv.ParseFloat וטפלו בשגיאה, כי משתמשים מקלידים כל דבר.

חבילת flag

לאפשרויות כמו -port 8080 -verbose השתמשו ב-flag. היא מנתחת, ממירה טיפוסים, מדווחת על שגיאות ומייצרת הודעת עזרה.

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())
}

בלי ארגומנטים התוכנית מדפיסה hello, world פעם אחת. בחלונית Args, נסו -name ו-Gopher בשני שדות, ואחר כך -count=3, -loud ו-extra בשלושה שדות נוספים. התוכנית מדפיסה HELLO, GOPHER! שלוש פעמים ואת remaining args: [extra].

איך flags עובדים:

• כל פונקציית הגדרה (flag.String, flag.Int, flag.Bool, flag.Float64, flag.Duration, flag.Uint64...) מקבלת שם, ערך ברירת מחדל ומחרוזת שימוש, ומחזירה מצביע. קראו את הערך עם *name אחרי flag.Parse().
• צורות ה-Var נקשרות למשתנה שכבר יש לכם: flag.IntVar(&cfg.Port, "port", 8080, "port"). זה מסודר יותר עבור struct של קונפיגורציה.
• משתמשים יכולים לכתוב -name value, -name=value, --name value או --name=value. Go לא מבחינה בין מקף אחד לשניים.
• ערכים בוליאניים צריכים = כדי לקבל ערך. -loud מציב true, -loud=false מציב false, אבל -loud false מציב true ומשאיר את false כארגומנט פוזיציוני.
• הניתוח נעצר בארגומנט הראשון שאינו flag (או ב---). prog file.txt -v מתייחס ל--v כארגומנט פוזיציוני. שימו את ה-flags קודם.
• flag.Args() מחזירה את הארגומנטים הפוזיציוניים שנשארו, flag.NArg() את מספרם, ו-flag.Arg(i) אחד מהם.

flag לא מוכר או ערך שגוי מדפיסים שגיאה ואת הוראות השימוש, ויוצאים עם סטטוס 2. -h או -help מדפיסים את הוראות השימוש ויוצאים עם סטטוס 0 (החל מ-Go 1.15). טקסט השימוש נוצר מההגדרות שלכם:

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")

הציבו פונקציה ב-flag.Usage כדי להדפיס כותרת משלכם לפני הקריאה ל-flag.PrintDefaults().

תת-פקודות עם FlagSet

לכלים כמו git commit -m msg יש תת-פקודות עם flags משלהן. צרו flag.FlagSet לכל תת-פקודה ובחרו ביניהן עם switch על הארגומנט הראשון:

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 גורם ל-Parse להחזיר שגיאה במקום לצאת, וכך הפונקציה נשארת ניתנת לבדיקה. run מקבלת את הארגומנטים כפרמטר במקום לקרוא את os.Args, כך שבדיקה יכולה לקרוא ישירות ל-run([]string{"list", "-all"}). נסו list ו--all בחלונית Args, או delete כדי לראות את מסלול השגיאה.

עבור CLIs גדולים עם פקודות מקוננות, השלמה אוטומטית ב-shell ותיעוד שנוצר אוטומטית, רוב הפרויקטים משתמשים בחבילה החיצונית github.com/spf13/cobra. חבילת flag הסטנדרטית מכסה היטב כלים קטנים.

משתני סביבה

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 מחזירה "" גם כשהמשתנה חסר וגם כשהוא מוגדר כמחרוזת ריקה. os.LookupEnv מבחינה ביניהם.
• הערכים הם תמיד מחרוזות. המירו ובדקו אותם בזמן העלייה, ונכשלו עם הודעה ברורה ולא באמצע טיפול בבקשה.
• os.Setenv משפיעה על התהליך הנוכחי ועל תהליכי בן שמופעלים אחר כך. היא לא יכולה לשנות את הסביבה של ה-shell שהפעיל אתכם.
• os.Environ() מחזירה את כל המשתנים כמחרוזות "KEY=value".

מבנה נפוץ לקונפיגורציה: flags לדברים שאדם מקליד, משתני סביבה להגדרות פריסה (פלטפורמות קונטיינרים מגדירות אותם), כש-flags גוברים על הסביבה והסביבה גוברת על ברירות המחדל.

קודי יציאה ו-os.Exit

תוכנית Go יוצאת עם סטטוס 0 כש-main חוזרת. os.Exit(code) מסיימת את התהליך מיד עם הסטטוס הזה. לפי המוסכמה, 0 הוא הצלחה, 1 הוא שגיאה כללית, ו-2 הוא שגיאת שימוש (חבילת flag משתמשת ב-2).

os.Exit לא מריצה פונקציות defer. קבצים לא נכתבים עד הסוף וניקוי של defer מדולג. log.Fatal קוראת ל-os.Exit(1) ויש לה אותה השפעה. השאירו את os.Exit במקום אחד, בסוף main, ושימו את התוכנית האמיתית בפונקציה run שמחזירה שגיאה, כמו בדוגמת תת-הפקודות:

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

כתבו הודעות שגיאה ל-os.Stderr, לא ל-os.Stdout, כדי שיישארו גלויות כשהפלט מופנה לקובץ או מועבר ב-pipe לפקודה אחרת. panic שלא טופל ב-recover יוצא עם סטטוס 2.

טעויות נפוצות

• גישה לאינדקס של os.Args בלי לבדוק את האורך. ארגומנטים חסרים גורמים ל-panic.
• קריאת flags לפני flag.Parse(). מקבלים את ברירות המחדל.
• שוכחים את ה-*. fmt.Println(port) מדפיס כתובת כמו 0xc000012345, לא את הערך.
• שמים flags אחרי ארגומנטים פוזיציוניים. prog input.txt -v לא מנתח את -v.
• -verbose false עבור flag בוליאני. כתבו -verbose=false.
• קוראים ל-os.Exit או ל-log.Fatal עמוק בתוך התוכנית. ניקוי ה-defer לא רץ אף פעם ואי אפשר לבדוק את הקוד. החזירו שגיאות למעלה עד main.