NAME

Test::PureASCII - Test that only ASCII characteres are used in your code

SYNOPSIS

use Test::PureASCII;
all_perl_files_are_pure_ascii();

or

use Test::PureASCII tests => $how_many;
file_is_pure_ascii($filename1, "only ASCII in $filaname1");
file_is_pure_ascii({ skip_data => 1 }, $filename2, "only ASCII in $filaname2");
...

The usual pure-ASCII test looks like:

use Test::More;
eval "use Test::PureASCII";
plan skip_all => "Test::PureASCII required" if $@;
all_perl_files_are_pure_ascii();

DESCRIPTION

This module allows to create tests to ensure that only 7-bit ASCII characters are used on Perl source files.

EXPORT

The functions available from this module are described next.

All of them accept as first argument a reference to a hash containing optional parameters. The usage of those parameters is explained on the Options subchapter.

file_is_pure_ascii([\%opts,] $filename [, $test_name])

checks that $filename contains only ASCII characters.

The optional argument $test_name will be included on the output when reporting errors.

all_perl_files_are_pure_ascii([\%opts,] @dirs)

find all the Perl source files contained in directories @dirs recursively and check that they only contain ASCII characters.

blib is used as the default directory if none is given.

all_files_are_pure_ascii([\%opts,] @dirs)

find all the files (Perl and non-Perl) contained in directories @dirs recursively and check that they only contain ASCII characters.

The current directory is used as the default directory if none is given.

Options

All the functions from this module accept the following options:

skip => \@list_of_files

@list_of_files can contain any combination of string and references to regular expressions. Files matching any of the entries will be skipped.

For instance:

all_files_are_pure_ascii({ skip => [qr/\.dat$/] });

skip_data => 1

On Perl files, skip any __DATA__ section found at the end.

forbid_control => 1

Tests fail when any control character that is not tab, CR neither LF is found.

forbid_tab => 1

Tests fail when tab characters are found.

forbid_cr => 1

Tests fail when carriage return (CR) characters are found. That can be useful when you want to force people working on your project to use the Unix conventions for line endings.

require_crlf => 1

Test fail when any CR or LF not being part of a CRLF sequence is found. That can be useful when you want to stick to Windows line ending conventions.

HINTS

The module recognizes some sequences or hints on the tested files that allow to skip specific exceptions. Usually you would include them as Perl comments.

pa_test_ignore

the line where this token is found is not checked for pure-ascii

pa_test_skip_lines($n)

the line where this token is found and the following $n are skipped

pa_test_end

the test for this file ends when this token is found

SEE ALSO

A nice table containing Unicode and Latin1 codes for common (at least in Europe) non-ASCII characters is available from http://www.alanwood.net/demos/ansi.html.

AUTHOR

Salvador Fañdino, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Qindel Formacion y Servicios S.L.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

This module contains code copied from Test::Pod Copyright (C) 2006 by Andy Lester.