/ 
File-Temp-MoreUtils-0.005
River stage one • 3 direct dependents • 5 total dependents
/ File::Temp::MoreUtils

NAME

File::Temp::MoreUtils - Provide more routines related to creating temporary files/dirs

VERSION

This document describes version 0.005 of File::Temp::MoreUtils (from Perl distribution File-Temp-MoreUtils), released on 2021-07-20.

SYNOPSIS

FUNCTIONS

tempdir_named

Usage:

tempdir_named(%args) -> any

Try to create a temporary directory with certain name (but used .1, .2, ... suffix if already exists) .

Examples:

  • Attempt to create /foo/source.dir/, and if already exists /foo/source.1.dir/ instead, and so on:

    tempdir_named(name => "/foo/source.dir");

  • Attempt to create source/ inside another temporary directory, and if already exists source.1/, and so on:

    tempdir_named(name => "source", dir => undef);

  • Attempt to create source.dir/, and if already exists source.tmp1.dir/, then source.tmp2.pdf, and so on:

    tempdir_named(name => "source.dir", suffix_start => "tmp1");

This is similar to tempfile_named(), but since there is no O_EXCL flag similar to opening a file, there is a race condition possible where you create a certain temporary directory and before you open/read the directory, someone else has replaced the directory with another. Therefore it is best if you create the specifically-named temporary directory inside another temporary directory.

Like File::Temp's tempdir(), it will return the path of the created temporary directory:

$dir

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • dir => dirname

    If specified, will create the temporary directory here.

    If specified and set to undef, will create new temporary directory using File::Temp's tempdir (with CLEANUP option set to true unless DEBUG environment variable is set to true) and use this temporary directory for the directory, including for subsequent invocation for the same process whenever dir is set to undef again.

  • name* => filename

  • suffix_start => str (default: 1)

    Will use Perl's post-increment operator (++) to increment the suffix, so this works with number as well as letter combinations, e.g. aa will be incremented to ab, ac and so on.

Return value: (any)

tempfile_named

Usage:

tempfile_named(%args) -> any

Try to create a temporary file with certain name (but used .1, .2, ... suffix if already exists) .

Examples:

  • Attempt to create source.pdf, and if already exists source.1.pdf, and so on:

    tempfile_named(name => "source.pdf");

  • Attempt to create source.pdf in a temporary directory, and if already exists source.1, and so on:

    tempfile_named(name => "source", dir => undef);

  • Attempt to create source.pdf, and if already exists source.tmp1.pdf, then source.tmp2.pdf, and so on:

    tempfile_named(name => "source.pdf", suffix_start => "tmp1");

Unlike File::Temp's tempfile() which creates a temporary file with a unique random name, this routine tries to create a temporary file with a specific name, but adds a counter suffix when the specified name already exists. Care has been taken to avoid race condition (using O_EXCL flag of sysopen). This is often desirable in the case when we want the temporary file to have a name similarity with another file.

And like File::Temp's tempfile(), will return:

($fh, $filename)

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • dir => dirname

    If specified, will create the temporary file here.

    If specified and set to undef, will create new temporary directory using File::Temp's tempdir (with CLEANUP option set to true unless DEBUG environment variable is set to true) and use this temporary directory for the directory, including for subsequent invocation for the same process whenever dir is set to undef again.

  • name* => filename

  • suffix_start => str (default: 1)

    Will use Perl's post-increment operator (++) to increment the suffix, so this works with number as well as letter combinations, e.g. aa will be incremented to ab, ac and so on.

Return value: (any)

ENVIRONMENT

DEBUG

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/File-Temp-MoreUtils.

SOURCE

Source repository is at https://github.com/perlancar/perl-File-Temp-MoreUtils.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=File-Temp-MoreUtils

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

File::Temp

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by perlancar@cpan.org.

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