Users/Meta.pm

filter: Statementstmt 96.5% 340 / 352 Branchbran 83.3% 135 / 162 Conditioncond 67.6% 48 / 71 MC/DCmcdc 48.8% 22 / 45 Subroutinesub 100% 31 / 31 Podpod 48.1% 13 / 27 totaltotal 85.6% 589 / 688 CC 122 SCAR 32.7
CC
122
Cov
89%
init_field_meta
63.9
config_to_yaml
17.0
validate_user_data
12.0
CRAP 26.3
↑ Summary Users/File.pm »
1 package Concierge::Users::Meta v0.9.4;
2 8 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 8 ▶use Carp qw/ croak carp /;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 8 ▶use YAML::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 # ABSTRACT: Metadata for fields in Concierge::Users
7  
8 1 ▶sub user_core_fields {
Subroutine user_core_fields: called CC=1 SCAR=0.0
Pod documented
9 1 return @Concierge::Users::Meta::core_fields;
10 }
11  
12 1 ▶sub user_standard_fields {
Subroutine user_standard_fields: called CC=1 SCAR=0.0
Pod documented
13 1 return @Concierge::Users::Meta::standard_fields;
14 }
15  
16 1 ▶sub user_system_fields {
Subroutine user_system_fields: called CC=1 SCAR=0.0
Pod documented
17 1 return @Concierge::Users::Meta::system_fields;
18 }
19  
20 # Get field definition for a specific field
21 # Returns complete hashref with all field attributes (type, default, validation, etc.)
22 # Returns undef if field definition not found in this instance's schema
23 410 ▶sub get_field_definition {
Subroutine get_field_definition: called CC=2 SCAR=7.6
Pod documented
24 410 my ($self, $field) = @_;
25  
26 # Only look in instance field_definitions (set during setup)
27 # Do NOT fall back to master list - schema should be enforced
28 410 ▶ if ($self->{field_definitions}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"field_definitions"}) 410 0 410
29 410 return $self->{field_definitions}{$field};
30 }
31  
32 # No field_definitions available (shouldn't happen in normal use)
33 0 return;
34 }
35  
36  
37 # May be directly called as Concierge::Users::Meta::init_field_meta
38 # or Concierge::Users::Meta->init_field_meta
39 # Users.pm calls it with its config, which includes any
40 # field definitions from the calling app, including
41 # overrides of attributes of the standard field definitions
42 # Returns the whole backend config, which includes the field definitions
43 # as well as the ordered field list.
44 98 ▶sub init_field_meta {
Subroutine init_field_meta: called CC=51 SCAR=41.6
Pod documented
45 98 my ($self, $config) = @_;
46 98 ▶ $config = ref $self eq __PACKAGE__ ? $config : $self;
Branch: 1 branch
BranchTrueFalseTotal
ref $self eq __PACKAGE__ ? : 0 98 98
47  
48 # Get field lists from package arrays
49 98 my @core_fields = @Concierge::Users::Meta::core_fields;
50 98 my @standard_fields = @Concierge::Users::Meta::standard_fields;
51 98 my @system_fields = @Concierge::Users::Meta::system_fields;
52  
53 # Assemble backend user data fields; always include core fields
54 98 my @fields = @core_fields;
55 # Start with built-in field definitions (clone to avoid modifying master hash)
56 my %merged_definitions = map {
57 98 $_ => { $Concierge::Users::Meta::field_definitions{$_}->%* }
58 } @core_fields, @system_fields;
59  
60 # Add requested standard fields
61 98 my @included_std_fields;
62 my @requested_fields;
63 98 ▶ if ( !$config->{include_standard_fields} or $config->{include_standard_fields} =~ /^all$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $config->{'include_standard_fields'} or $config->{'include_standard_fields'} =~ /^all$/iu) { } 26 72 98
Condition100%3/3
not $config->{"include_standard_fields"} or $config->{"include_standard_fields"} =~ /^all$/iu
l!l&&r!l&&!r
32372
MC/DC100%2/2
not $config->{"include_standard_fields"} or $config->{"include_standard_fields"} =~ /^all$/iu
not $config->{"include_standard_fields"} $config->{"include_standard_fields"} =~ /^all$/iu
Truth table100%3/3
not(A) or B
A= not $config->{"include_standard_fields"}B= $config->{"include_standard_fields"} =~ /^all$/iu
ABresult
1X1
011
000
64 26 @included_std_fields = @standard_fields;
65 }
66 else {
67 72 ▶ if ( ref $config->{include_standard_fields} eq 'ARRAY' ) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $config->{'include_standard_fields'} eq 'ARRAY') { } 70 2 72
elsif (not ref $config->{'include_standard_fields'}) { } 2 0 2
68 70 @requested_fields = map { lc $_ } $config->{include_standard_fields}->@*;
69 }
70 elsif ( ! ref $config->{include_standard_fields} ) {
71 2 @requested_fields = map { lc $_ } split /\s*[,;]\s*/ => $config->{include_standard_fields};
72 }
73 72 my %standard_fields = map { $_ => 1 } @standard_fields;
74 72 for my $fld (@requested_fields) {
75 162 ▶ if ($standard_fields{$fld}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($standard_fields{$fld}) { } 160 2 162
76 160 push @included_std_fields => $fld;
77 }
78 else {
79 2 carp "Non-standard field requested: $fld; configure with 'app_fields => [ ...]'";
80 }
81 }
82 }
83 98 push @fields, @included_std_fields;
84 98 for my $fld (@included_std_fields) {
85 $merged_definitions{$fld} = { $Concierge::Users::Meta::field_definitions{$fld}->%* }
86 446 ▶ if $Concierge::Users::Meta::field_definitions{$fld};
Branch: 1 branch
BranchTrueFalseTotal
if $Concierge::Users::Meta::field_definitions{$fld} 446 0 446
87 }
88  
89 # Process field_overrides - modify built-in field definitions
90 # Protected fields (cannot be overridden): user_id, created_date, last_mod_date
91 # Protected attributes (cannot be changed): field_name, category
92 98 ▶ if ($config->{field_overrides}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($config->{"field_overrides"}) 9 89 98
93 # my @protected_fields = qw/ user_id created_date last_mod_date /;
94 # my %protected_fields = map { $_ => 1 } @protected_fields;
95 # my @protected_attrs = qw/ field_name category /;
96 # my %protected_attrs = map { $_ => 1 } @protected_attrs;
97  
98 my @overrides = ref $config->{field_overrides} eq 'ARRAY'
99 ? $config->{field_overrides}->@*
100 9 ▶ : ();
Branch: 1 branch
BranchTrueFalseTotal
ref $config->{'field_overrides'} eq 'ARRAY' ? : 9 0 9
101  
102 9 foreach my $override (@overrides) {
103 13 ▶ next unless ref $override eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $override eq "HASH" 0 13 13
104  
105 13 my $field_name = $override->{field_name};
106 13 ▶ unless ($field_name) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($field_name) 0 13 13
107 0 carp "Field override missing field_name; skipping";
108 0 next;
109 }
110  
111 # Check if field is protected; only format_as and label may be overridden
112 13 ▶ if ( $field_name =~ /^(?:user_id|last_login_date|last_mod_date|created_date)$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($field_name =~ /^(?:user_id|last_login_date|last_mod_date|created_date)$/u) 7 6 13
113 7 my %allowed = map { $_ => 1 } qw/format_as label/;
114 7 my @apply = grep { $allowed{$_} } keys %$override;
115 7 ▶ my @blocked = grep { !$allowed{$_} && $_ ne 'field_name' } keys %$override;
Condition100%3/3
!$allowed{$_} && $_ ne 'field_name'
!ll&&!rl&&r
573
MC/DC100%2/2
!$allowed{$_} && $_ ne 'field_name'
!$allowed{$_} $_ ne 'field_name'
Truth table100%3/3
not(A) && B
A= !$allowed{$_}B= $_ ne 'field_name'
ABresult
0X0
100
111
116 7 ▶ carp "Field '$field_name' is protected; ignoring: " . join(', ', sort @blocked)
Branch: 1 branch
BranchTrueFalseTotal
if @blocked 3 4 7
117 if @blocked;
118 7 $merged_definitions{$field_name}{$_} = $override->{$_} for @apply;
119 7 next;
120 }
121  
122 # Check if field exists in merged_definitions
123 6 ▶ unless ($merged_definitions{$field_name}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($merged_definitions{$field_name}) 0 6 6
124 0 carp "Cannot override unknown field '$field_name'; field must be included via include_standard_fields or app_fields";
125 0 next;
126 }
127  
128 # Process each attribute in the override
129 6 my %warnings;
130 6 foreach my $attr (keys %$override) {
131 # Skip field_name itself (it's the identifier, not an attribute to override)
132 16 ▶ next if $attr eq 'field_name';
Branch: 1 branch
BranchTrueFalseTotal
if $attr eq "field_name" 6 10 16
133  
134 # Skip protected attributes
135 # if ($protected_attrs{$attr}) {
136 10 ▶ if ($attr =~ /field_name|category/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($attr =~ /field_name|category/u) 0 10 10
137 0 $warnings{$attr} = "protected attribute '$attr' cannot be changed";
138 0 next;
139 }
140  
141 # Validate validate_as against known types
142 10 ▶ if ($attr eq 'validate_as') {
Branch: 1 branch
BranchTrueFalseTotal
if ($attr eq "validate_as") 1 9 10
143 1 my $validator_type = $override->{$attr};
144 # unless ($known_validators{$validator_type}) {
145 1 ▶ unless ($Concierge::Users::Meta::type_validator_map{$validator_type}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($Concierge::Users::Meta::type_validator_map{$validator_type}) 1 0 1
146 1 $warnings{$attr} = "unknown validator type '$validator_type' - falling back to 'text'";
147 1 $merged_definitions{$field_name}{$attr} = 'text';
148 1 next;
149 }
150 }
151  
152 # Apply the override
153 9 $merged_definitions{$field_name}{$attr} = $override->{$attr};
154 }
155  
156 # Auto-update validate_as when type is changed (unless validate_as was also explicitly overridden)
157 6 ▶ if (exists $override->{type} && !exists $override->{validate_as}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $override->{"type"} and not exists $override->{"validate_as"}) 1 5 6
Condition66%2/3
exists $override->{"type"} and not exists $override->{"validate_as"}
!ll&&!rl&&r
501
MC/DC50%1/2
exists $override->{"type"} and not exists $override->{"validate_as"}
exists $override->{"type"} not exists $override->{"validate_as"}
Truth table66%2/3
A and not(B)
A= exists $override->{"type"}B= not exists $override->{"validate_as"}
ABresult
0X0
100
111
158 1 my $new_type = $override->{type};
159 # if ($known_validators{$new_type}) {
160 1 ▶ if ($Concierge::Users::Meta::type_validator_map{$new_type}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Concierge::Users::Meta::type_validator_map{$new_type}) 1 0 1
161 1 $merged_definitions{$field_name}{validate_as} = $new_type;
162 }
163 }
164  
165 # Auto-update must_validate when required is set to 1 (unless must_validate was explicitly overridden)
166 6 ▶ if (exists $override->{required} && $override->{required} == 1 && !exists $override->{must_validate}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $override->{"required"} and $override->{"required"} == 1 and not exists $override->{"must_validate"}) 1 5 6
Condition66%4/6
exists $override->{"required"} and $override->{"required"} == 1 and not exists $override->{"must_validate"}
!ll&&!rl&&r
501
exists $override->{"required"} and $override->{"required"} == 1
!ll&&!rl&&r
501
MC/DC33%1/3
exists $override->{"required"} and $override->{"required"} == 1 and not exists $override->{"must_validate"}
exists $override->{"required"} $override->{"required"} == 1 not exists $override->{"must_validate"}
Truth table50%2/4
A and B and not(C)
A= exists $override->{"required"}B= $override->{"required"} == 1C= not exists $override->{"must_validate"}
ABCresult
0XX0
10X0
1100
1111
167 1 $merged_definitions{$field_name}{must_validate} = 1;
168 }
169  
170 # Emit warnings if any
171 6 ▶ if (%warnings) {
Branch: 1 branch
BranchTrueFalseTotal
if (%warnings) 1 5 6
172 1 my $warning_list = join(', ', map { "$_: $warnings{$_}" } sort keys %warnings);
173 1 carp "Field '$field_name' override: $warning_list";
174 }
175 }
176 }
177  
178 # Add app's supplementary fields and merge their definitions
179 # But don't allow use of existing field names
180 98 ▶ if ($config->{app_fields}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($config->{"app_fields"}) 18 80 98
181 18 my %reserved_fields = map { $_ => 1 }
182 @standard_fields, @core_fields, @system_fields;
183 18 my @app_fields;
184 18 ▶ if (ref $config->{app_fields} eq 'ARRAY' ) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $config->{'app_fields'} eq 'ARRAY') { } 18 0 18
elsif (not ref $config->{'app_fields'}) { } 0 0 0
185 18 @app_fields = $config->{app_fields}->@*;
186 }
187 elsif (!ref $config->{app_fields} ) {
188 0 @app_fields = map { lc $_ } split /\s*[,;]\s*/ => $config->{app_fields};
189 }
190 18 FIELD: foreach my $field_def (@app_fields) {
191 23 my $field_name;
192 my $field_definition;
193 23 ▶ if (ref $field_def eq 'HASH') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $field_def eq 'HASH') { } 15 8 23
elsif (not ref $field_def) { } 8 0 8
194 15 $field_name = $field_def->{field_name};
195 15 ▶ if ($reserved_fields{$field_name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($reserved_fields{$field_name}) 0 15 15
196 0 carp "Supplemental field name $field_name already in use";
197 0 next FIELD;
198 }
199 # Build complete definition for app field
200 $field_definition = {
201 field_name => $field_name,
202 label => delete $field_def->{label} || labelize($field_name),
203 category => 'app',
204 # Include all provided attributes (type, default, validation, etc.)
205 map {
206 28 $_ => $field_def->{$_}
207 15 ▶ } grep { !/field_name|label|category/ } keys %$field_def
Condition66%2/3
delete $field_def->{'label'} || labelize($field_name)
l!l&&r!l&&!r
2130
MC/DC0%0/2
delete $field_def->{'label'} || labelize($field_name)
delete $field_def->{'label'} labelize($field_name)
Truth table66%2/3
A || B
A= delete $field_def->{'label'}B= labelize($field_name)
ABresult
1X1
011
000
208 };
209 15 ▶ $field_definition->{required} ||= 0;
Condition100%2/2
$field_definition->{"required"} ||= 0
l!l
114
MC/DC100%1/1
$field_definition->{"required"} ||= 0
$field_definition->{"required"}
Truth table100%2/2
A
A= $field_definition->{"required"}
Aresult
11
00
210 15 ▶ unless ( exists $field_definition->{null_value} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $field_definition->{"null_value"}) 15 0 15
211 15 ▶ $field_definition->{null_value} = $Concierge::Users::Meta::type_null_values{ $field_def->{type} || 'text' };
Condition50%1/2
$field_def->{'type'} || 'text'
l!l
150
MC/DC0%0/1
$field_def->{'type'} || 'text'
$field_def->{'type'}
Truth table50%1/2
A
A= $field_def->{'type'}
Aresult
11
00
212 }
213 } elsif ( !ref $field_def ) {
214 # Simple string field name - create minimal definition
215 8 $field_name = $field_def;
216 8 ▶ if ($reserved_fields{$field_name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($reserved_fields{$field_name}) 2 6 8
217 2 carp "Supplemental field name $field_name already in use";
218 2 next FIELD;
219 }
220 $field_definition = {
221 6 field_name => $field_name,
222 label => labelize($field_name),
223 category => 'app',
224 type => 'text', # Default type
225 validate_as => 'text', # Default validation
226 required => 0,
227 null_value => '',
228 };
229 }
230 21 $merged_definitions{$field_name} = $field_definition;
231 21 push @fields, $field_name;
232 }
233 }
234  
235 # Always add system fields
236 98 push @fields, @system_fields;
237  
238 # Auto-set defaults for enum fields that don't have explicit defaults
239 # Also create v_options (validated options) for internal use:
240 # - strip leading '*' (default marker)
241 # - strip ':Label' suffix (display label; stored value precedes the colon)
242 98 foreach my $field_name (keys %merged_definitions) {
243 1153 my $def = $merged_definitions{$field_name};
244  
245 # Process enum options: create v_options with markers stripped
246 1153 ▶ if ($def->{type} eq 'enum' && $def->{options}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($def->{"type"} eq "enum" and $def->{"options"}) 255 898 1153
Condition66%2/3
$def->{"type"} eq "enum" and $def->{"options"}
!ll&&!rl&&r
8980255
MC/DC50%1/2
$def->{"type"} eq "enum" and $def->{"options"}
$def->{"type"} eq "enum" $def->{"options"}
Truth table66%2/3
A and B
A= $def->{"type"} eq "enum"B= $def->{"options"}
ABresult
0X0
100
111
247 # Strip '*' prefix then ':Label' suffix to get bare stored values
248 255 my @clean_options = map { (s/^\*\s*//r) =~ s/:.*$//r } $def->{options}->@*;
249 255 $merged_definitions{$field_name}{v_options} = \@clean_options;
250  
251 # Auto-set default from * designated option for enum fields
252 # Check if default is undefined OR empty string (both should trigger auto-set)
253 255 ▶ if (!$def->{default} || $def->{default} eq '') {
Branch: 1 branch
BranchTrueFalseTotal
if (not $def->{"default"} or $def->{"default"} eq "") 255 0 255
Condition33%1/3
not $def->{"default"} or $def->{"default"} eq ""
l!l&&r!l&&!r
25500
MC/DC0%0/2
not $def->{"default"} or $def->{"default"} eq ""
not $def->{"default"} $def->{"default"} eq ""
Truth table33%1/3
not(A) or B
A= not $def->{"default"}B= $def->{"default"} eq ""
ABresult
1X1
011
000
254 255 my $default_option = '';
255 255 for my $opt ($def->{options}->@*) {
256 # Capture stored value only (before any ':Label' suffix)
257 257 ▶ if ($opt =~ /^\*([^:]*?)(?::.*)?$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opt =~ /^\*([^:]*?)(?::.*)?$/u) 254 3 257
258 254 $default_option = $1;
259 254 last;
260 }
261 }
262 255 $merged_definitions{$field_name}{default} = $default_option;
263 }
264 }
265 }
266  
267 98 my %field_meta = (
268 fields => [ @fields ],
269 field_definitions => { %merged_definitions },
270 );
271  
272 98 return \%field_meta;
273 }
274  
275 # Type-to-validator mapping for default validation
276 8 %Concierge::Users::Meta::type_validator_map = (
277 text => \&validate_text,
278 enum => \&validate_enum,
279 boolean => \&validate_boolean,
280 date => \&validate_date,
281 timestamp => \&validate_timestamp,
282 email => \&validate_email,
283 phone => \&validate_phone,
284 integer => \&validate_integer,
285 moniker => \&validate_moniker,
286 name => \&validate_name_field,
287 );
288  
289 8 %Concierge::Users::Meta::type_null_values = (
290 text => '',
291 enum => '',
292 boolean => '',
293 date => '0000-00-00',
294 timestamp => '0000-00-00 00:00:00',
295 email => '',
296 phone => '',
297 integer => 0,
298 moniker => '',
299 name => '',
300 );
301  
302 # Canonical field data types -- use for validating 'type' attribute values.
303 # moniker and name are validate_as targets only, not data types.
304 8 %Concierge::Users::Meta::field_types = (
305 text => 1,
306 boolean => 1,
307 integer => 1,
308 enum => 1,
309 email => 1,
310 phone => 1,
311 date => 1,
312 timestamp => 1,
313 );
314  
315 # Get field validator - returns validator based on validate_as or type
316 177 ▶sub get_field_validator {
Subroutine get_field_validator: called CC=6 SCAR=18.1
Pod documented
317 177 my ($self, $field) = @_;
318  
319 177 my $field_def = $self->get_field_definition($field);
320 177 ▶ return unless $field_def;
Branch: 1 branch
BranchTrueFalseTotal
unless $field_def 0 177 177
321  
322 # Check for validate_as specifier (JSON-serializable)
323 177 ▶ if ($field_def->{validate_as}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($field_def->{"validate_as"}) 168 9 177
324 168 my $validator_type = $field_def->{validate_as};
325 return $Concierge::Users::Meta::type_validator_map{$validator_type}
326 168 ▶ if $Concierge::Users::Meta::type_validator_map{$validator_type};
Branch: 1 branch
BranchTrueFalseTotal
if $Concierge::Users::Meta::type_validator_map{$validator_type} 168 0 168
327 }
328  
329 # Return type-derived validator if available
330 9 my $type = $field_def->{type};
331 return $Concierge::Users::Meta::type_validator_map{$type}
332 9 ▶ if $type && $Concierge::Users::Meta::type_validator_map{$type};
Branch: 1 branch
BranchTrueFalseTotal
if $type and $Concierge::Users::Meta::type_validator_map{$type} 8 1 9
Condition66%2/3
$type and $Concierge::Users::Meta::type_validator_map{$type}
!ll&&!rl&&r
018
MC/DC50%1/2
$type and $Concierge::Users::Meta::type_validator_map{$type}
$type $Concierge::Users::Meta::type_validator_map{$type}
Truth table66%2/3
A and B
A= $typeB= $Concierge::Users::Meta::type_validator_map{$type}
ABresult
0X0
100
111
333  
334 1 return; # No validator available
335 }
336  
337 # Get UI-friendly field hints for calling applications
338 # Returns hashref with: label, type, validate_as, max_length, options,
339 # description, required, default, null, format_as
340 # 'null' is the field's null_value (the sentinel for "no data").
341 # 'required' means operationally required at the service layer -- always,
342 # regardless of channel -- not app-level conditional required logic.
343 # 'format_as' hints how to present or input this field in a UI.
344 # Not validated; apps may supply their own format codes via setup.
345 26 ▶sub get_field_hints {
Subroutine get_field_hints: called CC=4 SCAR=17.9
Pod documented
346 26 my ($self, $field) = @_;
347  
348 26 my $field_def = $self->get_field_definition($field);
349 26 ▶ return unless $field_def;
Branch: 1 branch
BranchTrueFalseTotal
unless $field_def 0 26 26
350  
351 return {
352 label => $field_def->{label} || labelize($field_def->{field_name} || $field),
353 type => $field_def->{type},
354 validate_as => $field_def->{validate_as},
355 max_length => $field_def->{max_length},
356 options => $field_def->{options},
357 description => $field_def->{description},
358 required => $field_def->{required},
359 default => $field_def->{default},
360 null => $field_def->{null_value},
361 format_as => $field_def->{format_as},
362 26 ▶ };
Condition16%1/6
$field_def->{'label'} || labelize($field_def->{'field_name'} || $field)
l!l&&r!l&&!r
2600
$field_def->{'field_name'} || $field
l!l&&r!l&&!r
000
MC/DC0%0/2
$field_def->{'label'} || labelize($field_def->{'field_name'} || $field)
$field_def->{'label'} labelize($field_def->{'field_name'} || $field)
MC/DC0%0/2
$field_def->{'field_name'} || $field
$field_def->{'field_name'} $field
Truth table33%1/3
A || B
A= $field_def->{'label'}B= labelize($field_def->{'field_name'} || $field)
ABresult
1X1
011
000
Truth table0%0/3
A || B
A= $field_def->{'field_name'}B= $field
ABresult
1X1
011
000
363 }
364  
365 # Get the list of field names for this user object
366 1 ▶sub get_user_fields {
Subroutine get_user_fields: called CC=1 SCAR=0.0
Pod documented
367 1 my $self = shift;
368  
369 1 return $self->{fields};
370 }
371  
372 # Auto-generate label from field_name
373 23 ▶sub labelize {
Subroutine labelize: called CC=2 SCAR=6.9
Pod undocumented
374 23 my ($field_name) = @_;
375 23 ▶ return unless $field_name;
Branch: 1 branch
BranchTrueFalseTotal
unless $field_name 2 21 23
376  
377 # Convert underscore_case to Title Case
378 21 $field_name =~ s/_/ /g;
379 21 $field_name =~ s/\b(\w)/\u$1/g;
380  
381 21 return $field_name;
382 }
383  
384 # Generate current date in YYYY-MM-DD format
385 1 ▶sub current_date {
Subroutine current_date: called CC=1 SCAR=0.0
Pod undocumented
386 1 my ($mday, $mon, $year) = gmtime;
387 1 return sprintf("%04d-%02d-%02d", $year + 1900, $mon + 1, $mday);
388 }
389  
390 # Generate current timestamp in YYYY-MM-DD HH:MM:SS format
391 519 ▶sub current_timestamp {
Subroutine current_timestamp: called CC=1 SCAR=0.0
Pod undocumented
392 519 my ($sec, $min, $hour, $mday, $mon, $year) = gmtime;
393 519 return sprintf("%04d-%02d-%02d %02d:%02d:%02d",
394 $year + 1900, $mon + 1, $mday, $hour, $min, $sec);
395 }
396  
397 4 ▶sub archive_timestamp {
Subroutine archive_timestamp: called CC=1 SCAR=0.0
Pod undocumented
398 4 my ($sec, $min, $hour, $mday, $mon, $year) = localtime;
399 4 return sprintf("%04d%02d%02d_%02d%02d%02d",
400 $year + 1900, $mon + 1, $mday, $hour, $min, $sec);
401 }
402  
403 # ==============================================================================
404 # CONFIG DISPLAY METHODS
405 # ==============================================================================
406  
407 # Convert config hash to YAML format for storage
408 # Returns YAML string with warning header
409 83 ▶sub config_to_yaml {
Subroutine config_to_yaml: called CC=17 SCAR=28.3
Pod documented
410 83 my ($config, $storage_dir) = @_;
411  
412 # Build YAML header
413 83 my $yaml = '';
414 83 $yaml .= "#" . ("#" x 78) . "\n";
415 83 $yaml .= "# WARNING: This is a GENERATED file for reference ONLY\n";
416 83 $yaml .= "#\n";
417 83 $yaml .= "# Editing this file will NOT affect your Users setup configuration.\n";
418 83 $yaml .= "#\n";
419 83 $yaml .= "# This file is automatically generated from:\n";
420 83 $yaml .= "# users-config.json\n";
421 83 $yaml .= "#\n";
422 83 $yaml .= "# This file:\n";
423 83 $yaml .= "# $storage_dir/users-config.yaml\n";
424 83 $yaml .= "#" . ("#" x 78) . "\n";
425 83 $yaml .= "\n";
426  
427 # Configuration metadata
428 83 $yaml .= "Configuration:\n";
429 83 $yaml .= " Version: $config->{version}\n";
430 83 $yaml .= " Backend: $config->{backend_module}\n";
431 83 $yaml .= " Storage Directory: $storage_dir\n";
432 83 $yaml .= " Generated: $config->{generated}\n";
433 83 $yaml .= "\n";
434  
435 # Field Definitions
436 83 $yaml .= "Field Definitions:\n";
437  
438 # Organize fields by category
439 my %fields_by_category = (
440 991 'Core Fields' => [grep { my $f=$_; grep { $_ eq $f } @Concierge::Users::Meta::core_fields } @{$config->{fields}}],
441 991 'Standard Fields' => [grep { my $f=$_; grep { $_ eq $f } @Concierge::Users::Meta::standard_fields } @{$config->{fields}}],
442 991 'System Fields' => [grep { my $f=$_; grep { $_ eq $f } @Concierge::Users::Meta::system_fields } @{$config->{fields}}],
443 991 'Application Fields' => [grep { my $f=$_; my $found=0;
444 991 for my $cat (\@Concierge::Users::Meta::core_fields, \@Concierge::Users::Meta::standard_fields, \@Concierge::Users::Meta::system_fields) {
445 2973 ▶ $found = 1 if grep { $_ eq $f } @$cat;
Branch: 1 branch
BranchTrueFalseTotal
if grep {$_ eq $f;} @$cat 981 1992 2973
446 }
447 991 !$found;
448 83 } @{$config->{fields}}],
449 );
450  
451 83 foreach my $category ('Core Fields', 'Standard Fields', 'System Fields', 'Application Fields') {
452 332 my $fields = $fields_by_category{$category};
453 332 ▶ next unless $fields && @$fields;
Branch: 1 branch
BranchTrueFalseTotal
unless $fields and @$fields 82 250 332
Condition66%2/3
$fields and @$fields
!ll&&!rl&&r
082250
MC/DC50%1/2
$fields and @$fields
$fields @$fields
Truth table66%2/3
A and B
A= $fieldsB= @$fields
ABresult
0X0
100
111
454  
455 250 $yaml .= " $category:\n";
456 250 foreach my $field (@$fields) {
457 991 my $def = $config->{field_definitions}{$field};
458 991 ▶ next unless $def;
Branch: 1 branch
BranchTrueFalseTotal
unless $def 0 991 991
459  
460 991 $yaml .= " $field:\n";
461 991 $yaml .= " field_name: $def->{field_name}\n";
462 991 $yaml .= " type: $def->{type}\n";
463 991 $yaml .= " required: $def->{required}\n";
464  
465 # Only show validate_as if it's different from type
466 991 ▶ if ($def->{validate_as} && $def->{validate_as} ne $def->{type}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($def->{"validate_as"} and $def->{"validate_as"} ne $def->{"type"}) 190 801 991
Condition100%3/3
$def->{"validate_as"} and $def->{"validate_as"} ne $def->{"type"}
!ll&&!rl&&r
341460190
MC/DC100%2/2
$def->{"validate_as"} and $def->{"validate_as"} ne $def->{"type"}
$def->{"validate_as"} $def->{"validate_as"} ne $def->{"type"}
Truth table100%3/3
A and B
A= $def->{"validate_as"}B= $def->{"validate_as"} ne $def->{"type"}
ABresult
0X0
100
111
467 190 $yaml .= " validate_as: $def->{validate_as}\n";
468 }
469  
470 991 $yaml .= " default: " . _yaml_scalar_value($def->{default}) . "\n";
471  
472 # Show options if present
473 991 ▶ if ($def->{options} && @{$def->{options}}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($def->{"options"} and @{$def->{"options"};}) 217 774 991
Condition100%3/3
$def->{"options"} and @{$def->{"options"};}
!ll&&!rl&&r
8766217
MC/DC100%2/2
$def->{"options"} and @{$def->{"options"};}
$def->{"options"} @{$def->{"options"};}
Truth table100%3/3
A and B
A= $def->{"options"}B= @{$def->{"options"};}
ABresult
0X0
100
111
474 217 $yaml .= " options: (asterisk '*' designates default option)\n";
475 217 foreach my $opt (@{$def->{options}}) {
476 1173 $yaml .= " - $opt\n";
477 }
478 }
479  
480 # Show description if present
481 991 ▶ if ($def->{description}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($def->{"description"}) 981 10 991
482 981 $yaml .= " description: \"$def->{description}\"\n";
483 }
484  
485 # Show other key attributes if present
486 991 ▶ $yaml .= " max_length: $def->{max_length}\n" if $def->{max_length};
Branch: 1 branch
BranchTrueFalseTotal
if $def->{"max_length"} 982 9 991
487 991 ▶ $yaml .= " must_validate: $def->{must_validate}\n" if $def->{must_validate};
Branch: 1 branch
BranchTrueFalseTotal
if $def->{"must_validate"} 357 634 991
488 991 $yaml .= " null_value: " . _yaml_scalar_value($def->{null_value}) . "\n";
489 991 ▶ $yaml .= " format_as: $def->{format_as}\n" if defined $def->{format_as};
Branch: 1 branch
BranchTrueFalseTotal
if defined $def->{"format_as"} 984 7 991
490  
491 991 $yaml .= "\n";
492 }
493 }
494  
495 83 return $yaml;
496 }
497  
498 # Helper to properly quote YAML scalar values
499 1988 ▶sub _yaml_scalar_value {
Subroutine _yaml_scalar_value: called CC=6 SCAR=17.9
500 1988 my ($value) = @_;
501  
502 # Handle undefined values
503 1988 ▶ return 'null' unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 9 1979 1988
504  
505 # Handle empty strings
506 1979 ▶ return '""' if $value eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $value eq "" 1280 699 1979
507  
508 # Handle numeric values
509 699 ▶ return $value if $value =~ /^\-?\d+$/;
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^\-?\d+$/u 5 694 699
510  
511 # Handle boolean
512 694 ▶ return $value if $value =~ /^[01]$/;
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^[01]$/u 0 694 694
513  
514 # Quote strings with spaces or special chars
515 694 ▶ return $value if $value =~ /^\S+$/;
Branch: 1 branch
BranchTrueFalseTotal
if $value =~ /^\S+$/u 195 499 694
516 499 return "\"$value\"";
517 }
518  
519 # Return default configuration (from __DATA__ section) as a service hashref.
520 # Can be called as class method or instance method.
521 # Returns: { success => 1, config => $yaml_string }
522 1 ▶sub show_default_config {
Subroutine show_default_config: called CC=1 SCAR=0.0
Pod documented
523 1 my ($self, %params) = @_;
524  
525 1 my @data = <DATA>;
526 return {
527 1 success => 1,
528 config => join('', @data),
529 };
530 }
531  
532 # Show configuration for an existing setup
533 # Must be called as instance method on a Users object
534 # Parameters (optional hash):
535 # output_path => '/path/to/file.yaml' # Save to different location
536 3 ▶sub show_config {
Subroutine show_config: called CC=8 SCAR=21.1
Pod documented
537 3 my ($self, %params) = @_;
538  
539 # Check if this is a valid Users object with storage_dir
540 3 ▶ unless (ref $self && $self->{backend}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $self and $self->{"backend"}) 1 2 3
Condition66%2/3
ref $self and $self->{"backend"}
!ll&&!rl&&r
012
MC/DC50%1/2
ref $self and $self->{"backend"}
ref $self $self->{"backend"}
Truth table66%2/3
A and B
A= ref $selfB= $self->{"backend"}
ABresult
0X0
100
111
541 return {
542 1 success => 0,
543 message => "show_config() must be called on a Users instance. "
544 . "Use show_default_config() to view default configuration."
545 };
546 }
547  
548 # Get storage_dir from backend config
549 my $storage_dir = $self->{backend}{storage_dir}
550 or return {
551 2 ▶ success => 0,
Branch: 1 branch
BranchTrueFalseTotal
my $storage_dir = $self->{"backend"}{"storage_dir"} or return {"success", 0, "message", "Cannot determine storage directory from Users object"} 2 0 2
552 message => "Cannot determine storage directory from Users object"
553 };
554  
555 2 ▶ my $yaml_file = $params{output_path} || "$storage_dir/users-config.yaml";
Condition100%2/2
$params{'output_path'} || "$storage_dir/users-config.yaml"
l!l
11
MC/DC100%1/1
$params{'output_path'} || "$storage_dir/users-config.yaml"
$params{'output_path'}
Truth table100%2/2
A
A= $params{'output_path'}
Aresult
11
00
556  
557 # Check if YAML config file exists
558 2 ▶ unless (-f $yaml_file) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $yaml_file) 1 1 2
559 return {
560 1 success => 0,
561 message => "Configuration file not found: $yaml_file\n"
562 . "Note: YAML config files are created automatically during setup().\n"
563 . "If you just created this setup, the file should exist. "
564 . "Otherwise, the setup may be incomplete."
565 };
566 }
567  
568 # Read the YAML file and return its content
569 1 my $yaml_content;
570 1 eval {
571 1 ▶ open my $fh, '<', $yaml_file or croak "Cannot open $yaml_file: $!";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $yaml_file or croak("Cannot open ${yaml_file}: $!") 1 0 1
572 1 local $/;
573 1 $yaml_content = <$fh>;
574 1 close $fh;
575 };
576 1 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 1 1
577 return {
578 0 success => 0,
579 message => "Failed to read configuration file: $@"
580 };
581 }
582  
583 return {
584 1 success => 1,
585 config => $yaml_content,
586 config_file => $yaml_file,
587 };
588 }
589  
590  
591 # ==============================================================================
592 # VALIDATOR METHODS
593 # All validators receive: ($user_data, $field_name, $field_def)
594 # Validators modify $user_data->{$field_name} directly if substitution needed
595 # All validators return: { success => 1|0, message => "..." }
596 # ==============================================================================
597  
598 # Validate enum fields against options
599 10 ▶sub validate_enum {
Subroutine validate_enum: called CC=3 SCAR=11.0
Pod undocumented
600 10 my ($user_data, $field_name, $field_def) = @_;
601  
602 10 my $value = $user_data->{$field_name};
603  
604 # Use v_options (validated options without asterisks)
605 10 ▶ my $options = $field_def->{v_options} || [];
Condition50%1/2
$field_def->{'v_options'} || []
l!l
100
MC/DC0%0/1
$field_def->{'v_options'} || []
$field_def->{'v_options'}
Truth table50%1/2
A
A= $field_def->{'v_options'}
Aresult
11
00
606  
607 # Check if value is in the allowed options
608 10 ▶ if (grep { $_ eq $value } @$options) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep {$_ eq $value;} @$options) 7 3 10
609 7 return { success => 1 };
610 }
611  
612 return {
613 3 success => 0,
614 message => "$field_def->{label} must be one of: " . join(', ', @$options),
615 };
616 }
617  
618 # Validate text fields with length checking
619 4 ▶sub validate_text {
Subroutine validate_text: called CC=3 SCAR=11.0
Pod undocumented
620 4 my ($user_data, $field_name, $field_def) = @_;
621  
622 4 my $value = $user_data->{$field_name};
623  
624 # Check max_length
625 4 ▶ if ($field_def->{max_length} && length($value) > $field_def->{max_length}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($field_def->{"max_length"} and length $value > $field_def->{"max_length"}) 2 2 4
Condition66%2/3
$field_def->{"max_length"} and length $value > $field_def->{"max_length"}
!ll&&!rl&&r
022
MC/DC50%1/2
$field_def->{"max_length"} and length $value > $field_def->{"max_length"}
$field_def->{"max_length"} length $value > $field_def->{"max_length"}
Truth table66%2/3
A and B
A= $field_def->{"max_length"}B= length $value > $field_def->{"max_length"}
ABresult
0X0
100
111
626 return {
627 2 success => 0,
628 message => "$field_def->{label} must not exceed maximum length of $field_def->{max_length} characters"
629 };
630 }
631  
632 2 return { success => 1 };
633 }
634  
635 # Validate email format
636 110 ▶sub validate_email {
Subroutine validate_email: called CC=2 SCAR=6.9
Pod undocumented
637 110 my ($user_data, $field_name, $field_def) = @_;
638  
639 110 my $value = $user_data->{$field_name};
640  
641 # Check email format
642 110 ▶ if ($value =~ /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /^[a-zA-Z0-9._%+-]+\@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/u) 108 2 110
643 108 return { success => 1 };
644 }
645  
646 2 return { success => 0, message => "$field_def->{label} must be a valid email address" };
647 }
648  
649 # Validate date format
650 2 ▶sub validate_date {
Subroutine validate_date: called CC=2 SCAR=6.9
Pod undocumented
651 2 my ($user_data, $field_name, $field_def) = @_;
652  
653 2 my $value = $user_data->{$field_name};
654  
655 # Check YYYY-MM-DD format
656 2 ▶ if ($value =~ /^\d{4}-\d{2}-\d{2}$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /^\d{4}-\d{2}-\d{2}$/u) 1 1 2
657 1 return { success => 1 };
658 }
659  
660 return {
661 1 success => 0,
662 message => "Invalid date format for $field_def->{label}",
663 };
664 }
665  
666 # Validate timestamp format
667 3 ▶sub validate_timestamp {
Subroutine validate_timestamp: called CC=2 SCAR=6.9
Pod undocumented
668 3 my ($user_data, $field_name, $field_def) = @_;
669  
670 3 my $value = $user_data->{$field_name};
671  
672 # Check YYYY-MM-DD HH:MM:SS format
673 3 ▶ if ($value =~ /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}$/u) 2 1 3
674 2 return { success => 1 };
675 }
676  
677 return {
678 1 success => 0,
679 message => "Invalid timestamp format for $field_def->{label}, using null value"
680 };
681 }
682  
683 # Validate boolean (1|0) # or resolves Perl true/false?
684 3 ▶sub validate_boolean {
Subroutine validate_boolean: called CC=3 SCAR=11.0
Pod undocumented
685 3 my ($user_data, $field_name, $field_def) = @_;
686  
687 3 my $value = $user_data->{$field_name};
688  
689 # Check if value is explicitly 0 or 1
690 3 ▶ if (defined $value && $value =~ /^[01]$/) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value and $value =~ /^[01]$/u) 2 1 3
Condition66%2/3
defined $value and $value =~ /^[01]$/u
!ll&&!rl&&r
012
MC/DC50%1/2
defined $value and $value =~ /^[01]$/u
defined $value $value =~ /^[01]$/u
Truth table66%2/3
A and B
A= defined $valueB= $value =~ /^[01]$/u
ABresult
0X0
100
111
691 2 return { success => 1 };
692 }
693 # Invalid boolean
694 return {
695 1 success => 0,
696 message => "Invalid value '$value' for boolean $field_def->{label}"
697 };
698 }
699  
700 # Validate phone format
701 23 ▶sub validate_phone {
Subroutine validate_phone: called CC=3 SCAR=11.0
Pod undocumented
702 23 my ($user_data, $field_name, $field_def) = @_;
703  
704 23 my $value = $user_data->{$field_name};
705  
706 # Check phone format
707 23 ▶ if ($value =~ /^\+?[\d\s\-\(\)]+$/ && length($value) >= 7) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /^\+?[\d\s\-\(\)]+$/u and length $value >= 7) 21 2 23
Condition66%2/3
$value =~ /^\+?[\d\s\-\(\)]+$/u and length $value >= 7
!ll&&!rl&&r
0221
MC/DC50%1/2
$value =~ /^\+?[\d\s\-\(\)]+$/u and length $value >= 7
$value =~ /^\+?[\d\s\-\(\)]+$/u length $value >= 7
Truth table66%2/3
A and B
A= $value =~ /^\+?[\d\s\-\(\)]+$/uB= length $value >= 7
ABresult
0X0
100
111
708 21 return { success => 1 };
709 }
710  
711 # Invalid phone
712 2 return { success => 0, message => "$field_def->{label} must be a valid 10-character phone number" };
713 }
714  
715 # Validate integer
716 3 ▶sub validate_integer {
Subroutine validate_integer: called CC=2 SCAR=6.9
Pod undocumented
717 3 my ($user_data, $field_name, $field_def) = @_;
718  
719 3 my $value = $user_data->{$field_name};
720  
721 # Check integer format (allow negative numbers)
722 3 ▶ if ($value =~ /^\-?\d+$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /^\-?\d+$/u) 2 1 3
723 2 return { success => 1 };
724 }
725  
726 1 return { success => 0, message => "$field_def->{label} must be a whole number" };
727 }
728  
729 2 ▶sub validate_moniker {
Subroutine validate_moniker: called CC=3 SCAR=11.0
Pod undocumented
730 2 my ($user_data, $field_name, $field_def) = @_;
731  
732 2 my $value = $user_data->{$field_name};
733  
734 2 ▶ return { success => 0, message => "moniker is required as 2-24 alphanumeric characters, no spaces" }
Branch: 1 branch
BranchTrueFalseTotal
unless $value and $value =~ /^[a-zA-Z0-9]{2,24}$/u 1 1 2
Condition66%2/3
$value and $value =~ /^[a-zA-Z0-9]{2,24}$/u
!ll&&!rl&&r
011
MC/DC50%1/2
$value and $value =~ /^[a-zA-Z0-9]{2,24}$/u
$value $value =~ /^[a-zA-Z0-9]{2,24}$/u
Truth table66%2/3
A and B
A= $valueB= $value =~ /^[a-zA-Z0-9]{2,24}$/u
ABresult
0X0
100
111
735 unless $value && $value =~ /^[a-zA-Z0-9]{2,24}$/;
736  
737 1 return { success => 1 };
738 }
739  
740 16 ▶sub validate_name_field {
Subroutine validate_name_field: called CC=3 SCAR=11.0
Pod undocumented
741 16 my ($user_data, $field_name, $field_def) = @_;
742  
743 16 my $value = $user_data->{$field_name};
744  
745 # Allow letters, hyphens, apostrophes, and internal spaces
746 16 ▶ return { success => 0, message => "$field_def->{label} contains invalid characters" }
Branch: 1 branch
BranchTrueFalseTotal
unless $value and $value =~ /^[a-zA-Z00C0-024F'\342\200\231\-.]+(?:\s+[a-zA-Z00C0-024F'\342\200\231\-.]+)*$/u 1 15 16
Condition66%2/3
$value and $value =~ /^[a-zA-Z00C0-024F'\342\200\231\-.]+(?:\s+[a-zA-Z00C0-024F'\342\200\231\-.]+)*$/u
!ll&&!rl&&r
0115
MC/DC50%1/2
$value and $value =~ /^[a-zA-Z00C0-024F'\342\200\231\-.]+(?:\s+[a-zA-Z00C0-024F'\342\200\231\-.]+)*$/u
$value $value =~ /^[a-zA-Z00C0-024F'\342\200\231\-.]+(?:\s+[a-zA-Z00C0-024F'\342\200\231\-.]+)*$/u
Truth table66%2/3
A and B
A= $valueB= $value =~ /^[a-zA-Z00C0-024F'\342\200\231\-.]+(?:\s+[a-zA-Z00C0-024F'\342\200\231\-.]+)*$/u
ABresult
0X0
100
111
747 unless $value
748 && $value =~ /^[a-zA-Z\u00C0-\u024F'’\-.]+(?:\s+[a-zA-Z\u00C0-\u024F'’\-.]+)*$/;
749
750 15 return { success => 1 };
751 }
752  
753 8 @Concierge::Users::Meta::core_fields = ( qw/
754 user_id
755 moniker
756 user_status
757 access_level
758 / );
759  
760 8 @Concierge::Users::Meta::standard_fields = ( qw/
761 first_name
762 middle_name
763 last_name
764 prefix
765 suffix
766 organization
767 title
768 email
769 phone
770 text_ok
771 term_ends
772 / );
773  
774 8 @Concierge::Users::Meta::system_fields = ( qw/
775 last_login_date
776 last_mod_date
777 created_date
778 / );
779  
780 8 %Concierge::Users::Meta::field_definitions = (
781 # Core field definitions
782 user_id => {
783 field_name => 'user_id',
784 label => 'User ID',
785 description => 'User login ID - Primary authentication identifier',
786 type => 'text',
787 required => 1,
788 options => [],
789 default => '',
790 null_value => '',
791 max_length => 30,
792 must_validate => 0,
793 format_as => 'text',
794 },
795 moniker => {
796 field_name => 'moniker',
797 label => 'Moniker',
798 description => 'User\'s preferred display name, nickname, or initials',
799 type => 'text',
800 required => 1,
801 options => [],
802 default => '',
803 null_value => '',
804 max_length => 24,
805 validate_as => 'moniker',
806 must_validate => 1,
807 format_as => 'text',
808 },
809 user_status => {
810 field_name => 'user_status',
811 label => 'User Status',
812 description => 'Account status for access control',
813 type => 'enum',
814 required => 1,
815 options => ['*Eligible', 'OK', 'Inactive'],
816 default => '', # Will be auto-set to option with '*'
817 null_value => '',
818 max_length => 20,
819 validate_as => 'enum',
820 must_validate => 1,
821 format_as => 'options',
822 },
823 access_level => {
824 field_name => 'access_level',
825 label => 'Access Level',
826 description => 'Permission level for feature access',
827 type => 'enum',
828 required => 1,
829 options => ['*anon', 'visitor', 'member', 'staff', 'admin'],
830 default => '', # Will be auto-set to option with '*'
831 null_value => '',
832 max_length => 20,
833 validate_as => 'enum',
834 must_validate => 1,
835 format_as => 'options',
836 },
837  
838 # Standard field definitions
839 first_name => {
840 field_name => 'first_name',
841 label => 'First Name',
842 description => 'User\'s first name',
843 type => 'text',
844 required => 0,
845 options => [],
846 default => '',
847 null_value => '',
848 max_length => 50,
849 validate_as => 'name',
850 must_validate => 1,
851 format_as => 'text',
852 },
853 middle_name => {
854 field_name => 'middle_name',
855 label => 'Middle Name',
856 description => 'User\'s middle name',
857 type => 'text',
858 required => 0,
859 options => [],
860 default => '',
861 null_value => '',
862 max_length => 50,
863 validate_as => 'name',
864 must_validate => 1,
865 format_as => 'text',
866 },
867 last_name => {
868 field_name => 'last_name',
869 label => 'Last Name',
870 description => 'User\'s last name',
871 type => 'text',
872 required => 0,
873 options => [],
874 default => '',
875 null_value => '',
876 max_length => 50,
877 validate_as => 'name',
878 must_validate => 1,
879 format_as => 'text',
880 },
881 prefix => {
882 field_name => 'prefix',
883 label => 'Prefix',
884 description => 'Name prefix or title',
885 type => 'enum',
886 required => 0,
887 options => ['*', 'Dr', 'Mr', 'Ms', 'Mrs', 'Mx', 'Prof', 'Hon', 'Sir', 'Madam'],
888 default => '',
889 null_value => '', # Will be auto-set to option with '*'
890 max_length => 10,
891 validate_as => 'enum',
892 must_validate => 0,
893 format_as => 'options',
894 },
895 suffix => {
896 field_name => 'suffix',
897 label => 'Suffix',
898 description => 'Name suffix or professional designation',
899 type => 'enum',
900 required => 0,
901 options => ['*', 'Jr', 'Sr', 'II', 'III', 'IV', 'V', 'PhD', 'MD', 'DDS', 'Esq'],
902 default => '', # Will be auto-set to option with '*'
903 null_value => '',
904 max_length => 10,
905 validate_as => 'enum',
906 must_validate => 0,
907 format_as => 'options',
908 },
909 organization => {
910 field_name => 'organization',
911 label => 'Organization',
912 description => 'User\'s organization or affiliation',
913 type => 'text',
914 required => 0,
915 options => [],
916 default => '',
917 null_value => '',
918 max_length => 100,
919 validate_as => 'text',
920 must_validate => 0,
921 format_as => 'text',
922 },
923 title => {
924 field_name => 'title',
925 label => 'Title',
926 description => 'User\'s position or job title',
927 type => 'text',
928 required => 0,
929 options => [],
930 default => '',
931 null_value => '',
932 max_length => 100,
933 validate_as => 'text',
934 must_validate => 0,
935 format_as => 'text',
936 },
937 email => {
938 field_name => 'email',
939 label => 'Email',
940 description => 'Email address for notifications',
941 type => 'email',
942 required => 0,
943 options => [],
944 default => '',
945 null_value => '',
946 max_length => 255,
947 validate_as => 'email',
948 must_validate => 0,
949 format_as => 'text',
950 },
951 phone => {
952 field_name => 'phone',
953 label => 'Phone',
954 description => 'Phone number with country code',
955 type => 'phone',
956 required => 0,
957 options => [],
958 default => '',
959 null_value => '',
960 max_length => 20,
961 validate_as => 'phone',
962 must_validate => 0,
963 format_as => 'text',
964 },
965 text_ok => {
966 field_name => 'text_ok',
967 label => 'Text OK',
968 description => 'Consent for text messages (1=yes, 0=no)',
969 type => 'boolean',
970 required => 0,
971 options => [],
972 default => '',
973 null_value => '',
974 max_length => 1,
975 validate_as => 'boolean',
976 must_validate => 0,
977 format_as => 'boolean',
978 },
979 term_ends => {
980 field_name => 'term_ends',
981 label => 'Term Ends',
982 description => 'Account expiration date (YYYY-MM-DD)',
983 type => 'date',
984 required => 0,
985 options => [],
986 default => '',
987 null_value => '0000-00-00',
988 max_length => 10,
989 validate_as => 'date',
990 must_validate => 0,
991 format_as => 'date',
992 },
993 last_login_date => {
994 field_name => 'last_login_date',
995 label => 'Last Login Date',
996 description => 'Timestamp of last successful login',
997 type => 'timestamp',
998 required => 0,
999 options => [],
1000 default => '0000-00-00 00:00:00',
1001 null_value => '0000-00-00 00:00:00',
1002 max_length => 19,
1003 must_validate => 0,
1004 format_as => 'datetime',
1005 },
1006  
1007 # System field definitions
1008 last_mod_date => {
1009 field_name => 'last_mod_date',
1010 label => 'Last Modification Date',
1011 description => 'Timestamp of last profile modification',
1012 type => 'timestamp',
1013 required => 0,
1014 options => [],
1015 default => '0000-00-00 00:00:00',
1016 null_value => '0000-00-00 00:00:00',
1017 max_length => 19,
1018 must_validate => 0,
1019 format_as => 'datetime',
1020 },
1021 created_date => {
1022 field_name => 'created_date',
1023 label => 'Created Date',
1024 description => 'Timestamp when user account was created',
1025 type => 'timestamp',
1026 required => 0,
1027 options => [],
1028 default => '0000-00-00 00:00:00',
1029 null_value => '0000-00-00 00:00:00',
1030 max_length => 19,
1031 must_validate => 0,
1032 format_as => 'datetime',
1033 },
1034 );
1035  
1036 160 ▶sub validate_user_data {
Subroutine validate_user_data: called CC=12 SCAR=24.9
Pod documented
1037 160 my ($self, $user_data) = @_;
1038  
1039 return { success => 1, valid_data => $user_data, message => 'Validation skipped per environment variable USERS_SKIP_VALIDATION' }
1040 160 ▶ if $ENV{USERS_SKIP_VALIDATION};
Branch: 1 branch
BranchTrueFalseTotal
if $ENV{"USERS_SKIP_VALIDATION"} 2 158 160
1041  
1042 158 my @warnings;
1043 158 my $validated_data = {};
1044 158 foreach my ($field, $value) ( $user_data->%* ) {
1045 # Get field definition
1046 196 my $field_def = $self->get_field_definition($field);
1047  
1048 # Skip unknown fields with warning
1049 196 ▶ unless (defined $field_def) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $field_def) 14 182 196
1050 14 push @warnings, "Field '$field' not recognized in schema; input data skipped";
1051 14 next;
1052 }
1053  
1054 # Fail if a required field isn't provided a value
1055 # or the value is the same as the field's null_value
1056 182 ▶ if ( !defined $value or $value eq $field_def->{null_value} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $value or $value eq $field_def->{"null_value"}) 5 177 182
Condition66%2/3
not defined $value or $value eq $field_def->{"null_value"}
l!l&&r!l&&!r
05177
MC/DC50%1/2
not defined $value or $value eq $field_def->{"null_value"}
not defined $value $value eq $field_def->{"null_value"}
Truth table66%2/3
not(A) or B
A= not defined $valueB= $value eq $field_def->{"null_value"}
ABresult
1X1
011
000
1057 return { success => 0, message => "$field_def->{label} is required" }
1058 5 ▶ if $field_def->{required}; # Stops input
Branch: 1 branch
BranchTrueFalseTotal
if $field_def->{"required"} 0 5 5
1059 5 next; # OK if value is null_value and not required,
1060 # but no need to validate or input
1061 }
1062  
1063 # Get validator for this field
1064 177 my $validator = $self->get_field_validator($field);
1065 177 ▶ unless ($validator) { # No validator available, skip
Branch: 1 branch
BranchTrueFalseTotal
unless ($validator) 1 176 177
1066 1 push @warnings => "Validator not found for '$field'; input skipped";
1067 1 next;
1068 }
1069  
1070 # Run validator
1071 176 my $result = $validator->($user_data, $field, $field_def);
1072  
1073 # Collect warnings
1074 176 ▶ if ($result->{message}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($result->{"message"}) 15 161 176
1075 15 push @warnings, "$field: $result->{message}";
1076 }
1077  
1078 # Only validated data will be returned
1079 176 ▶ if ($result->{success}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($result->{'success'}) { } 161 15 176
elsif ($field_def->{'must_validate'}) { } 5 10 15
1080 161 $validated_data->{$field} = $value;
1081 }
1082 # Fail on validation errors only if must_validate is set for a field
1083 elsif ($field_def->{must_validate}) {
1084 5 return { success => 0, message => $result->{message}, field => $field };
1085 }
1086 }
1087  
1088 # Return success with validated data and any warnings
1089 153 my $outcome = { success => 1, valid_data => $validated_data };
1090 153 ▶ $outcome->{warnings} = \@warnings if @warnings;
Branch: 1 branch
BranchTrueFalseTotal
if @warnings 17 136 153
1091 153 return $outcome;
1092 }
1093  
1094 # Parse filter DSL string into filter structure
1095 11 ▶sub parse_filter_string {
Subroutine parse_filter_string: called CC=7 SCAR=19.5
Pod documented
1096 11 my ($self, $filter_string) = @_;
1097  
1098 11 my @or_groups = split /\s*\|\s*/, $filter_string;
1099 11 my @parsed_filters;
1100  
1101 11 foreach my $group (@or_groups) {
1102 11 my @and_conditions = split /\s*;\s*/, $group;
1103 11 my @parsed_and;
1104  
1105 11 foreach my $condition (@and_conditions) {
1106 # Parse [field][op][value]
1107 12 ▶ if ($condition =~ /^(\w+)(=|:|!|>|<)(.+)$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($condition =~ /^(\w+)(=|:|!|>|<)(.+)$/u) { } 10 2 12
1108 10 my ($field, $op, $value) = ($1, $2, $3);
1109  
1110 # Validate field exists
1111 10 ▶ unless (grep { $_ eq $field } @{$self->{fields}}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (grep {$_ eq $field;} @{$$self{"fields"};}) 3 7 10
1112 3 carp "Warning: Unknown field '$field' in filter";
1113 3 next;
1114 }
1115  
1116 7 push @parsed_and, {
1117 field => $field,
1118 op => $op,
1119 value => $value
1120 };
1121 } else {
1122 2 carp "Warning: Invalid filter condition '$condition'";
1123 }
1124 }
1125  
1126 # Only add non-empty AND groups
1127 11 ▶ if (@parsed_and) {
Branch: 1 branch
BranchTrueFalseTotal
if (@parsed_and) 7 4 11
1128 7 push @parsed_filters, \@parsed_and;
1129 }
1130 }
1131  
1132 # Return empty hash if no valid filters
1133 11 ▶ return {} unless @parsed_filters;
Branch: 1 branch
BranchTrueFalseTotal
unless @parsed_filters 4 7 11
1134  
1135 # Return structure for backend processing
1136 return {
1137 7 or_groups => \@parsed_filters,
1138 raw => $filter_string
1139 };
1140 }
1141  
1142 8 1;
1143  
1144 =head1 NAME
1145  
1146 Concierge::Users::Meta - Field definitions, validators, and configuration
1147 utilities for Concierge::Users
1148  
1149 =head1 VERSION
1150  
1151 v0.9.4
1152  
1153 =head1 SYNOPSIS
1154  
1155 use Concierge::Users;
1156  
1157 my $users = Concierge::Users->new('/path/to/users-config.json');
1158  
1159 # Introspect field schema
1160 my $fields = $users->get_user_fields(); # ordered field list
1161 my $def = $users->get_field_definition('email');
1162 my $hints = $users->get_field_hints('email');
1163  
1164 # Class-level field lists
1165 my @core = Concierge::Users::Meta::user_core_fields();
1166 my @std = Concierge::Users::Meta::user_standard_fields();
1167 my @sys = Concierge::Users::Meta::user_system_fields();
1168  
1169 # Display configuration
1170 Concierge::Users::Meta->show_default_config(); # built-in defaults
1171 $users->show_config(); # active setup
1172  
1173 =head1 DESCRIPTION
1174  
1175 Concierge::Users::Meta is the parent class for L<Concierge::Users> and all
1176 storage backends. It owns the master field definitions, the validation
1177 subsystem, the filter DSL parser, and the configuration display helpers.
1178 Application code normally interacts with Meta indirectly through a
1179 L<Concierge::Users> instance, but the introspection methods and class-level
1180 field lists are available for direct use.
1181  
1182 =head1 FIELD CATALOG
1183  
1184 Every user record is composed of fields drawn from three built-in
1185 categories plus an optional application category.
1186  
1187 =head2 Core Fields (4)
1188  
1189 Always present in every setup.
1190  
1191 =over 4
1192  
1193 =item B<user_id>
1194  
1195 Primary authentication identifier.
1196  
1197 type: text
1198 required: 1
1199 max_length: 30
1200 default: ""
1201 null_value: ""
1202 must_validate: 0
1203 description: User login ID - Primary authentication identifier
1204  
1205 =item B<moniker>
1206  
1207 User's preferred display name, nickname, or initials.
1208  
1209 type: text
1210 validate_as: moniker
1211 required: 1
1212 max_length: 24
1213 default: ""
1214 null_value: ""
1215 must_validate: 1
1216 description: User's preferred display name, nickname, or initials
1217  
1218 =item B<user_status>
1219  
1220 Account status for access control.
1221  
1222 type: enum
1223 validate_as: enum
1224 required: 1
1225 options: *Eligible, OK, Inactive
1226 max_length: 20
1227 default: Eligible (auto-set from * option)
1228 null_value: ""
1229 must_validate: 1
1230  
1231 This is a core field (always present), but its C<options> can be
1232 replaced via C<field_overrides> to match your application's workflow.
1233 See L</Field Overrides> for an example.
1234  
1235 =item B<access_level>
1236  
1237 Permission level for feature access.
1238  
1239 type: enum
1240 validate_as: enum
1241 required: 1
1242 options: *anon, visitor, member, staff, admin
1243 max_length: 20
1244 default: anon (auto-set from * option)
1245 null_value: ""
1246 must_validate: 1
1247  
1248 Core field (always present); C<options> can be replaced via
1249 C<field_overrides>. See L</Field Overrides>.
1250  
1251 =back
1252  
1253 =head2 Standard Fields (11)
1254  
1255 Included by default when C<include_standard_fields> is omitted or set
1256 to C<'all'>. Pass an arrayref of names to select specific fields, or
1257 an empty arrayref C<[]> to exclude all standard fields.
1258  
1259 B<Name fields:>
1260  
1261 =over 4
1262  
1263 =item B<first_name> -- type C<text>, validate_as C<name>, max 50, must_validate 1
1264  
1265 =item B<middle_name> -- type C<text>, validate_as C<name>, max 50, must_validate 1
1266  
1267 =item B<last_name> -- type C<text>, validate_as C<name>, max 50, must_validate 1
1268  
1269 =item B<prefix> -- type C<enum>, options: (none) Dr Mr Ms Mrs Mx Prof Hon Sir Madam, max 10
1270  
1271 =item B<suffix> -- type C<enum>, options: (none) Jr Sr II III IV V PhD MD DDS Esq, max 10
1272  
1273 =back
1274  
1275 B<Identity fields:>
1276  
1277 =over 4
1278  
1279 =item B<organization> -- type C<text>, validate_as C<text>, max 100
1280  
1281 =item B<title> -- type C<text>, validate_as C<text>, max 100
1282  
1283 =back
1284  
1285 B<Contact fields:>
1286  
1287 =over 4
1288  
1289 =item B<email> -- type C<email>, validate_as C<email>, max 255
1290  
1291 =item B<phone> -- type C<phone>, validate_as C<phone>, max 20
1292  
1293 =item B<text_ok> -- type C<boolean>, validate_as C<boolean>, null_value "", max 1
1294  
1295 =back
1296  
1297 B<Temporal fields:>
1298  
1299 =over 4
1300  
1301 =item B<term_ends> -- type C<date>, validate_as C<date>,
1302 null_value C<0000-00-00>, max 10
1303  
1304 =back
1305  
1306 All standard fields have C<required =E<gt> 0> by default.
1307  
1308 =head2 System Fields (3)
1309  
1310 Always appended to the field list. Auto-managed; not set through
1311 user or app data. Protected from overrides.
1312  
1313 =over 4
1314  
1315 =item B<last_login_date> -- type C<timestamp>, set by C<login_user()>;
1316 default C<0000-00-00 00:00:00>
1317  
1318 =item B<last_mod_date> -- type C<timestamp>, updated on every write
1319  
1320 =item B<created_date> -- type C<timestamp>, set once on creation
1321  
1322 =back
1323  
1324 =head1 FIELD ATTRIBUTES
1325  
1326 Each field definition is a hashref that may contain the following keys:
1327  
1328 =over 4
1329  
1330 =item C<field_name> -- Internal name (snake_case). Used as hash key and
1331 column/file identifier.
1332  
1333 =item C<category> -- One of C<core>, C<standard>, C<system>, or C<app>.
1334 Set automatically; protected from overrides.
1335  
1336 =item C<type> -- Data type: C<text>, C<email>, C<phone>, C<date>,
1337 C<timestamp>, C<boolean>, C<integer>, C<enum>.
1338  
1339 =item C<validate_as> -- Validator to use if different from C<type>.
1340 See L</VALIDATOR TYPES>.
1341  
1342 =item C<label> -- Human-readable label for UI display. Auto-generated
1343 from C<field_name> if omitted.
1344  
1345 =item C<description> -- Short explanatory text for documentation or UI
1346 hints.
1347  
1348 =item C<required> -- C<1> if the field must have a non-null value on
1349 creation; C<0> otherwise.
1350  
1351 =item C<must_validate> -- C<1> if a validation failure should reject the
1352 entire operation; C<0> to treat failure as a non-fatal warning.
1353  
1354 =item C<options> -- Arrayref of allowed values for C<enum> fields.
1355 Prefix one option with C<*> to designate the default (see
1356 L</Enum Default Convention>).
1357  
1358 =item C<default> -- Value assigned to the field on new-record creation
1359 when no value is supplied.
1360  
1361 =item C<null_value> -- Sentinel that represents "no data" for this field
1362 type (e.g. C<""> for text, C<""> for boolean, C<0000-00-00> for date).
1363  
1364 =item C<max_length> -- Maximum character length enforced by the C<text>
1365 validator and used as a UI hint.
1366  
1367 =back
1368  
1369 =head1 VALIDATOR TYPES
1370  
1371 Ten built-in validators are available. Each is selected by the field's
1372 C<validate_as> (or C<type> as fallback) and receives
1373 C<($user_data, $field_name, $field_def)>.
1374  
1375 =over 4
1376  
1377 =item B<text>
1378  
1379 Validates C<max_length> if defined. Accepts any string.
1380  
1381 null_value: ""
1382  
1383 =item B<email>
1384  
1385 Pattern: C<< /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/ >>
1386  
1387 null_value: ""
1388  
1389 =item B<phone>
1390  
1391 Digits, spaces, hyphens, parentheses, optional leading C<+>;
1392 minimum 7 characters.
1393  
1394 null_value: ""
1395  
1396 =item B<date>
1397  
1398 Pattern: C<YYYY-MM-DD> (C<< /^\d{4}-\d{2}-\d{2}$/ >>).
1399  
1400 null_value: "0000-00-00"
1401  
1402 =item B<timestamp>
1403  
1404 Pattern: C<YYYY-MM-DD HH:MM:SS> or C<YYYY-MM-DDTHH:MM:SS>.
1405  
1406 null_value: "0000-00-00 00:00:00"
1407  
1408 =item B<boolean>
1409  
1410 Strictly C<0> or C<1>.
1411  
1412 null_value: ""
1413  
1414 =item B<integer>
1415  
1416 Optional leading minus, digits only (C<< /^\-?\d+$/ >>).
1417  
1418 null_value: ""
1419  
1420 =item B<enum>
1421  
1422 Value must appear in the field's C<v_options> list (options with C<*>
1423 prefix stripped).
1424  
1425 null_value: ""
1426  
1427 =item B<moniker>
1428  
1429 2-24 alphanumeric characters, no spaces
1430 (C<< /^[a-zA-Z0-9]{2,24}$/ >>).
1431  
1432 null_value: ""
1433  
1434 C<moniker> is a C<validate_as> target only, not a data type. Use
1435 C<< type => 'text', validate_as => 'moniker' >> for fields that need
1436 this pattern.
1437  
1438 =item B<name>
1439  
1440 Letters (including accented), hyphens, apostrophes, and internal
1441 spaces.
1442  
1443 null_value: ""
1444  
1445 C<name> is a C<validate_as> target only, not a data type. Use
1446 C<< type => 'text', validate_as => 'name' >> for name fields.
1447  
1448 =back
1449  
1450 The eight canonical data types (C<text>, C<boolean>, C<integer>, C<enum>,
1451 C<email>, C<phone>, C<date>, C<timestamp>) are enumerated in
1452 C<%Concierge::Users::Meta::field_types>.
1453  
1454 =head2 validate_as vs type
1455  
1456 A field's C<type> declares its data type and determines the default
1457 validator. C<validate_as> overrides the validator without changing
1458 the type. For example, an application field with C<< type => 'text' >>
1459 and C<< validate_as => 'moniker' >> is stored as text but validated with
1460 the moniker pattern. When C<type> is changed via a field override and
1461 C<validate_as> is not explicitly set, C<validate_as> is updated
1462 automatically to match the new type.
1463  
1464 =head2 must_validate Behavior
1465  
1466 When C<must_validate> is C<1> for a field, a validation failure causes
1467 the entire C<register_user> or C<update_user> call to return
1468 C<< { success => 0 } >>. When C<must_validate> is C<0>, the field's
1469 value is silently dropped and a warning is appended to the response.
1470  
1471 Setting C<< required => 1 >> in a field override automatically enables
1472 C<must_validate> unless C<must_validate> is explicitly set in the same
1473 override.
1474  
1475 The environment variable C<USERS_SKIP_VALIDATION> bypasses all
1476 validation when set to a true value.
1477  
1478 =head1 FIELD CUSTOMIZATION
1479  
1480 =head2 Application Fields
1481  
1482 Pass C<app_fields> to C<< Concierge::Users->setup() >> as an arrayref.
1483 Each element is either a string (minimal definition) or a hashref (full
1484 definition):
1485  
1486 app_fields => [
1487 'nickname', # string shorthand
1488 { # full definition
1489 field_name => 'department',
1490 type => 'enum',
1491 options => ['*Engineering', 'Sales', 'Support'],
1492 required => 1,
1493 label => 'Department',
1494 },
1495 ],
1496  
1497 String shorthand creates a field with C<< type => 'text' >>,
1498 C<< validate_as => 'text' >>, C<< required => 0 >>.
1499  
1500 Reserved names (any core, standard, or system field name) are rejected
1501 with a warning.
1502  
1503 =head2 Field Overrides
1504  
1505 Pass C<field_overrides> to C<setup()> as an arrayref of hashrefs.
1506 Each must contain C<field_name> to identify the target:
1507  
1508 field_overrides => [
1509 {
1510 field_name => 'email',
1511 required => 1,
1512 label => 'Work Email',
1513 },
1514 ],
1515  
1516 B<Protected fields> (structural attributes blocked; C<format_as> and
1517 C<label> are allowed): C<user_id>, C<last_login_date>, C<last_mod_date>,
1518 C<created_date>.
1519  
1520 B<Protected attributes> that cannot be changed: C<field_name>,
1521 C<category>.
1522  
1523 Auto-behaviors:
1524  
1525 =over 4
1526  
1527 =item * Changing C<type> auto-updates C<validate_as> to match (unless
1528 C<validate_as> is also specified).
1529  
1530 =item * Setting C<< required => 1 >> auto-enables C<must_validate>
1531 (unless C<must_validate> is also specified).
1532  
1533 =item * An unknown C<validate_as> value falls back to C<text> with a
1534 warning.
1535  
1536 =back
1537  
1538 B<Overriding enum options:> Core fields like C<user_status> and
1539 C<access_level> are always present, but their C<options> are not
1540 fixed. Replace them with values that fit your domain:
1541  
1542 # Makerspace member status instead of the default
1543 # Eligible / OK / Inactive
1544 field_overrides => [
1545 {
1546 field_name => 'user_status',
1547 options => [qw( *Applicant Novice Skilled
1548 Expert Mentor Steward )],
1549 },
1550 ],
1551  
1552 The C<*>-prefixed option becomes the default (see L</Enum Default
1553 Convention>). Validation, filtering, and all other enum behaviors
1554 apply to the new option set automatically.
1555  
1556 =head2 Enum Default Convention
1557  
1558 In an C<options> arrayref, prefix exactly one value with C<*> to mark it
1559 as the default:
1560  
1561 options => ['*Free', 'Premium', 'Enterprise']
1562  
1563 The C<*> is stripped for validation (stored internally in C<v_options>).
1564 If no explicit C<default> is set for the field, the C<*>-marked option
1565 becomes the default automatically. A bare C<*> (e.g. in C<prefix> and
1566 C<suffix>) represents an empty default.
1567  
1568 =head1 FILTER DSL
1569  
1570 The C<list_users> method accepts a filter string with five operators and
1571 two combinators.
1572  
1573 =head2 Operators
1574  
1575 = exact match user_status=OK
1576 : substring (case-insensitive) last_name:smith
1577 ! not-contains (case-insensitive) email!example.org
1578 > greater than (string) last_login_date>2025-01-01
1579 < less than (string) term_ends<2026-01-01
1580  
1581 =head2 Combinators
1582  
1583 ; AND -- all conditions must match
1584 | OR -- at least one group must match
1585  
1586 AND binds tighter than OR: C<a=1;b=2|c=3> means
1587 C<(a=1 AND b=2) OR (c=3)>.
1588  
1589 =head2 Examples
1590  
1591 # Active members
1592 user_status=OK;access_level=member
1593  
1594 # Staff or admin
1595 access_level=staff|access_level=admin
1596  
1597 # Name search with status filter
1598 last_name:Garcia;user_status=OK
1599  
1600 # Recent logins
1601 last_login_date>2025-06-01
1602  
1603 Unknown fields in a filter string produce a warning and are skipped.
1604  
1605 =head1 METHODS
1606  
1607 =head2 Class Methods
1608  
1609 =head3 user_core_fields
1610  
1611 my @fields = Concierge::Users::Meta::user_core_fields();
1612  
1613 Returns the list of core field names:
1614 C<user_id>, C<moniker>, C<user_status>, C<access_level>.
1615  
1616 =head3 user_standard_fields
1617  
1618 my @fields = Concierge::Users::Meta::user_standard_fields();
1619  
1620 Returns the list of standard field names (12 fields).
1621  
1622 =head3 user_system_fields
1623  
1624 my @fields = Concierge::Users::Meta::user_system_fields();
1625  
1626 Returns the list of system field names: C<last_login_date>,
1627 C<last_mod_date>, C<created_date>.
1628  
1629 =head3 init_field_meta
1630  
1631 my $meta = Concierge::Users::Meta::init_field_meta(\%config);
1632  
1633 Processes the setup configuration and returns a hashref with C<fields>
1634 (ordered arrayref) and C<field_definitions> (hashref of field
1635 definitions). Called internally by C<< Concierge::Users->setup() >>.
1636  
1637 =head3 show_default_config
1638  
1639 my $result = Concierge::Users::Meta->show_default_config();
1640 print $result->{config} if $result->{success};
1641  
1642 Returns C<< { success => 1, config => $yaml_string } >> containing the
1643 built-in default field configuration template. Always succeeds.
1644 Callers decide how to use the string (print, log, display, etc.).
1645  
1646 =head2 Instance Methods
1647  
1648 =head3 get_field_definition
1649  
1650 my $def = $users->get_field_definition('email');
1651  
1652 Returns the complete field definition hashref for the named field, or
1653 C<undef> if the field is not in the current schema.
1654  
1655 =head3 get_field_validator
1656  
1657 my $code_ref = $users->get_field_validator('email');
1658  
1659 Returns the validator code reference for the named field based on its
1660 C<validate_as> or C<type>, or C<undef> if no validator is available.
1661  
1662 =head3 get_field_hints
1663  
1664 my $hints = $users->get_field_hints('email');
1665  
1666 Returns a hashref of consumer-friendly attributes for a field:
1667 C<label>, C<type>, C<validate_as>, C<max_length>, C<options>,
1668 C<description>, C<required>, C<default>, C<null>, C<format_as>.
1669  
1670 C<null> is the field's null value (the sentinel for "no data").
1671  
1672 C<required> means operationally required at the service layer -- always,
1673 regardless of channel (web form, CLI, programmatic). It is distinct
1674 from app-level conditional required logic, which calling applications
1675 manage independently.
1676  
1677 C<format_as> is a hint for the consuming application about how to present
1678 or input this field. It is not used or validated by Concierge itself.
1679  
1680 Standard fields always have C<format_as> set to one of the Concierge
1681 conventions. Applications may override C<format_as> on any standard
1682 field via C<field_overrides> during setup, and may set it to any value
1683 on app-defined fields via C<app_fields>. Whatever value is supplied
1684 passes through unchanged and is returned by C<get_field_hints()>,
1685 allowing an application to store its own native format codes or
1686 identifiers directly in the field definition and retrieve them later
1687 without any translation layer.
1688  
1689 Concierge convention values for C<format_as>: C<text>, C<options>,
1690 C<boolean>, C<number>, C<date>, C<datetime>, C<time>. All built-in
1691 enum fields use C<options>; the C<options> key in the hints hashref
1692 carries the full list of valid values, which consuming applications
1693 may use for both input widgets and display (e.g. rendering a
1694 previously selected value in context of its full option set).
1695  
1696 =head3 get_user_fields
1697  
1698 my $fields = $users->get_user_fields();
1699  
1700 Returns the ordered arrayref of field names for this instance's schema.
1701  
1702 =head3 validate_user_data
1703  
1704 my $result = $users->validate_user_data(\%data);
1705  
1706 Validates C<%data> against the field schema. Returns
1707 C<< { success => 1, valid_data => \%clean } >> on success (with optional
1708 C<warnings> arrayref), or C<< { success => 0, message => $reason } >>
1709 on failure.
1710  
1711 =head3 parse_filter_string
1712  
1713 my $filters = $users->parse_filter_string('user_status=OK;access_level=member');
1714  
1715 Parses a filter DSL string into an internal structure suitable for
1716 backend list methods. See L</FILTER DSL>.
1717  
1718 =head3 show_config
1719  
1720 my $result = $users->show_config();
1721 print $result->{config} if $result->{success};
1722  
1723 my $result = $users->show_config(output_path => '/path/to/other.yaml');
1724  
1725 Returns C<< { success => 1, config => $yaml_string, config_file => $path } >>
1726 with the active YAML configuration for this instance. Callers decide
1727 how to use the string. Must be called on a L<Concierge::Users> instance
1728 (not a class method).
1729  
1730 Returns C<< { success => 0, message => $reason } >> if the instance has
1731 no backend, the storage directory cannot be determined, or the YAML
1732 file is missing or unreadable.
1733  
1734 =head3 config_to_yaml
1735  
1736 my $yaml = Concierge::Users::Meta::config_to_yaml(\%config, $storage_dir);
1737  
1738 Converts a configuration hashref to a human-readable YAML string with a
1739 warning header. Used internally during C<setup()>.
1740  
1741 =head1 SEE ALSO
1742  
1743 L<Concierge::Users> -- main API and CRUD operations
1744  
1745 L<Concierge::Users::SQLite>, L<Concierge::Users::File>,
1746 L<Concierge::Users::YAML> -- storage backend implementations
1747  
1748 =head1 AUTHOR
1749  
1750 Bruce Van Allen <bva@cruzio.com>
1751  
1752 =head1 LICENSE
1753  
1754 This module is free software; you can redistribute it and/or modify it
1755 under the terms of the Artistic License 2.0.
1756  
1757 =cut
1758  
1759 __DATA__
↑ Summary Users/File.pm »