FilePathを標準ライブラリに追加する

FilePath とその中核型（FilePath.Anchor、FilePath.Component、FilePath.ComponentView）を Swift モジュールに追加し、currency typeとしてパスを受け渡せるようにします。この Proposal では、FilePath を型として成立させるための「構築」「分解」「解決（resolution）」「C相互運用」のための最小限のAPIまでが対象で、lastComponent や stem のようなシンタックス上の便利メソッドなどは後続の提案に回されます。

APIの全体像は次のようなイメージです。

var path: FilePath = "/var/www/static/index.html"

path.isAbsolute                      // true
path.hasTrailingSeparator            // false

print(path.anchor)                   // Optional(/)
for component in path.components {
    print(component, component.kind) // "var": .regular, "www": .regular, ...
}

// ファイルシステムに問い合わせて解決する
let resolved = try path.resolve()

// コンポーネント列を操作してパスを組み立てる
var config: FilePath = "/etc/nginx"
config.components.append("nginx.conf")
// config は "/etc/nginx/nginx.conf"

以降、主要な設計ポイントを順に見ていきます。

FilePath の内部表現と基本形

FilePath はSendableな値型で、プラットフォームネイティブの文字（Linux / Darwinでは CChar、Windowsでは UInt16）のnull終端されたシーケンスとして値を保持します。空のパスは FilePath() で得られ、isEmpty で判定できます。/ や C:\ のようなアンカーのみのパスは空ではありません。なお、NUL バイト（0x00）はどのプラットフォームでも妥当なパスバイトではないため、String や Span から構築する失敗可能イニシャライザは NUL を含む入力に対して nil を返します。

public struct FilePath: Sendable {
  public init()
  public static var separator: FilePath.CodeUnit { get }  // Linux/Darwinは "/"、Windowsは "\" を表すコードユニット
  public var isEmpty: Bool { get }
}

separator の型はプラットフォームのコードユニット（Linux / Darwinは CChar、Windowsは UInt16）です。String 由来の Character ではなく、FilePath 内部の表現に直接対応する低レベルな型を返す形になっています。

分解モデル: アンカー + コンポーネント + サフィックス

Proposalの中心概念は、どんなパスも次の3つに分解できるという分解モデルです。

• アンカー（anchor）: パスの基準点を表す、先頭の領域
• コンポーネント列: 基準点から辿るための相対コンポーネント（FilePath.ComponentView が正規化して提示する）
• サフィックス: 最終コンポーネントを解決したあとの挙動をカーネルに指示する、末尾の領域

たとえばLinuxの /foo/bar は、アンカーが /、コンポーネント列が [foo, bar]、末尾のセパレータなし、となります。この3軸に分けて理解することで、プラットフォーム差のある構文を型で吸収する、というのが FilePath の設計です。

アンカー（FilePath.Anchor）

アンカーはコンポーネント列に先立つ領域で、単なるルートだけでなく、ボリュームや解決方法の指定まで担います。

• Linuxでは絶対パスの / のみ
• Darwinではこれに加えて、カーネルへの解決フラグ（/.nofollow/、/.resolve/3/）やボリューム参照（/.vol/1234/5678）を含みうる
• Windowsではドライブレター（C:\、C:）、UNC名（\\server\share）、デバイスパス（\\.\pipe）、verbatimパス（\\?\C:\）、カレントドライブのルート（\）などが当たる

FilePath.Anchor は isRooted プロパティを持ち、絶対パスかrootedかを問い合わせられます。さらに driveLetter / isVerbatimComponent が #if os(Windows) のもとで提供され、Windowsのアンカーが持つ固有の構造を露出させます。相対パスの場合は path.anchor は nil です。

var winPath: FilePath = #"C:\Users\dev\project"#
winPath.anchor?.driveLetter            // Optional("C")
winPath.anchor?.isVerbatimComponent    // Optional(false)

// 「conventional」形式から「verbatim-component」形式へアンカーだけ付け替える
winPath.anchor = #"\\?\C:\"#
print(winPath)                         // \\?\C:\Users\dev\project

// Darwin上で、カーネルの解決フラグを剥がしたいときはアンカーだけ "/" に差し替える
var darwinPath: FilePath = "/.nofollow/etc/passwd"
darwinPath.anchor = "/"
print(darwinPath)                      // /etc/passwd

driveLetter の型は Unicode.Scalar? で、ドライブを示す : の直前にある1コードユニットをそのまま返します。A-Z 以外の文字も理論上はドライブレターになりうるためケース正規化は行われず、もしWindowsの UInt16 表現で対応するペアを持たないサロゲートが入っていれば U+FFFD が返ります。

Windowsのパスは大きく3つのスタイル（conventional / device-namespace / verbatim-component）に分類され、FilePath.Anchor はこの違いを型として保持します。特にverbatim-component（\\?\）では / はセパレータでなく正当なコンポーネント文字で、. / .. も特別扱いされないなど、構文そのものが変わる点が重要です。

また、Darwinのアンカーには正規化ルールがあります。/.resolve/1/ は同じXNUフラグを指す /.nofollow/ に、/.vol/NNNN/2/ は「ボリュームルート（inode 2）」を指す /.vol/NNNN/@/ に、構築時に正規化されます。

コンポーネント（FilePath.Component / FilePath.ComponentView）

FilePath.Component は1つのパスコンポーネントを表し、空にはならず、ディレクトリセパレータを含みません。kind プロパティで、通常のコンポーネント（.regular）、カレントディレクトリ（.currentDirectory、.）、親ディレクトリ（.parentDirectory、..）を区別できます。ただしWindowsのverbatim-componentパスでは . / .. は通常の名前として扱われるため、同じ . というバイト列でも、置かれたパスのアンカー次第で kind が変わります。

FilePath.ComponentView は BidirectionalCollection かつ RangeReplaceableCollection で、パスのコンポーネント列を正規化した形で提示します。

• 連続するセパレータは無視される（a///b → [a, b]）
• 非verbatimのWindowsパスでは / と \ は同じセパレータとして扱われる
• 中間の . コンポーネントは落とされる（a/./b → [a, b]）。ただし rootless パスの先頭に現れた ./foo のような . は残る
• .. コンポーネントは常に保持される（a/../b → [a, .., b]）

var path: FilePath = "/home/username/scripts/tree"
let scriptIdx = path.components.lastIndex(of: "scripts")!
path.components.insert("bin", at: scriptIdx)
// path は "/home/username/bin/scripts/tree"

Windows上で FilePath.Component(verbatim:) を使えば、/ を含む文字列もverbatim-componentパス向けの正当なコンポーネントとして作成できます。

サフィックス: 末尾のセパレータとリソースフォーク

サフィックスはコンポーネントではなく、「最終コンポーネントを解決したあとの挙動」をカーネルに指示する部分です。2種類あります。

• 末尾のセパレータ（trailing separator）: Linux / Darwin / Windowsすべてに存在。/tmp/foo/ のような末尾の / は、最終コンポーネントをディレクトリとして扱うよう要求し、シンボリックリンクの解決を行わせる、という意味を持つ
• リソースフォーク サフィックス（Darwinのみ）: ファイルのresource forkを指す、固定の /..namedfork/rsrc サフィックス

この2つは同時には現れず、どちらも等価性（==）に影響します。たとえば FilePath("/tmp/foo") != FilePath("/tmp/foo/") です。swift-systemの FilePath は末尾のセパレータを構築時に落としていましたが、標準ライブラリ版では保持する方針に変わります。

extension FilePath {
  public var hasTrailingSeparator: Bool { get set }
  public func withTrailingSeparator() -> FilePath
  public func withoutTrailingSeparator() -> FilePath
}

#if canImport(Darwin)
extension FilePath {
  public var isResourceFork: Bool { get set }
  public func withResourceFork() -> FilePath
  public func withoutResourceFork() -> FilePath
}
#endif

分解からの再構築

分解の逆操作として、アンカー・コンポーネント列・サフィックスからパスを組み立てるイニシャライザも用意されます。文字列リテラルで同じパスを書いたときと同じ正規化が適用されます。

extension FilePath {
  public init(
    anchor: Anchor?,
    _ components: some Sequence<Component>,
    hasTrailingSeparator: Bool = false
  )
}

#if canImport(Darwin)
extension FilePath {
  public init(
    anchor: Anchor?,
    _ components: some Sequence<Component>,
    resourceFork: Bool
  )
}
#endif

absolute / rooted

アンカーの性質から派生する概念として、isAbsolute と、Windows固有の「rooted」の区別があります。

• absolute: 現在の作業ディレクトリや環境変数などに依存せず、名前付きボリュームのルートだけを基準に場所を一意に決められるパス
• Linux / Darwinでは / で始まるパスが absolute
• Windowsでは C:\、\\server\share\、\\?\C:\、\\.\pipe のように「ドライブまたはボリュームを明示しつつルートから始まる」ものが absolute。\foo や C:foo は rooted だが absolute ではない
• ~ で始まるパスはシェル展開を行わないため、絶対パスとしては扱われない

FilePath.Anchor.isRooted は、Windowsでこの「rooted だが absolute ではない」状態を拾うためのプロパティです。Linux / Darwinでは rooted ≡ absolute なので、実質的にWindows向けの区別です。「絶対パスでない」かどうかは !path.isAbsolute で判定し、専用の isRelative は提供されません。

解決（resolve()）

FilePath.resolve() は、ファイルシステムに問い合わせて絶対パス形式を得る操作です。

• 結果のパスはabsoluteで、シンボリックリンクを含まず、. / .. も含まない
• すべての中間コンポーネントが存在する必要があり、失敗時は throw する
• 結果はスナップショットであり、以降のファイルシステム変更で無効になる可能性がある

extension FilePath {
  @available(*, noasync)
  public func resolve() throws -> FilePath
}

resolve() は同期的でブロッキングする操作なので、@available(*, noasync) が付与されており、async コンテキストから直接呼ぶと診断されます。非ブロッキングな async 版や非ブロッキングな sync 版は今後の課題として位置づけられています。

Windowsのverbatim-componentパス（\\?\）では . / .. は特殊扱いされないため、解決後のパスにもそのまま残ることがあります。Darwinでは、解決結果のアンカーに /.nofollow/ のような解決フラグが挿入される場合があります。シンボリックリンクを使わない「lexical resolution」や、ベースディレクトリから逃げないことを保証する「resolve-beneath」は、このProposalのスコープ外で将来の作業とされています。

表示・比較・ハッシュ

FilePath / FilePath.Anchor / FilePath.Component は、Hashable、Comparable、CustomStringConvertible、CustomDebugStringConvertible、ExpressibleByStringLiteral に適合します。String からの非失敗イニシャライザが FilePath にはありますが、Anchor と Component はバリデーションのため失敗可能イニシャライザのみです（文字列リテラル経由はtrapする可能性があります）。

print(FilePath("a///b"))      // "a/b"
print(FilePath("a/./b"))      // "a/b"
print(FilePath("/./foo"))     // "/foo"
print(FilePath("/tmp/foo/"))  // "/tmp/foo/"

FilePath("a///b") == FilePath("a/b")              // true（正規化後に同じ）
FilePath("/tmp/foo") != FilePath("/tmp/foo/")     // true（trailing separatorが異なる）
FilePath("/.nofollow/foo/bar") != FilePath("/foo/bar")    // true（Darwinのアンカーが異なる）
FilePath(#"\\.\C:\foo\bar"#) != FilePath(#"C:\foo\bar"#)  // true（Windowsのアンカーが異なる）

等価性は「2つのパスが同じ綴りか（無意味な重複セパレータや中間の . を正規化したうえで）」という純粋に構文的な判定で、ファイルシステムへの問い合わせは行いません。そのため、ハードリンクやシンボリックリンクを踏まえた「同じ実体を指す」という意味での同値性は、これとは別の概念です。Comparable の順序は、正規化後のバイト表現に対する辞書順です。

FilePath.ComponentView も Hashable / Comparable に適合しますが、比較対象はコンポーネント部分のみで、アンカーやサフィックスは無視されます。

文字列・バイト列との相互変換

String との相互変換は init(decoding:) / init?(validating:) で、Linux / DarwinではUTF-8、WindowsではUTF-16として解釈します。validating 版は不正なUnicodeのとき nil を返し、decoding 版は不正バイトを U+FFFD に置き換えます。FilePath.Anchor / FilePath.Component にも同様のAPIが用意されます。

extension String {
  public init(decoding path: FilePath)
  public init?(validating path: FilePath)
  // Anchor / Component 向けの同様のAPI
}

C相互運用: withCodeUnits(_:) と Span

C APIへの受け渡し用に、プラットフォームの CodeUnit（Linux / Darwinは CChar、Windowsは UInt16）でアクセスするAPIが用意されます。中心となるのは、String.withCString(_:) に近い形のクロージャベースAPIで、ポインタとコードユニット数（null終端を除く）の両方を受け取れます。これにより、文字数を再計算せずにC関数へ渡せます。

extension FilePath {
  public typealias CodeUnit = /* CChar or UInt16 */

  /// path のnull終端バッファのポインタと、null終端を含まないコードユニット数を渡す
  public func withCodeUnits<Result, E: Error>(
    _ body: (UnsafePointer<FilePath.CodeUnit>, Int) throws(E) -> Result
  ) throws(E) -> Result

  /// 借用ストレージとして、null終端を含まないコードユニット列を取得
  public var codeUnits: Span<FilePath.CodeUnit> { get }

  /// 末尾のnull終端を含むコードユニット列
  public var nullTerminatedCodeUnits: Span<FilePath.CodeUnit> { get }

  /// null終端を含まないSpanから構築。`NUL` が含まれていると `nil`
  public init?(codeUnits: Span<FilePath.CodeUnit>)

  public init<E: Error>(
    capacity: Int,
    initializingCodeUnitsWith initializer: (inout OutputSpan<FilePath.CodeUnit>) throws(E) -> Void
  ) throws(E)
}

FilePath.Anchor / FilePath.Component / FilePath.ComponentView にも、それぞれ対応する codeUnits: Span<FilePath.CodeUnit> が生えます。コンポーネントは内部にセパレータやnull終端を含みません。

String 由来のイニシャライザも、NUL を含む入力を弾くために失敗可能になります。FilePath / FilePath.Anchor / FilePath.Component のすべてで、init?(_ string: String) が NUL を含む文字列に対して nil を返します（FilePath についても文字列リテラル経由はtrapしますが、ランタイムの String からは失敗可能になります）。

swift-system との移行

既存の SystemPackage.FilePath / System.FilePath は、対応するツールチェインに対しては Swift.FilePath への条件付きtypealiasを通じて移行できます。

#if compiler(>=6.4) // 本提案が導入されるバージョン
public typealias FilePath = Swift.FilePath
#else
public struct FilePath { ... }
#endif

これにより、syntactic API などの既存機能は新しい FilePath 上の拡張として提供でき、ソース互換性を保ったまま移行できます。Darwinの System.FilePath にはABIコミットメントがあるため、既存バイナリ向けにはABIレベルのリダイレクトで互換性が確保されます。swift-systemの FilePath.Root は FilePath.Anchor に置き換えられる形で正式にdeprecatedとなります。