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

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

このコミットは、Go言語の標準ライブラリ encoding/xml パッケージにおいて、XMLマーシャリング（Goの構造体からXMLへの変換）およびアンマーシャリング（XMLからGoの構造体への変換）時に特定のフィールドを無視するための「xml:"-"」タグに関するドキュメントを追加するものです。これは、元々関連する変更セット（CL）に含まれるべきでしたが、見落とされていたドキュメントの追記となります。

コミット

commit e3ab30bbc1f17d04fd2f5ce4ea767e0121c5c886
Author: Gustavo Niemeyer <gustavo@niemeyer.net>
Date:   Tue Jan 24 21:04:40 2012 -0200

    encoding/xml: add docs for ignoring tag
    
    That was supposed to be in the original CL, but missed
    the files.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5570052

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

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

元コミット内容

このコミットは、encoding/xml パッケージのドキュメントに、構造体のフィールドに xml:"-" タグを付与することで、そのフィールドがXMLのマーシャリングおよびアンマーシャリングの対象から除外されることを明記するものです。具体的には、marshal.go にマーシャリング時の除外に関する記述を、read.go にアンマーシャリング時の除外に関する記述を追加しています。

変更の背景

コミットメッセージによると、このドキュメントの追加は、元々関連する変更セット（Change List, CL）の一部として含まれるべきでしたが、ファイルが見落とされたためにこのコミットで別途追加されることになりました。これは、encoding/xml パッケージの機能として xml:"-" タグによるフィールドの無視が既に実装されていたものの、その挙動が公式ドキュメントに明記されていなかったため、ユーザーがこの機能を利用する際の明確な指針を提供することを目的としています。

前提知識の解説

Go言語の encoding/xml パッケージ

encoding/xml パッケージは、Go言語の標準ライブラリの一部であり、Goの構造体とXMLデータの間で相互変換（マーシャリングとアンマーシャリング）を行う機能を提供します。これにより、XML形式の設定ファイルやデータ交換、Webサービスとの連携などが容易になります。

Goの構造体タグ (Struct Tags)

Go言語では、構造体のフィールドに「タグ」と呼ばれる文字列を付与することができます。これらのタグは、リフレクション（実行時に型情報を検査・操作する機能）を通じてアクセスされ、特定のパッケージやライブラリがそのフィールドをどのように扱うべきかを指示するために使用されます。encoding/xml パッケージもこの構造体タグを利用して、XML要素名、属性、または特定の処理（例: omitempty、xml:"-"）を制御します。

タグの形式は通常 key:"value" のようになります。encoding/xml の場合、xml がキーとなり、その値によってXMLへのマッピング方法が定義されます。

xml:"-" タグの役割

xml:"-" タグは、encoding/xml パッケージにおいて非常に重要な役割を果たします。このタグが構造体のフィールドに付与されると、XMLマーシャラー（構造体をXMLに変換する処理）およびアンマーシャラー（XMLを構造体に変換する処理）に対して、そのフィールドを完全に無視するように指示します。

  • マーシャリング時: xml:"-" が付与されたフィールドは、生成されるXML出力には含まれません。これは、Goの構造体には存在するが、XML表現には含めたくない内部的なフィールドや一時的なデータがある場合に特に有用です。
  • アンマーシャリング時: xml:"-" が付与されたフィールドは、入力XMLデータから対応する要素や属性があっても、その値が構造体のフィールドにマッピングされることはありません。フィールドはGoのゼロ値（数値型なら0、文字列型なら""、ポインタ型ならnilなど）のままになります。これは、XMLデータには存在するが、Goの構造体では受け取りたくない、あるいは処理する必要がないデータがある場合に役立ちます。

このタグは、XMLスキーマとGoの構造体の間に完全な1対1のマッピングがない場合や、セキュリティ上の理由から特定の情報をXMLに含めたくない場合などに、柔軟なデータ変換を可能にします。

技術的詳細

このコミットは、encoding/xml パッケージの marshal.go と read.go のコメントセクションに、xml:"-" タグの挙動に関する説明を追加しています。

marshal.go への変更

marshal.go は、Goの構造体をXMLに変換する（マーシャリング）ロジックを主に含んでいます。追加された行は、Marshaler インターフェースの説明の下にある、構造体のフィールドがXML要素にどのようにマッピングされるかというセクションにあります。

変更前は、XMLNameフィールドが省略されることや、name,attr タグや ,attr タグの挙動が説明されていましたが、xml:"-" タグによるフィールドの省略については明記されていませんでした。

追加された行 // - a field with tag "-" is omitted. は、このギャップを埋め、xml:"-" タグが付与されたフィールドがXML出力から除外されることを明確に示しています。これにより、開発者は構造体内の特定のフィールドをXMLに含めないように制御できることが、公式ドキュメントで保証されることになります。

read.go への変更

read.go は、XMLデータをGoの構造体に変換する（アンマーシャリング）ロジックを主に含んでいます。追加された行は、XML要素がGoの構造体フィールドにどのようにマッピングされるかというセクションにあります。

同様に、変更前は、XMLName フィールドの扱い、name,attr や ,attr タグの挙動、そして ,any タグのフォールバックメカニズムが説明されていましたが、xml:"-" タグによるフィールドの無視については触れられていませんでした。

追加された行 // * A struct field with tag "-" is never unmarshalled into. は、xml:"-" タグが付与された構造体フィールドには、XMLからのデータがアンマーシャルされないことを明確に述べています。これにより、開発者はXMLデータの一部を意図的に無視し、構造体の対応するフィールドをGoのゼロ値のままに保つことができるという挙動が、ドキュメントによって確認できるようになります。

これらのドキュメントの追加は、encoding/xml パッケージの使いやすさと理解度を向上させ、開発者がXMLデータとGoの構造体をより効果的に扱うための重要な情報を提供します。

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

diff --git a/src/pkg/encoding/xml/marshal.go b/src/pkg/encoding/xml/marshal.go
index 77413cb573..4ef2a50eac 100644
--- a/src/pkg/encoding/xml/marshal.go
+++ b/src/pkg/encoding/xml/marshal.go
@@ -48,6 +48,7 @@ type Marshaler interface {
 // The XML element for a struct contains marshalled elements for each of the
 // exported fields of the struct, with these exceptions:
 //     - the XMLName field, described above, is omitted.
+//     - a field with tag "-" is omitted.
 //     - a field with tag "name,attr" becomes an attribute with
 //       the given name in the XML element.
 //     - a field with tag ",attr" becomes an attribute with the
diff --git a/src/pkg/encoding/xml/read.go b/src/pkg/encoding/xml/read.go
index 8b23fd58a0..871fe059cf 100644
--- a/src/pkg/encoding/xml/read.go
+++ b/src/pkg/encoding/xml/read.go
@@ -132,6 +132,8 @@ import (
 //      of the above rules and the struct has a field with tag ",any",
 //      unmarshal maps the sub-element to that struct field.
 //
+//   * A struct field with tag "-" is never unmarshalled into.
+//
 // Unmarshal maps an XML element to a string or []byte by saving the
 // concatenation of that element's character data in the string or
 // []byte. The saved []byte is never nil.

コアとなるコードの解説

上記の差分は、encoding/xml パッケージ内の2つのファイル、marshal.go と read.go に対する変更を示しています。これらの変更は、既存のコメントブロックに新しい行を追加する形で行われています。

src/pkg/encoding/xml/marshal.go の変更

marshal.go の変更は、Marshaler インターフェースのドキュメントブロック内、特に「構造体のエクスポートされた各フィールドがXML要素としてマーシャリングされる際の例外」を説明する箇所にあります。

  • + // - a field with tag "-" is omitted.

この行は、Goの構造体フィールドに xml:"-" というタグが付与されている場合、そのフィールドがXMLへのマーシャリング時に完全に省略されることを明記しています。これは、生成されるXML出力に特定のフィールドを含めたくない場合に、開発者がこのタグを使用できることを示唆しています。

src/pkg/encoding/xml/read.go の変更

read.go の変更は、XMLデータがGoの構造体フィールドにアンマーシャリングされる際のルールを説明するコメントブロック内にあります。

  • + // * A struct field with tag "-" is never unmarshalled into.

この行は、Goの構造体フィールドに xml:"-" というタグが付与されている場合、XMLからのアンマーシャリング時にそのフィールドにデータがマッピングされることはない、という挙動を明確にしています。つまり、XMLデータにそのフィールドに対応する要素や属性が存在しても、構造体内のそのフィールドはGoのゼロ値のまま維持されます。

これらの変更は、コードの動作自体を変更するものではなく、既存の機能（xml:"-" タグによるフィールドの無視）に関するドキュメントを補完し、開発者がこのパッケージをより正確に理解し、利用できるようにすることを目的としています。

関連リンク

参考にした情報源リンク