.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Portability::Files 3pm"
.TH Test::Portability::Files 3pm "2009-06-22" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Portability::Files \- Check file names portability
.SH "VERSION"
.IX Header "VERSION"
Version 0.05
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Test::More;
\&    eval "use Test::Portability::Files";
\&    plan skip_all => "Test::Portability::Files required for testing filenames portability" if $@;
\&    options(all_tests => 1);  # to be hyper\-strict
\&    run_tests();
.Ve
.SH "DESCRIPTION"
.IX Header "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 \*(L"Files and Filesystems\*(R" in perlport. 
The author of a distribution can select which tests to execute.
.PP
To use this module, simply copy the code from the synopsis in a test 
file named \fIt/portfs.t\fR for example, and add it to your \fI\s-1MANIFEST\s0\fR. 
You can delete the call to \f(CW\*(C`options()\*(C'\fR to enable only most common tests.
.PP
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:
.IP "\(bu" 4
\&\f(CW\*(C`use_file_find\*(C'\fR is \fInot\fR enabled (check only the names as listed 
in \fI\s-1MANIFEST\s0\fR)
.IP "\(bu" 4
\&\f(CW\*(C`test_amiga_length\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_ansi_chars\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_case\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_dos_length\*(C'\fR is \fInot\fR enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_mac_length\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_one_dot\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_space\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_special_chars\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_symlink\*(C'\fR is enabled
.IP "\(bu" 4
\&\f(CW\*(C`test_vms_length\*(C'\fR is enabled
.PP
To change any option, please see \f(CW\*(C`options()\*(C'\fR.
.SH "EXPORT"
.IX Header "EXPORT"
The following functions are exported:
.IP "\(bu" 4
\&\f(CW\*(C`options()\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`run_tests()\*(C'\fR
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP """options()""" 4
.el .IP "\f(CWoptions()\fR" 4
.IX Item "options()"
Set the module options, in particular, select which tests to execute. 
Expects a hash.
.Sp
\&\fBGeneral options\fR
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`use_file_find\*(C'\fR \- set to 1 to check all the files in the current 
hierarchy using \f(CW\*(C`File::Find\*(C'\fR instead of only checking files listed 
in \fI\s-1MANIFEST\s0\fR.
.RE
.RS 4
.Sp
\&\fBTests\fR
.IP "\(bu" 4
\&\f(CW\*(C`all_tests\*(C'\fR \- select all tests.
.IP "\(bu" 4
\&\f(CW\*(C`test_amiga_length\*(C'\fR \- check that the name fits within AmigaOS name length 
limitations (107 characters).
.IP "\(bu" 4
\&\f(CW\*(C`test_ansi_chars\*(C'\fR \- check that the name only uses the portable filename 
characters as defined by \s-1ANSI\s0\ C and recommended by perlport.
.IP "\(bu" 4
\&\f(CW\*(C`test_case\*(C'\fR \- check that the name of the file does not clash with 
the name of another file on case-insensitive filesystems.
.IP "\(bu" 4
\&\f(CW\*(C`test_dir_noext\*(C'\fR \- check that the directory has no extension.
.IP "\(bu" 4
\&\f(CW\*(C`test_dos_length\*(C'\fR \- check that the name fits within \s-1DOS\s0 name length limitations 
(8 characters max for the base name, 3 characters max for the extension).
.IP "\(bu" 4
\&\f(CW\*(C`test_mac_length\*(C'\fR \- check that the name fits within Mac \s-1OS\s0 Classic name length 
limitations (31 characters).
.IP "\(bu" 4
\&\f(CW\*(C`test_one_dot\*(C'\fR \- check that the name only has one dot.
.IP "\(bu" 4
\&\f(CW\*(C`test_space\*(C'\fR \- check that the name has nos space.
.IP "\(bu" 4
\&\f(CW\*(C`test_special_chars\*(C'\fR \- check that the name does not use special characters.
.IP "\(bu" 4
\&\f(CW\*(C`test_symlink\*(C'\fR \- check that the file is not a symbolic link.
.IP "\(bu" 4
\&\f(CW\*(C`test_vms_length\*(C'\fR \- check that the name fits within \s-1VMS\s0 name length limitations 
(39 characters max for the base name, 39 characters max for the extension).
.RE
.RS 4
.Sp
\&\fBExample\fR
.Sp
.Vb 1
\&    options(use_file_find => 1, all_tests => 1);
.Ve
.Sp
selects all tests and runs them against all files found using \f(CW\*(C`File::Find\*(C'\fR.
.RE
.ie n .IP """test_name_portability()""" 4
.el .IP "\f(CWtest_name_portability()\fR" 4
.IX Item "test_name_portability()"
Test the portability of the given file name.
.ie n .IP """run_tests()""" 4
.el .IP "\f(CWrun_tests()\fR" 4
.IX Item "run_tests()"
Execute the tests selected by \f(CW\*(C`options()\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perlport
.SH "AUTHOR"
.IX Header "AUTHOR"
Se\*'bastien Aperghis-Tramoni, <sebastien@aperghis.net>
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-test\-portability\-files@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.  I will be notified, and then you'll automatically
be notified of progress on your bug as I make changes.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2004 Se\*'bastien Aperghis-Tramoni, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.