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

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

このコミットは、Go 1リリースにおけるencoding/xmlパッケージの変更点に関するドキュメントの更新を目的としています。具体的には、doc/go1.htmlとdoc/go1.tmplファイルに、encoding/xmlパッケージのAPI変更、特に型名の変更、新しいエンコーダ/デコーダの導入、およびフィールドタグの書式変更について追記されています。また、net/urlパッケージに関する既存のドキュメント内のリンク修正も含まれています。

コミット

commit 7b5048570a32f477cd946298a643ae89c7a01f3c
Author: Gustavo Niemeyer <gustavo@niemeyer.net>
Date:   Thu Jan 26 00:59:50 2012 -0200

    doc/go1: add encoding/xml changes
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/5569067

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

https://github.com/golang/go/commit/7b5048570a32f477cd946298a643ae89c7a01f3c

元コミット内容

doc/go1: add encoding/xml changes

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

変更の背景

このコミットの背景には、Go言語の最初の安定版リリースであるGo 1の準備があります。Go 1では、標準ライブラリのAPI安定化と改善が広範に行われました。encoding/xmlパッケージもその対象の一つであり、他のマーシャリング（構造体とデータ形式間の変換）パッケージ（例: encoding/gobやencoding/json）との設計の一貫性を高めるための変更が加えられました。

これらの変更は、既存のコードベースに影響を与える可能性があるため、Go 1のリリースノートおよび移行ガイドとなるdoc/go1.html（およびそのテンプレートdoc/go1.tmpl）に詳細を記述する必要がありました。ユーザーがGo 1へスムーズに移行できるよう、APIの変更点、特にgofixツールで自動的に更新できない部分（例: フィールドタグの変更）について明確に説明することが求められました。

前提知識の解説

Go言語のencodingパッケージ群

Go言語の標準ライブラリには、様々なデータ形式とGoのデータ構造（主に構造体）との間でデータを変換するためのencodingパッケージ群が用意されています。これらは、Goの構造体を特定の形式（JSON、XML、Gobなど）に変換する「マーシャリング（Marshal）」と、その逆の「アンマーシャリング（Unmarshal）」の機能を提供します。

  • encoding/json: JSON形式との間でGoの構造体を変換します。Web APIなどで広く利用されます。
  • encoding/gob: Go独自のバイナリ形式であるGob形式との間でGoの構造体を変換します。Goプログラム間でのデータ転送や永続化に適しています。
  • encoding/xml: XML形式との間でGoの構造体を変換します。XMLは設定ファイルやデータ交換フォーマットとして利用されることがあります。

これらのパッケージは、Goの構造体のフィールドに「タグ」を付与することで、マーシャリング/アンマーシャリング時の挙動を制御できます。例えば、json:"field_name"のように指定することで、JSON形式でのフィールド名を変更したり、特定のフィールドを無視したりできます。

Go 1リリース

Go 1は、2012年3月28日にリリースされたGo言語の最初の安定版です。このリリースでは、言語仕様、標準ライブラリ、およびツールチェインが安定化され、将来のバージョンとの互換性が保証されました。Go 1以降、既存のGo 1プログラムが新しいGoバージョンで動作しなくなるような、互換性のない変更は原則として行われないことになりました。このコミットは、Go 1リリースに向けたドキュメント整備の一環です。

gofixツール

gofixは、Go言語のツールチェインに含まれるコマンドラインツールです。Go言語のバージョンアップに伴うAPIの変更や非推奨化に対応するため、古いGoコードを新しいAPIに自動的に書き換える機能を提供します。これにより、開発者は手動でのコード修正の手間を大幅に削減できます。しかし、すべての変更を自動的に修正できるわけではなく、特にセマンティックな変更や複雑なロジックの変更は手動での対応が必要です。

技術的詳細

このコミットで追加されたencoding/xmlパッケージに関するドキュメントの変更点は、以下の技術的な詳細を含んでいます。

  1. Parser型のDecoder型へのリネームとDecodeメソッドの導入:

    • Go 1以前のencoding/xmlパッケージには、XMLをパースするためのParser型が存在しました。Go 1では、この型がDecoderにリネームされ、より汎用的なDecodeメソッドが導入されました。これは、encoding/gobやencoding/jsonといった他のencodingパッケージにおけるDecoderの命名規則と一貫性を持たせるための変更です。
    • Decoder型は、io.ReaderからXMLデータを読み込み、Goの構造体にデコードする役割を担います。

  2. Encoder型の導入:

    • XMLデータをGoの構造体からエンコードするためのEncoder型が新たに導入されました。これにより、ストリーム（io.Writer）へのXMLデータの書き出しがより効率的かつ構造的に行えるようになりました。
    • Encoder型は、io.WriterにXMLデータを書き出す役割を担います。

  3. MarshalおよびUnmarshal関数の変更:

    • Go 1では、トップレベルのMarshalおよびUnmarshal関数が、ストリームではなく[]byte（バイトスライス）を直接扱うように変更されました。これにより、メモリ上にXMLデータを完全に読み込むか、または完全に書き出す場合にこれらの関数を使用するようになりました。
    • ストリームを扱う場合は、新しく導入されたEncoderおよびDecoder型を使用することが推奨されます。

  4. フィールドタグの書式変更とマッチング規則の厳格化:

    • Goの構造体フィールドに付与するXMLタグの書式が、encoding/jsonパッケージのタグ書式に近づけられました。新しい書式は xml:"name,flag" の形式です。
    • 以前は xml:"attr" のように指定していた属性のタグは、Go 1からは xml:",attr" のように、要素名が空であることを明示する形式になりました。単に xml:"attr" と書いた場合、それは要素名が "attr" であることを意味するようになり、以前とは異なる意味を持つことになります。
    • フィールドタグ、フィールド名、XML属性名、要素名とのマッチングが大文字・小文字を区別するようになりました。これにより、より厳密なXMLのパースと生成が可能になります。
    • XMLNameフィールドタグが存在する場合、その値はマーシャリングされるXML要素の名前と一致する必要があります。

  5. gofixによる自動更新の限界:

    • gofixツールは、encoding/xmlパッケージの多くの使用箇所を自動的に更新できますが、Unmarshal関数の一部の呼び出しや、特にフィールドタグの変更については自動更新ができません。
    • これは、フィールドタグの変更がセマンティックな意味合いを持つため、gofixが自動的に正しい意図を判断できないためです。したがって、開発者は手動でフィールドタグを修正する必要があることが強調されています。

これらの変更は、encoding/xmlパッケージのAPIをより一貫性のあるものにし、他のencodingパッケージとの親和性を高めることを目的としていました。

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

このコミットは、Go 1のドキュメントファイルであるdoc/go1.htmlとdoc/go1.tmplに対する変更です。以下に、encoding/xmlパッケージに関する主要な追加箇所を抜粋します。

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1520,6 +1520,50 @@ Code that uses the old fields will fail to compile and must be updated by hand.
 The semantic changes make it difficult for gofix to update automatically.\n </p>\n \n+<h3 id=\"xml\">The xml package</h3>\n+\n+<p>\n+In Go 1, the <a href=\"/pkg/encoding/xml/\"><code>xml</code></a> package\n+has been brought closer in design to the other marshaling packages such\n+as <a href=\"/pkg/encoding/gob/\"><code>encoding/gob</code></a>.\n+</p>\n+\n+<p>\n+The old <code>Parser</code> type is renamed\n+<a href=\"/pkg/encoding/xml/#Decoder\"><code>Decoder</code></a> and has a new\n+<a href=\"/pkg/encoding/xml/#Decoder.Decode\"><code>Decode</code></a> method. An\n+<a href=\"/pkg/encoding/xml/#Encoder\"><code>Encoder</code></a> type was also\n+introduced.\n+</p>\n+\n+<p>\n+The functions <a href=\"/pkg/encoding/xml/#Marshal\"><code>Marshal</code></a>\n+and <a href=\"/pkg/encoding/xml/#Unmarshal\"><code>Unmarshal</code></a>\n+work with <code>[]byte</code> values now. To work with streams,\n+use the new <a href=\"/pkg/encoding/xml/#Encoder\"><code>Encoder</code></a>\n+and <a href=\"/pkg/encoding/xml/#Decoder\"><code>Decoder</code></a> types.\n+</p>\n+\n+<p>\n+When marshaling or unmarshaling values, the format of supported flags in\n+field tags has changed to be closer to the\n+<a href=\"/pkg/encoding/json\"><code>json</code></a> package\n+(<code>`xml:\"name,flag\"`</code>). The matching done between field tags, field\n+names, and the XML attribute and element names is now case-sensitive.\n+The <code>XMLName</code> field tag, if present, must also match the name\n+of the XML element being marshaled.\n+</p>\n+\n+<p>\n+<em>Updating</em>:\n+Gofix will update most uses of the package except for some calls to\n+<code>Unmarshal</code>. Special care must be taken with field tags,\n+since gofix will not update them and if not fixed by hand they will\n+misbehave silently in some cases. For example, the old\n+<code>\"attr\"</code> is now written <code>\",attr\"</code> while plain\n+<code>\"attr\"</code> remains valid but with a different meaning.\n+</p>\n+\n```

また、`net/url`パッケージに関する既存のドキュメント内のリンク修正も行われています。これは、`#URL`のようなフラグメント識別子の前に`/`を追加する修正です。

```diff
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1455,12 +1455,12 @@ or <code>panic</code> should be updated to use the new methods.\n <h3 id=\"url\">The url package</h3>\n \n <p>\n-In Go 1 several fields from the <a href=\"/pkg/net/url#URL\"><code>url.URL</code></a> type\n+In Go 1 several fields from the <a href=\"/pkg/net/url/#URL\"><code>url.URL</code></a> type\n were removed or replaced.\n </p>\n \n <p>\n-The <a href=\"/pkg/net/url#URL.String\"><code>String</code></a> method now\n+The <a href=\"/pkg/net/url/#URL.String\"><code>String</code></a> method now\n predictably rebuilds an encoded URL string using all of <code>URL</code>\'s\n fields as necessary. The resulting string will also no longer have\n passwords escaped.\n@@ -1473,9 +1473,9 @@ method may be used in its place.\n \n <p>\n The old <code>RawUserinfo</code> field is replaced by the <code>User</code>\n-field, of type <a href=\"/pkg/net/url#Userinfo\"><code>*net.Userinfo</code></a>.\n-Values of this type may be created using the new <a href=\"/pkg/net/url#User\"><code>net.User</code></a>\n-and <a href=\"/pkg/net/url#UserPassword\"><code>net.UserPassword</code></a>\n+field, of type <a href=\"/pkg/net/url/#Userinfo\"><code>*net.Userinfo</code></a>.\n+Values of this type may be created using the new <a href=\"/pkg/net/url/#User\"><code>net.User</code></a>\n+and <a href=\"/pkg/net/url/#UserPassword\"><code>net.UserPassword</code></a>\n functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code>\n functions are also gone.\n </p>\n@@ -1510,7 +1510,7 @@ path for such URLs. In Go 1, the cited URL parses as:\n </pre>\n \n <p>\n-A new <a href=\"/pkg/net/url#URL.RequestURI\"><code>RequestURI</code></a> method was\n+A new <a href=\"/pkg/net/url/#URL.RequestURI\"><code>RequestURI</code></a> method was\n added to <code>URL</code>.\n </p>\n \n```

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

このコミットは、Go 1のリリースノートの一部として、`encoding/xml`パッケージの重要な変更点をユーザーに伝えるためのHTMLドキュメント（およびそのテンプレート）を更新しています。

*   **`<h3>The xml package</h3>`**: `encoding/xml`パッケージに関する新しいセクションが追加されたことを示します。
*   **`has been brought closer in design to the other marshaling packages such as encoding/gob.`**: `encoding/xml`が`encoding/gob`などの他のマーシャリングパッケージと設計思想を近づけたことを説明しています。これはAPIの一貫性を高めるための重要な変更です。
*   **`The old Parser type is renamed Decoder and has a new Decode method. An Encoder type was also introduced.`**: 以前の`Parser`型が`Decoder`にリネームされ、新しい`Decode`メソッドが追加されたこと、そして`Encoder`型が新たに導入されたことを明記しています。これにより、ストリームベースのXML処理がより明確になります。
*   **`The functions Marshal and Unmarshal work with []byte values now. To work with streams, use the new Encoder and Decoder types.`**: トップレベルの`Marshal`と`Unmarshal`関数が`[]byte`を扱うようになり、ストリーム処理には`Encoder`と`Decoder`を使用すべきであることが説明されています。これは、APIの役割分担を明確にするための変更です。
*   **`When marshaling or unmarshaling values, the format of supported flags in field tags has changed to be closer to the json package (xml:"name,flag").`**: フィールドタグの書式が`json`パッケージに近づき、`xml:"name,flag"`の形式になったことを示しています。これは、Goのタグ付け規則全体の一貫性を高めるための変更です。
*   **`The matching done between field tags, field names, and the XML attribute and element names is now case-sensitive.`**: XML要素名や属性名とのマッチングが大文字・小文字を区別するようになったことを強調しています。これにより、XMLの仕様により厳密に準拠するようになります。
*   **`The XMLName field tag, if present, must also match the name of the XML element being marshaled.`**: `XMLName`タグの要件が追加されたことを示しています。
*   **`Gofix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, since gofix will not update them and if not fixed by hand they will misbehave silently in some cases.`**: `gofix`ツールによる自動更新の限界について説明しています。特にフィールドタグは手動での修正が必要であり、そうしないとサイレントに誤動作する可能性があるという重要な警告が含まれています。
*   **`For example, the old "attr" is now written ",attr" while plain "attr" remains valid but with a different meaning.`**: フィールドタグの具体的な変更例として、属性を示す`"attr"`が`",attr"`に変わったことを示し、単なる`"attr"`が異なる意味を持つようになったことを説明しています。これは、ユーザーが最も混乱しやすい点の一つであり、明確な例示が重要です。

`net/url`に関する変更は、既存のドキュメント内のリンクが正しく機能するように、URLのフラグメント識別子（`#`）の前に`/`を追加する修正です。これは、ドキュメントの正確性を保つための軽微な修正です。

全体として、このコミットはGo 1への移行を支援するための重要なドキュメント更新であり、特に`encoding/xml`パッケージの変更点について詳細かつ具体的な情報を提供することで、開発者の移行作業を円滑にすることを目的としています。

## 関連リンク

*   Go 1 Release Notes: [https://go.dev/doc/go1](https://go.dev/doc/go1) (このコミットが更新しているドキュメント自体)
*   Go `encoding/xml` package documentation: [https://pkg.go.dev/encoding/xml](https://pkg.go.dev/encoding/xml)
*   Go `encoding/json` package documentation: [https://pkg.go.dev/encoding/json](https://pkg.go.dev/encoding/json)
*   Go `encoding/gob` package documentation: [https://pkg.go.dev/encoding/gob](https://pkg.go.dev/encoding/gob)
*   Go `gofix` tool documentation (Go 1.0.x): [https://go.dev/doc/go1.0.html#gofix](https://go.dev/doc/go1.0.html#gofix) (Go 1.0のリリースノート内の`gofix`に関する記述)

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

*   コミット情報: `/home/orange/Project/comemo/commit_data/11410.txt`
*   Go 1 Release Notes: [https://go.dev/doc/go1](https://go.dev/doc/go1)
*   Go `encoding/xml` package documentation: [https://pkg.go.dev/encoding/xml](https://pkg.go.dev/encoding/xml)
*   Go `gofix` tool: [https://go.dev/cmd/gofix/](https://go.dev/cmd/gofix/) (現在の`gofix`のドキュメント)
*   Go 1.0 Release Notes (for historical context on `gofix`): [https://go.dev/doc/go1.0.html](https://go.dev/doc/go1.0.html)
*   Go `encoding/json` package documentation: [https://pkg.go.dev/encoding/json](https://pkg.go.dev/encoding/json)
*   Go `encoding/gob` package documentation: [https://pkg.go.dev/encoding/gob](https://pkg.go.dev/encoding/gob)
*   Go `net/url` package documentation: [https://pkg.go.dev/net/url](https://pkg.go.dev/net/url)
*   Google Search (for general context on Go 1 and `encoding/xml` changes).