1File::Find::utf8(3)   User Contributed Perl Documentation  File::Find::utf8(3)
2
3
4

NAME

6       File::Find::utf8 - Fully UTF-8 aware File::Find
7

VERSION

9       version 0.014
10

SYNOPSIS

12           # Use the utf-8 versions of find and finddepth
13           use File::Find::utf8;
14           find(\&wanted, @directories_to_search);
15
16           # Revert back to non-utf-8 versions
17           no File::Find::utf8;
18           finddepth(\&wanted, @directories_to_search);
19
20           # Export only the find function
21           use File::Find::utf8 qw(find);
22           find(\&wanted, @directories_to_search);
23
24           # Export no functions
25           use File::Find::utf8 qw(:none); # NOT "use File::Find::utf8 qw();"!
26           File::Find::find(\&wanted, @directories_to_search);
27

DESCRIPTION

29       While the original File::Find functions are capable of handling UTF-8
30       quite well, they expect and return all data as bytes, not as
31       characters.
32
33       This module replaces the File::Find functions with fully UTF-8 aware
34       versions, both expecting and returning characters.
35
36       Note: Replacement of functions is not done on DOS, Windows, and OS/2 as
37       these systems do not have full UTF-8 file system support.
38
39   Behaviour
40       The module behaves as a pragma so you can use both "use
41       File::Find::utf8" and "no File::Find::utf8" to turn utf-8 support on or
42       off.
43
44       By default, both find() and finddepth() are exported (as with the
45       original File::Find), if you want to prevent this, use use
46       File::Find::utf8 qw(:none). (As all the magic happens in the module's
47       import function, you can not simply use "use File::Find::utf8 qw()")
48
49       File::Find warning levels are properly propagated. Note though that for
50       propagation of fatal File::Find warnings, Perl 5.12 or higher is
51       required (or the appropriate version of warnings).
52

ATTRIBUTES

54   $File::Find::utf8::SPECIALVARS
55       By default "File::Find::utf8" only decodes the normal File::Find
56       variables $_, $File::Find::name, $File::Find::dir, and (when "follow"
57       or "follow_fast" is in effect) $File::Find::fullname for use in the
58       "preprocess", "wanted", and "postporcess" functions.
59
60       If for any reason (e.g., compatibility with find.pl or find2perl) you
61       also need the special variables $File::Find::topdir,
62       $File::Find::topdev, $File::Find::topino, $File::Find::topmode, and
63       $File::Find::topnlink to be decoded, specify "local
64       $File::Find::utf8::COMPATILBILITY = 1;" in your code. The extra
65       decoding that needs to happen will impact performance though, so use
66       only when absolutely necessary.
67
68   $File::Find::utf8::UTF8_CHECK
69       By default "File::Find::utf8" marks decoding errors as fatal (default
70       value for this setting is "Encode::FB_CROAK"). If you want, you can
71       change this by setting "File::Find::utf8::UTF8_CHECK". The value
72       "Encode::FB_WARN" reports the encoding errors as warnings, and
73       "Encode::FB_DEFAULT" will completely ignore them. Please see Encode for
74       details. Note: "Encode::LEAVE_SRC" is always enforced.
75

BUGS

77       Please report any bugs or feature requests on the bugtracker website
78       <https://github.com/HayoBaan/File-Find-utf8/issues>.
79
80       When submitting a bug or request, please include a test-file or a patch
81       to an existing test-file that illustrates the bug or desired feature.
82

COMPATIBILITY

84       The filesystems of Dos, Windows, and OS/2 do not (fully) support UTF-8.
85       The File::Find function will therefore not be replaced on these
86       systems.
87

SEE ALSO

89       •   File::Find -- The original module.
90
91       •   Cwd::utf8 -- Fully utf-8 aware version of the Cwd functions.
92
93       •   utf8::all -- Turn on utf-8, all of it. This was also the module I
94           first added the utf-8 aware versions of Cwd and File::Find to
95           before moving them to their own package.
96

AUTHOR

98       Hayo Baan <info@hayobaan.com>
99

101       This software is copyright (c) 2014 by Hayo Baan.
102
103       This is free software; you can redistribute it and/or modify it under
104       the same terms as the Perl 5 programming language system itself.
105
106
107
108perl v5.38.0                      2023-07-20               File::Find::utf8(3)
Impressum