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

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

このコミットは、Go言語の公式ドキュメントの一部である「Codewalk」内のsharemem.xmlファイルにおける、コード参照の修正に関するものです。具体的には、Codewalkが参照するGoソースコード内のコメントや文字列の先頭文字のケース変更に対応するため、XMLファイル内の参照パス（正規表現）を更新しています。

コミット

  • コミットハッシュ: ae8d8abfebd11450bde5722f22fc32320660bf6a
  • 作者: Rob Pike r@golang.org
  • コミット日時: 2012年3月24日 土曜日 08:12:52 +1100
  • コミットメッセージ: 
    codewalk/sharemem.xml: fix references to files

R=golang-dev, iant
CC=golang-dev
https://golang.org/cl/5877064

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

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

元コミット内容

codewalk/sharemem.xml: fix references to files

R=golang-dev, iant
CC=golang-dev
https://golang.org/cl/5877064

変更の背景

このコミットの背景には、Go言語の「Codewalk」というインタラクティブなチュートリアルシステムと、その内部的なコード参照メカニズムがあります。Codewalkは、特定のGoソースコードファイル内の特定のセクションをハイライト表示することで、コードの解説を行います。このセクションの指定には、ファイルパスと正規表現が用いられます。

doc/codewalk/sharemem.xmlは、共有メモリに関するCodewalkの定義ファイルであり、urlpoll.goというサンプルコードを参照しています。元のsharemem.xmlでは、urlpoll.go内のコードセクションを特定するために、正規表現で「create our」、「launch the StateMonitor」といった小文字で始まるフレーズを検索していました。

しかし、何らかの理由（例えば、urlpoll.go内のコメントや文字列がスタイルガイドの変更などにより更新され、先頭が大文字になった場合）で、参照先のurlpoll.go内の該当するコメントや文字列が「Create our」、「Launch the StateMonitor」のように大文字で始まる形に変更された可能性があります。正規表現はデフォルトで大文字・小文字を区別するため、この変更によってsharemem.xml内の既存の参照が機能しなくなり、Codewalkが正しくコードセクションを表示できなくなる問題が発生しました。

このコミットは、この参照の不整合を修正し、Codewalkが引き続き意図したコードセクションを正確に表示できるようにするために行われました。

前提知識の解説

Go Codewalks

Go Codewalksは、Go言語のコードをインタラクティブに解説するためのツールおよびドキュメント形式です。Goのソースコードと、そのコードの各部分を説明するテキストを組み合わせることで、ユーザーはコードをステップバイステップで読み進めながら、その動作や設計思想を理解することができます。

Codewalkは通常、XML形式の定義ファイル（例: sharemem.xml）と、解説対象のGoソースコードファイル（例: urlpoll.go）で構成されます。XMLファイル内では、<step>タグを用いて各解説ステップを定義し、src属性を使って参照するGoソースコードのファイルパスと、そのファイル内の特定のコードブロックを特定するための正規表現を指定します。

XMLのsrc属性と正規表現

CodewalkのXML定義ファイルにおいて、<step>タグのsrc属性は非常に重要です。この属性は、以下の形式でコードセクションを指定します。

src="[ファイルパス]:/[開始正規表現]/,/[終了正規表現]/"

  • [ファイルパス]: 参照するGoソースコードファイルのパス。
  • [開始正規表現]: コードブロックの開始位置を特定するための正規表現。
  • [終了正規表現]: コードブロックの終了位置を特定するための正規表現。

この正規表現は、Goソースコードファイルの内容に対してマッチングが行われます。正規表現はデフォルトで大文字・小文字を区別するため、もし参照先のコード内の文字列のケースが変更されると、正規表現がマッチしなくなり、Codewalkがコードセクションを正しく表示できなくなります。

正規表現 (Regular Expressions) の基礎

正規表現は、文字列のパターンを記述するための強力なツールです。このコミットに関連する正規表現の重要な側面は「大文字・小文字の区別」です。

  • 大文字・小文字の区別 (Case Sensitivity): 多くの正規表現エンジンでは、デフォルトで大文字と小文字を区別します。例えば、正規表現/create our/は「create our」にはマッチしますが、「Create our」にはマッチしません。
  • マッチング: 正規表現は、指定されたパターンに合致する文字列を検索します。Codewalkのsrc属性では、開始正規表現と終了正規表現に挟まれたコードブロックが抽出されます。

技術的詳細

このコミットの技術的な核心は、Go Codewalkシステムがコードスニペットを特定するために使用する正規表現のケースセンシティブな性質にあります。

doc/codewalk/sharemem.xmlファイルは、urlpoll.goというGoのサンプルコードを解説するCodewalkの定義です。このXMLファイル内では、<step>タグのsrc属性を使って、urlpoll.go内の特定のコード行範囲を指定しています。この指定は、ファイルパスと、そのファイル内でコードブロックの開始と終了を示す正規表現のペアによって行われます。

元のsharemem.xmlでは、以下のようなsrc属性がありました。

  • src="doc/codewalk/urlpoll.go:/create our/,/complete/"
  • src="doc/codewalk/urlpoll.go:/launch the StateMonitor/,/statusInterval/"
  • src="doc/codewalk/urlpoll.go:/launch some Poller/,/}/"
  • src="doc/codewalk/urlpoll.go:/send some Resources/,/}\\(\\)/"

これらの正規表現は、それぞれ「create our」、「launch the StateMonitor」、「launch some Poller」、「send some Resources」という小文字で始まるフレーズにマッチするように設計されていました。

しかし、何らかの変更（例えば、urlpoll.go内のコメントや変数名、文字列リテラルがGoのコーディング規約やスタイル変更によって大文字で始まるように修正された場合）により、urlpoll.go内の実際のコードが以下のように変更されたと仮定できます。

  • Create our
  • Launch the StateMonitor
  • Launch some Poller
  • Send some Resources

正規表現はデフォルトで大文字・小文字を区別するため、元の正規表現（例: /create our/）は、変更後のコード（例: Create our）にはマッチしません。この不一致が原因で、Codewalkはurlpoll.go内の対応するコードセクションを見つけることができなくなり、結果としてCodewalkの表示が壊れてしまいます。

このコミットは、この問題を解決するために、sharemem.xml内のsrc属性に含まれる正規表現を、参照先のurlpoll.go内の実際のコードのケース（大文字始まり）に合わせて修正しています。これにより、Codewalkは再び正確なコードセクションを特定し、表示できるようになります。

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

変更はdoc/codewalk/sharemem.xmlファイルに集中しています。具体的には、以下の4つの<step>タグのsrc属性が修正されています。

--- a/doc/codewalk/sharemem.xml
+++ b/doc/codewalk/sharemem.xml
@@ -65,7 +65,7 @@ and then loops passing completed Resources back to the pending
 channel after appropriate delays.\n </step>\n \n-<step title=\"Creating channels\" src=\"doc/codewalk/urlpoll.go:/create our/,/complete/\">\n+<step title=\"Creating channels\" src=\"doc/codewalk/urlpoll.go:/Create our/,/complete/\">\n First, main makes two channels of *Resource, pending and complete.\n <br/><br/>\n Inside main, a new goroutine sends one Resource per URL to pending\n@@ -75,7 +75,7 @@ The pending and complete channels are passed to each of the Poller\n goroutines, within which they are known as in and out. \n </step>\n \n-<step title=\"Initializing StateMonitor\" src=\"doc/codewalk/urlpoll.go:/launch the StateMonitor/,/statusInterval/\">\n+<step title=\"Initializing StateMonitor\" src=\"doc/codewalk/urlpoll.go:/Launch the StateMonitor/,/statusInterval/\">\n StateMonitor will initialize and launch a goroutine that stores the state \n of each Resource. We will look at this function in detail later. \n <br/><br/>\n@@ -83,14 +83,14 @@ For now, the important thing to note is that it returns a channel of State,\n which is saved as status and passed to the Poller goroutines.\n </step>\n \n-<step title=\"Launching Poller goroutines\" src=\"doc/codewalk/urlpoll.go:/launch some Poller/,/}/\">\n+<step title=\"Launching Poller goroutines\" src=\"doc/codewalk/urlpoll.go:/Launch some Poller/,/}/\">\n Now that it has the necessary channels, main launches a number of\n Poller goroutines, passing the channels as arguments.\n The channels provide the means of communication between the main, Poller, and \n StateMonitor goroutines.\n </step>\n \n-<step title=\"Send Resources to pending\" src=\"doc/codewalk/urlpoll.go:/send some Resources/,/}\\(\\)/\">\n+<step title=\"Send Resources to pending\" src=\"doc/codewalk/urlpoll.go:/Send some Resources/,/}\\(\\)/\">\n To add the initial work to the system, main starts a new goroutine\n that allocates and sends one Resource per URL to pending.\n <br/><br/>\n```

具体的には、以下の変更が行われています。

1.  `src="doc/codewalk/urlpoll.go:/create our/,/complete/"`
    ↓
    `src="doc/codewalk/urlpoll.go:/Create our/,/complete/"`
    （`create` → `Create`）

2.  `src="doc/codewalk/urlpoll.go:/launch the StateMonitor/,/statusInterval/"`
    ↓
    `src="doc/codewalk/urlpoll.go:/Launch the StateMonitor/,/statusInterval/"`
    （`launch` → `Launch`）

3.  `src="doc/codewalk/urlpoll.go:/launch some Poller/,/}/"`
    ↓
    `src="doc/codewalk/urlpoll.go:/Launch some Poller/,/}/"`
    （`launch` → `Launch`）

4.  `src="doc/codewalk/urlpoll.go:/send some Resources/,/}\\(\\)/"`
    ↓
    `src="doc/codewalk/urlpoll.go:/Send some Resources/,/}\\(\\)/"`
    （`send` → `Send`）

## コアとなるコードの解説

これらの変更は、`doc/codewalk/sharemem.xml`ファイルが`urlpoll.go`内の特定のコードスニペットを正確に参照できるようにするために行われました。

Codewalkシステムは、XMLファイル内の`src`属性で指定された正規表現を使用して、対応するGoソースコードファイルから関連するコードブロックを抽出します。正規表現はデフォルトで大文字・小文字を区別するため、もし`urlpoll.go`内のコメントや文字列が小文字から大文字に変わった場合、元のXMLファイル内の正規表現はもはやマッチしなくなります。

このコミットでは、正規表現のパターンを、参照先の`urlpoll.go`内の実際のコードの先頭文字のケース（小文字から大文字へ）に合わせて修正しています。例えば、`create our`という正規表現が`Create our`に変更されたのは、`urlpoll.go`内の該当するコードが「Create our」という形で記述されるようになったためです。

これにより、Codewalkは`urlpoll.go`内の正しいコードセクションを再び見つけ出し、インタラクティブなチュートリアルが期待通りに機能するようになります。これは、ドキュメントとコードベースの同期を保つための、保守的な修正と言えます。

## 関連リンク

*   Go Change-ID: [https://golang.org/cl/5877064](https://golang.org/cl/5877064)

## 参考にした情報源リンク

*   Go Codewalks (公式ドキュメントや関連するGoプロジェクトのドキュメント)
*   正規表現の基本的な概念と大文字・小文字の区別に関する情報
*   XMLの構造と属性に関する一般的な知識