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

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

このコミットは、Go言語の標準ライブラリ text/tabwriter パッケージのドキュメントを改善することを目的としています。具体的には、tabwriter.Writer の Init メソッドの使用例を example_test.go に追加し、既存の tabwriter.go 内のコメントから古い使用例を削除しています。これにより、tabwriter パッケージの利用方法がより明確になり、開発者が簡単に理解できるようになります。

コミット

commit 5f2ecbff71a69d51e9e40d915433e372d07344e7
Author: Robert Griesemer <gri@golang.org>
Date:   Tue Feb 21 14:48:17 2012 -0800

    text/tabwriter: fix documentation by adding an example.
    
    R=rsc, r
    CC=golang-dev
    https://golang.org/cl/5685069

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

https://github.com/golang/go/commit/5f2ecbff71a69d51e9e40d915433e372d07344e7

元コミット内容

このコミットの元の内容は以下の通りです。

text/tabwriter: fix documentation by adding an example.

これは、「text/tabwriter パッケージのドキュメントを例を追加することで修正する」という意味です。

変更の背景

Go言語の標準ライブラリ text/tabwriter は、テキストを整形してタブ区切りやスペース区切りのカラムをきれいに揃えるためのパッケージです。しかし、その使用方法、特に Writer 型の Init メソッドの引数の意味や挙動が、ドキュメント内のコメントだけでは直感的に理解しにくいという問題がありました。

Go言語では、Example 関数を _test.go ファイル内に記述することで、その関数のドキュメントに自動的に実行可能なコード例として表示される仕組みがあります。これにより、ユーザーはコード例を実際に実行して動作を確認できるため、ドキュメントの理解度が飛躍的に向上します。

このコミットは、tabwriter.Writer.Init メソッドのドキュメントを改善し、より分かりやすくするために、具体的な使用例を example_test.go ファイルとして追加することを目的としています。これにより、ユーザーは tabwriter の機能をより簡単に学習し、利用できるようになります。また、既存の tabwriter.go 内のコメントにあった古い、かつ実行不可能な例を削除することで、ドキュメントの一貫性と正確性を保っています。

前提知識の解説

Go言語の text/tabwriter パッケージ

text/tabwriter パッケージは、Go言語の標準ライブラリの一部であり、テキストデータを整形して、列を揃えるための機能を提供します。特に、ターミナル出力やログ出力など、人間が読みやすい形式でデータを表示する際に非常に役立ちます。

主な機能は以下の通りです。

  • カラムの自動調整: 入力されたテキストの各行を解析し、指定された区切り文字（タブなど）に基づいてカラムを検出し、各カラムの幅を自動的に調整して揃えます。
  • パディング: カラム間に指定された文字（スペースなど）を挿入し、読みやすさを向上させます。
  • アライメント: カラム内のテキストを左寄せ、右寄せ、または中央寄せに設定できます。

tabwriter.Writer 型

tabwriter パッケージの中心となるのが Writer 型です。これは io.Writer インターフェースをラップし、書き込まれたデータを整形して基になる io.Writer に出力します。

tabwriter.Writer.Init メソッド

Init メソッドは Writer を初期化するために使用されます。そのシグネチャは以下の通りです。

func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer

各引数の意味は以下の通りです。

  • output io.Writer: 整形されたテキストの出力先となる io.Writer です。通常は os.Stdout などが指定されます。
  • minwidth int: 各カラムの最小幅を指定します。この幅よりも短いカラムは、パディング文字で埋められます。
  • tabwidth int: タブ文字 (\t) が何文字分の幅として扱われるかを指定します。これは、タブストップの概念に似ています。
  • padding int: カラム間の最小パディング（空白）文字数を指定します。これにより、隣接するカラムのテキストがくっつくのを防ぎます。
  • padchar byte: パディングに使用する文字を指定します。通常はスペース (' ') またはタブ ('\t') が使用されます。
  • flags uint: 整形動作を制御するためのビットフラグです。例えば、tabwriter.AlignRight を指定すると、カラム内のテキストが右寄せになります。

Go言語の Example 関数

Go言語のテストパッケージ (_test.go ファイル) では、Example というプレフィックスを持つ関数を定義することで、その関数のドキュメントにコード例を自動的に含めることができます。これらの例は go test コマンドで実行され、出力が期待される出力と一致するかどうかが検証されます。これにより、ドキュメントのコード例が常に最新かつ正確であることが保証されます。

Example 関数の命名規則は以下の通りです。

  • Example(): パッケージ全体の例。
  • ExampleF(): 関数 F の例。
  • ExampleT_M(): 型 T のメソッド M の例。

また、// Output: コメントを例の最後に記述することで、その例の標準出力が期待される出力と一致するかどうかを go test が検証します。

技術的詳細

このコミットは、text/tabwriter パッケージのドキュメントを改善するために、以下の2つの主要な変更を行っています。

  1. src/pkg/text/tabwriter/example_test.go の新規作成: このファイルは、tabwriter.Writer.Init メソッドの具体的な使用例を提供します。2つの異なる整形パターンを示しています。

    • タブ区切り: タブストップが8のタブ区切りカラムで整形する例。
    • スペース区切り（右寄せ）: 最小幅5、パディング1、右寄せのスペース区切りカラムで整形する例。 これらの例は、fmt.Fprintln を使用して tabwriter.Writer にデータを書き込み、最後に Flush() を呼び出して整形された出力を os.Stdout に書き出すプロセスを示しています。 また、// output: コメントブロックが含まれており、go test コマンドがこの例の出力を検証するために使用されます。これにより、ドキュメントのコード例が常に正しく動作することが保証されます。

  2. src/pkg/text/tabwriter/tabwriter.go からのコメント削除: tabwriter.go ファイル内の Writer.Init メソッドのドキュメントコメントから、古い、かつ実行不可能な使用例が削除されました。これらの例は、コードとして実行できないため、ユーザーにとっては混乱の原因となる可能性がありました。新しい example_test.go に実行可能な例が追加されたため、これらの古いコメントは不要となり、削除されました。

この変更により、tabwriter パッケージのドキュメントはより実践的で、理解しやすくなりました。ユーザーは example_test.go を参照することで、tabwriter.Writer.Init メソッドの様々な引数がどのように出力に影響するかを直接確認できるようになります。

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

src/pkg/text/tabwriter/example_test.go (新規ファイル)

--- /dev/null
+++ b/src/pkg/text/tabwriter/example_test.go
@@ -0,0 +1,38 @@
+// 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 tabwriter_test
+
+import (
+	"fmt"
+	"os"
+	"text/tabwriter"
+)
+
+func ExampleWriter_Init() {
+	w := new(tabwriter.Writer)
+
+	// Format in tab-separated columns with a tab stop of 8.
+	w.Init(os.Stdout, 0, 8, 0, '\t', 0)
+	fmt.Fprintln(w, "a\tb\tc\td\t.")
+	fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
+	fmt.Fprintln(w)
+	w.Flush()
+
+	// Format right-aligned in space-separated columns of minimal width 5
+	// and at least one blank of padding (so wider column entries do not
+	// touch each other).
+	w.Init(os.Stdout, 5, 0, 1, ' ', tabwriter.AlignRight)
+	fmt.Fprintln(w, "a\tb\tc\td\t.")
+	fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
+	fmt.Fprintln(w)
+	w.Flush()
+
+	// output:
+	// a		b		c		d		.
+	// 123	12345	1234567	123456789	.
+	//
+	//     a     b       c         d.
+	//   123 12345 1234567 123456789.
+}

src/pkg/text/tabwriter/tabwriter.go (変更)

--- a/src/pkg/text/tabwriter/tabwriter.go
+++ b/src/pkg/text/tabwriter/tabwriter.go
@@ -169,12 +169,6 @@ const (
 //			to the tab width in the viewer displaying the result)
 //	flags		formatting control
 //
-// To format in tab-separated columns with a tab stop of 8:
-//		b.Init(w, 8, 1, 8, '\t', 0);
-//
-// To format in space-separated columns with at least 4 spaces between columns:
-//		b.Init(w, 0, 4, 8, ' ', 0);
-//
 func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer {
 	if minwidth < 0 || tabwidth < 0 || padding < 0 {
 		panic("negative minwidth, tabwidth, or padding")

コアとなるコードの解説

example_test.go の解説

このファイルは、tabwriter パッケージの ExampleWriter_Init 関数を定義しています。この関数は、tabwriter.Writer の Init メソッドの2つの異なる使用例を示しています。

  1. タブ区切りでの整形:

    w.Init(os.Stdout, 0, 8, 0, '\t', 0)
fmt.Fprintln(w, "a\tb\tc\td\t.")
fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
fmt.Fprintln(w)
w.Flush()
    • w.Init(os.Stdout, 0, 8, 0, '\t', 0):
      • os.Stdout: 標準出力に書き込みます。
      • minwidth=0: 最小幅は指定しません（コンテンツの幅に合わせます）。
      • tabwidth=8: タブ文字 (\t) は8文字分の幅として扱われます。
      • padding=0: カラム間のパディングは指定しません。
      • padchar='\t': パディング文字はタブです。
      • flags=0: フラグは指定しません（デフォルトは左寄せ）。
    • fmt.Fprintln(w, ...): Writer に文字列を書き込みます。文字列内のタブ (\t) がカラムの区切りとして認識されます。
    • w.Flush(): バッファリングされたデータを整形して出力します。

  2. スペース区切り（右寄せ）での整形:

    w.Init(os.Stdout, 5, 0, 1, ' ', tabwriter.AlignRight)
fmt.Fprintln(w, "a\tb\tc\td\t.")
fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
fmt.Fprintln(w)
w.Flush()
    • w.Init(os.Stdout, 5, 0, 1, ' ', tabwriter.AlignRight):
      • os.Stdout: 標準出力に書き込みます。
      • minwidth=5: 各カラムの最小幅は5文字です。
      • tabwidth=0: タブ幅は指定しません（スペース区切りのため）。
      • padding=1: カラム間に少なくとも1文字のパディング（空白）を入れます。
      • padchar=' ': パディング文字はスペースです。
      • flags=tabwriter.AlignRight: カラム内のテキストを右寄せにします。
    • 同様に fmt.Fprintln でデータを書き込み、Flush() で出力します。

// output: コメントブロックは、この Example 関数を実行した際の期待される出力を示しています。go test コマンドは、このコメントと実際の出力を比較し、一致しない場合はテストを失敗させます。これにより、ドキュメントの例が常に正確であることが保証されます。

tabwriter.go の解説

tabwriter.go から削除されたコメントは、Writer.Init メソッドのドキュメントの一部でした。これらは、Init メソッドの引数の設定例を示していましたが、コードとして実行できる形式ではなかったため、新しい example_test.go に実行可能な例が追加されたことで不要となりました。

削除されたコメントは以下の通りです。

// To format in tab-separated columns with a tab stop of 8:
//		b.Init(w, 8, 1, 8, '\t', 0);
//
// To format in space-separated columns with at least 4 spaces between columns:
//		b.Init(w, 0, 4, 8, ' ', 0);

これらのコメントは、Init メソッドの引数の意味を説明するものでしたが、具体的なコンテキスト（w や b が何であるか、io.Writer がどこから来るかなど）が不足しており、そのままでは実行できませんでした。example_test.go の追加により、これらの例はより完全で実行可能な形で提供されることになりました。

関連リンク

  • Go言語 text/tabwriter パッケージのドキュメント: https://pkg.go.dev/text/tabwriter
  • Go言語の Example 関数に関する公式ドキュメント（go doc testing または go help test で確認可能）

参考にした情報源リンク

  • Go言語の公式ドキュメント (pkg.go.dev)
  • Go言語のテストに関する一般的な情報源
  • Gitのコミット履歴と差分表示
  • Go言語の text/tabwriter パッケージのソースコード