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

このコミットは、Go言語のドキュメント生成ツールである tmpltohtml (Goのプレゼンテーションツール present の一部) に、コードスニペットの抽出を容易にする新機能を追加するものです。具体的には、出力に含めたくない行を OMIT というマーカーで指定することで、その行が最終的なHTML出力から除外されるようになります。これにより、プレゼンテーションやドキュメント内で表示するコードをより柔軟に制御できるようになります。

コミット

commit 940c25faa4e495a13d6411fe23640c9d16b1e986
Author: Rob Pike <r@golang.org>
Date:   Fri Dec 9 08:31:04 2011 -0800

    tmpltohtml: feature for easier snippet extraction
    Lines that end with OMIT are omitted from the output.
    A comment such as
            // Example stops here. OMIT
    can be used as a marker but not appear in the output.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5477050

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

https://github.com/golang/go/commit/940c25faa4e495a13d6411fe23640c9d16b1e986

元コミット内容

tmpltohtml: feature for easier snippet extraction
Lines that end with OMIT are omitted from the output.
A comment such as
        // Example stops here. OMIT
can be used as a marker but not appear in the output.

変更の背景

Go言語には、コードスニペットを含むプレゼンテーションやドキュメントを生成するための present ツールが存在します。このツールは、Goのソースコードから特定の範囲を抽出し、HTML形式で表示する機能を持っています。しかし、プレゼンテーションの文脈では、コードの全体像を示す必要がない場合や、ボイラープレートコード（定型的な記述）やインポート文など、本質的ではない部分を非表示にしたい場合があります。

このコミット以前は、このような不要な行を手動で削除するか、抽出範囲を厳密に指定する必要がありました。これは、特に多くのコードスニペットを扱う場合に手間がかかり、コードの可読性を損なう可能性がありました。

この変更の背景には、present ツールを利用するユーザーが、より簡単に、かつ柔軟にコードスニペットを整形し、プレゼンテーションの意図に沿った形で表示できるようにするという目的があります。OMIT マーカーを導入することで、ソースコード自体に変更を加えることなく、表示される内容を制御できるようになり、ドキュメント作成の効率と品質が向上します。

前提知識の解説

このコミットを理解するためには、以下の前提知識が必要です。

• Go言語の present ツール: present は、Go言語の公式ツールセットの一部であり、.slide または .article 形式のテキストファイルからHTMLプレゼンテーションや記事を生成するために使用されます。このツールは、Goのソースコードを埋め込み、シンタックスハイライトや特定の行の強調表示などの機能を提供します。
• tmpltohtml: tmpltohtml は、present ツールの内部で利用されるコンポーネントの一つで、テンプレートとHTML変換を担当します。具体的には、present ファイル内で指定されたコードスニペットをGoのソースファイルから抽出し、HTMLに埋め込む処理を行います。
• コードスニペットの抽出: present ツールでは、{{code "filename" "/start_regex/" "/end_regex/"}} のような構文を使用して、指定されたファイルから正規表現にマッチする行範囲のコードを抽出できます。このコミットは、この抽出されたコードの表示方法をさらに制御するためのものです。
• 正規表現: コードスニペットの抽出範囲を指定するために正規表現が使用されます。正規表現は、文字列のパターンを記述するための強力なツールです。
• Goの標準ライブラリ strings: Goの標準ライブラリである strings パッケージは、文字列操作のための多くの関数を提供します。このコミットでは、文字列の末尾が特定の文字列で終わるかどうかをチェックする strings.HasSuffix 関数が使用されています。

技術的詳細

このコミットの技術的な核心は、tmpltohtml がコードスニペットを処理する際に、特定のマーカーを持つ行を検出して出力から除外するロジックを追加した点にあります。

具体的には、doc/tmpltohtml.go ファイル内の multipleLines 関数が変更されています。この関数は、指定されたファイルから複数行のコードを抽出する役割を担っています。変更前は、単に指定された行範囲のコードを結合して返していました。

変更後、multipleLines 関数は、抽出された各行に対してループ処理を行い、その行が OMIT\n (つまり、行末に "OMIT" と改行文字がある) で終わるかどうかを strings.HasSuffix を使用してチェックします。もし条件に合致した場合、その行の内容を空文字列に置き換えます。これにより、strings.Join で行を結合する際に、OMIT マーカーが付いた行は実質的に削除され、最終的な出力には含まれなくなります。

このアプローチの利点は以下の通りです。

1. 非破壊的: ソースコード自体を変更することなく、表示内容を制御できます。OMIT マーカーはコメントとして追加されるため、Goコンパイラには影響を与えません。
2. 柔軟性: プレゼンテーションの目的や表示したい内容に応じて、特定の行を簡単に表示・非表示に切り替えることができます。
3. 可読性: OMIT マーカーは、コードの意図を損なうことなく、どの行が省略されるかを明確に示します。

この機能は、特に複雑な例や、特定の概念に焦点を当てたい場合に非常に有効です。例えば、インポート文やエラーハンドリングの定型的な部分を隠し、関数の主要なロジックのみを強調表示するといった使い方が考えられます。

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

変更は doc/tmpltohtml.go ファイルに集中しています。

--- a/doc/tmpltohtml.go
+++ b/doc/tmpltohtml.go
@@ -16,7 +16,13 @@
 //	{{code "foo.go" `/^func.main/` `/^}/`
 //
 // Patterns can be `/regular expression/`, a decimal number, or "$\"
-// to signify the end of the file.
+// to signify the end of the file. In multi-line matches,
+// lines that end with the four characters
+//	OMIT
+// are omitted from the output, making it easy to provide marker
+// lines in the input that will not appear in the output but are easy
+// to identify by pattern.
+\n package main
 \n import (
 \n@@ -153,6 +159,11 @@ func multipleLines(file, text string, arg1, arg2 interface{}) string {\
 \t} else if line2 < line1 {\
 \t\tlog.Fatalf(\"lines out of order for %q: %d %d\", text, line1, line2)\
 \t}\
+\tfor k := line1 - 1; k < line2; k++ {\
+\t\tif strings.HasSuffix(lines[k], \"OMIT\\n\") {\
+\t\t\tlines[k] = \"\"\
+\t\t}\
+\t}\
 \treturn strings.Join(lines[line1-1:line2], \"\")
 }\
 \n

コアとなるコードの解説

変更は主に multipleLines 関数内で行われています。

1. コメントの追加: ファイルの冒頭のコメントブロックに、OMIT マーカーの新しい動作に関する説明が追加されています。

   // to signify the end of the file. In multi-line matches,
   // lines that end with the four characters
   //	OMIT
   // are omitted from the output, making it easy to provide marker
   // lines in the input that will not appear in the output but are easy
   // to identify by pattern.
   

   これは、tmpltohtml のユーザーがこの新機能を理解し、利用するための重要なドキュメントです。

2. OMIT 処理ロジックの追加: multipleLines 関数内で、抽出された行の配列 lines をループ処理する新しい for ループが追加されています。

   	for k := line1 - 1; k < line2; k++ {
   		if strings.HasSuffix(lines[k], "OMIT\n") {
   			lines[k] = ""
   		}
   	}
   

   • for k := line1 - 1; k < line2; k++: これは、抽出対象となる行の範囲 (line1 から line2 まで) を反復処理します。line1 - 1 は、Goのスライスが0ベースインデックスであるため、行番号を調整しています。
   • if strings.HasSuffix(lines[k], "OMIT\\n"): 各行 lines[k] が文字列 "OMIT\n" で終わるかどうかをチェックします。\n は改行文字を表しており、行末に OMIT があることを正確に検出します。
   • lines[k] = "": もし条件が真であれば、その行の内容を空文字列に設定します。これにより、後続の strings.Join 呼び出しで、この行は実質的に出力から削除されます。

このシンプルな変更により、tmpltohtml は、OMIT マーカーを含む行を自動的にフィルタリングし、よりクリーンで目的に合ったコードスニペットを生成できるようになりました。

関連リンク

• Go言語の present ツールに関する公式ドキュメント: https://pkg.go.dev/golang.org/x/tools/present (現在の present ツールのドキュメント)
• Go言語の strings パッケージ: https://pkg.go.dev/strings

参考にした情報源リンク

• GitHubコミットページ: https://github.com/golang/go/commit/940c25faa4e495a13d6411fe23640c9d16b1e986
• Go present ツールの OMIT 機能に関する解説記事 (Web検索結果より):
  • https://medium.com/@charly3pins/go-present-tool-for-presentations-101-f0e0e0e0e0e0 (例として挙げられた記事の一つ)
  • https://hexang.org/post/go-present-tool-tips/ (例として挙げられた記事の一つ)
  • https://charly3pins.dev/posts/go-present-tool-for-presentations-101/ (例として挙げられた記事の一つ)