وسائط سطر الأوامر في Golang: os.Args وflag ومتغيّرات البيئة

os.Args

os.Args شريحة من النصوص. 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 وسيطًا واحدًا بداخله مسافة. في الطرفية تتولّى الصدفة التقسيم، فالمكافئ هو 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].

كيف تعمل الخيارات:

• كل دالة تعريف (flag.String وflag.Int وflag.Bool وflag.Float64 وflag.Duration وflag.Uint64...) تأخذ اسمًا وقيمة افتراضية ونص استخدام، وتعيد مؤشرًا. اقرأ القيمة بـ *name بعد flag.Parse().
• صيغ Var تربط الخيار بمتغيّر موجود لديك: flag.IntVar(&cfg.Port, "port", 8080, "port"). وهذا أرتب مع بنية إعدادات.
• يمكن للمستخدمين كتابة -name value أو -name=value أو --name value أو --name=value. لا تفرّق Go بين شرطة واحدة وشرطتين.
• الخيارات المنطقية تحتاج = لتأخذ قيمة. -loud تضبط true، و-loud=false تضبط false، أما -loud false فتضبط true وتترك false وسيطًا موضعيًا.
• يتوقّف التحليل عند أول وسيط ليس خيارًا (أو عند --). في prog file.txt -v يُعامل -v وسيطًا موضعيًا. ضع الخيارات أولًا.
• تعيد flag.Args() الوسائط الموضعية المتبقّية، وflag.NArg() عددها، وflag.Arg(i) واحدًا منها.

الخيار المجهول أو القيمة الخاطئة يطبع خطأ ونص الاستخدام، ويخرج بالحالة 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 لها أوامر فرعية بخيارات خاصة بها. أنشئ 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 لترى مسار الخطأ.

لواجهات سطر الأوامر الكبيرة ذات الأوامر المتداخلة والإكمال التلقائي في الصدفة والتوثيق المولَّد، تستخدم معظم المشاريع المكتبة الخارجية 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 في العملية الحالية والعمليات الفرعية التي تبدأ لاحقًا. ولا تستطيع تغيير بيئة الصدفة التي شغّلت برنامجك.
• تعيد os.Environ() كل المتغيّرات على شكل نصوص "KEY=value".

ترتيب شائع للإعدادات: الخيارات لما يكتبه الإنسان، ومتغيّرات البيئة لإعدادات النشر (منصات الحاويات تضبطها)، والخيارات تتقدّم على البيئة، والبيئة تتقدّم على القيم الافتراضية.

رموز الخروج وos.Exit

يخرج برنامج Go بالحالة 0 عندما تعود main. تنهي os.Exit(code) العملية فورًا بتلك الحالة. اصطلاحًا 0 نجاح، و1 خطأ عام، و2 خطأ في الاستخدام (الحزمة flag تستخدم 2).

لا تنفّذ os.Exit الدوال المؤجّلة. لا تُفرَّغ الملفات ويُتخطّى تنظيف 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، لتبقى ظاهرة عند توجيه المخرجات إلى ملف أو تمريرها إلى أمر آخر. الـ panic غير المستعاد يخرج بالحالة 2.

أخطاء شائعة

• فهرسة os.Args دون التحقّق من طولها. الوسائط الناقصة تسبّب panic.
• قراءة الخيارات قبل flag.Parse(). ستحصل على القيم الافتراضية.
• نسيان *. تطبع fmt.Println(port) عنوانًا مثل 0xc000012345 لا القيمة.
• وضع الخيارات بعد الوسائط الموضعية. في prog input.txt -v لا يُحلَّل -v.
• كتابة -verbose false لخيار منطقي. اكتب -verbose=false.
• استدعاء os.Exit أو log.Fatal في عمق البرنامج. لا يُنفَّذ التنظيف المؤجّل ولا يمكن اختبار الشيفرة. أعد الأخطاء صعودًا إلى main.