| 1 | # | ||||||||||
| 2 | # Copyright (c) 2003-2020 Christian Jaeger, copying@christianjaeger.ch | ||||||||||
| 3 | # | ||||||||||
| 4 | # This is free software, offered under either the same terms as perl 5 | ||||||||||
| 5 | # or the terms of the Artistic License version 2 or the terms of the | ||||||||||
| 6 | # MIT License (Expat version). See the file COPYING.md that came | ||||||||||
| 7 | # bundled with this file. | ||||||||||
| 8 | # | ||||||||||
| 9 | |||||||||||
| 10 | =head1 NAME | ||||||||||
| 11 | |||||||||||
| 12 | Chj::xopendir | ||||||||||
| 13 | |||||||||||
| 14 | =head1 SYNOPSIS | ||||||||||
| 15 | |||||||||||
| 16 | use Chj::xopendir; | ||||||||||
| 17 | { | ||||||||||
| 18 | my $dir = xopendir "/foo"; | ||||||||||
| 19 | while (defined(my $item = $dir->read)) { | ||||||||||
| 20 | print $item; | ||||||||||
| 21 | } | ||||||||||
| 22 | } # $dir is closed automatically (issuing a warning on error) | ||||||||||
| 23 | |||||||||||
| 24 | =head1 DESCRIPTION | ||||||||||
| 25 | |||||||||||
| 26 | Something like IO::Dir, but more lightweight (IO::Dir takes about 0.3 seconds | ||||||||||
| 27 | to load on my laptop, whereas this module takes less than 30ms), and with | ||||||||||
| 28 | functions/methods that throw (currently untyped) exceptions on error. | ||||||||||
| 29 | |||||||||||
| 30 | |||||||||||
| 31 | =head1 FUNCTIONS | ||||||||||
| 32 | |||||||||||
| 33 | =over 4 | ||||||||||
| 34 | |||||||||||
| 35 | =item xopendir ("path") | ||||||||||
| 36 | |||||||||||
| 37 | Open the given dir or croak on errors. Returns an anonymous symbol | ||||||||||
| 38 | blessed into Chj::xopendir::dir, which can be used both as object | ||||||||||
| 39 | or filehandle (more correctly: anonymous glob) (? always? Perl is a | ||||||||||
| 40 | bit complicated when handling filehandles in indirect object notation). | ||||||||||
| 41 | |||||||||||
| 42 | =item perhaps_opendir ($path) | ||||||||||
| 43 | |||||||||||
| 44 | Try to open given directory path, if successful return the filehandle, | ||||||||||
| 45 | otherwise return () and leave $! set. | ||||||||||
| 46 | |||||||||||
| 47 | =item perhaps_xopendir ($path) | ||||||||||
| 48 | |||||||||||
| 49 | Same as perhaps_opendir but throw exception on all errors except for | ||||||||||
| 50 | ENOENT. | ||||||||||
| 51 | |||||||||||
| 52 | =back | ||||||||||
| 53 | |||||||||||
| 54 | =head1 CLASS METHODS | ||||||||||
| 55 | |||||||||||
| 56 | =over 4 | ||||||||||
| 57 | |||||||||||
| 58 | =item new ("path") | ||||||||||
| 59 | |||||||||||
| 60 | Same as xopendir, but in object oriented notation (overridable). | ||||||||||
| 61 | |||||||||||
| 62 | =back | ||||||||||
| 63 | |||||||||||
| 64 | =head1 OBJECT METHODS | ||||||||||
| 65 | |||||||||||
| 66 | =over 4 | ||||||||||
| 67 | |||||||||||
| 68 | =item read | ||||||||||
| 69 | |||||||||||
| 70 | =item xread | ||||||||||
| 71 | |||||||||||
| 72 | Read one dir entry in scalar context, all entries in list context. | ||||||||||
| 73 | xread croaks if it detects an error, though it's quite unsure if | ||||||||||
| 74 | that really works (see also module source). | ||||||||||
| 75 | |||||||||||
| 76 | =item nread | ||||||||||
| 77 | |||||||||||
| 78 | =item xnread | ||||||||||
| 79 | |||||||||||
| 80 | Same as read/xread but discard "." and ".." entries. | ||||||||||
| 81 | |||||||||||
| 82 | =item xclose | ||||||||||
| 83 | |||||||||||
| 84 | Close dirhandle and croak on error. (If not called before descruction | ||||||||||
| 85 | of the object, the filehandle is closed anyway, but only a warning | ||||||||||
| 86 | is issued upon errors in that case.) | ||||||||||
| 87 | |||||||||||
| 88 | =back | ||||||||||
| 89 | |||||||||||
| 90 | =head1 SEE ALSO | ||||||||||
| 91 | |||||||||||
| 92 | L<Chj::xopen> | ||||||||||
| 93 | |||||||||||
| 94 | =head1 NOTE | ||||||||||
| 95 | |||||||||||
| 96 | This is alpha software! Read the status section in the package README | ||||||||||
| 97 | or on the L<website|http://functional-perl.org/>. | ||||||||||
| 98 | |||||||||||
| 99 | =cut | ||||||||||
| 100 | |||||||||||
| 101 | #' | ||||||||||
| 102 | |||||||||||
| 103 | package Chj::xopendir; | ||||||||||
| 104 | 25 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 105 | 25 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 106 | 25 | ▶ | use warnings FATAL => 'uninitialized'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 107 | 25 | ▶ | use Chj::IO::Dir; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 108 | 25 | ▶ | use Exporter 'import'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 109 | |||||||||||
| 110 | 25 | our @EXPORT = qw(xopendir perhaps_opendir perhaps_xopendir); | |||||||||
| 111 | |||||||||||
| 112 | 25 | ▶ | use FP::Carp; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 113 | |||||||||||
| 114 | 0 | ▶ | sub xopendir { | ||||||||
|
Subroutine
xopendir: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 115 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 116 | 0 | unshift @_, 'Chj::IO::Dir'; | |||||||||
| 117 | 0 | goto &Chj::IO::Dir::xopendir; | |||||||||
| 118 | } | ||||||||||
| 119 | |||||||||||
| 120 | 0 | ▶ | sub perhaps_opendir { | ||||||||
|
Subroutine
perhaps_opendir: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 121 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 122 | 0 | unshift @_, 'Chj::IO::Dir'; | |||||||||
| 123 | 0 | goto &Chj::IO::Dir::perhaps_opendir; | |||||||||
| 124 | } | ||||||||||
| 125 | |||||||||||
| 126 | 0 | ▶ | sub perhaps_xopendir { | ||||||||
|
Subroutine
perhaps_xopendir: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 127 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 128 | 0 | unshift @_, 'Chj::IO::Dir'; | |||||||||
| 129 | 0 | goto &Chj::IO::Dir::perhaps_xopendir; | |||||||||
| 130 | } | ||||||||||
| 131 | |||||||||||
| 132 | 25 | 1; | |||||||||