view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

version 0.016

# SYNOPSIS

    # Use the utf-8 versions of find and finddepth
    use File::Find::utf8;
    find(\&wanted, @directories_to_search);

    # Revert back to non-utf-8 versions
    no File::Find::utf8;
    finddepth(\&wanted, @directories_to_search);

    # Export only the find function
    use File::Find::utf8 qw(find);
    find(\&wanted, @directories_to_search);

    # Export no functions
    use File::Find::utf8 qw(:none); # NOT "use File::Find::utf8 qw();"!
    File::Find::find(\&wanted, @directories_to_search);

# DESCRIPTION

While the original [File::Find](https://metacpan.org/pod/File%3A%3AFind) functions are capable of handling
UTF-8 quite well, they expect and return all data as bytes, not as
characters.

This module replaces the [File::Find](https://metacpan.org/pod/File%3A%3AFind) functions with fully UTF-8
aware versions, both expecting and returning characters.

**Note:** Replacement of functions is not done on DOS, Windows, and OS/2
as these systems do not have full UTF-8 file system support.

## Behaviour

The module behaves as a pragma so you can use both `use
File::Find::utf8` and `no File::Find::utf8` to turn utf-8 support on
or off.

By default, both find() and finddepth() are exported (as with the original
[File::Find](https://metacpan.org/pod/File%3A%3AFind)), if you want to prevent this, use `use File::Find::utf8
qw(:none)`. (As all the magic happens in the module's import function,
you can not simply use `use File::Find::utf8 qw()`)

[File::Find](https://metacpan.org/pod/File%3A%3AFind) warning levels are properly propagated. Note though that
for propagation of fatal [File::Find](https://metacpan.org/pod/File%3A%3AFind) warnings, Perl 5.12 or higher
is required (or the appropriate version of [warnings](https://metacpan.org/pod/warnings)).

# ATTRIBUTES

## $File::Find::utf8::SPECIALVARS

By default `File::Find::utf8` only decodes the _normal_
[File::Find](https://metacpan.org/pod/File%3A%3AFind) variables `$_`, `$File::Find::name`,
`$File::Find::dir`, and (when `follow` or `follow_fast` is in
effect) `$File::Find::fullname` for use in the `preprocess`,
`wanted`, and `postporcess` functions.

If for any reason (e.g., compatibility with find.pl or find2perl) you
also need the _special_ variables `$File::Find::topdir`,
`$File::Find::topdev`, `$File::Find::topino`,
`$File::Find::topmode`, and `$File::Find::topnlink` to be decoded,
specify `local $File::Find::utf8::COMPATILBILITY = 1;` in your
code. The extra decoding that needs to happen will impact performance
though, so use only when absolutely necessary.

## $File::Find::utf8::UTF8\_CHECK

By default `File::Find::utf8` marks decoding errors as fatal (default value
for this setting is `Encode::FB_CROAK`). If you want, you can change this by
setting `File::Find::utf8::UTF8_CHECK`. The value `Encode::FB_WARN` reports
the encoding errors as warnings, and `Encode::FB_DEFAULT` will completely
ignore them. Please see [Encode](https://metacpan.org/pod/Encode) for details. Note: `Encode::LEAVE_SRC` is
_always_ enforced.

# BUGS

Please report any bugs or feature requests on the bugtracker
[website](https://github.com/HayoBaan/File-Find-utf8/issues).

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.

# COMPATIBILITY

The filesystems of Dos, Windows, and OS/2 do not (fully) support
UTF-8. The [File::Find](https://metacpan.org/pod/File%3A%3AFind) function will therefore not be replaced on these
systems.

# SEE ALSO

- [File::Find](https://metacpan.org/pod/File%3A%3AFind) -- The original module.
- [Cwd::utf8](https://metacpan.org/pod/Cwd%3A%3Autf8) -- Fully utf-8 aware version of the [Cwd](https://metacpan.org/pod/Cwd) functions.
- [utf8::all](https://metacpan.org/pod/utf8%3A%3Aall) -- Turn on utf-8, all of it. This was also the module I first added the utf-8 aware versions of [Cwd](https://metacpan.org/pod/Cwd) and [File::Find](https://metacpan.org/pod/File%3A%3AFind) to bef...

# AUTHOR

Hayo Baan <info@hayobaan.com>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Hayo Baan.

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