lib/Logic/Relational/Query.pm

filter: Statementstmt 95.3% 123 / 129 Branchbran 81.6% 49 / 60 Conditioncond 60.9% 25 / 41 MC/DCmcdc 36.0% 9 / 25 Subroutinesub 94.7% 18 / 19 Podpod 100% 14 / 14 totaltotal 82.6% 238 / 288 CC 50 SCAR 23.9
CC
50
Cov
86%
all_tuples
23.1
next
16.0
new
11.5
CRAP 10.9
« blib/lib/Logic/Relational/Goal/Call.pm ↑ Summary lib/Logic/Relational/Serializer.pm »
1 package Logic::Relational::Query;
2  
3 27 ▶use v5.38;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 27 ▶use experimental 'signatures';
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 =head1 NAME
7  
8 Logic::Relational::Query - Manages the execution and backtracking search of a query.
9  
10 =head1 SYNOPSIS
11  
12 use Logic::Relational::Query;
13 my $query = Logic::Relational::Query->new(
14 program => $program,
15 goals => [$goal],
16 predicates => $predicates_snapshot,
17 );
18 while (my $solution = $query->next) {
19 ...
20 }
21  
22 =head1 DESCRIPTION
23  
24 C<Logic::Relational::Query> executes the logical goals using a depth-first search
25 and an explicit agenda of execution states. This design avoids deep recursion or
26 complex mutable call stacks, while supporting ancestor cycle pruning and subgoal
27 memoization.
28  
29 =head1 METHODS
30  
31 =head2 new
32  
33 Constructor. Takes C<program> (Program), C<goals> (arrayref), and C<predicates>
34 (snapshot of the predicates hash).
35  
36 =head2 trace
37  
38 Sets or returns the trace event callback coderef.
39  
40 =head2 next
41  
42 Performs the search step. Returns the next C<Logic::Relational::Solution> object,
43 or C<undef> if all solutions have been exhausted.
44  
45 =head2 reify_solution
46  
47 Constructs a C<Logic::Relational::Solution> object from a successful execution state.
48  
49 =head2 is_true
50  
51 Returns 1 if the query succeeds at least once, 0 otherwise.
52  
53 =head2 is_success
54  
55 Alias for C<is_true>.
56  
57 =head2 all
58  
59 Returns all solutions (up to C<limit>, default 10,000).
60  
61 =head2 all_values
62  
63 Returns all bindings for the given variable across all solutions.
64  
65 =head2 distinct_values
66  
67 Returns unique bindings for the given variable in discovery order.
68  
69 =head2 all_tuples
70  
71 Extracts arrayref tuples for an arrayref of variables across all solutions,
72 deduplicating tuples by default (pass C<distinct =E<gt> 0> to keep duplicates).
73  
74 =head2 first_value
75  
76 Returns the variable's value from the first solution, or C<undef>.
77  
78 =head2 value
79  
80 Alias for C<first_value>.
81  
82 =head2 max_steps
83  
84 Returns the maximum resolution steps allowed for this query (default: 100,000; 0 for unlimited).
85  
86 =head2 step_count
87  
88 Returns the number of resolution steps executed so far by this query iterator.
89  
90 =cut
91  
92 27 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
93  
94 27 our $DEFAULT_MAX_STEPS = 100_000;
95  
96 163 ▶sub new ( $class, %args ) {
Subroutine new: called CC=11 SCAR=24.4
Pod documented
97 163 ▶ my $program = $args{program} // croak "program is required";
Condition50%1/2
$args{"program"} // croak("program is required")
l!l
1630
MC/DC0%0/1
$args{"program"} // croak("program is required")
$args{"program"}
Truth table50%1/2
A
A= $args{"program"}
Aresult
11
00
98 163 ▶ my $goals = $args{goals} // croak "goals is required";
Condition50%1/2
$args{"goals"} // croak("goals is required")
l!l
1630
MC/DC0%0/1
$args{"goals"} // croak("goals is required")
$args{"goals"}
Truth table50%1/2
A
A= $args{"goals"}
Aresult
11
00
99 my $predicates = $args{predicates}
100 163 ▶ // croak "predicates snapshot is required";
Condition50%1/2
$args{"predicates"} // croak("predicates snapshot is required")
l!l
1630
MC/DC0%0/1
$args{"predicates"} // croak("predicates snapshot is required")
$args{"predicates"}
Truth table50%1/2
A
A= $args{"predicates"}
Aresult
11
00
101  
102 163 require Logic::Relational::Substitution;
103 163 require Logic::Relational::State;
104 my $initial_subst = $args{substitution}
105 163 ▶ // Logic::Relational::Substitution->new;
Condition66%2/3
$args{"substitution"} // "Logic::Relational::Substitution"->new
l!l&&r!l&&!r
521110
MC/DC0%0/2
$args{"substitution"} // "Logic::Relational::Substitution"->new
$args{"substitution"} "Logic::Relational::Substitution"->new
Truth table66%2/3
A // B
A= $args{"substitution"}B= "Logic::Relational::Substitution"->new
ABresult
1X1
011
000
106 163 ▶ my $table_cache = $args{table_cache} // {};
Condition100%2/2
$args{"table_cache"} // {}
l!l
52111
MC/DC100%1/1
$args{"table_cache"} // {}
$args{"table_cache"}
Truth table100%2/2
A
A= $args{"table_cache"}
Aresult
11
00
107 my $initial_state = Logic::Relational::State->new(
108 substitution => $initial_subst,
109 goals => $goals,
110 163 ▶ ancestors => $args{ancestors} // [],
Condition100%2/2
$args{"ancestors"} // []
l!l
33130
MC/DC100%1/1
$args{"ancestors"} // []
$args{"ancestors"}
Truth table100%2/2
A
A= $args{"ancestors"}
Aresult
11
00
111 table_cache => $table_cache,
112 );
113  
114 163 my $max_steps;
115 163 ▶ if ( exists $args{max_steps} ) {
Branch: 2 branches
BranchTrueFalseTotal
if (exists $args{'max_steps'}) { } 2 161 163
elsif ($program->can('max_steps') and defined $program->max_steps) { } 2 159 161
116 2 $max_steps = $args{max_steps};
117 }
118 ▶ elsif ( $program->can('max_steps') && defined $program->max_steps ) {
Condition66%2/3
$program->can("max_steps") and defined $program->max_steps
!ll&&!rl&&r
01592
MC/DC50%1/2
$program->can("max_steps") and defined $program->max_steps
$program->can("max_steps") defined $program->max_steps
Truth table66%2/3
A and B
A= $program->can("max_steps")B= defined $program->max_steps
ABresult
0X0
100
111
119 2 $max_steps = $program->max_steps;
120 }
121 else {
122 159 $max_steps = $DEFAULT_MAX_STEPS;
123 }
124  
125 my $self = {
126 program => $program,
127 predicates => $predicates,
128 generators => $args{generators} // {},
129 163 ▶ table_cache => $table_cache,
Condition50%1/2
$args{"generators"} // {}
l!l
1630
MC/DC0%0/1
$args{"generators"} // {}
$args{"generators"}
Truth table50%1/2
A
A= $args{"generators"}
Aresult
11
00
130 agenda => [$initial_state],
131 trace_cb => undef,
132 is_backtracking => 0,
133 max_steps => $max_steps,
134 step_count => 0,
135 };
136 163 return bless $self, $class;
137 }
138  
139 5 ▶sub max_steps ($self) { return $self->{max_steps}; }
Subroutine max_steps: called CC=1 SCAR=0.0
Pod documented
140 3 ▶sub step_count ($self) { return $self->{step_count}; }
Subroutine step_count: called CC=1 SCAR=0.0
Pod documented
141  
142 2 ▶sub trace ( $self, $callback = undef ) {
Subroutine trace: called CC=3 SCAR=11.1
Pod documented
143 2 ▶ if ( defined $callback ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $callback) 2 0 2
144 2 $self->{trace_cb} = $callback;
145 }
146 2 return $self->{trace_cb};
147 }
148  
149 530 ▶sub next ($self) {
Subroutine next: called CC=16 SCAR=27.7
Pod documented
150 530 my $trace_cb = $self->{trace_cb};
151  
152 530 ▶ while ( my $state = pop @{ $self->{agenda} } ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $state = pop @{$$self{"agenda"};}) 1870 106 1976
153 1870 $self->{step_count}++;
154 1870 ▶ if ( defined $self->{max_steps} && $self->{max_steps} > 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"max_steps"} and $self->{"max_steps"} > 0) 1419 451 1870
Condition66%2/3
defined $self->{"max_steps"} and $self->{"max_steps"} > 0
!ll&&!rl&&r
04511419
MC/DC50%1/2
defined $self->{"max_steps"} and $self->{"max_steps"} > 0
defined $self->{"max_steps"} $self->{"max_steps"} > 0
Truth table66%2/3
A and B
A= defined $self->{"max_steps"}B= $self->{"max_steps"} > 0
ABresult
0X0
100
111
155 1419 ▶ if ( $self->{step_count} > $self->{max_steps} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"step_count"} > $self->{"max_steps"}) 1 1418 1419
156 croak "Query exceeded maximum resolution steps of "
157 . $self->{max_steps}
158 1 . " (possible recursion or unbounded search). "
159 . "Specify max_steps => 0 for unlimited or a higher limit.";
160 }
161 }
162 1869 ▶ if ( $state->has_goals
Branch: 1 branch
BranchTrueFalseTotal
if ($state->has_goals and ref $state->goals->[0] eq "Logic::Relational::Goal::EndCall") 140 1729 1869
Condition100%3/3
$state->has_goals and ref $state->goals->[0] eq "Logic::Relational::Goal::EndCall"
!ll&&!rl&&r
4191310140
MC/DC100%2/2
$state->has_goals and ref $state->goals->[0] eq "Logic::Relational::Goal::EndCall"
$state->has_goals ref $state->goals->[0] eq "Logic::Relational::Goal::EndCall"
Truth table100%3/3
A and B
A= $state->has_goalsB= ref $state->goals->[0] eq "Logic::Relational::Goal::EndCall"
ABresult
0X0
100
111
163 && ref( $state->goals->[0] ) eq 'Logic::Relational::Goal::EndCall' )
164 {
165 140 my ( $end_goal, @rem ) = $state->split_first_goal;
166 140 my @succ = $end_goal->expand(
167 state => $state,
168 substitution => $state->substitution,
169 remaining => \@rem,
170 );
171 140 push @{ $self->{agenda} }, reverse @succ;
172 140 next;
173 }
174  
175 1729 ▶ if ( $self->{is_backtracking} && $trace_cb ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"is_backtracking"} and $trace_cb) 1 1728 1729
Condition100%3/3
$self->{"is_backtracking"} and $trace_cb
!ll&&!rl&&r
13563721
MC/DC100%2/2
$self->{"is_backtracking"} and $trace_cb
$self->{"is_backtracking"} $trace_cb
Truth table100%3/3
A and B
A= $self->{"is_backtracking"}B= $trace_cb
ABresult
0X0
100
111
176 1 require Logic::Relational::TraceEvent;
177 1 $trace_cb->(
178 Logic::Relational::TraceEvent->new(
179 type => 'backtrack',
180 goal => $state->goals->[0],
181 substitution => $state->substitution
182 )
183 );
184 1 $self->{is_backtracking} = 0;
185 }
186  
187 1729 ▶ if ( !$state->has_goals ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($state->has_goals) 419 1310 1729
188 419 ▶ if ($trace_cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($trace_cb) 1 418 419
189 1 require Logic::Relational::TraceEvent;
190 1 $trace_cb->(
191 Logic::Relational::TraceEvent->new(
192 type => 'solution',
193 goal => undef,
194 substitution => $state->substitution
195 )
196 );
197 }
198 419 $self->{is_backtracking} = 1;
199 419 return $self->reify_solution($state);
200 }
201  
202 1310 my ( $goal, @remaining ) = $state->split_first_goal;
203  
204 1310 ▶ if ($trace_cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($trace_cb) 12 1298 1310
205 12 require Logic::Relational::TraceEvent;
206 12 $trace_cb->(
207 Logic::Relational::TraceEvent->new(
208 type => 'call',
209 goal => $goal,
210 substitution => $state->substitution
211 )
212 );
213 }
214  
215 my @successors = $goal->expand(
216 state => $state,
217 program => $self->{program},
218 predicates => $self->{predicates},
219 generators => $self->{generators},
220 1310 substitution => $state->substitution,
221 remaining => \@remaining,
222 );
223  
224 1306 ▶ if ( scalar @successors > 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @successors > 0) { } 1197 109 1306
225 1197 $self->{is_backtracking} = 0;
226 1197 ▶ if ($trace_cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($trace_cb) 10 1187 1197
227 10 require Logic::Relational::TraceEvent;
228 10 $trace_cb->(
229 Logic::Relational::TraceEvent->new(
230 type => 'success',
231 goal => $goal,
232 substitution => $state->substitution
233 )
234 );
235 10 ▶ if ( scalar @successors > 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @successors > 1) 3 7 10
236 3 $trace_cb->(
237 Logic::Relational::TraceEvent->new(
238 type => 'choice',
239 goal => $goal,
240 substitution => $state->substitution
241 )
242 );
243 }
244 }
245 }
246 else {
247 109 $self->{is_backtracking} = 1;
248 109 ▶ if ($trace_cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($trace_cb) 2 107 109
249 2 require Logic::Relational::TraceEvent;
250 2 $trace_cb->(
251 Logic::Relational::TraceEvent->new(
252 type => 'fail',
253 goal => $goal,
254 substitution => $state->substitution
255 )
256 );
257 }
258 }
259  
260 1306 push @{ $self->{agenda} }, reverse @successors;
261 }
262 106 return undef;
263 }
264  
265 419 ▶sub reify_solution ( $self, $state ) {
Subroutine reify_solution: called CC=1 SCAR=0.0
Pod documented
266 419 require Logic::Relational::Solution;
267 419 return Logic::Relational::Solution->new(
268 substitution => $state->substitution, );
269 }
270  
271 use overload
272 2 ▶ bool => sub ( $self, $, $ ) { $self->is_true },
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
273 27 fallback => 1;
274  
275 5 ▶sub is_true ($self) {
Subroutine is_true: called CC=2 SCAR=6.9
Pod documented
276 5 ▶ return $self->next ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$self->next ? : 3 2 5
277 }
278  
279 0 ▶sub is_success ($self) {
Subroutine is_success: not called CC=1 SCAR=6.9
Pod documented
280 0 return $self->is_true;
281 }
282  
283 12 ▶sub all ( $self, %options ) {
Subroutine all: called CC=6 SCAR=17.9
Pod documented
284 12 ▶ my $limit = exists $options{limit} ? $options{limit} : 10_000;
Branch: 1 branch
BranchTrueFalseTotal
exists $options{'limit'} ? : 1 11 12
285 12 my @solutions;
286  
287 12 ▶ while ( my $sol = $self->next ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $sol = $self->next) 44 11 55
288 44 push @solutions, $sol;
289 44 ▶ if ( defined $limit && scalar(@solutions) >= $limit ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $limit and scalar @solutions >= $limit) 1 43 44
Condition66%2/3
defined $limit and scalar @solutions >= $limit
!ll&&!rl&&r
0431
MC/DC50%1/2
defined $limit and scalar @solutions >= $limit
defined $limit scalar @solutions >= $limit
Truth table66%2/3
A and B
A= defined $limitB= scalar @solutions >= $limit
ABresult
0X0
100
111
290 1 last;
291 }
292 }
293  
294 12 ▶ return wantarray ? @solutions : \@solutions;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 11 1 12
295 }
296  
297 8 ▶sub all_values ( $self, $var, %options ) {
Subroutine all_values: called CC=2 SCAR=6.9
Pod documented
298 8 my @sols = $self->all(%options);
299 8 my @values = map { $_->value($var) } @sols;
300 8 ▶ return wantarray ? @values : \@values;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 7 1 8
301 }
302  
303 2 ▶sub distinct_values ( $self, $var, %options ) {
Subroutine distinct_values: called CC=4 SCAR=14.0
Pod documented
304 2 my @vals = $self->all_values( $var, %options );
305 2 require Logic::Relational::State;
306 2 require Logic::Relational::Substitution;
307 2 my $dummy_state = Logic::Relational::State->new(
308 substitution => Logic::Relational::Substitution->new,
309 goals => [],
310 );
311 2 my %seen;
312 my @unique;
313 2 for my $v (@vals) {
314 8 my $sig = $dummy_state->canonical_term_signature($v);
315 8 ▶ if ( !$seen{$sig}++ ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($seen{$sig}++) 8 0 8
316 8 push @unique, $v;
317 }
318 }
319 2 ▶ return wantarray ? @unique : \@unique;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 2 0 2
320 }
321  
322 1 ▶sub all_tuples ( $self, @args ) {
Subroutine all_tuples: called CC=12 SCAR=31.4
Pod documented
323 1 my $vars;
324 my %options;
325 1 ▶ if ( @args && ref( $args[0] ) eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args and ref $args[0] eq 'ARRAY') { } 1 0 1
Condition33%1/3
@args and ref $args[0] eq "ARRAY"
!ll&&!rl&&r
001
MC/DC0%0/2
@args and ref $args[0] eq "ARRAY"
@args ref $args[0] eq "ARRAY"
Truth table33%1/3
A and B
A= @argsB= ref $args[0] eq "ARRAY"
ABresult
0X0
100
111
326 1 $vars = shift @args;
327 1 %options = @args;
328 }
329 else {
330 0 my @v_list;
331 0 ▶ while ( @args && ref( $args[0] ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args and ref $args[0]) 0 0 0
Condition0%0/3
@args and ref $args[0]
!ll&&!rl&&r
000
MC/DC0%0/2
@args and ref $args[0]
@args ref $args[0]
Truth table0%0/3
A and B
A= @argsB= ref $args[0]
ABresult
0X0
100
111
332 0 push @v_list, shift @args;
333 }
334 0 $vars = \@v_list;
335 0 %options = @args;
336 }
337 1 ▶ croak "all_tuples requires an arrayref or list of variables"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $vars eq "ARRAY" and @$vars 0 1 1
Condition33%1/3
ref $vars eq "ARRAY" and @$vars
!ll&&!rl&&r
001
MC/DC0%0/2
ref $vars eq "ARRAY" and @$vars
ref $vars eq "ARRAY" @$vars
Truth table33%1/3
A and B
A= ref $vars eq "ARRAY"B= @$vars
ABresult
0X0
100
111
338 unless ref($vars) eq 'ARRAY' && @$vars;
339 1 ▶ my $distinct = exists $options{distinct} ? $options{distinct} : 1;
Branch: 1 branch
BranchTrueFalseTotal
exists $options{'distinct'} ? : 0 1 1
340 1 my @sols = $self->all(%options);
341  
342 1 require Logic::Relational::State;
343 1 require Logic::Relational::Substitution;
344 1 my $dummy_state = Logic::Relational::State->new(
345 substitution => Logic::Relational::Substitution->new,
346 goals => [],
347 );
348  
349 1 my %seen;
350 my @tuples;
351 1 for my $sol (@sols) {
352 12 my @tuple = map { $sol->value($_) } @$vars;
353 12 ▶ if ($distinct) {
Branch: 1 branch
BranchTrueFalseTotal
if ($distinct) 12 0 12
354 12 my $sig = $dummy_state->canonical_term_signature( \@tuple );
355 12 ▶ next if $seen{$sig}++;
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$sig}++ 0 12 12
356 }
357 12 push @tuples, \@tuple;
358 }
359 1 ▶ return wantarray ? @tuples : \@tuples;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 1 0 1
360 }
361  
362 2 ▶sub first_value ( $self, $var ) {
Subroutine first_value: called CC=2 SCAR=7.2
Pod documented
363 2 ▶ my $sol = $self->next // return undef;
Condition50%1/2
$self->next // (return undef)
l!l
20
MC/DC0%0/1
$self->next // (return undef)
$self->next
Truth table50%1/2
A
A= $self->next
Aresult
11
00
364 2 return $sol->value($var);
365 }
366  
367 1 ▶sub value ( $self, $var ) {
Subroutine value: called CC=1 SCAR=0.0
Pod documented
368 1 return $self->first_value($var);
369 }
370  
371 27 1;
« blib/lib/Logic/Relational/Goal/Call.pm ↑ Summary lib/Logic/Relational/Serializer.pm »