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

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

このコミットは、Go 1リリースに向けたドキュメント更新の一部であり、特にdoc/go1.htmlとdoc/go1.tmplファイルに、Go 1における主要なパッケージの変更点に関する記述を追加しています。具体的には、htmlパッケージの導入、httpパッケージのリファクタリング、およびos.FileInfo型の変更について詳細な説明が加えられています。これらの変更は、Go言語の安定版リリースに向けてAPIの整理と改善を行うことを目的としています。

コミット

commit f76bd4fe0f55b753481e5d20b52155090a22ab42
Author: Rob Pike <r@golang.org>
Date:   Mon Dec 12 19:25:25 2011 -0800

    doc/go1: more package updates
    Everything there (as first draft) except the time package.
    
    R=golang-dev, adg, bradfitz
    CC=golang-dev
    https://golang.org/cl/5487052

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

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

元コミット内容

doc/go1: more package updates Everything there (as first draft) except the time package.

このコミットは、Go 1リリースに向けたドキュメントdoc/go1.htmlおよびdoc/go1.tmplに、いくつかのパッケージに関する更新情報を追加するものです。特にtimeパッケージ以外の主要なパッケージの変更点が、ドラフトとして記述されています。

変更の背景

Go言語は、2012年3月に初の安定版リリースであるGo 1を迎えました。Go 1の目標の一つは、将来のバージョンとの互換性を保証し、APIの安定性を提供することでした。このコミットは、Go 1リリースに向けて、既存のパッケージAPIの整理、新しい機能の導入、そしてそれらの変更がユーザーコードに与える影響を明確にするためのドキュメント整備の一環として行われました。

特に、httpパッケージのように頻繁に使用されるパッケージでは、利用頻度の低いユーティリティ関数を分離することで、コアAPIをよりシンプルに保つ必要がありました。また、os.FileInfoのように、より汎用的なインターフェースベースの設計に移行することで、異なるOS間での互換性を高めつつ、システム固有の詳細を抽象化する狙いがありました。htmlパッケージの導入は、Web開発におけるHTML5の重要性を鑑み、標準ライブラリとして堅牢なHTMLパーサーを提供するためのものでした。

これらの変更は、Go 1の互換性保証の原則に基づき、既存のコードベースへの影響を最小限に抑えつつ、必要に応じてgofixツールによる自動更新をサポートする形で進められました。

前提知識の解説

このコミットを理解するためには、以下のGo言語の基本的な概念とツールの知識が役立ちます。

  • Go言語のパッケージシステム: Go言語は、コードをパッケージに分割して管理します。標準ライブラリには、net/http、os、htmlなどの多くの組み込みパッケージが含まれています。
  • インターフェース (Interfaces): Goのインターフェースは、メソッドのシグネチャの集合を定義します。型がインターフェースのすべてのメソッドを実装していれば、そのインターフェースを満たすと見なされます。これにより、ポリモーフィズムを実現し、柔軟な設計が可能になります。
  • gofixツール: gofixは、Go言語の古いコードを新しいAPIに自動的に更新するためのコマンドラインツールです。Go言語のバージョンアップに伴うAPI変更の際に、開発者の移行コストを軽減するために提供されました。
  • HTML5パーサー: HTML5はWebコンテンツの標準マークアップ言語です。HTML5パーサーは、HTMLドキュメントを解析し、その構造をプログラムが扱える形式（通常はDOMツリー）に変換するソフトウェアです。
  • HTTPプロトコル: Hypertext Transfer Protocol (HTTP) は、Web上でデータを交換するためのプロトコルです。Goのnet/httpパッケージは、HTTPクライアントとサーバーの実装を提供します。
  • ファイル情報 (File Information): オペレーティングシステムは、ファイル名、サイズ、パーミッション、更新日時などのファイルに関するメタデータを提供します。Goのosパッケージは、これらのファイル情報にアクセスするための機能を提供します。
  • システムコール (System Calls): オペレーティングシステムのカーネルが提供するサービスをプログラムが利用するためのインターフェースです。ファイルシステムへのアクセスやプロセス管理など、低レベルな操作に用いられます。

技術的詳細

このコミットで追加されたドキュメントは、Go 1における以下の主要な変更点を説明しています。

  1. htmlパッケージの導入:

    • Go 1で新たに導入されたhtmlパッケージは、HTML5のフルパーサーを提供します。これにより、Go言語でHTMLドキュメントの解析、操作、生成が容易になります。
    • このパッケージは新規追加であるため、既存のコードの更新は不要です。

  2. httpパッケージのリファクタリング:

    • net/httpパッケージは、Go 1でリファクタリングされ、一部のユーティリティ関数がnet/httputilサブディレクトリに移動されました。これは、HTTPクライアントが稀にしか必要としない機能を分離し、net/httpパッケージのコアAPIをより簡潔に保つためです。
    • 移動された主な項目には、ClientConn, DumpRequest, DumpRequestOut, DumpResponse, NewChunkedReader, NewChunkedWriter, NewClientConn, NewProxyClientConn, NewServerConn, NewSingleHostReverseProxy, ReverseProxy, ServerConnなどがあります。
    • また、Request.RawURLフィールドが削除されました。これは歴史的な遺物であり、Go 1では不要と判断されました。
    • 更新について: gofixツールは、影響を受ける一部のプログラムを自動的に更新しますが、RawURLの使用箇所は手動で修正する必要があります。

  3. os.FileInfo型の変更:

    • Go 1では、os.FileInfo型がstructからinterfaceに変更されました。これにより、ファイル情報の表現がより柔軟になり、異なるOS固有のファイルシステム詳細を抽象化できるようになりました。
    • 新しいos.FileInfoインターフェースは以下のメソッドを定義します: 
      type FileInfo interface {
    Name() string       // base name of the file
    Size() int64        // length in bytes
    Mode() FileMode     // file mode bits
    ModTime() time.Time // modification time
    IsDir() bool        // abbreviation for Mode().IsDir()
}
    • ファイルモード情報は、新たに導入されたos.FileMode型に移動されました。os.FileModeは、IsDir、Perm、Stringなどのメソッドを持つシンプルな整数型です。
    • システム固有のファイルモードやi-numberなどの詳細は、FileInfoインターフェースから完全に削除されました。代わりに、各オペレーティングシステムのosパッケージがFileInfoインターフェースの実装（例: *os.FileStat）を提供し、その中にSysフィールドが含まれます。このSysフィールドは、システム固有のファイルメタデータの表現を格納します。
    • 例えば、Unixシステムでファイルのi-numberを取得するには、os.FileInfoを*os.FileStatに型アサートし、さらにそのSysフィールドを*syscall.Stat_tに型アサートする必要があります。 
      fi, err := os.Stat("hello.go")
if err != nil {
    log.Fatal(err)
}
// Make sure it's an implementation known to package os.
fileStat, ok := fi.(*os.FileStat)
if !ok {
    log.Fatal("hello.go: not an os File")
}
// Now check that it's a Unix file.
unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
if !ok {
    log.Fatal("hello.go: not a Unix file")
}
fmt.Printf("file i-number: %d\n", unixStat.Ino)
    • ほとんどのFileInfoの使用箇所では、標準インターフェースのメソッドのみが必要とされます。
    • 更新について: gofixツールは、古いos.FileInfoおよびos.FileMode APIを使用しているコードを自動的に更新します。しかし、システム固有のファイル詳細を必要とするコードは、手動で更新する必要があります。

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

このコミットは、Go言語のソースコード自体ではなく、Go 1リリースに関するドキュメントファイルであるdoc/go1.htmlとdoc/go1.tmplに変更を加えています。

具体的には、以下のセクションが追加または更新されています。

  • doc/go1.html および doc/go1.tmpl の両ファイルに、以下のHTMLコンテンツが追加されています。

    • htmlパッケージに関するセクション:

      <h3 id="html">The html package</h3>
<p>
The <a href="/pkg/html/"><code>html</code></a> package in Go 1 provides
a full parser for HTML5.
</p>
<p>
<em>Updating</em>:
Since the package's functionality is new, no updating is necessary.
</p>

    • httpパッケージに関するセクション:

      <h3 id="http">The http package</h3>
<p>
In Go 1 the <a href="/pkg/http/"><code>http</code></a> package is refactored,
putting some of the utilities into a
<a href="/pkg/httputil/"><code>httputil</code></a> subdirectory.
These pieces are only rarely needed by HTTP clients.
The affected items are:
</p>
<ul>
<li>ClientConn</li>
<li>DumpRequest</li>
<li>DumpRequest</li>
<li>DumpRequestOut</li>
<li>DumpResponse</li>
<li>NewChunkedReader</li>
<li>NewChunkedWriter</li>
<li>NewClientConn</li>
<li>NewProxyClientConn</li>
<li>NewServerConn</li>
<li>NewSingleHostReverseProxy</li>
<li>ReverseProxy</li>
<li>ServerConn</li>
</ul>
<p>
Also, the <code>Request.RawURL</code> field has been removed; it was a
historical artifact.
</p>
<p>
<em>Updating</em>:
Gofix will update the few programs that are affected except for
uses of <code>RawURL</code>, which must be fixed by hand.
</p>

    • os.FileInfo型に関するセクション:

      <h3 id="os_fileinfo">The os.FileInfo type</h3>
<p>
Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
changing it from a struct to an interface:
</p>
<pre>
    type FileInfo interface {
        Name() string       // base name of the file
        Size() int64        // length in bytes
        Mode() FileMode     // file mode bits
        ModTime() time.Time // modification time
        IsDir() bool        // abbreviation for Mode().IsDir()
    }
</pre>
<p>
The file mode information has been moved into a subtype called
<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
methods.
</p>
<p>
The system-specific details of file modes and properties such as (on Unix)
i-number have been removed from <code>FileInfo</code> altogether.
Instead, each operating system's <code>os</code> package provides an
implementation of the <code>FileInfo</code> interface, <code>*os.FileStat</code>,
which in turn contains a <code>Sys</code> field that stores the
system-specific representation of file metadata.
For instance, to discover the i-number of a file on a Unix system, unpack
the <code>FileInfo</code> like this:
</p>
<pre>
    fi, err := os.Stat("hello.go")
    if err != nil {
        log.Fatal(err)
    }
    // Make sure it's an implementation known to package os.
    fileStat, ok := fi.(*os.FileStat)
    if !ok {
        log.Fatal("hello.go: not an os File")
    }
    // Now check that it's a Unix file.
    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
    if !ok {
        log.Fatal("hello.go: not a Unix file")
    }
    fmt.Printf("file i-number: %d\n", unixStat.Ino)
</pre>
<p>
Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
the i-number expression could be contracted to
</p>
<pre>
    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
</pre>
<p>
The vast majority of uses of <code>FileInfo</code> need only the methods
of the standard interface.
</p>	
<p>
<em>Updating</em>:
Gofix will update code that uses the old equivalent of the current <code>os.FileInfo</code>
and <code>os.FileMode</code> API.
Code that needs system-specific file details will need to be updated by hand.
</p>

コアとなるコードの解説

このコミット自体は、Go言語のランタイムやライブラリのコードを変更するものではなく、Go 1リリースノートの一部となるドキュメントを更新するものです。したがって、「コアとなるコード」とは、Go 1のAPI変更に関する説明が記述されたドキュメントの内容を指します。

追加されたHTMLスニペットは、Go 1で導入されたhtmlパッケージ、リファクタリングされたhttpパッケージ、そして変更されたos.FileInfo型について、開発者向けに以下の情報を提供しています。

  • 機能の概要: 各パッケージや型の目的と提供する機能。
  • APIの変更点: httpパッケージにおけるユーティリティ関数の移動やRequest.RawURLの削除、os.FileInfoがインターフェースになったことなど、具体的なAPIの変更点。
  • 移行ガイド: 既存のコードをGo 1に適合させるための「Updating」セクション。gofixツールによる自動更新の可否や、手動での修正が必要なケース（例: Request.RawURLの使用、os.FileInfoのシステム固有の詳細へのアクセス）が明記されています。
  • コード例: os.FileInfoの変更を説明するために、Unixシステムでi-numberを取得する具体的なGoコード例が示されています。これは、インターフェースの型アサーションとシステム固有のデータへのアクセス方法を理解する上で非常に重要です。

これらのドキュメントは、Go 1への移行をスムーズにし、開発者が新しいAPIを正しく理解し、既存のコードを適切に更新できるようにするための重要な情報源となります。

関連リンク

  • Go 1 Release Notes (公式ドキュメント): Go 1のリリース時に公開された公式の変更点リスト。このコミットで追加された内容は、その一部を構成します。
  • net/httpパッケージのドキュメント:
  • net/httputilパッケージのドキュメント:
  • osパッケージのドキュメント:
  • htmlパッケージのドキュメント:
  • gofixツールに関する情報:
    • Goの公式ブログやドキュメントでgofixに関する詳細が提供されています。

参考にした情報源リンク

  • Go 1 Release Notes (上記「関連リンク」と同じ)
  • Go言語の公式ドキュメント (pkg.go.dev)
  • Go言語のGitHubリポジトリ (golang/go)
  • Go言語の設計に関する議論やメーリングリストのアーカイブ (golang-devなど)
  • Go言語の歴史に関する記事やブログポスト