CONSTRUCTOR¶

new([$path, $options, ...])

Create a new instance pointing to the specified $path. $options is an optional hashref of options.

$path will be created (or the constructor will die). If $path is undefined, a unique path will be automatically generated; otherwise it is an error for $path to already exist.

UTILITY METHODS¶

touch($file ...)

Create the specified $files and track their state.

create($file,%options)

Create the specified $file and track its state. The %options hash supports the following:

mkdir($directory)

Create the specified $directory; dies if mkdir fails.

name($file)

Returns the name of the $file, relative to the directory; including any seperator normalization. $file need not exist. This method is used internally by most other methods to translate file paths.

For portability, this method implicitly splits the path on UNIX-style / seperators, and rejoins it with the local directory seperator.

Absent any seperator substitution, the returned value would be equivalent to $file.

path($file)

Returns the path for the $file, including the directory name and any substitutions. $file need not exist.

check_file($file)

Checks whether the specified $file exists, and updates its state accordingly. Returns true if $file exists, false otherwise.

This method is used internally by the corresponding test methods.

check_directory($directory)

Checks whether the specified $directory exists, and updates its state accordingly. Returns true if $directory exists, false otherwise.

This method is used internally by the corresponding test methods.

Note that replacing a file with a directory, or vice versa, would require calling both check_file and check_directory to update the state to reflect both changes.

remove_files($file...)

Remove the specified $files; return the number of files removed.

remove_directories($directory...)

Remove the specified $directoriess; return the number of directories removed.

clean

Remove all known files, then call rmdir on the directory; returns the status of the rmdir. The presence of any unknown files will cause the rmdir to fail, leaving the directory with these unknown files.

This method is called automatically when the object goes out of scope.

count_unknown

count_missing

Returns a count of the unknown or missing files and directories. Note that files and directores are interchangeable when counting missing files, but not when counting unknown files.

TEST METHODS¶

The test methods validate the state of the test directory, calling Test::Builder's ok and diag methods to generate output.

has ($file, $test_name)

hasnt($file, $test_name)

Verify the status of $file, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated.

has_dir ($directory, $test_name);

hasnt_dir($directory, $test_name);

Verify the status of $directory, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated.

is_ok($test_name)

Pass if the test directory has no missing or extra files.

clean_ok([$test_name])

Equivalent to ok(clean,$test_name)

EXAMPLES¶

Calling an external program to move a file

 $dir->touch('my-file.txt');
 system ('gzip', $dir->path('my-file.txt'));
 $dir->has  ('my-file.txt.gz', '.gz file is added');
 $dir->hasnt('my-file.txt',    '.txt file is removed');
 $dir->is_ok; #verify no other changes to $dir