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

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

このコミットは、Go言語の標準ライブラリであるstringsパッケージに、Fields関数の使用例を追加するものです。具体的には、src/pkg/strings/example_test.goという新しいファイルを作成し、strings.Fields関数の動作を示すシンプルなコードスニペットを導入しています。これにより、開発者がstrings.Fieldsの挙動をより簡単に理解し、自身のコードで適切に利用できるよう、ドキュメントとテストの両面から貢献しています。

コミット

commit 10f1b6a0744bac6af16c72a48448027e7041ea25
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Fri Feb 3 11:17:55 2012 -0800

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

https://github.com/golang/go/commit/10f1b6a0744bac6af16c72a48448027e7041ea25

元コミット内容

strings: add Fields example

R=golang-dev, rsc, r
CC=golang-dev
https://golang.org/cl/5629043

変更の背景

Go言語の標準ライブラリでは、各関数の使い方を明確にするために、_test.goファイル内にExample関数を記述することが推奨されています。これらのExample関数は、単なるテストケースとして機能するだけでなく、Goの公式ドキュメント（go docコマンドやpkg.go.dev）に自動的に組み込まれ、ユーザーが関数をどのように使用するかを視覚的に理解するための重要な役割を果たします。

このコミットの背景には、strings.Fields関数の利用方法をより分かりやすく示すことで、ライブラリの使いやすさを向上させる目的があります。特に、文字列の分割処理は多くのアプリケーションで頻繁に利用されるため、具体的な例を提供することで、開発者がこの関数をより迅速かつ正確に導入できるようになります。

前提知識の解説

Go言語のstringsパッケージ

stringsパッケージは、Go言語の標準ライブラリの一部であり、UTF-8でエンコードされた文字列を操作するための便利な関数群を提供します。文字列の検索、置換、分割、結合、大文字・小文字変換など、多岐にわたる機能が含まれています。

strings.Fields関数

strings.Fields関数は、文字列を一つ以上の連続するUnicodeホワイトスペース（スペース、タブ、改行など）で分割し、空でない部分文字列のスライスを返します。この関数は、特にユーザー入力のパースや、テキストデータから単語を抽出する際に非常に有用です。

例: strings.Fields(" hello world ") は ["hello", "world"] を返します。

Go言語のexample_test.goファイルとExample関数

Go言語では、テストファイル（_test.goで終わるファイル）内にExampleというプレフィックスを持つ関数を定義することで、その関数の使用例を記述できます。これらのExample関数は、以下の特徴を持ちます。

  1. ドキュメント生成: go docコマンドやpkg.go.devなどのGoの公式ドキュメントツールによって自動的に認識され、関数の説明の一部として表示されます。これにより、ユーザーは関数のAPIドキュメントと同時に具体的な使用例を確認できます。
  2. テスト実行: go testコマンドを実行すると、Example関数も実行されます。fmt.Printlnなどの出力関数が使用されている場合、その出力はコメント行（// Output:）に記述された期待される出力と比較されます。一致しない場合はテストが失敗します。これにより、例が常に正しく動作することが保証されます。
  3. 可読性: シンプルで分かりやすいコードスニペットを提供することで、関数の意図と使い方を直感的に伝えることができます。

Example関数は、通常、package_testという形式のパッケージ名で定義されます。これは、テスト対象のパッケージとは異なるパッケージとしてテストを実行することで、外部からパッケージを利用する際の挙動をシミュレートするためです。

技術的詳細

このコミットは、stringsパッケージのFields関数の使用例をexample_test.goファイルに追加することで、Goのドキュメンテーションシステムとテストフレームワークの機能を活用しています。

src/pkg/strings/example_test.goという新しいファイルが作成されています。Goの慣例では、example_test.goファイルは、パッケージの公開APIの使用例を記述するために使用されます。このファイルは、strings_testというパッケージ名で定義されており、これはテスト対象のstringsパッケージとは別のパッケージとして扱われることを意味します。これにより、stringsパッケージが外部からどのように利用されるかを正確にシミュレートできます。

追加されたExampleFields関数は、func ExampleFields()というシグネチャを持っています。Goのテストツールは、このExampleプレフィックスを認識し、この関数を特別な例として扱います。

関数内部では、strings.Fields(" foo bar baz ")が呼び出され、複数のスペースで区切られた文字列が分割されています。strings.Fieldsは、連続するホワイトスペースを単一の区切り文字として扱い、結果として空の文字列を含まないスライスを返します。この例では、先頭と末尾のスペース、および単語間の複数のスペースが適切に処理されることを示しています。

fmt.Printf("Fields are: %q", strings.Fields(" foo bar baz "))という行は、strings.Fieldsの戻り値をフォーマットして標準出力に出力します。%q動詞は、Goの文字列リテラル形式で値を引用符で囲んで出力するために使用されます。これにより、出力されるスライスの各要素が引用符で囲まれ、文字列であることが明確に示されます。

このExample関数がgo testコマンドで実行されると、その出力は自動的にキャプチャされ、もし// Output:コメントが存在すれば、そのコメントに続く行と比較されます。このコミットでは// Output:コメントは含まれていませんが、これはGoのドキュメント生成時に例として表示されることを主目的としているためです。もしテストとして厳密に検証したい場合は、// Output: ["foo" "bar" "baz"]のような行を追加することが可能です。

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

diff --git a/src/pkg/strings/example_test.go b/src/pkg/strings/example_test.go
new file mode 100644
index 0000000000..16e53678b2
--- /dev/null
+++ b/src/pkg/strings/example_test.go
@@ -0,0 +1,15 @@
+// Copyright 2012 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 strings_test
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Fields are: ["foo" "bar" "baz"]
+func ExampleFields() {
+	fmt.Printf("Fields are: %q", strings.Fields("  foo bar  baz   "))
+}

コアとなるコードの解説

追加されたコードは、src/pkg/strings/example_test.goという新しいファイルに記述されています。

  1. ライセンスヘッダ:

    // Copyright 2012 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.

    これはGoプロジェクトの標準的なライセンスヘッダであり、コードの著作権と利用条件を示しています。

  2. パッケージ宣言:

    package strings_test

    このファイルがstrings_testパッケージに属することを宣言しています。これは、テスト対象のstringsパッケージとは異なるパッケージであり、外部からstringsパッケージを利用するシナリオをシミュレートするために使用されます。

  3. インポート:

    import (
	"fmt"
	"strings"
)

    fmtパッケージはフォーマットされたI/O（この場合はPrintf関数）のために、stringsパッケージはテスト対象のFields関数のためにインポートされています。

  4. ExampleFields関数:

    // Fields are: ["foo" "bar" "baz"]
func ExampleFields() {
	fmt.Printf("Fields are: %q", strings.Fields("  foo bar  baz   "))
}
    • func ExampleFields(): Goのテストツールが例として認識する関数シグネチャです。
    • // Fields are: ["foo" "bar" "baz"]: このコメントは、Example関数の出力が期待される形式であることを示唆しています。go testが実行されると、この行は無視されますが、ドキュメント生成時には例のコンテキストとして役立ちます。
    • strings.Fields(" foo bar baz "): ここがstrings.Fields関数の実際の呼び出しです。入力文字列は、先頭、末尾、および単語間に複数のスペースを含んでいます。strings.Fieldsはこれらの余分なスペースを適切に処理し、["foo", "bar", "baz"]という文字列スライスを返します。
    • fmt.Printf("Fields are: %q", ...): Printf関数を使用して、結果を標準出力に出力します。%qフォーマット動詞は、文字列スライスの各要素をGoの文字列リテラル形式（引用符で囲まれた形式）で出力します。これにより、出力はFields are: ["foo" "bar" "baz"]のようになります。

このコードは、strings.Fields関数がどのように動作し、特に複数のスペースや前後のスペースをどのように扱うかを明確に示しており、Goのドキュメンテーションとテストのベストプラクティスに従っています。

関連リンク

参考にした情報源リンク