実行できるGoドキュメント: コマンドライン引数

Q: Goでコマンドライン引数を取得するには？

os.Args は、インデックス0にプログラム名、その後に引数を持つ []string です。os.Args[1:] がユーザーの入力した引数です。インデックスを使う前に len(os.Args) をチェックしないと、引数がないときにプログラムがpanicします。

Q: Goでflagパッケージを使うには？

フラグを宣言し、flag.Parse() を呼んでから読みます：port := flag.Int("port", 8080, "port to listen on")、flag.Parse()、fmt.Println(*port)。関数はポインタを返します。ユーザーは -port=9000、-port 9000、--port 9000 のように書き、-h で自動生成された使い方が表示されます。

Q: Goで環境変数を読むには？

os.Getenv("HOME") は値を返し、変数が設定されていなければ空文字列を返します。未設定と空の値に設定されている場合を区別するには v, ok := os.LookupEnv("HOME") を使います。os.Setenv は現在のプロセスと、その後に開始する子プロセスの環境を変更します。

Q: Goのos.Exitはdeferした関数を実行しますか？

実行しません。os.Exit は指定したステータスコードでただちにプロセスを終了し、deferした呼び出しは実行されないので、バッファされた出力が失われたり、ファイルがフラッシュされなかったりすることがあります。よくあるパターンは func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) } } で、実際の処理とdeferはすべて run の中に置きます。

os.Args

os.Args は文字列のスライスです。os.Args[0] はプログラムの名前で、残りはシェルが渡したとおりの引数です。

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パネルでは、各フィールドが1つの引数になり、そのまま渡されます。3つのフィールドに hello、two words、-v を入れてみてください。プログラムは3つの引数を受け取り、two words は空白を含んだまま1つの引数です。ターミナルではシェルが分割するので、同じことは go run . hello "two words" -v になります。

インデックスを使う前に必ず len(os.Args) をチェックします。引数がないときの os.Args[1] は index out of range [1] with length 1 でpanicします。

引数は文字列です。ユーザーは何でも入力するので、数値は 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 を1回表示します。Argsパネルで、2つのフィールドに -name と Gopher を、さらに3つのフィールドに -count=3、-loud、extra を入れてみてください。プログラムは HELLO, GOPHER! を3回表示し、remaining args: [extra] と表示します。

フラグの仕組みは次のとおりです。

各定義関数（flag.String、flag.Int、flag.Bool、flag.Float64、flag.Duration、flag.Uint64 など）は、名前、デフォルト値、使い方の文字列を受け取り、ポインタ を返します。値は flag.Parse() の後に *name で読みます。
Var 版は既存の変数に結びつけます：flag.IntVar(&cfg.Port, "port", 8080, "port")。設定用の構造体にはこちらのほうがすっきりします。
ユーザーは -name value、-name=value、--name value、--name=value のどれでも書けます。Goはダッシュ1つと2つを区別しません。
真偽値に値を渡すには = が必要。 -loud はtrueに、-loud=false はfalseにしますが、-loud false はtrueにして false を位置引数として残します。
パースは最初のフラグでない引数（または --）で止まる。 prog file.txt -v は -v を位置引数として扱います。フラグは先に置きます。
flag.Args() は残った位置引数を返し、flag.NArg() はその数を、flag.Arg(i) はそのうちの1つを返します。

未知のフラグや不正な値はエラーと使い方を表示し、ステータス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.PrintDefaults() を呼ぶ前に独自のヘッダーを表示するには、flag.Usage に関数を設定します。

FlagSetによるサブコマンド

git commit -m msg のようなツールには、独自のフラグを持つサブコマンドがあります。サブコマンドごとに flag.FlagSet を作り、最初の引数に対するswitchで1つを選びます。

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"}) を呼べます。Argsパネルで list と -all を試すか、エラーの経路を見るには delete を試してください。

ネストしたコマンド、シェルの補完、ドキュメントの生成を持つ大きなCLIでは、多くのプロジェクトがサードパーティの 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のプログラムは、main が戻るとステータス0で終了します。os.Exit(code) はそのステータスでただちにプロセスを終了します。慣習として、0は成功、1は一般的なエラー、2は使い方のエラーです（flag パッケージは2を使います）。

os.Exit はdeferした関数を実行しません。 ファイルはフラッシュされず、defer の後始末も飛ばされます。log.Fatal は os.Exit(1) を呼ぶので同じ効果があります。os.Exit は main の最後の1か所にとどめ、サブコマンドの例のように、実際のプログラムはエラーを返す run 関数に置きます。

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

エラーメッセージは os.Stdout ではなく os.Stderr に書きます。そうすれば、出力をファイルにリダイレクトしたり別のコマンドにパイプしたりしても見えたままです。回復されなかったpanicはステータス2で終了します。

よくある間違い

長さをチェックせずに os.Args にインデックスでアクセスする。 引数がないとpanicします。
flag.Parse() の前にフラグを読む。 デフォルト値しか得られません。
* を忘れる。 fmt.Println(port) は値ではなく 0xc000012345 のようなアドレスを表示します。
位置引数の後にフラグを置く。 prog input.txt -v は -v をパースしません。
真偽値のフラグに -verbose false と書く。 -verbose=false と書きます。
プログラムの深いところで os.Exit や log.Fatal を呼ぶ。 deferした後始末が実行されず、コードをテストできません。エラーを main まで返します。

よくある質問

Goでコマンドライン引数を取得するには？

os.Args は、インデックス0にプログラム名、その後に引数を持つ []string です。os.Args[1:] がユーザーの入力した引数です。インデックスを使う前に len(os.Args) をチェックしないと、引数がないときにプログラムがpanicします。

Goでflagパッケージを使うには？

フラグを宣言し、flag.Parse() を呼んでから読みます：port := flag.Int("port", 8080, "port to listen on")、flag.Parse()、fmt.Println(*port)。関数はポインタを返します。ユーザーは -port=9000、-port 9000、--port 9000 のように書き、-h で自動生成された使い方が表示されます。

Goで環境変数を読むには？

os.Getenv("HOME") は値を返し、変数が設定されていなければ空文字列を返します。未設定と空の値に設定されている場合を区別するには v, ok := os.LookupEnv("HOME") を使います。os.Setenv は現在のプロセスと、その後に開始する子プロセスの環境を変更します。

Goのos.Exitはdeferした関数を実行しますか？

実行しません。os.Exit は指定したステータスコードでただちにプロセスを終了し、deferした呼び出しは実行されないので、バッファされた出力が失われたり、ファイルがフラッシュされなかったりすることがあります。よくあるパターンは func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) } } で、実際の処理とdeferはすべて run の中に置きます。