List of Struct [text.Baldanders.info]

Struct2pflag v0.2.0 をリリースした

2026-05-29T09:13:56+00:00

昨年 goark/struct2pflag の最初のリリースを行ったが，その後，骨折やら何やらでずうっと止まっていた。最近ようやくこれを使う機会があったが，いくつか機能が足りなかったので，それらを追加して v0.2.0 としてリリースした。

Release v0.2.0 · goark/struct2pflag

追加機能のひとつは環境変数をバインドする BindEnv() 関数である。こんな感じに使う。

type Env struct {
    TopN int           `env:"TOP_N" pflag:"top-n,n,number of top tags"`
    Wait time.Duration `env:"WAIT"  pflag:"wait,w,wait duration"`
}

func main() {
    env := Env{TopN: 10, Wait: time.Second}

    if err := struct2pflag.BindEnv(&env); err != nil {
        _ = fmt.Fprintln(os.Stderr, err)
        return
    }
    struct2pflag.BindDefault(&env)
    pflag.Parse()
}

本当は hymkor/struct2env を使いたかったのだが， string 型しかサポートしてないため泣く泣く自作した。コードを書いたのは AI だけど（笑）

もうひとつは Bind() および BindEnv() 関数で対応する型を増やしたこと。今のところ，対応状況は以下のようになっている。

Type	`Bind`	`BindEnv`
`bool`	✓	✓
`int`	✓	✓
`int8` / `int16` / `int32` / `int64`		✓
`uint`	✓	✓
`uint8` / `uint16` / `uint32` / `uint64`		✓
`float32`	✓	✓
`float64`	✓	✓
`string`	✓	✓
`time.Duration`	✓	✓

本当は []string もサポートしたかったが，キリがないので見送った。必要にかられれば対応する。 spf13/pflag がサポートしている型って物凄くあるので，全部カバーするのは面倒なのだ。いや，どうせコードを書くのは AI なんだけど。

参考図書

初めてのGo言語第2版 ―他言語プログラマーのためのイディオマティックGo実践ガイド: Jon Bodner (著), 武舎広幸 (翻訳); オライリー・ジャパン 2025-08-05 (Release 2025-08-05); 単行本（ソフトカバー）; 4814401191 (ASIN), 9784814401192 (EAN), 4814401191 (ISBN); 評価

[Comment] 第2版。 Generics の説明が大幅に改訂されたらしい。練習問題も追加されている。

reviewed by Spiegel on 2025-11-02 (powered by PA-APIv5)

Go言語 100Tips ありがちなミスを把握し、実装を最適化する impress top gearシリーズ: Teiva Harsanyi (著), 柴田芳樹 (著); インプレス 2023-08-18 (Release 2023-08-18); Kindle版; B0CFL1DK8Q (ASIN); 評価

[Comment] 版元で PDF 版を購入可能。事実上の Effective Go とも言える充実の内容。オリジナルは敢えてタイトルに “tips” という単語を入れるのを避けたのに邦題が「100 Tips」とかなっていて，原作者がお怒りとの噂（あくまで噂）

reviewed by Spiegel on 2023-08-18 (powered by PA-APIv5)

プログラミング言語Go (ADDISON-WESLEY PROFESSIONAL COMPUTING SERIES): Alan A.A. Donovan (著), Brian W. Kernighan (著), 柴田芳樹 (翻訳); 丸善出版 2016-06-20; 単行本（ソフトカバー）; 4621300253 (ASIN), 9784621300251 (EAN), 4621300253 (ISBN); 評価

[Comment] 著者のひとりは（あの「バイブル」とも呼ばれる）通称 “K&R” の K のほうである。この本は Go 言語の教科書と言ってもいいだろう。と思ったら絶版状態らしい（2025-01 現在）。復刊を望む！

reviewed by Spiegel on 2016-07-13 (powered by PA-APIv5)

hymkor/struct2flag から fork した goark/struct2pflag をリリースした

2025-11-23T09:33:12+00:00

以前 golang セクションで紹介した hymkor/struct2flag だが，これは標準の flag パッケージを使っている。他の類似の flag パッケージついては

オプション体系が GNU っぽくなってしまったり、"flag" の機能まで内包していて、そこまで要らないということで選定候補から外した

Goの構造体タグによるコマンドラインオプション・設定ファイル・環境変数の一元管理 - 標準愚痴出力より

とのことで，それはそれで妥当な選択だと思う。

ただ，私は GNU 拡張シンタックスに対応した spf13/pflag が使いたかったのよ。

というわけで，オリジナルの hymkor/struct2flag から fork して spf13/pflag を使うよう改造した goark/struct2pflag をリリースした¹。使い方は hymkor/struct2flag とほぼ同じ。以前書いた「struct2flag でコマンドライン解析」のコードを goark/struct2pflag を使って書き換えてみる。

package main

import (
	"fmt"
	"strings"

	"github.com/goark/struct2pflag"
	"github.com/spf13/pflag"
)

type Flags struct {
	N    bool   `pflag:"no-newline,n,omit trailing newline"`
	Sep  string `pflag:"sep,s,separator"`
	Strs []string
}

func NewFlags() *Flags {
	return &Flags{N: false, Sep: " ", Strs: []string{}}
}

func Echo(f *Flags) {
	fmt.Print(strings.Join(f.Strs, f.Sep))
	if !f.N {
		fmt.Println()
	}
}

func main() {
	f := NewFlags()
	struct2pflag.BindDefault(f)
	pflag.Parse()
	f.Strs = pflag.Args()

	Echo(f)
}

flag が spf13/pflag に hymkor/struct2flag が goark/struct2pflag に置き換わったほか，構造体タグのプレフィックスが flag: から pflag: に変わっている点に注目。ヘルプを表示させると

$ go run echo4a.go -h
Usage of /tmp/go-build2259633867/b001/exe/echo4a:
  -n, --no-newline   omit trailing newline
  -s, --sep string   separator (default " ")

てな感じに長いオプション名と一文字の短いオプション名が併記されているのが分かる。実際に動かしてみると

$ go run echo4a.go --sep / May the Force be with you
May/the/Force/be/with/you

$ go run echo4a.go -s / May the Force be with you
May/the/Force/be/with/you

と長いオプション名でも短いオプション名でも同じ動作になることが分かる。 spf13/pflag の挙動については拙文「標準 flag パッケージを pflag パッケージに置き換える」で簡単に紹介しているので，そちらも参考にどうぞ。

hymkor/struct2flag で使う構造体タグ flag: も受け入れるようにした（flag: と pflag: は混在可能）。

type Flags struct {
	N    bool   `flag:"n,omit trailing newline"`
	Sep  string `flag:"s,separator"`
	Strs []string
}

ただし，この場合は長いオプション名のみ定義されるため

$ go run echo4b.go -h
Usage of /tmp/go-build1365887832/b001/exe/echo4b:
      --n          omit trailing newline
      --s string   separator (default " ")

という感じに，あくまでも spf13/pflag のルールで構成されるのでご注意を。

一応 hymkor/struct2flag と同程度の機能は持たせている。今後は浮動小数点数や時間を指定できたらいいな，と思っている。他に spf13/pflag ではオプション値を格納する変数側を slice にすることで同じオプションを複数回指定できる機能もあるので，それもサポートしたいところ。まぁ，あくまでも私が使う際に必要に応じて拡張するということで。リクエスト等ありましたら PR いただけると助かります。

参考図書

初めてのGo言語第2版 ―他言語プログラマーのためのイディオマティックGo実践ガイド: Jon Bodner (著), 武舎広幸 (翻訳); オライリー・ジャパン 2025-08-05 (Release 2025-08-05); 単行本（ソフトカバー）; 4814401191 (ASIN), 9784814401192 (EAN), 4814401191 (ISBN); 評価

[Comment] 第2版。 Generics の説明が大幅に改訂されたらしい。練習問題も追加されている。

reviewed by Spiegel on 2025-11-02 (powered by PA-APIv5)

Go言語 100Tips ありがちなミスを把握し、実装を最適化する impress top gearシリーズ: Teiva Harsanyi (著), 柴田芳樹 (著); インプレス 2023-08-18 (Release 2023-08-18); Kindle版; B0CFL1DK8Q (ASIN); 評価

reviewed by Spiegel on 2023-08-18 (powered by PA-APIv5)

プログラミング言語Go (ADDISON-WESLEY PROFESSIONAL COMPUTING SERIES): Alan A.A. Donovan (著), Brian W. Kernighan (著), 柴田芳樹 (翻訳); 丸善出版 2016-06-20; 単行本（ソフトカバー）; 4621300253 (ASIN), 9784621300251 (EAN), 4621300253 (ISBN); 評価

reviewed by Spiegel on 2016-07-13 (powered by PA-APIv5)

最初は GitHub の fork 機能をそのまま使っていたが自己 pull request の際に，うっかりオリジナルの hymkor/struct2flag の方に PR しそうになったため fork 関係を切り離した。やり方は「GithubでForkしたリポジトリをFork元から切り離して管理する」を参考にした。ありがたや 🙇 ↩︎

XML データの Unmarshalling

2018-03-16T11:40:27+00:00

今回は XML の Unmarshalling について。つっても Unmarshalling 自体は encoding/xml パッケージを使って

stdata := &StructData{}
if err := xml.Unmarshal([]byte(xmldata), stdata); err != nil {
    fmt.Fprintln(os.Stderr, err)
    return
}

などとすればよい。問題は XML データを受け入れる構造体（上述のコードで言うなら StructData）をどう定義するかだ。

今回のお題となる XML データとして以下を考える。

<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:foaf="http://xmlns.com/foaf/0.1/"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:cc="http://web.resource.org/cc/"
>
  <foaf:Document rdf:about="https://text.baldanders.info/">
    <dc:title lang="ja">text.Baldanders.info</dc:title>
    <dc:creator>Spiegel</dc:creator>
    <dc:date>2018-03-16T20:40:27+09:00</dc:date>
    <cc:license rdf:resource="https://creativecommons.org/licenses/by-sa/4.0/"/>
  </foaf:Document>
</rdf:RDF>

この XML データの特徴は以下の通り。

要素名や属性名が名前空間（namespace）を含んでいる
要素の値として属性値と要素の内容（要素タグで囲まれているエリア）がある
時刻情報（RFC 3339 形式）を含んでいる

これを struct タグでどのように記述するかを次節から検討する。

名前空間について

たとえば名前空間を含まない

<creator>Spiegel</creator>

であれば struct タグは単純に

Creator string `xml:"creator"`

と記述できる。しかし実際には

<dc:creator>Spiegel</dc:creator>

と名前空間を含んでいるため， struct タグを厳密に記述するなら

Creator string `xml:"http://purl.org/dc/terms/ creator"`

とする必要がある。名前空間の指定は短縮名の dc ではなく URI http://purl.org/dc/terms/ を記述する。なお（名前空間を除いた）要素名や属性の混濁がないのであれば

Creator string `xml:"creator"`

のままでも問題なく parse できる。この場合，名前空間は無視されるようだ。

値の取得

<dc:title> の値には属性値と要素の内容の複数が含まれている。

<dc:title lang="ja">text.Baldanders.info</dc:title>

これらの値を全て取得するなら struct タグの記述は以下のようになる。

Title struct {
    Language string `xml:"lang,attr"`
    Name     string `xml:",chardata"`
} `xml:"http://purl.org/dc/terms/ title"`

ちなみに要素の内容が <![CDATA[ ... ]]> で囲まれるデータであれば chardata ではなく cdata を指定するとよい。

時刻情報の処理

xml.Unmarshal() 関数には時刻情報を time.Time 型に変換するロジックは用意されていない（基本型ではないので当然だが）。したがって文字列から time.Time 型に変換するロジックを自前で組み込む必要がある。

今回はフォーマットが RFC 3339 であることを前提に以下のようにした。

type Time struct {
    time.Time
}

func (t *Time) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
    var v string
    if err := d.DecodeElement(&v, &start); err != nil {
        return err
    }
    tm, err := time.Parse(time.RFC3339, v)
    if err != nil {
        return err
    }
    *t = Time{tm}
    return nil
}

独自定義の Time 型が time.Time 型のラッパー・クラスになっている点に注目。この Time 型に UnmarshalXML() 関数を定義している。これで構造体の要素は以下のように記述できる。

Date Time `xml:"http://purl.org/dc/terms/ date"`

xml.Unmarshal() 関数は Time 型を解析するために Time.UnmarshalXML() 関数を呼び出すわけだ。 encoding/xml パッケージでは UnmarshalXML() 関数は以下のように定義されている。

type Unmarshaler interface {
    UnmarshalXML(d *Decoder, start StartElement) error
}

xml.Unmarshaler インタフェースを持つ型であれば XML Unmarshalling 可能である¹。

サンプルコード

以上を踏まえてお題の XML データの Unmarshalling コードは以下のようになる。

package main

import (
    "encoding/xml"
    "fmt"
    "os"
    "time"
)

var xmldata = `
<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:foaf="http://xmlns.com/foaf/0.1/"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:cc="http://web.resource.org/cc/"
>
  <foaf:Document rdf:about="https://text.baldanders.info/">
    <dc:title lang="ja">text.Baldanders.info</dc:title>
    <dc:creator>Spiegel</dc:creator>
    <dc:date>2018-03-16T20:40:27+09:00</dc:date>
    <cc:license rdf:resource="https://creativecommons.org/licenses/by-sa/4.0/"/>
  </foaf:Document>
</rdf:RDF>
`

type Time struct {
    time.Time
}

func (t *Time) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
    var v string
    if err := d.DecodeElement(&v, &start); err != nil {
        return err
    }
    tm, err := time.Parse(time.RFC3339, v)
    if err != nil {
        return err
    }
    *t = Time{tm}
    return nil
}

type RDF struct {
    XMLName  xml.Name `xml:"http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF"`
    Document struct {
        URI   string `xml:"http://www.w3.org/1999/02/22-rdf-syntax-ns# about,attr"`
        Title struct {
            Language string `xml:"lang,attr,omitempty"`
            Name     string `xml:",chardata"`
        } `xml:"http://purl.org/dc/terms/ title"`
        Creator string `xml:"http://purl.org/dc/terms/ creator"`
        Date    Time   `xml:"http://purl.org/dc/terms/ date"`
        License struct {
            URI string `xml:"http://www.w3.org/1999/02/22-rdf-syntax-ns# resource,attr"`
        } `xml:"http://web.resource.org/cc/ license"`
    } `xml:"http://xmlns.com/foaf/0.1/ Document"`
}

func main() {
    rdf := &RDF{}
    if err := xml.Unmarshal([]byte(xmldata), rdf); err != nil {
        fmt.Fprintln(os.Stderr, err)
        return
    }
}

自前で解析するより遥かにマシだが，面倒くさいことには変わりない。 XML とか○ねばいいのに（笑）

たとえば <dc:title> 要素の内容だけ取れればええんじゃあ！という場合は

type RDF struct {
    Title string `xml:"Document>title"`
}

と要素を > で繋ぐ記述も可能。ただこの記述では名前空間をうまく指定できなかった。うーん。

XML の Marshalling については機会があれば。つか，構造化されたデータを XML Marshalling するのは不毛な気がする。フォーマットが決まってるのであればテンプレートを使ったほうが早いんじゃないかなぁ…

【おまけ】 xml.Unmarshal() 関数の中身

余談だが xml.Unmarshal() 関数の中身は

func Unmarshal(data []byte, v interface{}) error {
	return NewDecoder(bytes.NewReader(data)).Decode(v)
}

となっている。

したがって入力がバイトデータであれば，わざわざ自前で Reader を作って xml.NewDecoder() を呼び出す必要はない。逆に入力が Reader であるなら xml.NewDecoder() で xml.Decoder を生成するほうがいいかもしれない。状況で使い分けよう。

ブックマーク

Struct タグについて

参考図書

プログラミング言語Go (ADDISON-WESLEY PROFESSIONAL COMPUTING SERIES): Alan A.A. Donovan (著), Brian W. Kernighan (著), 柴田芳樹 (翻訳); 丸善出版 2016-06-20; 単行本（ソフトカバー）; 4621300253 (ASIN), 9784621300251 (EAN), 4621300253 (ISBN); 評価

reviewed by Spiegel on 2016-07-13 (powered by PA-APIv5)

セマンティック HTML/XHTML: 神崎正英 (著); 毎日コミュニケーションズ 2009-05-28; 単行本（ソフトカバー）; 483993195X (ASIN), 9784839931957 (EAN), 483993195X (ISBN); 評価

[Comment] 残念ながら紙の本は実質的に絶版なんですよねぇ。是非デジタル化を希望します。

reviewed by Spiegel on 2014-08-17 (powered by PA-APIv5)

もちろん Marshalling 用の xml.Marshaler インタフェースも存在する。 ↩︎

Struct タグについて

2016-02-04T15:11:53+00:00

たとえば struct で構造化されている情報を特定のファイルやデータベースに出力したり，逆にファイルやデータベースの情報を struct に流し込みたい場合に struct の各フィールドに目印になる情報があると便利である。この目印として機能するのが struct タグである¹。

struct タグは以下のように記述する。

By convention, tag strings are a concatenation of optionally space-separated key:"value" pairs. Each key is a non-empty string consisting of non-control characters other than space (U+0020 ' '), quote (U+0022 '"'), and colon (U+003A ':'). Each value is quoted using U+0022 '"' characters and Go string literal syntax.

via reflect - The Go Programming Language

type Server struct {
    Host      string `elem:"host"`
    IPAddress string `elem:"ip_address"`
    Port      int    `elem:"port"`
    Note      string `elem:"note"`
}

このタグ情報を取得するには reflect パッケージを使う。たとえばこんな感じ。

package main

import (
    "fmt"
    "reflect"
)

type Server struct {
    Host      string `elem:"host"`
    IPAddress string `elem:"ip_address"`
    Port      int    `elem:"port"`
    Note      string `elem:"note"`
}

func main() {
    s := Server{}
    t := reflect.TypeOf(s)
    for i := 0; i < t.NumField(); i++ {
        field := t.Field(i)
        fmt.Printf("Name=%s , tag(elem)=%s\n", field.Name, field.Tag.Get("elem"))
    }
}

これを実行するとこうなる。

Name=Host , tag(elem)=host
Name=IPAddress , tag(elem)=ip_address
Name=Port , tag(elem)=port
Name=Note , tag(elem)=note

実際には reflect を直接使う局面は少なく，既にあるパッケージを利用することが多い。たとえば struct による構造化データを JSON 形式に出力する encoding/json パッケージがある。

package main

import (
    "encoding/json"
    "fmt"
)

type Server struct {
    Host      string `json:"host"`
    IPAddress string `json:"ip_address"`
    Port      int    `json:"port"`
    Note      string `json:"note"`
}

func main() {
    s := Server{Host: "localhost", IPAddress: "127.0.0.1", Port: 8080, Note: "Web Application"}
    j, err := json.MarshalIndent(s, "", "  ")
    if err != nil {
        return
    }
    fmt.Println(string(j))
}

これを実行するとこうなる。

{
  "host": "localhost",
  "ip_address": "127.0.0.1",
  "port": 8080,
  "note": "Web Application"
}

Server の内容が JSON 形式で出力されているのが分かるだろう。 JSON の要素名がタグで指定した名前になっていることを確認してほしい。

反対もやってみよう。

package main

import (
    "encoding/json"
    "fmt"
)

type Server struct {
    Host      string `json:"host"`
    IPAddress string `json:"ip_address"`
    Port      int    `json:"port"`
    Note      string `json:"note"`
}

func main() {
    svr := []byte(`{
  "host": "localhost",
  "ip_address": "127.0.0.1",
  "port": 8080,
  "note": "Web Application"
}`)
    var s Server
    if err := json.Unmarshal(svr, &s); err != nil {
        return
    }
    fmt.Println(s)
}

実行結果はこうなる。

{localhost 127.0.0.1 8080 Web Application}

きれいに struct に値が入っているのが分かると思う。

ちなみにタグの書式は key:"value" だが，間違って記述しても単に無視されるだけでコンパイル時も実行時もエラーにならないので注意が必要である。なおタグ書式の文法ミスについては，静的検査ツールの vet でチェックできる。

タグは複数列挙することができる。たとえばサンプルの構造体を TOML にも対応させたいなら

type Server struct {
    Host      string `json:"host" toml:"host"`
    IPAddress string `json:"ip_address" toml:"ip_address"`
    Port      int    `json:"port" toml:"port"`
    Note      string `json:"note" toml:"note"`
}

などとする（デリミタは空白文字）。じゃあ，先ほどと同じようにして TOML で出力してみる。 TOML を扱うには github.com/BurntSushi/toml パッケージを使うとよい。

package main

import (
    "bytes"
    "fmt"

    "github.com/BurntSushi/toml"
)

type Server struct {
    Host      string `json:"host" toml:"host"`
    IPAddress string `json:"ip_address" toml:"ip_address"`
    Port      int    `json:"port" toml:"port"`
    Note      string `json:"note" toml:"note,omitempty"`
}

func main() {
    s := Server{Host: "localhost", IPAddress: "127.0.0.1", Port: 8080, Note: ""}
    t := new(bytes.Buffer)
    if err := toml.NewEncoder(t).Encode(s); err != nil {
        return
    }
    fmt.Println(t.String())
}

実行結果は以下の通り。

host = "localhost"
ip_address = "127.0.0.1"
port = 8080

omitempty オプションはフィールドが空（nil または空文字列）の場合に出力を省略できる²。このオプションは encoding/json パッケージでも使える。

ついでに反対もやってみよう。

package main

import (
    "fmt"

    "github.com/BurntSushi/toml"
)

type Server struct {
    Host      string `json:"host" toml:"host"`
    IPAddress string `json:"ip_address" toml:"ip_address"`
    Port      int    `json:"port" toml:"port"`
    Note      string `json:"note" toml:"note,omitempty"`
}

func main() {
    svr := `
host = "localhost"
ip_address = "127.0.0.1"
port = 8080
note = "Web Application"
`
    var s Server
    if _, err := toml.Decode(svr, &s); err != nil {
        return
    }
    fmt.Println(s)
}

結果は以下の通り。

{localhost 127.0.0.1 8080 Web Application}

このように struct で正規化できる情報であれば，タグ機能を使うことでアプリケーション外部とのやり取りがだいぶ楽になる。

ブックマーク

Go 言語に関するブックマーク集はこちら。

「アノテーション（annotation）」と呼ぶ人もいる。たぶん Java の annotation 機能を意識しているんだろう。 ↩︎
数値の場合は omitzero オプションを付けると 0 のときに出力を省略できる。ただし BurntSushi/toml パッケージでは Decode() がうまく動かないらしい。実は omitempty オプションも Decode() 時の挙動が怪しいんだよなぁ。 TOML パーサの別実装としては naoina/toml というのもある。これは最新の TOML 仕様に追随しているようだが omitzero オプションには対応していない。 ↩︎