| 1 | package App::FileSync::Ignore; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | # .gitignore-style exclusion patterns, compiled once per session and matched | ||||||||||||||||||||||||||||
| 4 | # against every path in the tree. | ||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 330 | ▶ | use App::FileSync::Platform; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | 330 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 9 | 330 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | 330 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||
| 12 | 330 | ▶ | use Readonly; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 13 | 330 | ▶ | use Sub::Private { mode => 'enforce' }; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | 330 | ▶ | use App::FileSync::Args qw(named); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | 330 | ▶ | use version; our $VERSION = version->declare('0.002.1'); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | # A line that is blank or a comment ("# note", or a lone "#"). "#*#" is a | ||||||||||||||||||||||||||||
| 20 | # pattern (Emacs autosave files), as .gitignore allows with a backslash. | ||||||||||||||||||||||||||||
| 21 | 330 | Readonly my $COMMENT => qr/\A\s*(?:#\s|#\z|\z)/; | |||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | =encoding utf8 | ||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | =head1 NAME | ||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||
| 27 | App::FileSync::Ignore - .gitignore-style path exclusion | ||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||
| 29 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | my $ignore = App::FileSync::Ignore->new(patterns => [ '*.tmp', '!keep.tmp', 'build/' ]); | ||||||||||||||||||||||||||||
| 32 | print "skip\n" if $ignore->match('src/a.tmp'); | ||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||
| 34 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||
| 36 | Patterns follow .gitignore: C<*> matches within one component, C<**/> | ||||||||||||||||||||||||||||
| 37 | matches any number of directories, C<?> one character, a leading C<!> | ||||||||||||||||||||||||||||
| 38 | re-includes, a leading C</> anchors at the root, and a pattern without a slash | ||||||||||||||||||||||||||||
| 39 | matches at any depth. Later patterns win. A path inside an ignored directory | ||||||||||||||||||||||||||||
| 40 | is ignored. | ||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||
| 42 | =head1 METHODS | ||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||
| 44 | =head2 new | ||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||
| 46 | Purpose: compile a list of patterns. | ||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||
| 48 | Args: C<patterns> (arrayref of strings; undefined entries, blanks and comments | ||||||||||||||||||||||||||||
| 49 | are skipped), C<case_insensitive> (boolean). | ||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||
| 51 | Returns: an C<App::FileSync::Ignore> object. | ||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||
| 53 | Side Effects: none. The caller's list is not modified. | ||||||||||||||||||||||||||||
| 54 | |||||||||||||||||||||||||||||
| 55 | Usage: | ||||||||||||||||||||||||||||
| 56 | |||||||||||||||||||||||||||||
| 57 | my $ignore = App::FileSync::Ignore->new(patterns => $config->{ignore}); | ||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||
| 59 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | my $ignore = App::FileSync::Ignore->new( | ||||||||||||||||||||||||||||
| 62 | patterns => [ '*.bak', '# editor files', '*~' ], | ||||||||||||||||||||||||||||
| 63 | case_insensitive => 1, | ||||||||||||||||||||||||||||
| 64 | ); | ||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||
| 66 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | =head4 INPUT | ||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||
| 70 | { | ||||||||||||||||||||||||||||
| 71 | patterns => { type => 'arrayref', optional => 1 }, | ||||||||||||||||||||||||||||
| 72 | case_insensitive => { type => 'boolean', optional => 1 }, | ||||||||||||||||||||||||||||
| 73 | } | ||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||
| 75 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | { type => 'object', isa => 'App::FileSync::Ignore' } | ||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||
| 79 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||
| 81 | Key Meaning Resolution | ||||||||||||||||||||||||||||
| 82 | args.invalid patterns is not a list pass an arrayref | ||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||
| 86 | new(ps, ci) = ⟨compiled ↦ ⟨(neg(p), re(p, ci)) | p ← ps, ¬ comment(p)⟩⟩ | ||||||||||||||||||||||||||||
| 87 | ps' = ps | ||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||
| 89 | =cut | ||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | 600 | ▶ | sub new { | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=8 SCAR=20.8
Pod
documented
| |||||||||||||||||||||||||||||
| 92 | 600 | my $class = shift; | |||||||||||||||||||||||||||
| 93 | 600 | my $args = named(\@_, { | |||||||||||||||||||||||||||
| 94 | patterns => { type => 'arrayref', optional => 1 }, | ||||||||||||||||||||||||||||
| 95 | case_insensitive => { type => 'boolean', optional => 1 }, | ||||||||||||||||||||||||||||
| 96 | }, 'Ignore->new'); | ||||||||||||||||||||||||||||
| 97 | |||||||||||||||||||||||||||||
| 98 | 600 | my @compiled; | |||||||||||||||||||||||||||
| 99 | 600 | ▶ | for my $given (@{ $args->{patterns} || [] }) { | ||||||||||||||||||||||||||
|
Condition100%2/2
$args->{'patterns'} || []
MC/DC100%1/1
$args->{'patterns'} || []
$args->{'patterns'}
Truth table100%2/2
A
A= $args->{'patterns'}
| |||||||||||||||||||||||||||||
| 100 | 7703 | ▶ | next unless defined $given; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 101 | 7703 | ▶ | next if $given =~ $COMMENT; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||
| 103 | # Work on a copy: the list usually belongs to the repo config, which | ||||||||||||||||||||||||||||
| 104 | # the server sends on to the client after building this object. | ||||||||||||||||||||||||||||
| 105 | 7701 | my $raw = $given; | |||||||||||||||||||||||||||
| 106 | 7701 | ▶ | my $negated = $raw =~ s/\A!// ? 1 : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 107 | 7701 | $raw =~ s/\A\s+//; | |||||||||||||||||||||||||||
| 108 | 7701 | $raw =~ s/\s+\z//; | |||||||||||||||||||||||||||
| 109 | 7701 | ▶ | next unless length $raw; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||
| 111 | 7701 | my $re = _glob_to_re($raw); | |||||||||||||||||||||||||||
| 112 | push @compiled, { | ||||||||||||||||||||||||||||
| 113 | negated => $negated, | ||||||||||||||||||||||||||||
| 114 | 7701 | ▶ | re => $args->{case_insensitive} ? qr/\A$re\z/i : qr/\A$re\z/, | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 115 | }; | ||||||||||||||||||||||||||||
| 116 | } | ||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | 600 | return bless { compiled => \@compiled }, $class; | |||||||||||||||||||||||||||
| 119 | } | ||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||
| 121 | =head2 match | ||||||||||||||||||||||||||||
| 122 | |||||||||||||||||||||||||||||
| 123 | Purpose: decide whether a path is excluded. | ||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||
| 125 | Args: C<$path>, relative and C</>-separated. | ||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||
| 127 | Returns: 1 when the path, or any directory above it, is ignored; otherwise 0. | ||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||
| 129 | Side Effects: none. | ||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||
| 131 | Usage: | ||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||
| 133 | next if $ignore->match($relative_path); | ||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||
| 135 | =head3 EXAMPLE | ||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||
| 137 | my $ignore = App::FileSync::Ignore->new(patterns => [ 'build' ]); | ||||||||||||||||||||||||||||
| 138 | print $ignore->match('build/out/a.o'), "\n"; # 1 | ||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||
| 140 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||
| 142 | =head4 INPUT | ||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||
| 144 | [ | ||||||||||||||||||||||||||||
| 145 | { name => 'self', type => 'object' }, | ||||||||||||||||||||||||||||
| 146 | { name => 'path', type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||
| 147 | ] | ||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||
| 149 | =head4 OUTPUT | ||||||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||||
| 151 | { type => 'integer', min => 0, max => 1 } | ||||||||||||||||||||||||||||
| 152 | |||||||||||||||||||||||||||||
| 153 | =head3 MESSAGES | ||||||||||||||||||||||||||||
| 154 | |||||||||||||||||||||||||||||
| 155 | None. Called once per path, so arguments are checked by hand. | ||||||||||||||||||||||||||||
| 156 | |||||||||||||||||||||||||||||
| 157 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | ignored(c) ⇔ last ⟨ ¬neg(p) | p ← compiled, c ∈ re(p) ⟩ = true | ||||||||||||||||||||||||||||
| 160 | match(path) ⇔ ∃ a : {path} ∪ ancestors(path) • ignored(a) | ||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||
| 162 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||
| 163 | |||||||||||||||||||||||||||||
| 164 | candidates := path, then each directory above it | ||||||||||||||||||||||||||||
| 165 | for each candidate: | ||||||||||||||||||||||||||||
| 166 | state := not ignored | ||||||||||||||||||||||||||||
| 167 | for each pattern in order: if it matches, state := not negated | ||||||||||||||||||||||||||||
| 168 | if state is ignored: return 1 | ||||||||||||||||||||||||||||
| 169 | return 0 | ||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||
| 171 | =cut | ||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||
| 173 | 1551 | ▶ | sub match { | ||||||||||||||||||||||||||
|
Subroutine
match: called CC=9 SCAR=22.1
Pod
documented
| |||||||||||||||||||||||||||||
| 174 | 1551 | my ($self, $path) = @_; | |||||||||||||||||||||||||||
| 175 | |||||||||||||||||||||||||||||
| 176 | 1551 | ▶ | return 0 unless defined $path && length $path; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $path and length $path
MC/DC0%0/2
defined $path and length $path
defined $path
length $path
Truth table33%1/3
A and B
A= defined $pathB= length $path
| |||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||
| 178 | # A path inside an ignored directory is ignored too, even if the caller | ||||||||||||||||||||||||||||
| 179 | # only asks about the file (the scanner prunes at the directory, but this | ||||||||||||||||||||||||||||
| 180 | # keeps the answer correct for every caller). | ||||||||||||||||||||||||||||
| 181 | 1551 | my @candidates = ($path); | |||||||||||||||||||||||||||
| 182 | 1551 | my $prefix = $path; | |||||||||||||||||||||||||||
| 183 | 1551 | ▶ | push @candidates, $prefix while $prefix =~ s{/[^/]+\z}{}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||
| 185 | 1551 | for my $candidate (@candidates) { | |||||||||||||||||||||||||||
| 186 | 1663 | my $ignored = 0; | |||||||||||||||||||||||||||
| 187 | 1663 | for my $pattern (@{ $self->{compiled} }) { | |||||||||||||||||||||||||||
| 188 | 20808 | ▶ | $ignored = $pattern->{negated} ? 0 : 1 if $candidate =~ $pattern->{re}; | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 189 | } | ||||||||||||||||||||||||||||
| 190 | 1663 | ▶ | return 1 if $ignored; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 191 | } | ||||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||
| 193 | 1346 | return 0; | |||||||||||||||||||||||||||
| 194 | } | ||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||
| 196 | # _glob_to_re | ||||||||||||||||||||||||||||
| 197 | # Purpose: translate one .gitignore-style glob into a regex body. | ||||||||||||||||||||||||||||
| 198 | # Entry: $pattern has had its "!" and surrounding blanks removed. | ||||||||||||||||||||||||||||
| 199 | # Exit: returns the regex source (not anchored; new() anchors it). | ||||||||||||||||||||||||||||
| 200 | # Side effects: none. Hand-written rather than Text::Glob, which has no | ||||||||||||||||||||||||||||
| 201 | # "**" and no "slash-less pattern matches at any depth" rule. | ||||||||||||||||||||||||||||
| 202 | 7701 | ▶ | sub _glob_to_re :Private { | ||||||||||||||||||||||||||
|
Subroutine
_glob_to_re: called CC=10 SCAR=23.2
| |||||||||||||||||||||||||||||
| 203 | 7701 | my ($pattern) = @_; | |||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | # A leading slash anchors; a trailing one (.gitignore's directory marker) | ||||||||||||||||||||||||||||
| 206 | # does not, so "build/" matches "build" at any depth as git users expect. | ||||||||||||||||||||||||||||
| 207 | 7701 | $pattern =~ s{/\z}{}; | |||||||||||||||||||||||||||
| 208 | 7701 | ▶ | my $anchored = $pattern =~ s{\A/}{} ? 1 : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 209 | 7701 | ▶ | my $has_slash = $pattern =~ m{/} ? 1 : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||
| 211 | # Translate token by token: "**/" any directories, "**" anything, "*" | ||||||||||||||||||||||||||||
| 212 | # within a component, "?" one character, everything else literally. | ||||||||||||||||||||||||||||
| 213 | 7701 | my $re = ''; | |||||||||||||||||||||||||||
| 214 | 7701 | ▶ | while (length $pattern) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 215 | 65706 | ▶ | if ($pattern =~ s{\A\*\*/}{}) { | ||||||||||||||||||||||||||
|
Branch: 4 branches
| |||||||||||||||||||||||||||||
| 216 | 1 | $re .= '(?:.*/)?'; | |||||||||||||||||||||||||||
| 217 | } elsif ($pattern =~ s{\A\*\*}{}) { | ||||||||||||||||||||||||||||
| 218 | 0 | $re .= '.*'; | |||||||||||||||||||||||||||
| 219 | } elsif ($pattern =~ s{\A\*}{}) { | ||||||||||||||||||||||||||||
| 220 | 4738 | $re .= '[^/]*'; | |||||||||||||||||||||||||||
| 221 | } elsif ($pattern =~ s{\A\?}{}) { | ||||||||||||||||||||||||||||
| 222 | 0 | $re .= '[^/]'; | |||||||||||||||||||||||||||
| 223 | } else { | ||||||||||||||||||||||||||||
| 224 | 60967 | $re .= quotemeta(substr($pattern, 0, 1, '')); | |||||||||||||||||||||||||||
| 225 | } | ||||||||||||||||||||||||||||
| 226 | } | ||||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||||
| 228 | # A pattern without a slash matches any path segment, like .gitignore. | ||||||||||||||||||||||||||||
| 229 | 7701 | ▶ | return ($anchored || $has_slash) ? $re : "(?:.*/)?$re"; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$anchored or $has_slash
MC/DC100%2/2
$anchored or $has_slash
$anchored
$has_slash
Truth table100%3/3
A or B
A= $anchoredB= $has_slash
| |||||||||||||||||||||||||||||
| 230 | 330 | ▶ | } | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 231 | |||||||||||||||||||||||||||||
| 232 | 330 | 1; | |||||||||||||||||||||||||||
| 233 | |||||||||||||||||||||||||||||
| 234 | __END__ | ||||||||||||||||||||||||||||