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

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

このコミットは、Go言語のGo 1リリースに向けたドキュメントの修正であり、特にdoc/go1.htmlとdoc/go1.tmplファイルにおけるマージの競合を解決し、Go 1で導入された様々なパッケージの変更点を正確に反映させることを目的としています。コミットメッセージは、バージョン管理システムMercurial (hg) がマージ処理で問題を引き起こしたことへの言及を含んでおり、Gitの使用を推奨するユーモラスなコメントが添えられています。

コミット

commit c2e58dc568093cb0d8967d62e7081aa2781de89f
Author: Adam Langley <agl@golang.org>
Date:   Tue Feb 14 07:13:57 2012 -0500

    go1.tmpl: fix merge
    
    hg massively messed up a simple merge for 9d7addec2635 in what I can
    only imagine was a public service announcement that everyone should
    use git.
    
    R=golang-dev
    CC=golang-dev
    https://golang.org/cl/5668043

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

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

元コミット内容

このコミットは、go1.tmplファイルにおけるマージの修正を目的としています。具体的には、Go 1リリースノートのHTMLドキュメント (doc/go1.html) とそのテンプレート (doc/go1.tmpl) に、Go 1で変更された標準ライブラリのAPIに関する詳細な説明を追加・修正しています。

変更の背景

Go 1は、Go言語にとって最初の安定版リリースであり、将来にわたる互換性を保証するための重要なマイルストーンでした。このリリースでは、言語仕様だけでなく、標準ライブラリの多くのパッケージでAPIの変更や改善が行われました。これらの変更は、Go言語の設計思想である「シンプルさ」「効率性」「並行性」をさらに追求し、より堅牢で使いやすいライブラリを提供するために必要でした。

このコミットの背景には、Go 1リリースノートの正確性を確保するという目的があります。特に、バージョン管理システムであるMercurial (hg) がマージ処理で問題を引き起こし、ドキュメントの整合性が損なわれたため、その修正が必要となりました。これは、Go 1のリリースを控える中で、ユーザーが最新かつ正確な情報にアクセスできるようにするための重要な作業でした。

前提知識の解説

このコミットの変更内容を理解するためには、以下の前提知識が役立ちます。

  • Go 1リリース: Go言語の最初の安定版リリースであり、言語と標準ライブラリのAPIに多くの変更が加えられました。このリリース以降、Go言語は後方互換性を重視する方針に転換しました。
  • 標準ライブラリ: Go言語に同梱されている豊富なパッケージ群で、ファイルI/O、ネットワーク通信、データ構造、暗号化など、様々な機能を提供します。
  • API変更: 既存の関数や型のシグネチャ、動作、名前などが変更されることです。Go 1では、より一貫性のある、使いやすいAPIを目指して多くの変更が行われました。
  • go fixツール: Go 1で導入されたツールで、古いGoコードをGo 1の新しいAPIに自動的に更新する機能を提供します。ただし、すべての変更を自動で修正できるわけではなく、手動での修正が必要な場合もあります。
  • Mercurial (hg) と Git: どちらも分散型バージョン管理システムです。コミットメッセージでは、Mercurialのマージ機能が不適切に動作したことが示唆されており、Gitへの移行が示唆されています。

技術的詳細

このコミットは、Go 1リリースノートのドキュメント (doc/go1.html および doc/go1.tmpl) に、以下のGo標準ライブラリパッケージにおけるAPI変更の詳細を記述しています。

bufio パッケージ

  • NewReaderSize および NewWriterSize 関数の変更: Go 1では、bufio.NewReaderSize および bufio.NewWriterSize 関数が、無効なサイズ引数に対してエラーを返さなくなりました。代わりに、引数のサイズが小さすぎるか無効な場合、適切なサイズに調整されるようになりました。
  • Scanner 型の導入: Go 1では、テキストデータを効率的に読み取るための新しいScanner型が導入されました。これにより、行、単語、バイトなどの単位でデータを簡単に処理できるようになりました。
  • Reader メソッドの追加: Discard, Reset, Size, WriteTo といった新しいメソッドが Reader に追加され、バッファリングされたI/Oの操作性が向上しました。

compress/flate, compress/gzip, compress/zlib パッケージ

  • NewWriterXxx 関数のAPI統一: これらのパッケージのNewWriterXxx関数は、圧縮レベルを引数に取る場合、(*Writer, error)を返すように統一されました。圧縮レベルを引数に取らない場合は、*Writerを返します。
  • compress/gzip の型名変更: gzipパッケージ内のCompressor型とDecompressor型が、それぞれWriterとReaderにリネームされました。
  • compress/flate の型削除: flateパッケージのWrongValueError型が削除されました。

encoding/binary パッケージ

  • TotalSize から Size への変更: binary.TotalSize 関数が binary.Size に置き換えられました。新しい Size 関数は、reflect.Value ではなく interface{} を引数に取るようになりました。

encoding/xml パッケージ

  • 他のマーシャリングパッケージとの整合性: encoding/xml パッケージは、encoding/gob のような他のマーシャリングパッケージの設計に近づけられました。
  • Parser から Decoder へのリネーム: 古い Parser 型は Decoder にリネームされ、新しい Decode メソッドが追加されました。
  • Encoder 型の導入: XMLをエンコードするための新しい Encoder 型が導入されました。
  • Marshal と Unmarshal の []byte 対応: Marshal および Unmarshal 関数は、ストリームではなく []byte 値を扱うようになりました。ストリームを扱う場合は、新しい Encoder および Decoder 型を使用します。
  • フィールドタグの書式変更: フィールドタグの書式が encoding/json パッケージに近づけられ、xml:"name,flag" の形式になりました。
  • 大文字・小文字の区別: フィールドタグ、フィールド名、XML属性名、要素名とのマッチングにおいて、大文字・小文字が区別されるようになりました。
  • XMLName フィールドタグの要件: XMLName フィールドタグが存在する場合、マーシャリングされるXML要素の名前と一致する必要があります。
  • go fix ツールによる更新: go fix ツールは、このパッケージのほとんどの使用箇所を更新しますが、フィールドタグは手動で修正する必要があります。例えば、古い "attr" は ",attr" と記述されるようになり、単なる "attr" は異なる意味を持つようになりました。

go/scanner, go/parser, go/printer, go/doc パッケージ

  • Mode 型の導入: これらのパッケージで設定モードフラグを扱うための具体的な Mode 型が導入されました。
  • go/scanner の変更:
    • AllowIllegalChars と InsertSemis モードが削除されました。これらは主にGoソースファイル以外のスキャンに有用でしたが、その目的には text/scanner パッケージを使用するべきとされました。
    • スキャナーの Init メソッドに提供される ErrorHandler が、インターフェースではなく単なる関数になりました。
    • ErrorVector 型が削除され、既存の ErrorList 型が推奨されるようになりました。
  • go/parser の変更: パース関数のセットが、主要なパース関数と ParseDir、ParseExpr といった便利な関数に絞られました。
  • go/printer の変更:
    • 追加の構成モード SourcePos がサポートされました。これが設定されると、生成された出力に元のソースコードの位置情報を示す //line コメントが出力されます。
    • 新しい CommentedNode 型が導入され、任意の ast.Node にコメントを関連付けられるようになりました。
  • go/doc の変更: PackageDoc などの型名から Doc サフィックスが削除され、簡素化されました。

net/http パッケージ

  • Request.RawURL フィールドの削除: Request.RawURL フィールドが削除されました。これは歴史的な遺物とされました。
  • 重複パターン登録時のパニック: Handle および HandleFunc 関数、および ServeMux の同様のメソッドは、同じパターンを二度登録しようとするとパニックを起こすようになりました。
  • パッケージの再編成: http パッケージは net/http に移動され、URL解析関連の関数は新しい url パッケージに移動されました。
  • Client.Get の戻り値変更: Client.Get メソッドの finalURL 戻り値が削除され、http.Response オブジェクト内の新しい Request フィールドを通じてアクセスできるようになりました。
  • Values 型の導入: map[string][]string が使用されていた多くの箇所で、新しい Values 型が導入され、データ処理が効率化されました。
  • FileSystem インターフェースの導入: FileServer ヘルパーが FileSystem 引数を受け入れるようになり、カスタムのファイルシステムを実装して任意のデータをサーブできるようになりました。

image パッケージ

  • 型名変更と削除: image.ColorImage 型が image.Uniform にリネームされました。image.Tiled 型は削除されました。

log/syslog パッケージ

  • NewLogger 関数の変更: syslog.NewLogger 関数が、log.Logger に加えてエラーも返すようになりました。
  • Go 1での新規パッケージ: log/syslog パッケージ自体はGo 1で標準ライブラリに新しく追加されたパッケージです。

os パッケージ

  • Time 関数の削除: Time 関数が削除され、呼び出し元は time パッケージの Time 型を使用するべきとされました。
  • Exec 関数の削除: Exec 関数が削除され、呼び出し元は syscall パッケージの Exec を使用するべきとされました（利用可能な場合）。
  • ShellExpand から ExpandEnv へのリネーム: ShellExpand 関数が ExpandEnv にリネームされました。
  • ファイルディスクリプタの型変更: NewFile 関数が int ではなく uintptr 型のファイルディスクリプタ (fd) を取るようになりました。また、ファイルの Fd メソッドも uintptr を返すようになりました。
  • エラーハンドリングの統一: os.Error 型が削除され、すべての標準パッケージが新しい error インターフェースを使用するように更新されました。errors.New が新しいエラーを作成する標準的な方法となりました。

testing/script パッケージ

  • パッケージの削除: testing/script パッケージは削除されました。コミットメッセージでは「それは残骸だった (It was a dreg.)」と述べられており、Go 1の最終リリースには含まれない実験的な、あるいは不要なコードであったことを示唆しています。Web検索の結果によると、testscript パッケージはGo 1リリースよりもかなり後の2018年頃に導入されたものであり、このコミットで削除された testing/script は、それとは異なる、Go 1リリース前の実験的なテストスクリプト関連のコードであった可能性が高いです。

url パッケージ

  • net/http からの分離と機能強化: net/http パッケージからURL解析関連の機能が分離され、独立した net/url パッケージとして提供されるようになりました。
  • *URL 型の新しいメソッド: EscapedFragment(), EscapedPath(), Hostname(), JoinPath(), Port(), Redacted() など、URLコンポーネントへのより詳細なアクセスと制御を提供するメソッドが追加されました。
  • パスのエスケープ/アンエスケープ関数: PathEscape() と PathUnescape() 関数が導入され、URLパスセグメントのエスケープとアンエスケープを処理できるようになりました。
  • ParseRequestURI 関数の追加: HTTPリクエストで受信した生のURLを解析するための ParseRequestURI 関数が追加されました。

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

このコミットのコアとなる変更は、doc/go1.html と doc/go1.tmpl という2つのドキュメントファイルに対するものです。これらのファイルは、Go 1のリリースノートを構成しており、Go言語の標準ライブラリにおけるAPI変更の詳細を記述しています。

diff --git a/doc/go1.html b/doc/go1.html
index da31b91408..9b62d1a1ad 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -867,6 +867,40 @@ longer has a <code>Write</code> method. Its presence was a mistake.
 and must be updated by hand. Such code is almost certainly incorrect.
 </p>
 
+<h3 id=\"bufio\">The bufio package</h3>
+
+<p>
+In Go 1, <a href=\"/pkg/bufio/#NewReaderSize\"><code>bufio.NewReaderSize</code></a>
+and
+<a href=\"/pkg/bufio/#NewWriterSize\"><code>bufio.NewWriterSize</code></a>
+functions no longer return an error for invalid sizes.
+If the argument size is too small or invalid, it is adjusted.
+</p>
+
+<p>
+<em>Updating</em>:
+What little code is affected will be caught by the compiler and must be updated by hand.
+</p>
+
+<h3 id=\"bufio\">The compress/flate, compress/gzip and compress/zlib packages</h3>
+
+<p>
+In Go 1, the <code>NewWriterXxx</code> functions in
+<a href=\"/pkg/compress/flate\"><code>compress/flate</code></a>,
+<a href=\"/pkg/compress/gzip\"><code>compress/gzip</code></a> and
+<a href=\"/pkg/compress/zlib\"><code>compress/zlib</code></a>
+all return <code>(*Writer, error)</code> if they take a compression level,
+and <code>*Writer</code> otherwise. Package <code>gzip</code>\'s
+<code>Compressor</code> and <code>Decompressor</code> types have been renamed
+to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>\'s
+<code>WrongValueError</code> type has been removed.
+</p>
+
+<p>
+<em>Updating</em>
+What little code is affected will be caught by the compiler and must be updated by hand.
+</p>
+
 <h3 id=\"crypto_aes_des\">The crypto/aes and crypto/des packages</h3>
 
 <p>
@@ -936,6 +970,63 @@ to be implemented in the future.
 No changes will be needed.
 </p>
 
+<h3 id=\"encoding_binary\">The encoding/binary package</h3>               
+
+<p>
+In Go 1, the <code>binary.TotalSize</code> function has been replaced by
+<a href=\"/pkg/encoding/binary/#Size\"><code>Size</code></a>,
+which takes an <code>interface{}</code> argument rather than
+a <code>reflect.Value</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+What little code is affected will be caught by the compiler and must be updated by hand.
+</p>
+
+<h3 id=\"encoding_xml\">The encoding/xml package</h3>
+
+<p>
+In Go 1, the <a href=\"/pkg/encoding/xml/\"><code>xml</code></a> package
+has been brought closer in design to the other marshaling packages such
+as <a href=\"/pkg/encoding/gob/\"><code>encoding/gob</code></a>.
+</p>
+
+<p>
+The old <code>Parser</code> type is renamed
+<a href=\"/pkg/encoding/xml/#Decoder\"><code>Decoder</code></a> and has a new
+<a href=\"/pkg/encoding/xml/#Decoder.Decode\"><code>Decode</code></a> method. An
+<a href=\"/pkg/encoding/xml/#Encoder\"><code>Encoder</code></a> type was also     introducted.
+</p>
+
+<p>
+The functions <a href=\"/pkg/encoding/xml/#Marshal\"><code>Marshal</code></a>
+and <a href=\"/pkg/encoding/xml/#Unmarshal\"><code>Unmarshal</code></a>
+work with <code>[]byte</code> values now. To work with streams,
+use the new <a href=\"/pkg/encoding/xml/#Encoder\"><code>Encoder</code></a>
+and <a href=\"/pkg/encoding/xml/#Decoder\"><code>Decoder</code></a> types.
+</p>
+
+<p>
+When marshaling or unmarshaling values, the format of supported flags in
+field tags has changed to be closer to the
+<a href=\"/pkg/encoding/json\"><code>json</code></a> package
+(<code>`xml:\"name,flag\"`</code>). The matching done between field tags, field
+names, and the XML attribute and element names is now case-sensitive.
+The <code>XMLName</code> field tag, if present, must also match the name
+of the XML element being marshaled.
+</p>
+
+<p>
+<em>Updating</em>:
+Running <code>go fix</code> will update most uses of the package except for some calls to
+<code>Unmarshal</code>. Special care must be taken with field tags,
+since the fix tool will not update them and if not fixed by hand they will
+misbehave silently in some cases. For example, the old
+<code>\"attr\"</code> is now written <code>\",attr\"</code> while plain
+<code>\"attr\"</code> remains valid but with a different meaning.
+</p>
+
 <h3 id=\"expvar\">The expvar package</h3>
 
 <p>
@@ -985,6 +1076,15 @@ The <code>Duration</code> flag is new and affects no existing code.\n Several packages under <code>go</code> have slightly revised APIs.\n </p>\n 
+<p>
+A concrete <code>Mode</code> type was introduced for configuration mode flags
+in the packages
+<a href=\"/pkg/go/scanner/\"><code>go/scanner</code></a>,
+<a href=\"/pkg/go/parser/\"><code>go/parser</code></a>,
+<a href=\"/pkg/go/printer/\"><code>go/printer</code></a>, and
+<a href=\"/pkg/go/doc/\"><code>go/doc</code></a>.
+</p>
+
 <p>
 The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
 from the <a href=\"/pkg/go/scanner/\"><code>go/scanner</code></a> package. They were mostly
@@ -993,6 +1093,16 @@ useful for scanning text other then Go source files. Instead, the
 for that purpose.\n </p>\n 
+<p>
+The <a href=\"/pkg/go/scanner/#ErrorHandler\"><code>ErrorHandler</code></a> provided
+to the scanner\'s <a href=\"/pkg/go/scanner/#Scanner.Init\"><code>Init</code></a> method is
+now simply a function rather than an interface. The <code>ErrorVector</code> type has
+been removed in favor of the (existing) <a href=\"/pkg/go/scanner/#ErrorList\"><code>ErrorList</code></a>
+type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding
+an <code>ErrorVector</code> in a client of the scanner, now a client should maintain
+an <code>ErrorList</code>.
+</p>
+
 <p>
 The set of parse functions provided by the <a href=\"/pkg/go/parser/\"><code>go/parser</code></a>
 package has been reduced to the primary parse function
@@ -1001,6 +1111,17 @@ convenience functions <a href=\"/pkg/go/parser/#ParseDir\"><code>ParseDir</code></
 and <a href=\"/pkg/go/parser/#ParseExpr\"><code>ParseExpr</code></a>.\n </p>\n 
+<p>
+The <a href=\"/pkg/go/printer/\"><code>go/printer</code></a> package supports an additional
+configuration mode <a href=\"/pkg/go/printer/#Mode\"><code>SourcePos</code></a>;
+if set, the printer will emit <code>//line</code> comments such that the generated
+output contains the original source code position information. The new type
+<a href=\"/pkg/go/printer/#CommentedNode\"><code>CommentedNode</code></a> can be  
+used to provide comments associated with an arbitrary
+<a href=\"/pkg/go/ast/#Node\"><code>ast.Node</code></a> (until now only
+<a href=\"/pkg/go/ast/#File\"><code>ast.File</code></a> carried comment information).
+</p>
+
 <p>
 The type names of the <a href=\"/pkg/go/doc/\"><code>go/doc</code></a> package have been
 streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
@@ -1098,10 +1219,16 @@ The affected items are:\n </ul>\n \n <p>\n-Also, the <code>Request.RawURL</code> field has been removed; it was a\n+The <code>Request.RawURL</code> field has been removed; it was a\n historical artifact.\n </p>\n 
+<p>
+The <code>Handle</code> and <code>HandleFunc</code>
+functions, and the similarly-named methods of <code>ServeMux</code>,
+now panic if an attempt is made to register the same pattern twice.\n </p>\n 
 <p>\n <em>Updating</em>:\n Running <code>go fix</code> will update the few programs that are affected except for\n@@ -1138,9 +1265,7 @@ packages.\n The old <code>image.ColorImage</code> type is still in the <code>image</code>\n package but has been renamed\n <a href=\"/pkg/image/#Uniform\"><code>image.Uniform</code></a>,\n-while <code>image.Tiled</code>\n-has been renamed\n-<a href=\"/pkg/image/#Repeated\"><code>image.Repeated</code></a>.\n+while <code>image.Tiled</code> has been removed.\n </p>\n 
 <p>\n This table lists the renamings.\n@@ -1201,7 +1326,6 @@ This table lists the renamings.\n <td colspan=\"2\"><hr></td>\n </tr>\n <tr><td>image.ColorImage</td> <td>image.Uniform</td></tr>\n-<tr><td>image.Tiled</td> <td>image.Repeated</td></tr>\n </table>\n 
 <p>\n@@ -1226,6 +1350,18 @@ and\n Running <code>go fix</code> will update almost all code affected by the change.\n </p>\n 
+<h3 id=\"log_syslog\">The log/syslog package</h3>\n+\n+<p>\n+In Go 1, the <a href=\"/pkg/log/syslog/#NewLogger\"><code>syslog.NewLogger</code></a>     \n+function returns an error as well as a <code>log.Logger</code>.\n+</p>\n+\n+<p>\n+<em>Updating</em>:\n+What little code is affected will be caught by the compiler and must be updated by hand.\n+</p>\n+\n <h3 id=\"mime\">The mime package</h3>\n 
 <p>\n@@ -1272,7 +1408,27 @@ Code that uses the old methods will fail to compile and must be updated by hand.\n The semantic change makes it difficult for the fix tool to update automatically.\n </p>\n 
-<h3 id=\"os_fileinfo\">The os.FileInfo type</h3>\n+<h3 id=\"os\">The os package</h3>\n+\n+<p>The <code>Time</code> function has been removed; callers should use\n+the <a href=\"/pkg/time/#Time\"><code>Time</code></a> type from the\n+<code>time</code> package.</p>\n+\n+<p>The <code>Exec</code> function has been removed; callers should use\n+<code>Exec</code> from the <code>syscall</code> package, where available.</p>\n+\n+<p>The <code>ShellExpand</code> function has been renamed to <a\n+href=\"/pkg/os/#ExpandEnv\"><code>ExpandEnv</code></a>.</p>\n+\n+<p>The <a href=\"/pkg/os/#NewFile\"><code>NewFile</code></a> function\n+now takes a <code>uintptr</code> fd, instead of an <code>int</code>.\n+The <a href=\"/pkg/os/#File.Fd\"><code>Fd</code></a> method on files now\n+also returns a <code>uintptr</code>.</p>\n+\n+<p><em>Updating</em>: Code will fail to compile and must be updated\n+by hand.  </p>\n+\n+<h4 id=\"os_fileinfo\">The os.FileInfo type</h4>\n 
 <p>\n Go 1 redefines the <a href=\"/pkg/os/#FileInfo\"><code>os.FileInfo</code></a> type,\n@@ -1546,6 +1702,17 @@ Existing code is unaffected, although benchmarks that use <code>println</code>\n or <code>panic</code> should be updated to use the new methods.\n </p>\n 
+<h3 id=\"testing_script\">The testing/script package</h3>\n+\n+<p>\n+The testing/script package has been deleted. It was a dreg.\n+</p>\n+\n+<p>\n+<em>Updating</em>:\n+No code is likely to be affected.\n+</p>\n+\n <h3 id=\"url\">The url package</h3>

この差分は、Go 1リリースノートのHTMLコンテンツに、各パッケージの変更に関する新しいセクションを追加していることを示しています。具体的には、<h3> タグで始まる各パッケージのセクションが追加され、その中に変更内容、APIの更新、および既存コードの更新方法に関する説明が記述されています。

コアとなるコードの解説

このコミットは、Go言語のソースコード自体を変更するものではなく、Go 1のリリースノートというドキュメントを更新するものです。したがって、「コアとなるコード」とは、Go 1のAPI変更を説明するドキュメントのコンテンツそのものを指します。

差分を見ると、以下のパターンで変更が加えられていることがわかります。

  1. 新しいセクションの追加: 各パッケージの変更点について、<h3> タグで始まる新しいセクションが追加されています。例えば、<h3>The bufio package</h3> や <h3>The encoding/xml package</h3> などです。
  2. 変更内容の詳細な説明: 各セクション内では、Go 1で導入された具体的なAPI変更（関数名の変更、引数の変更、戻り値の変更、型の追加・削除など）が詳細に記述されています。
  3. 更新ガイドライン: 既存のGoコードをGo 1の新しいAPIに適合させるための「Updating」セクションが含まれています。多くの場合、「コンパイラが変更を検出し、手動で更新する必要がある」と記載されていますが、encoding/xml のように go fix ツールが一部の更新を自動で行うものの、フィールドタグのような特定の箇所は手動での注意が必要である旨も明記されています。
  4. リンクの追加: 関連するGoパッケージのドキュメントへのリンク (<a href="/pkg/...">) が多数追加されており、ユーザーが詳細なAPIドキュメントに簡単にアクセスできるようになっています。

このコミットは、Go 1のリリースを控える中で、開発者やユーザーが新しいGo 1環境にスムーズに移行できるよう、変更点を明確に伝えるための重要な情報提供の役割を担っています。特に、Mercurialのマージ問題に起因するドキュメントの不整合を修正することで、リリースノートの信頼性を高めています。

関連リンク

参考にした情報源リンク