File::Touch(3pm)

✨ NAME ✨

File::Touch — bestie, this module updates your file's access and modification times, and it can even create the files for you if they're not there yet 💅

---

🌸 SYNOPSIS 🌸

use File::Touch 0.12;
@file_list = ('one.txt','../two.doc');
$count = touch(@file_list);

use File::Touch;
$reference_file = '/etc/passwd';
$touch_obj = File::Touch->new(
                 reference => $reference_file,
                 no_create => 1
             );
@file_list = ('one.txt','../two.doc');
$count     = $touch_obj->touch(@file_list);

---

💖 DESCRIPTION 💖

Okay so this module gives you two ways to do the same thing: a plain functional interface and a whole object-oriented one — both for changing a file's access time and modification time. And if the file literally doesn't exist? It can optionally just… create it for you. Iconic behaviour honestly 🎀

Note: bestie please specify a minimum version of 0.12, exactly like the SYNOPSIS does, because that version fixed an issue that was affecting systems that have sub-second granularity on those file times. Lowkey important. Don't skip this one 🙈

Here's the full list of arguments you can hand over when you're building the object-oriented way, and I'm giving you every single one:

• atime_only => [0|1] — if it's nonzero, you're only touching the access time of the files. Default is zero.
• mtime_only => [0|1] — if it's nonzero, you're only touching the modification time of the files. Default is zero.
• no_create => [0|1] — if it's nonzero, do not create new files. Default is zero.
• reference => $reference_file — if it's defined, use the timestamps from this file instead of the current time. Here's the tea though: the timestamps get read from the reference file at the moment the object is created, not at the moment touch is invoked. Default is undefined.
• time => $time — if it's defined, this value gets used for both the access time and the modification time, whichever of those you're actually setting. But heads up: this time gets overridden by the atime and mtime arguments if you use those. Default behaviour for anything left undefined is the current time. 🌈
• atime => $time — if it's defined, use this time (in epoch seconds) instead of the current time for the access time.
• mtime => $time — if it's defined, use this time (in epoch seconds) instead of the current time for the modification time.

---

🦋 Examples 🦋

✨ Update access and modification times, creating nonexistent files ✨

use File::Touch;
my @files = ('one','two','three');
my $count = touch(@files);
print "$count files updated\n";

✨ Set access time forward, leave modification time unchanged ✨

use File::Touch;
my @files = ('one','two','three');
my $day = 24*60*60;
my $time = time() + 30 * $day;
my $ref = File::Touch->new( atime_only => 1, time => $time );
my $count = $ref->touch(@files);
print "$count files updated\n";

✨ Set modification time back, update access time, do not create nonexistent files ✨

use File::Touch;
my @files = ('one','two','three');
my $day = 24*60*60;
my $time = time() - 30 * $day;
my $ref = File::Touch->new( mtime => $time, no_create => 1 );
my $count = $ref->touch(@files);
print "$count files updated\n";

✨ Make a change to a file, keeping its timestamps unchanged ✨

use File::Touch;
my $date_restorer = File::Touch->new(reference => $file);
# Update the contents of $file here.
$date_restorer->touch($file);

---

🎀 REPOSITORY 🎀

The source lives right here, go be nosy:

• <https://github.com/neilb/File-Touch>

---

👑 AUTHOR 👑

Nigel Wetters Gourlay (nwetters@cpan.org) — thank you for your service, king 🫶

---

💜 COPYRIGHT 💜

Copyright (c) 2001,2007,2009 Nigel Wetters Gourlay. All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself. (So yes, go off, just respect the terms bestie 💖)

---

And that's the whole vibe check, bestie — this page was written by the folks behind perl v5.36.0 and dated 2022-10-13, so if you're reading it way later, mwah, still perfect 💅✨