lib/App/Test/Generator/Provenance.pm

filter: Statementstmt 100% 52 / 52 Branchbran 62.5% 5 / 8 Conditioncond 41.6% 5 / 12 MC/DCmcdc 14.2% 1 / 7 Subroutinesub 100% 17 / 17 Podpod 100% 6 / 6 totaltotal 84.3% 86 / 102 CC 9 SCAR 8.9
CC
9
Cov
86%
source_checks_types
5.0
source_is_valid
4.2
source_is_documented
3.3
CRAP 2.4
« lib/App/Test/Generator/Mutation/Base.pm ↑ Summary blib/lib/App/Test/Generator/Exporter/YAML.pm »
1 package App::Test::Generator::Provenance;
2  
3 388 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 388 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 388 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 388 our $VERSION = '0.50';
9  
10 388 our @EXPORT_OK = qw(
11 SOURCE_VALIDATOR SOURCE_INPUT_SPEC SOURCE_POD
12 SOURCE_CODE SOURCE_SIGNATURE SOURCE_FIELD
13 sources documented_sources type_checks_source
14 source_is_valid source_is_documented source_checks_types
15 );
16  
17 =head1 NAME
18  
19 App::Test::Generator::Provenance - The allowed values of a schema parameter's C<_source> marker
20  
21 =head1 VERSION
22  
23 Version 0.50
24  
25 =head1 SYNOPSIS
26  
27 use App::Test::Generator::Provenance qw(
28 SOURCE_POD source_is_documented source_is_valid
29 );
30  
31 # When the extractor records where a parameter came from
32 $spec->{_source} = SOURCE_POD;
33  
34 # When the harness decides whether a constraint is documentation
35 $is_hint = source_is_documented($spec->{_source});
36  
37 =head1 DESCRIPTION
38  
39 Every generated schema parameter carries a C<_source> marker saying where
40 its type and constraints came from. The extractor writes the marker and
41 the generated harness reads it, so both must agree on the same set of
42 values. Defining that set here, once, stops the two from drifting apart:
43 the extractor can only emit a value from L</sources>, and the harness only
44 treats a value from L</documented_sources> as documentation.
45  
46 The markers are:
47  
48 value meaning
49 validator the routine's own validator confirmed the type
50 input_spec an input specification in the POD declared the type
51 pod ordinary POD prose declared the type or a constraint
52 code the routine's code revealed the parameter
53 signature a subroutine signature declared the parameter
54 field a field declaration declared the parameter
55  
56 A documented marker (C<input_spec> or C<pod>) describes valid input; it
57 is not a check the routine was seen to make. C<validator> is the marker
58 that says the routine checks types itself. The other markers say only
59 that the parameter exists.
60  
61 =head1 CONSTANTS
62  
63 =head2 SOURCE_VALIDATOR, SOURCE_INPUT_SPEC, SOURCE_POD, SOURCE_CODE, SOURCE_SIGNATURE, SOURCE_FIELD
64  
65 The six allowed marker values, exported on request.
66  
67 =head1 FUNCTIONS
68  
69 =head2 sources
70  
71 Returns the allowed marker values as a list. Use it to validate a marker
72 read from a schema.
73  
74 =head3 API SPECIFICATION
75  
76 =head4 input
77  
78 {}
79  
80 =head4 output
81  
82 {}
83  
84 A list of strings, not a reference. No type is declared because the schema
85 format has no type for a returned list.
86  
87 =head2 documented_sources
88  
89 Returns the markers that describe documentation rather than an enforced
90 check: C<pod> and C<input_spec>.
91  
92 =head3 API SPECIFICATION
93  
94 =head4 input
95  
96 {}
97  
98 =head4 output
99  
100 {}
101  
102 A list of strings, not a reference. No type is declared because the schema
103 format has no type for a returned list.
104  
105 =head2 type_checks_source
106  
107 Returns the marker that says the routine checks types itself:
108 C<validator>.
109  
110 =head3 API SPECIFICATION
111  
112 =head4 input
113  
114 {}
115  
116 =head4 output
117  
118 { type => SCALAR }
119  
120 =head2 source_is_valid
121  
122 $ok = source_is_valid($source);
123  
124 True when the marker is one of L</sources>.
125  
126 =head3 API SPECIFICATION
127  
128 =head4 input
129  
130 {
131 source => { type => 'any', optional => 1 },
132 }
133  
134 An undefined value or a reference is never a marker and gives 0; nothing
135 is thrown.
136  
137 =head4 output
138  
139 { type => SCALAR }
140  
141 1 or 0.
142  
143 =head2 source_is_documented
144  
145 $hint = source_is_documented($source);
146  
147 True when the marker is one of L</documented_sources>. An undefined or
148 unknown marker is not documentation.
149  
150 =head3 API SPECIFICATION
151  
152 =head4 input
153  
154 {
155 source => { type => 'any', optional => 1 },
156 }
157  
158 An undefined value or a reference is never a marker and gives 0; nothing
159 is thrown.
160  
161 =head4 output
162  
163 { type => SCALAR }
164  
165 1 or 0.
166  
167 =head2 source_checks_types
168  
169 $checked = source_checks_types($source);
170  
171 True when the marker is L</type_checks_source>.
172  
173 =head3 API SPECIFICATION
174  
175 =head4 input
176  
177 {
178 source => { type => 'any', optional => 1 },
179 }
180  
181 An undefined value or a reference is never a marker and gives 0; nothing
182 is thrown.
183  
184 =head4 output
185  
186 { type => SCALAR }
187  
188 1 or 0.
189  
190 =head1 AUTHOR
191  
192 Nigel Horne, C<< <njh at nigelhorne.com> >>
193  
194 =head1 LICENCE AND COPYRIGHT
195  
196 Copyright 2026 Nigel Horne.
197  
198 Usage is subject to the terms of GPL2.
199 If you use it,
200 please let me know.
201  
202 =cut
203  
204 388 ▶use constant SOURCE_VALIDATOR => 'validator';
Subroutine BEGIN: called CC=1 SCAR=0.0
205 388 ▶use constant SOURCE_INPUT_SPEC => 'input_spec';
Subroutine BEGIN: called CC=1 SCAR=0.0
206 388 ▶use constant SOURCE_POD => 'pod';
Subroutine BEGIN: called CC=1 SCAR=0.0
207 388 ▶use constant SOURCE_CODE => 'code';
Subroutine BEGIN: called CC=1 SCAR=0.0
208 388 ▶use constant SOURCE_SIGNATURE => 'signature';
Subroutine BEGIN: called CC=1 SCAR=0.0
209 388 ▶use constant SOURCE_FIELD => 'field';
Subroutine BEGIN: called CC=1 SCAR=0.0
210  
211 388 ▶use constant _SOURCES => [
Subroutine BEGIN: called CC=1 SCAR=0.0
212 SOURCE_VALIDATOR,
213 SOURCE_INPUT_SPEC,
214 SOURCE_POD,
215 SOURCE_CODE,
216 SOURCE_SIGNATURE,
217 SOURCE_FIELD,
218 388 ];
219  
220 388 ▶use constant _DOCUMENTED_SOURCES => [
Subroutine BEGIN: called CC=1 SCAR=0.0
221 SOURCE_POD,
222 SOURCE_INPUT_SPEC,
223 388 ];
224  
225 sub sources
226 254 ▶{
Subroutine sources: called CC=1 SCAR=0.0
Pod documented
227 254 return @{_SOURCES()};
228 }
229  
230 sub documented_sources
231 674 ▶{
Subroutine documented_sources: called CC=1 SCAR=0.0
Pod documented
232 674 return @{_DOCUMENTED_SOURCES()};
233 }
234  
235 sub type_checks_source
236 421 ▶{
Subroutine type_checks_source: called CC=1 SCAR=0.0
Pod documented
237 421 return SOURCE_VALIDATOR();
238 }
239  
240 sub source_is_valid
241 256 ▶{
Subroutine source_is_valid: called CC=4 SCAR=14.5
Pod documented
242 256 my ($source) = @_;
243  
244 256 ▶ return 0 unless defined($source) && !ref($source) && length($source);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $source and not ref $source and length $source 4 252 256
Condition50%3/6
defined $source and not ref $source and length $source
!ll&&!rl&&r
04252
defined $source and not ref $source
!ll&&!rl&&r
00256
MC/DC33%1/3
defined $source and not ref $source and length $source
defined $source not ref $source length $source
Truth table50%2/4
A and not(B) and C
A= defined $sourceB= not ref $sourceC= length $source
ABCresult
0XX0
10X0
1100
1111
245 252 return scalar grep { $_ eq $source } sources();
246 }
247  
248 sub source_is_documented
249 253 ▶{
Subroutine source_is_documented: called CC=3 SCAR=12.0
Pod documented
250 253 my ($source) = @_;
251  
252 253 ▶ return 0 unless defined($source) && !ref($source);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $source and not ref $source 0 253 253
Condition33%1/3
defined $source and not ref $source
!ll&&!rl&&r
00253
MC/DC0%0/2
defined $source and not ref $source
defined $source not ref $source
Truth table33%1/3
A and not(B)
A= defined $sourceB= not ref $source
ABresult
0X0
100
111
253 253 return scalar grep { $_ eq $source } documented_sources();
254 }
255  
256 sub source_checks_types
257 254 ▶{
Subroutine source_checks_types: called CC=4 SCAR=16.1
Pod documented
258 254 my ($source) = @_;
259  
260 254 ▶ return 0 unless defined($source) && !ref($source);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $source and not ref $source 0 254 254
Condition33%1/3
defined $source and not ref $source
!ll&&!rl&&r
00254
MC/DC0%0/2
defined $source and not ref $source
defined $source not ref $source
Truth table33%1/3
A and not(B)
A= defined $sourceB= not ref $source
ABresult
0X0
100
111
261 254 ▶ return ($source eq SOURCE_VALIDATOR()) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$source eq 'validator' ? : 0 254 254
262 }
263  
264 388 1;
« lib/App/Test/Generator/Mutation/Base.pm ↑ Summary blib/lib/App/Test/Generator/Exporter/YAML.pm »