Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 1688] ファイルの概要

このコミットは、Go言語の標準ライブラリである flag パッケージの内部構造と外部インターフェースに重要な変更を加えています。具体的には、コマンドライン引数をパースするための flag.go ファイルが大幅に修正され、そのテストコードである flag_test.go が新規に追加されています。

コミット

commit bbc190b3ee927f5dc6c518dbda547596e79a4bbb
Author: Rob Pike <r@golang.org>
Date:   Mon Feb 16 19:43:15 2009 -0800

    make interface to the flags themselves more public.
    add visitor functions to scan the flags.
    add a way to set a flag.
    add a flag test.
    
    R=rsc
    DELTA=169  (99 added, 19 deleted, 51 changed)
    OCL=25076
    CL=25078

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/bbc190b3ee927f5dc6c6c518dbda547596e79a4bbb

元コミット内容

このコミットは、Go言語の flag パッケージにおいて、フラグ自体へのインターフェースをより公開し、フラグを走査するためのビジター関数を追加し、プログラムからフラグを設定する方法を提供することを目的としています。また、これらの新機能の動作を検証するためのテストも追加されています。

変更の背景

このコミットの背景には、flag パッケージの柔軟性とプログラムからの制御能力の向上という明確な意図があります。

  1. フラグインターフェースの公開: 以前の flag パッケージでは、個々のフラグの内部表現や操作方法が十分に公開されていませんでした。これにより、開発者がプログラム内でフラグの状態を詳細に検査したり、動的に操作したりすることが困難でした。この変更は、Flag 構造体のフィールドをエクスポート（大文字で始まるように変更）することで、これらの情報へのアクセスを容易にし、より高度なフラグ操作を可能にしています。

  2. ビジター関数の追加: コマンドライン引数として定義されたすべてのフラグ、または実際に設定されたフラグをプログラム的に走査する機能は、デバッグ、ドキュメンテーション生成、あるいはカスタムのフラグ処理ロジックを実装する上で非常に有用です。Visit および VisitAll 関数は、このようなニーズに応えるために導入されました。これにより、開発者はフラグの定義や現在の値を簡単に列挙できるようになります。

  3. プログラムからのフラグ設定機能: コマンドライン引数としてではなく、プログラムの実行中に動的にフラグの値を設定したいというユースケースが存在します。例えば、設定ファイルから値を読み込んだり、他のロジックに基づいてデフォルト値を上書きしたりする場合です。Set 関数は、この機能を提供し、flag パッケージの柔軟性を大幅に向上させます。

  4. テストの追加: 新しい機能が追加される際には、その機能が正しく動作することを保証するためのテストが不可欠です。flag_test.go の追加は、これらの新機能の堅牢性を確保し、将来の変更による回帰を防ぐための重要なステップです。

これらの変更は、flag パッケージをより強力で、開発者にとって使いやすいものにすることを目的としています。

前提知識の解説

このコミットの変更内容を理解するためには、以下のGo言語の基本的な概念と flag パッケージの役割について理解しておく必要があります。

Go言語の flag パッケージ

Go言語の flag パッケージは、コマンドライン引数を解析するための標準ライブラリです。これにより、開発者はアプリケーションが起動される際に、ユーザーが指定するオプションや設定値を簡単に受け取ることができます。

基本的な使用方法は以下の通りです。

  1. フラグの定義: flag.String(), flag.Int(), flag.Bool() などの関数を使用して、フラグの名前、デフォルト値、および使用方法の説明（usage message）を定義します。これらの関数は、フラグの値を保持する変数のポインタを返します。
  2. フラグのパース: flag.Parse() 関数を呼び出すことで、コマンドライン引数が解析され、定義されたフラグ変数に値が設定されます。この関数は通常、main 関数の冒頭で呼び出されます。
  3. フラグ値へのアクセス: flag.Parse() の呼び出し後、定義時に取得したポインタを介してフラグの値にアクセスできます。

例:

package main

import (
	"flag"
	"fmt"
)

func main() {
	name := flag.String("name", "World", "名前を指定します")
	age := flag.Int("age", 30, "年齢を指定します")
	verbose := flag.Bool("verbose", false, "詳細出力を有効にします")

	flag.Parse()

	fmt.Printf("Hello, %s!\n", *name)
	fmt.Printf("You are %d years old.\n", *age)
	if *verbose {
		fmt.Println("Verbose mode is enabled.")
	}
}

このプログラムを go run main.go -name "Go Developer" -age 5 -verbose のように実行すると、指定された値がフラグ変数に設定されます。

Go言語のインターフェース

Go言語のインターフェースは、メソッドのシグネチャの集合を定義する型です。インターフェースは、特定の動作を「契約」として定義し、その契約を満たす任意の型がそのインターフェースを実装していると見なされます。Goでは、型がインターフェースのすべてのメソッドを実装していれば、その型は暗黙的にそのインターフェースを実装していることになります。明示的な implements キーワードは不要です。

このコミットでは、FlagValue という新しいインターフェースが導入されており、これはフラグの値を扱うための統一された方法を提供します。

Go言語の構造体とエクスポート

Go言語では、構造体（struct）は関連するデータをまとめるための複合データ型です。構造体のフィールドや関数の名前が大文字で始まる場合、それはパッケージの外部からアクセス可能（エクスポートされる）になります。小文字で始まる場合は、そのパッケージ内でのみアクセス可能です。このコミットでは、Flag 構造体のフィールドが小文字から大文字に変更され、外部からのアクセスが可能になっています。

技術的詳細

このコミットにおける技術的な変更は、主に flag パッケージの内部構造の再設計と、新しい公開APIの導入に焦点を当てています。

FlagValue インターフェースの導入

最も重要な変更点の一つは、_Value インターフェースが FlagValue インターフェースにリネームされ、そのメソッドシグネチャが変更されたことです。

変更前:

type _Value interface {
	str() string;
}

変更後:

type FlagValue interface {
	String() string;
	set(string) bool;
}
  • str() メソッドが String() にリネームされました。これは、Go言語の慣習である fmt.Stringer インターフェース（String() string メソッドを持つ）に準拠するためです。これにより、フラグの値を文字列として表現する際に、標準的なGoのメカニズムを利用できるようになります。
  • set(string) bool メソッドが追加されました。このメソッドは、文字列形式の値をフラグに設定する責任を持ちます。設定が成功した場合は true を、失敗した場合は false を返します。これにより、flag パッケージは、異なる型のフラグ（bool, int, stringなど）に対して、文字列からの値のパースと設定を統一的に処理できるようになります。

この FlagValue インターフェースの導入により、boolValue, intValue, int64Value, uintValue, uint64Value, stringValue といった具体的な値型がこのインターフェースを実装するように変更されました。特に、set メソッドは、以前は各値型が直接その型の値を引数として受け取っていましたが、変更後はすべて string を引数として受け取り、内部で型変換を行うようになりました。これにより、flag.Set 関数が任意の型のフラグに対して統一的に文字列を渡せるようになります。

Flag 構造体のフィールドのエクスポート

Flag 構造体のフィールドが、パッケージ外部からアクセスできるようにエクスポートされました。

変更前:

type Flag struct {
	name	string;	// name as it appears on command line
	usage	string;	// help message
	value	_Value;	// value as set
	defvalue	string;	// default value (as text); for usage message
}

変更後:

type Flag struct {
	Name	string;	// name as it appears on command line
	Usage	string;	// help message
	Value	FlagValue;	// value as set
	DefValue	string;	// default value (as text); for usage message
}
  • name -> Name
  • usage -> Usage
  • value -> Value
  • defvalue -> DefValue

これらのフィールドがエクスポートされたことで、開発者は flag.Lookup() 関数などを使って Flag オブジェクトを取得した後、その名前、使用方法、現在の値、デフォルト値といった情報に直接アクセスできるようになりました。これは、カスタムのヘルプメッセージ生成や、フラグの状態をプログラム的に検査する際に非常に有用です。

ビジター関数の追加: VisitAll と Visit

フラグを走査するための新しい公開関数が追加されました。

  • VisitAll(fn func(*Flag)): この関数は、定義されているすべてのフラグ（コマンドラインで設定されたかどうかにかかわらず）を走査し、それぞれの Flag オブジェクトを引数として fn 関数を呼び出します。これにより、アプリケーションがサポートするすべてのフラグとその詳細を列挙できます。
  • Visit(fn func(*Flag)): この関数は、実際にコマンドラインで設定された（またはプログラム的に Set された）フラグのみを走査し、それぞれの Flag オブジェクトを引数として fn 関数を呼び出します。これは、ユーザーが明示的に指定した設定を検査する際に役立ちます。

これらの関数は、flag パッケージの内部マップ (flags.formal と flags.actual) をイテレートすることで実装されています。

フラグ設定機能の追加: Set

プログラムからフラグの値を設定するための新しい公開関数が追加されました。

  • Set(name, value string) bool: この関数は、指定された name のフラグを、文字列 value を使って設定します。内部的には、対応する Flag オブジェクトの FlagValue インターフェースの set メソッドを呼び出します。設定が成功した場合は true を、フラグが見つからないか、値のパースに失敗した場合は false を返します。

この機能により、例えば設定ファイルから読み込んだ値をフラグに適用したり、テストコードで特定のフラグ状態をシミュレートしたりすることが容易になります。

PrintDefaults の変更

PrintDefaults 関数は、VisitAll 関数を利用するように変更されました。これにより、フラグのデフォルト値の出力ロジックがより簡潔になり、VisitAll の導入によって提供される新しい抽象化を活用しています。

parseOne メソッドの簡素化

allFlags 構造体の parseOne メソッド（コマンドライン引数を個別にパースする内部関数）は、FlagValue インターフェースの set メソッドを活用するように大幅に簡素化されました。以前は、各フラグの型（bool, string, intなど）に応じて個別の型アサーションと値のパースロジックが必要でしたが、flag.Value.set(value) の呼び出しに統一されました。これにより、コードの重複が減り、保守性が向上しています。

コアとなるコードの変更箇所

src/lib/flag.go

  • _Value インターフェースから FlagValue インターフェースへの変更と set メソッドの追加:

    --- a/src/lib/flag.go
+++ b/src/lib/flag.go
@@ -205,25 +215,27 @@ func newStringValue(val string, p *string) *stringValue {
 	return &stringValue(p)
 }
 
-func (s *stringValue) set(val string) {
+func (s *stringValue) set(val string) bool {
 	*s.p = val;
+	return true;
 }
 
-func (s *stringValue) str() string {
+func (s *stringValue) String() string {
 	return fmt.Sprintf("%#q", *s.p)
 }
 
-// -- Value interface
-type _Value interface {
-	str() string;
+// -- FlagValue interface
+type FlagValue interface {
+	String() string;
+	set(string) bool;
 }

    同様に、boolValue, intValue, int64Value, uintValue, uint64Value の set メソッドも string を引数にとり bool を返すように変更され、str() メソッドは String() にリネームされました。

  • Flag 構造体のフィールドのエクスポート:

    --- a/src/lib/flag.go
+++ b/src/lib/flag.go
@@ -234,10 +246,45 @@ type allFlags struct {
 
 var flags *allFlags = &allFlags(make(map[string] *Flag), make(map[string] *Flag), 1)
 
-func PrintDefaults() {
+// Visit all flags, including those defined but not set.
+func VisitAll(fn func(*Flag)) {
 	for k, f := range flags.formal {
-\t\tprint("  -", f.name, "=", f.defvalue, ": ", f.usage, "\n");
+\t\tfn(f)
+\t}\n+}
+\n+// Visit only those flags that have been set
+func Visit(fn func(*Flag)) {
+\tfor k, f := range flags.actual {
+\t\tfn(f)
+\t}\n+}
+\n+func Lookup(name string) *Flag {
+\tf, ok := flags.formal[name];
+\tif !ok {
+\t\treturn nil
+\t}\n+\treturn f
+}\n+\n+func Set(name, value string) bool {
+\tf, ok := flags.formal[name];
+\tif !ok {
+\t\treturn false
+\t}\n+\tok = f.Value.set(value);\n+\tif !ok {
+\t\treturn false
+\t}\n+\tflags.actual[name] = f;\n+\treturn true;\n+}
+\n+func PrintDefaults() {
+\tVisitAll(func(f *Flag) {
+\t\tprint("  -", f.Name, "=", f.DefValue, ": ", f.Usage, "\n");
+\t})\n     }

  • VisitAll, Visit, Lookup, Set 関数の追加: 上記の差分に示されています。

  • add 関数の変更: Flag 構造体の初期化方法が変更され、FlagValue インターフェースを使用するように修正されました。

    --- a/src/lib/flag.go
+++ b/src/lib/flag.go
@@ -266,12 +313,9 @@ func NArg() int {
 	return len(sys.Args) - flags.first_arg
 }
 
-func add(name string, value _Value, usage string) {
-\tf := new(Flag);\n-\tf.name = name;\n-\tf.usage = usage;\n-\tf.value = value;\n-\tf.defvalue = value.str();	// Remember the default value as a string; it won't change.
+func add(name string, value FlagValue, usage string) {
+\t// Remember the default value as a string; it won't change.
+\tf := &Flag(name, usage, value, value.String());
  \tdummy, alreadythere := flags.formal[name];
  \tif alreadythere {
  \t\tprint("flag redefined: ", name, "\n");

  • parseOne メソッドの簡素化: FlagValue.set メソッドを利用するように変更されました。

    --- a/src/lib/flag.go
+++ b/src/lib/flag.go
@@ -388,16 +432,14 @@ func (f *allFlags) parseOne(index int) (ok bool, next int)\n     	\tprint("flag provided but not defined: -", name, "\n");
 	\t\tUsage();
 	}\n    -\tif f, ok := flag.value.(*boolValue); ok {
+\tif f, ok := flag.Value.(*boolValue); ok {	// special case: doesn't need an arg
 	\tif has_value {
-\t\t\tk, ok := atob(value);\n    -\t\t\tif !ok {\n    +\t\t\tif !f.set(value) {\n     	\t\t\tprint("invalid boolean value ", value, " for flag: -", name, "\n");
 	\t\t\t\tUsage();
 	\t\t\t}\n    -\t\t\tf.set(k)
 	\t} else {
-\t\t\tf.set(true)
+\t\t\tf.set("true")
 	\t}\n     	} else {
 	\t// It must have a value, which might be the next argument.
@@ -411,24 +453,10 @@ func (f *allFlags) parseOne(index int) (ok bool, next int)\
 	\t\t\tprint("flag needs an argument: -", name, "\n");
 	\t\t\tUsage();
 	\t}\n    -\t\tif f, ok := flag.value.(*stringValue); ok {
-\t\t\tf.set(value)
-\t\t} else {
-\t\t\t// It's an integer flag.  TODO(r): check for overflow?
-\t\t\tk, ok := atoi(value);\n    -\t\t\tif !ok {\n    -\t\t\t\tprint("invalid integer value ", value, " for flag: -", name, "\n");
+\t\tok = flag.Value.set(value);\n    +\t\tif !ok {\n    +\t\t\tprint("invalid value ", value, " for flag: -", name, "\n");
 	\t\t\t\tUsage();
-\t\t\t}\n    -\t\t\tif f, ok := flag.value.(*intValue); ok {
-\t\t\t\tf.set(int(k));
-\t\t\t} else if f, ok := flag.value.(*int64Value); ok {
-\t\t\t\tf.set(k);\n    -\t\t\t} else if f, ok := flag.value.(*uintValue); ok {
-\t\t\t\tf.set(uint(k));
-\t\t\t} else if f, ok := flag.value.(*uint64Value); ok {
-\t\t\t\tf.set(uint64(k));
-\t\t\t}\n     	\t}\n     	}\n     	flags.actual[name] = flag;

src/lib/flag_test.go

  • 新規ファイルの追加: flag パッケージの新しいテストファイルが追加されました。 
    // Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package flag

import (
	"flag";
	"fmt";
	"testing";
)

var (
	test_bool = flag.Bool("test_bool", true, "bool value");
	test_int = flag.Int("test_int", 1, "int value");
	test_int64 = flag.Int64("test_int64", 1, "int64 value");
	test_uint = flag.Uint("test_uint", 1, "uint value");
	test_uint64 = flag.Uint64("test_uint64", 1, "uint64 value");
	test_string = flag.String("test_string", "1", "string value");
)

// Because this calls flag.Parse, it needs to be the only Test* function
func TestEverything(t *testing.T) {
	flag.Parse();
	m := make(map[string] *flag.Flag);
	visitor := func(f *flag.Flag) {
		if len(f.Name) > 5 && f.Name[0:5] == "test_" {
			m[f.Name] = f
		}
	};
	flag.VisitAll(visitor);
	if len(m) != 6 {
		t.Error("flag.VisitAll misses some flags");
		for k, v := range m {
			t.Log(k, *v)
		}
	}
	m = make(map[string] *flag.Flag);
	flag.Visit(visitor);
	if len(m) != 0 {
		t.Errorf("flag.Visit sees unset flags");
		for k, v := range m {
			t.Log(k, *v)
		}
	}
	// Now set some flags
	flag.Set("test_bool", "false");
	flag.Set("test_uint", "1234");
	flag.Visit(visitor);
	if len(m) != 2 {
		t.Error("flag.Visit fails after set");
		for k, v := range m {
			t.Log(k, *v)
		}
	}
}

コアとなるコードの解説

FlagValue インターフェースと set(string) bool メソッド

この変更は、flag パッケージの設計において非常に重要です。以前は、各フラグの型（bool, int, string など）に応じて、値を設定するための異なるメソッド（例: boolValue.set(bool), intValue.set(int)）が存在していました。しかし、flag.Set のような統一された設定関数を導入するためには、すべてのフラグ型が共通のインターフェースを介して文字列を受け取り、それを自身の型にパースして設定できる必要があります。

FlagValue インターフェースに set(string) bool メソッドが追加されたことで、この要件が満たされました。各具体的な値型（boolValue, intValue など）は、この set メソッドを実装し、渡された文字列を適切な型に変換して自身のポインタに格納します。変換に失敗した場合は false を返します。これにより、flag.Set 関数は、フラグの具体的な型を知ることなく、文字列として値を渡すだけでフラグを設定できるようになりました。これは、ポリモーフィズムの典型的な例であり、コードの柔軟性と拡張性を高めます。

str() から String() へのリネームは、Goの標準ライブラリにおける慣習 (fmt.Stringer インターフェース) に従うもので、これによりフラグの値を文字列として表現する際に、より自然な方法が提供されます。

Flag 構造体のフィールドのエクスポート

Flag 構造体のフィールド（Name, Usage, Value, DefValue）がエクスポートされたことで、flag パッケージの利用者は、定義された個々のフラグに関するメタデータや現在の値にプログラム的にアクセスできるようになりました。

  • Name: コマンドラインでフラグを指定する際に使用される名前。
  • Usage: フラグの目的を説明するヘルプメッセージ。
  • Value: フラグの現在の値を保持する FlagValue インターフェース型の値。これにより、FlagValue インターフェースのメソッド（String() や set()）を介して、フラグの値を操作したり、文字列として取得したりできます。
  • DefValue: フラグのデフォルト値の文字列表現。これは、ヘルプメッセージの表示などに利用されます。

この変更により、例えば、アプリケーションが独自のヘルプメッセージを生成したり、定義されているすべてのフラグを動的にリストアップしたりするような、より高度なユースケースが可能になります。

VisitAll と Visit 関数

これらのビジター関数は、flag パッケージに「内省（introspection）」の機能を追加します。

  • VisitAll: アプリケーションが定義しているすべてのフラグを列挙します。これは、デバッグツール、自動ドキュメンテーション生成、またはフラグの定義を検証するテストなどで非常に役立ちます。
  • Visit: 実際にユーザーによって設定された（またはプログラム的に Set された）フラグのみを列挙します。これは、ユーザーがどのような設定を行ったかを把握し、それに基づいて特定のロジックを実行する場合に有用です。

これらの関数は、flag パッケージの内部状態（定義されたフラグのマップ flags.formal と、実際に設定されたフラグのマップ flags.actual）を安全に走査するための公開されたメカニズムを提供します。

Set 関数

Set 関数は、プログラムの実行中にフラグの値を動的に変更する機能を提供します。これは、コマンドライン引数としてではなく、設定ファイルからの読み込み、環境変数からの値の取得、または他のプログラムロジックに基づいてフラグの値を設定する必要がある場合に不可欠です。

Set 関数は、内部的に Lookup 関数を使用して指定された名前のフラグを見つけ、その Flag オブジェクトの Value フィールド（FlagValue インターフェース）の set メソッドを呼び出します。これにより、Set 関数は、フラグの具体的な型に関係なく、統一された方法で値を設定できます。

flag_test.go の追加

新しいテストファイル flag_test.go は、これらの新機能（VisitAll, Visit, Set）が期待通りに動作することを検証します。特に、TestEverything 関数は、さまざまな型のフラグを定義し、VisitAll がすべてのフラグを正しく見つけること、Visit が最初は何も見つけないこと、そして Set 関数でフラグを設定した後に Visit が設定されたフラグのみを正しく見つけることを確認しています。これは、flag パッケージの堅牢性を保証し、将来の変更が既存の機能に悪影響を与えないようにするための重要なステップです。

関連リンク

参考にした情報源リンク