NAME
App::Test::Generator::Provenance - The allowed values of a schema parameter's _source marker
VERSION
Version 0.49
SYNOPSIS
use App::Test::Generator::Provenance qw(
SOURCE_POD source_is_documented source_is_valid
);
# When the extractor records where a parameter came from
$spec->{_source} = SOURCE_POD;
# When the harness decides whether a constraint is documentation
$is_hint = source_is_documented($spec->{_source});
DESCRIPTION
Every generated schema parameter carries a _source marker saying where its type and constraints came from. The extractor writes the marker and the generated harness reads it, so both must agree on the same set of values. Defining that set here, once, stops the two from drifting apart: the extractor can only emit a value from "sources", and the harness only treats a value from "documented_sources" as documentation.
The markers are:
value meaning
validator the routine's own validator confirmed the type
input_spec an input specification in the POD declared the type
pod ordinary POD prose declared the type or a constraint
code the routine's code revealed the parameter
signature a subroutine signature declared the parameter
field a field declaration declared the parameter
A documented marker (input_spec or pod) describes valid input; it is not a check the routine was seen to make. validator is the marker that says the routine checks types itself. The other markers say only that the parameter exists.
CONSTANTS
SOURCE_VALIDATOR, SOURCE_INPUT_SPEC, SOURCE_POD, SOURCE_CODE, SOURCE_SIGNATURE, SOURCE_FIELD
The six allowed marker values, exported on request.
FUNCTIONS
sources
Returns the allowed marker values as a list. Use it to validate a marker read from a schema.
API SPECIFICATION
input
{}
output
{}
A list of strings, not a reference. No type is declared because the schema format has no type for a returned list.
documented_sources
Returns the markers that describe documentation rather than an enforced check: pod and input_spec.
API SPECIFICATION
input
{}
output
{}
A list of strings, not a reference. No type is declared because the schema format has no type for a returned list.
type_checks_source
Returns the marker that says the routine checks types itself: validator.
API SPECIFICATION
input
{}
output
{ type => SCALAR }
source_is_valid
$ok = source_is_valid($source);
True when the marker is one of "sources".
API SPECIFICATION
input
{
source => { type => 'any', optional => 1 },
}
An undefined value or a reference is never a marker and gives 0; nothing is thrown.
output
{ type => SCALAR }
1 or 0.
source_is_documented
$hint = source_is_documented($source);
True when the marker is one of "documented_sources". An undefined or unknown marker is not documentation.
API SPECIFICATION
input
{
source => { type => 'any', optional => 1 },
}
An undefined value or a reference is never a marker and gives 0; nothing is thrown.
output
{ type => SCALAR }
1 or 0.
source_checks_types
$checked = source_checks_types($source);
True when the marker is "type_checks_source".
API SPECIFICATION
input
{
source => { type => 'any', optional => 1 },
}
An undefined value or a reference is never a marker and gives 0; nothing is thrown.
output
{ type => SCALAR }
1 or 0.
AUTHOR
Nigel Horne, <njh at nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the terms of GPL2. If you use it, please let me know.