NAME

Promised::File - File system operations

SYNOPSIS

use Promised::File;
$file = Promised::File->new_from_path ('path/to/file.txt');
$file->read_byte_string->then (sub { warn $_[0] });
$file->read_char_string->then (sub { warn $_[0] });
$p = $file->write_byte_string ($bytes);
$p = $file->write_char_string ($chars);

DESCRIPTION

The Promised::File class provides file system operations returning Promise objects.

METHOD

Following methods are available:

$file = Promised::File->new_from_path ($string)

Create a Promised::File object with the specified path.

The path must be a Unix style character string of the relative or absolute path to the file. A relative path is resolved against the current working directory. (However, it does not support resolving of ~ syntax (home directory). It is recommended that an absolute path be specified as the argument.)

Paths in non-unix platforms such as Windows are not supported. Paths in character encoding other than UTF-8 (or binary data) are not supported.

$file = Promised::File->new_from_raw_path ($byte_string)

Smilar to new_from_path, but the argument is interpreted as a byte string.

Don't use this method unless you know how non UTF-8 byte string is handled by the platform.

$file = Promised::File->new_temp_directory (no_cleanup => BOOLEAN)

Cerate a Promised::File object representing a new temporary directory created by File::Temp.

By default, the directory is removed after any reference to the file object is discarded. If a named parameter whose name is no_cleanup is set to a boolean true value, the directory is not removed.

$string = $file->path_string

Return a string that represents the path to the file. It might or might not be equal to the path given upon the creation of the file object. It might or might not be absolute.

$file->stat->then (sub { $stat = shift })

Return a Promise, which is resolved with the stat File::stat object for the file. See perldoc -f stat and File::stat for details. Note that the object is cached such that the promise returned by the method is always resolved with the same object. If the file is not found, the promise is rejected.

$file->lstat->then (sub { $stat = shift })

Return a Promise, which is resolved with the lstat File::stat object for the file. See perldoc -f lstat and File::stat for details. Note that the object is cached such that the promise returned by the method is always resolved with the same object. If the file is not found, the promise is rejected.

$file->is_file->then (sub { $boolean = shift })

$file->is_directory->then (sub { $boolean = shift })

$file->is_symlink->then (sub { $boolean = shift })

$file->is_executable->then (sub { $boolean = shift })

Return a Promise, which is resolved with whether it is a file (-f), a directory (-d), a symlink (-l), or an executable file (-x), respectively. If the file is not found, the promise is resolved with false.

$file->chmod ($mode)->then (...)

Change the file's permission to the specified value (e.g. 0777 for world-readable).

$stream = $file->read_bytes

Return a ReadableStream that is a readable byte stream of the content of the file. If the specified file is not found, the stream is in error.

$file->read_byte_string->then (sub { $bytes = shift })

Return a Promise, which is resolved with the content of the file as a byte string. If the specified file is not found, the promise is rejected.

$file->read_char_string->then (sub { $chars = shift })

Return a Promise, which is resolved with the content of the file interpreted as a UTF-8 encoded byte sequence, represented as a Perl utf8 string. If the specified file is not found, the promise is rejected.

$stream = $file->write_bytes

Return a WritableStream that is a writable stream written into the specified file. Any existing file is overwritten. The stream is in error if failed.

Any data written to the stream (i.e. the argument to the writer's write method) must be an ArrayBufferView (such as DataView and TypedArray::Uint8Array).

Aborting the stream (i.e. the abort method) closes the file, without completing the outstanding writes, and in fact the pending creation of the file, depending on when the stream is aborted. Therefore, the stream should not be aborted unless the application (and the user) no longer have any interest to the file's content at all.

$promise = $file->write_byte_string ($bytes)

Return a Promise, which is resolved after the specified byte string is written to the specified file. Any existing file is overwritten. The promise is rejected if failed.

$promise = $file->write_char_string ($chars)

Return a Promise, which is resolved after the specified character string is written to the specified file in UTF-8 character encoding. Any existing file is overwritten. The promise is rejected if failed.

$file->mkpath->then (...)

Create a directory at $file's path (if not yet). Ancestor directories are also created, if necessary. Any conflicting file will result in an error.

$file->mkpath_parent->then (...)

Create a directory that is the parent of $file's path (if not yet). Ancestor directories are also created, if necessary. Any conflicting file will result in an error.

$file->remove_tree (OPTIONS)->then (...)

Remove a file or directory of $file's path (if any), as well as any descendant.

The following option can be specified as named arguments:

unsafe => BOOLEAN (default: false)

If false, any descendant with read-only permission is not deleted (see File::Path).

$file->get_child_names->then (sub { $names = $_[0] })

Return a Promise, which is resolved with an array reference of the file names in the directory specified by the path of the $file object. The array items are the names of the files and directories directly beglonging to the directory, without directory paths, as byte strings. Special directories . and .. are not included in the array. It is rejected if there is no such directory or it is not a directory.

$file->lock_new_file (signal => $signal, timeout => $seconds)->then (...)

Exclusively lock the file, using flock (i.e. advisory locking). If the file is not found, a new file is created before locking.

The method returns a promise, which is resolved when a lock is acquired (or rejected with an error when failed).

The following options can be specified as named arguments:

signal => $signal (required)

An AbortSignal object. If it is aborted before the lock is acquired, the locking is canceled and the returned promised is rejected with an AbortError. If it is aborted after the lock is acquired, the lock is released.

This option is required. The lock must be released.

timeout => $seconds

The duration the method's attempt to acquire a lock is continued, in seconds. If not specified, no timeout is enforced. If timeouted, the returned promise is rejected.

interval => $seconds

The duration between the method's repeated attempts to acquire a lock, in seconds.

$file->move_from ($string)->then (...)

Move a file. The first argument is a path to the original file. It is moved to the $file's path.

It must be a normal file (not a directory).

$file->copy_from ($string)->then (...)

Copy a file. The first argument is a path to the original file. It is copied to the $file's path.

It must be a normal file (not a directory).

$file->hardlink_from ($string, OPTIONS)->then (...)

Create a hardlink. The first arugment is a path to the linked file. A new file is created at $file's path and is associated to the existing file <$string>'s content.

It must be a normal file (not a directory).

The following options can be specified as named arguments:

fallback => BOOLEAN (default: false)

If true, fallback to copy_from on failure (e.g. when the specified path and the file's path are on different filesystem).

replace => BOOLEAN (default: false)

If true, any existing file at $file's path is removed before the creation of new hardlink. Otherwise, any existing file will result in an error.

DEPENDENCY

The module requires Perl 5.12 or later.

The module requires Promise <https://github.com/wakaba/perl-promise> and AnyEvent.

Methods read_bytes and write_bytes requires the ReadableStream and WritableStream modules from the perl-streams package <https://github.com/manakai/perl-streams>. Methods get_child_names and lock_new_file require Streams::IOError from the perl-streams package.

If the Web::Encoding module (from the perl-web-encodings package <https://github.com/manakai/perl-web-encodings>) is available, that module is used to encode or decode UTF-8 texts in a way compatible with the Web. Otherwise, the Perl's Encode module is used instead.

Method lock_new_file requires AnyEvent::FileLock.

Methods move_from and copy_from, as well as method hardlink_from with option fallback_to_copy, requires AnyEvent::AIO and IO::AIO.

AUTHOR

Wakaba <[email protected]>.

HISTORY

This repository was located at <https://github.com/wakaba/perl-promised-file> until 18 April 2023, then transferred to <https://github.com/pawjy/perl-promised-file>.

LICENSE

Copyright 2015-2024 Wakaba <[email protected]>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.