std.file

ファイル操作やディレクトリ走査のためのユーティリティです。このモジュールの関数は、ファイル全体を一つの単位として扱うように、つまりファイル全体を一気に読み書きするように設計されています。細かく内容について操作するには std.stdio を使用してください。

Source:
std/file.d

License:
Boost License 1.0.

Authors:
Walter Bright, Andrei Alexandrescu

class FileException: object.Exception;

ファイル入出力エラーが発生したときに投げられる例外です。

immutable uint errno;: OSのエラーコードです。
this(in char[] name, in char[] message);: ファイルの名前とエラーメッセージを受け取るコンストラクタです。
this(in char[] name, uint errno = GetLastError);: ファイルの名前とエラー番号 (Windows では GetLastError、Posix では getErrno) を受け取るコンストラクタです。

void[] read(in char[] name, size_t upTo = uint.max);

ファイル name を読み取り、読み込まれたbyteの配列を返します。ファイルが upTo よりも大きいときは upTo バイトまで読み込まれます。

Example:

import std.file, std.stdio;
void main()
{
   auto bytes = cast(ubyte[]) read("filename", 5);
   if (bytes.length == 5)
       writefln("The fifth byte of the file is 0x%x", bytes[4]);
}

Returns:
型の指定されていない、読み込まれたバイト配列

Throws:
FileException をエラー時に投げる

S readText(S = string)(in char[] name);

テキストファイルを読み込んで検証して返します。(検証には std.utf.validate を使用します)。S は文字幅とconst性の任意の組み合わせの文字列型が指定できます。文字幅変換は行われません。ファイル name のエンコーディングと S のエンコーディングが違う場合は、検証エラーになります。

Returns:
読み込まれた文字列

Throws:
ファイルエラー時には FileException。 UTFデコードエラー時には UtfException。

Example:

enforce(system("echo abc>deleteme") == 0);
scope(exit) remove("deleteme");
enforce(chomp(readText("deleteme")) == "abc");

void write(in char[] name, const void[] buffer);

ファイル name[] に buffer[] を書き込みます。

Throws:
FileException をエラー時に投げる

Example:

import std.file;
void main()
{
   int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
   write("filename", a);
   assert(cast(int[]) read("filename") == a);
}

void append(in char[] name, in void[] buffer);

ファイル name に buffer[] を追記します。

Throws:
FileException on error.

Example:

import std.file;
void main()
{
   int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
   write("filename", a);
   int[] b = [ 13, 21 ];
   append("filename", b);
   assert(cast(int[]) read("filename") == a ~ b);
}

void rename(in char[] from, in char[] to);

ファイル from を to に改名します。

Throws:
FileException をエラー時に投げる

void remove(in char[] name);

ファイル name を削除します。

Throws:
FileException をエラー時に投げる

ulong getSize(in char[] name);

ファイル name[] のサイズを取得します。

Throws:
FileException をエラー時に投げる

void getTimes(in char[] name, out d_time ftc, out d_time fta, out d_time ftm);

ファイル name[] の作成/最終アクセス/更新日時を返します。

Throws:
FileException をエラー時に投げる

d_time lastModified(in char[] name);

ファイル name の最終更新日時を返します。ファイルが存在しない場合、FileException を投げます。

d_time lastModified(in char[] name, d_time returnIfMissing);

ファイル name の最終更新日時を返します。ファイルが存在しない場合、returnIfMissing を返します。

典型的な使用例としては、 make や ant のようなビルド自動化ツールがあります。ファイル target をファイル source から再ビルドする必要があるかどうか (つまり target が source より古いか存在しないケース) のチェックをするには、以下のような比較を行います。source が存在しない場合には (存在すべきなので) FileException 例外を投げます。その一方で、 target が存在しない場合には、デフォルト値 d_time.min を返すことで無限に古いファイルという扱いにし、正しくビルドを行います。

if (lastModified(source) >= lastModified(target, d_time.min))
{
    // (再)ビルドが必要
}
else
{
    // target は最新版
}

bool exists(in char[] name);

ファイル(またはディレクトリ) name[] が存在するかどうか

uint getAttributes(in char[] name);

ファイル name の属性を得ます。

Throws:
FileException をエラー時に投げる

bool isdir(in char[] name);

name がディレクトリかどうか

Throws:
name が存在しなければ FileException を投げる

bool isfile(in char[] name);

name はファイルか？

Throws:
name が存在しなければ FileException を投げる

void chdir(in char[] pathname);

カレントディレクトリを pathname に変更

Throws:
FileException をエラー時に投げる

void mkdir(in char[] pathname);

ディレクトリ pathname を作成

Throws:
FileException をエラー時に投げる

void mkdirRecurse(in char[] pathname);

ディレクトリと、もし存在しなければその親ディレクトリを再帰的に作成

void rmdir(in char[] pathname);

ディレクトリ pathname を削除

Throws:
FileException をエラー時に投げる

string getcwd();

カレントディレクトリを取得

Throws:
FileException をエラー時に投げる

struct DirEntry;

ディレクトリエントリ

string name;: ファイルかディレクトリの名前
ulong size;: ファイルのバイト数
d_time creationTime;: ファイル作成日時
d_time lastAccessTime;: ファイル最終アクセス日時
d_time lastWriteTime;: ファイル最終更新日時
const bool isdir();: DirEntryがディレクトリの場合true
const bool isfile();: DirEntryがファイルの場合true

void listdir(in char[] pathname, bool delegate(DirEntry* de) callback);

pathname 内のファイルそれぞれに対応する DirEntry を列挙して、 callback delegate に渡します。

Note:
この関数は取り除かれる予定です。新しいコードでは dirEntries (下参照) を使用してください。

Parameters:

bool delegate(DirEntry* de) callback

毎回それぞれのパス文字列を処理する Delegate。処理を続行するには true を、終了するには false を返すこと。

Example:
このプログラムは、自身を含めパス引数以下の全てのファイルをリストアップします。

 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    bool callback(DirEntry* de)
    {
      if (de.isdir)
        listdir(de.name, &callback);
      else
        writefln(de.name);
      return true;
    }

    listdir(args[1], &callback);
 }

void copy(in char[] from, in char[] to);

ファイル from をファイル to へコピーします。タイムスタンプは保たれます。

void setTimes(in char[] name, d_time fta, d_time ftm);

ファイル name のアクセス/更新日時を設定します。

Throws:
エラー時に FileException

void rmdirRecurse(in char[] pathname);

ディレクトリと、サブディレクトリを含むその中身を再帰的に削除します。

enum SpanMode;

dirEntries (下を参照) に指定するディレクトリ展開モードの指定

shallow: ディレクトリ１つの中身だけを列挙します（サブディレクトリには潜りません）
depth: ディレクトリを深さ優先(※訳注: 帰りがけ順？)で列挙します。つまり、サブディレクトリの中身がサブディレクトリ自身より先に列挙されます。例として、再帰的にファイルを削除する場合などに便利です。
breadth: ディレクトリを幅優先(※訳注: 行きがけ順？)で列挙します。つまり、サブディレクトリ自身の直後に中身列挙が行われます。

DirIterator dirEntries(string path, SpanMode mode);

foreachでディレクトリの内容を列挙します。foreachで情報を受け取る変数の型は名前のみ必要なら string、追加情報まで必要なら DirEntry とします。引数 mode は、ディレクトリをたどる順番の指定です。ファイル名として返される文字列には、 path が接頭辞として含まれます。

Example:

 // ディレクトリ内をdepthモードで列挙
 foreach (string name; dirEntries("destroy/me", SpanMode.depth))
 {
     remove(name);
 }
 // ディレクトリ内をbreadthモードで列挙
 foreach (string name; dirEntries(".", SpanMode.breadth))
 {
     writeln(name);
 }
 // ディレクトリ内を詳細な情報付きで列挙
 foreach (DirEntry e; dirEntries("dmd-testing", SpanMode.breadth))
 {
     writeln(e.name, "\t", e.size);
 }

Select!(Types.length == 1,Types[0][],Tuple!(Types)[]) slurp(Types...)(string filename, in char[] format);

ファイル全体を配列に読み込みます。

Example:

// ファイルのロード; 各行は int, double の形式
// とする
auto a = slurp!(int, double)("filename", "%s, %s");

string[] listdir(in char[] pathname);

ディレクトリの内容を返します。内容の名前には pathname は含まれません。

Throws:
FileException をエラー時に投げる

Example:
このプログラムは、指定されたパス引数内の全てのファイルとサブディレクトリをリストアップします。

 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    auto dirs = std.file.listdir(args[1]);

    foreach (d; dirs)
        writefln(d);
 }

string[] listdir(in char[] pathname, in char[] pattern); string[] listdir(in char[] pathname, RegExp r);

ディレクトリとサブディレクトリにある全てのファイルのうち、 pattern または正規表現 r にマッチするもののみを返します。

Parameters:

char[] pathname	ディレクトリ名
char[] pattern	ワイルドカード入り文字列。例えば "*.d" 対応しているワイルドカード文字列は、 std.path の fnmatch() に記述されています。
r	正規表現です。より強力なパターンマッチに使用します。

Example:
このプログラムは、第一引数として渡されたパス上にある拡張子 "d" のファイルを全てリストアップします。

 import std.stdio;
 import std.file;

 void main(string[] args)
 {
    auto d_source_files = std.file.listdir(args[1], "*.d");

    foreach (d; d_source_files)
        writefln(d);
 }

"d" もしくは "obj" の拡張子を持つファイルを探す、正規表現バージョンです：

 import std.stdio;
 import std.file;
 import std.regexp;

 void main(string[] args)
 {
    auto d_source_files = std.file.listdir(args[1], RegExp(r"\.(d|obj)$"));

    foreach (d; d_source_files)
        writefln(d);
 }

void listdir(in char[] pathname, bool delegate(string filename) callback);

pathname 内の全てのファイルとディレクトリ名を、 callback delegate に渡します。

Note:
この関数は非推奨となりました。新しいコードでは dirEntries (下参照) を使用してください。

Parameters:

bool delegate(string filename) callback

それぞれのパス文字列を処理する Delegate。処理を続行するには true を、終了するには false を返すこと。

Example:
このプログラムは、自身を含めパス引数以下の全てのファイルをリストアップします。

 import std.stdio;
 import std.path;
 import std.file;

 void main(string[] args)
 {
    auto pathname = args[1];
    string[] result;

    bool listing(string filename)
    {
      result ~= std.path.join(pathname, filename);
      return true; // continue
    }

    listdir(pathname, &listing);

    foreach (name; result)
      writefln("%s", name);
 }