NAME

       Test::Portability::Files - Check file names portability

VERSION

       version 0.10

SYNOPSIS

           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

       This module is used to check the portability across operating systems of the names of the
       files present in the distribution of a module.  The tests use the advices given in "Files
       and Filesystems" in perlport.  The author of a distribution can select which tests to
       execute.

       To use this module, simply copy the code from the synopsis in a test file named t/portfs.t
       for example, and add it to your MANIFEST.  You can delete the call to "options()" to
       enable only most common tests.

       By default, not all tests are enabled because some are judged too cumbersome to be
       practical, especially since some of the most limited platforms (like MS-DOS) seem to be no
       longer supported.  Here are the default options:

       •   "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

       To change any option, please see "options()".

EXPORT

       The following functions are exported:

       •   "options()"

       •   "run_tests()"

FUNCTIONS

       "options()"
           Set the module options, in particular, select which tests to execute.  Expects a hash.

           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.

           •   "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.

           •   "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);

           selects all tests and runs them against all files found using "File::Find".

       "test_name_portability()"
           Test the portability of the given file name.

       "run_tests()"
           Execute the tests selected by "options()".

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>

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.

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.