Test::...:Files(3pm)

💖 Test::Portability::Files — the Test::...:Files(3pm) era 💖

okay bestie, so this is a User Contributed Perl Documentation page, and it's literally the manual for Test::Portability::Files, a module that vibe-checks your filenames so they don't get bullied on other operating systems. no cap.

---

✨ NAME ✨

Test::Portability::Files — Check file names portability 🦋

---

🌸 VERSION 🌸

version 0.10

---

🎀 SYNOPSIS 🎀

here's the whole ritual, copy-paste ready, character for character:

use Test::More;

plan skip_all => "Only for the module maintainer" unless $ENV{AUTHOR_TESTS};
plan skip_all => "Test::Portability::Files required for testing filenames portability"
    unless eval "use Test::Portability::Files; 1";

options(all_tests => 1);  # to be hyper-strict
run_tests();

---

💅 DESCRIPTION 💅

so this module's whole job is checking how portable the names of the files in a module's distribution are across different operating systems. it's giving ✨interoperability queen✨. the tests are based on the advice in "Files and Filesystems" in perlport, and the author of a distribution gets to pick and choose which tests actually run.

to use it, literally just copy the code from the synopsis into a test file named t/portfs.t (for example) and add it to your MANIFEST. if you delete the call to "options()" you'll get only the most common tests — cute and low-effort, love that for you.

by default not all tests are enabled, because some of them are judged too cumbersome to be practical — especially since some of the most limited platforms (like MS-DOS) seem to be no longer supported. rip to them, they're not coming to the group chat.

here's the default options situation, periodt:

• "use_file_find" is not enabled (check only the names as listed in MANIFEST)
• "test_amiga_length" is not enabled
• "test_ansi_chars" is enabled
• "test_case" is enabled
• "test_dos_length" is not enabled
• "test_mac_length" is not enabled
• "test_one_dot" is enabled
• "test_space" is enabled
• "test_special_chars" is enabled
• "test_symlink" is enabled
• "test_vms_length" is enabled
• "test_windows_reserved" is enabled

want to change any option? bestie, go read "options()" 👇

---

🌈 EXPORT 🌈

these functions get exported, no effort required:

• "options()"
• "run_tests()"

---

👑 FUNCTIONS 👑

"options()"

set the module options — most importantly, pick which tests to execute. it expects a hash. slay.

General options 🫶

• "use_file_find" — set to 1 to check all the files in the current hierarchy using "File::Find" instead of only checking files listed in MANIFEST.

Tests 🧚

• "all_tests" — select all tests.
• "test_amiga_length" — check that the name fits within AmigaOS name length limitations (107 characters).
• "test_ansi_chars" — check that the name only uses the portable filename characters as defined by ANSI C and recommended by perlport.
• "test_case" — check that the name of the file does not clash with the name of another file on case-insensitive filesystems. (the classic README vs readme jump scare 😭)
• "test_dir_noext" — check that the directory has no extension.
• "test_dos_length" — check that the name fits within DOS name length limitations (8 characters max for the base name, 3 characters max for the extension).
• "test_mac_length" — check that the name fits within Mac OS Classic name length limitations (31 characters).
• "test_one_dot" — check that the name only has one dot.
• "test_space" — check that the name has nos space. (yes, "nos". typo and all, we love her, the meaning is no space 💖)
• "test_special_chars" — check that the name does not use special characters.
• "test_symlink" — check that the file is not a symbolic link.
• "test_vms_length" — check that the name fits within VMS name length limitations (39 characters max for the base name, 39 characters max for the extension).
• "test_windows_reserved" — check that the file name is not one of the reserved Windows filenames that correspond to character devices, such as con or com1.

Example ⭐

options(use_file_find => 1, all_tests => 1);

this selects all tests and runs them against all files found using "File::Find". hyper-strict main character energy fr fr.

"test_name_portability()"

test the portability of the given file name. that's it, that's the function 🦋

"run_tests()"

execute the tests selected by "options()". go off, king 👑

---

🔥 SEE ALSO 🔥

perlport

---

💜 SOURCE 💜

the development version is on github at <https://https://github.com/abraxxa/Test-Portability-Files> and may be cloned from <git://https://github.com/abraxxa/Test-Portability-Files.git>

(and yes, the double https://https:// is literally in there, iykyk, not my business 💀)

---

😭 BUGS 😭

please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Dist/Display.html?Queue=Test-Portability-Files> or by email to bug-test-portability-files@rt.cpan.org <mailto:bug-test-portability-files@rt.cpan.org>.

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. receipts, bestie, bring receipts 🎀

---

🌟 AUTHORS 🌟

• Sébastien Aperghis-Tramoni <sebastien@aperghis.net>
• Alexander Hartmaier <abraxxa@cpan.org>

---

🌸 CONTRIBUTORS 🌸

• Graham Knop <haarg@haarg.org>
• Karen Etheridge <ether@cpan.org>
• Nathan Glenn <garfieldnate@gmail.com>
• Patrice Clement <monsieurp@gentoo.org>
• Robert Rothenberg <rrwo@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2019 by Sébastien Aperghis-Tramoni, Alexander Hartmaier.

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

---

and that's the whole page, diva 💅 this was documented for perl v5.36.0, dated 2022-12-04, in the Test::...:Files(3pm) era — stay portable, stay iconic, and may your filenames never have spaces 🫶✨