blib/lib/SignalWire/POM/Section.pm

filter: Statementstmt 20.0% 32 / 160 Branchbran 3.1% 2 / 64 Conditioncond 3.2% 2 / 61 MC/DCmcdc 0.0% 0 / 37 Subroutinesub 52.6% 10 / 19 Podpod 0.0% 0 / 7 totaltotal 13.2% 46 / 348 CC 61 SCAR 54.5
CC
61
Cov
13%
render_xml
462.0
render_markdown
380.0
to_hash
110.0
CRAP 233.2
« blib/lib/SignalWire/Skills/Builtin/Datasphere.pm ↑ Summary blib/lib/SignalWire/POM/PromptObjectModel.pm »
1 package SignalWire::POM::Section;
2 # Copyright (c) 2025 SignalWire
3 # Licensed under the MIT License.
4 #
5 # Typed POM Section — Perl port of signalwire.pom.pom.Section
6 # (signalwire-python/signalwire/signalwire/pom/pom.py).
7 #
8 # Each Section has a title, optional body text, optional bullet points,
9 # and any number of nested subsections. The class can render itself as
10 # Markdown or XML and serialise to a hash for JSON/YAML emission.
11 #
12 # Output format MUST match the Python reference byte-for-byte; see
13 # t/pom/prompt_object_model.t for the parity assertions.
14  
15 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 1 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
19 1 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
20 1 ▶use Tie::IxHash;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 # ---------- attributes ----------
23  
24 # title is optional only on the top-level/first section of a POM; for
25 # subsections the caller is required to provide one (validated in
26 # add_subsection / set when calling the constructor directly).
27 has title => (
28 is => 'rw',
29 0 ▶ default => sub { undef },
Subroutine __ANON__: not called CC=1 SCAR=6.9
30 1 );
31  
32 has body => (
33 is => 'rw',
34 0 ▶ default => sub { '' },
Subroutine __ANON__: not called CC=1 SCAR=6.9
35 1 );
36  
37 has bullets => (
38 is => 'rw',
39 0 ▶ default => sub { [] },
Subroutine __ANON__: not called CC=1 SCAR=6.9
40 1 );
41  
42 has subsections => (
43 is => 'rw',
44 4 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
45 1 );
46  
47 # Whether this section should be auto-numbered when rendered alongside
48 # numbered siblings. ``undef`` means "follow sibling default"; explicit
49 # 0 forces a section to stay un-numbered even when siblings are
50 # numbered. Mirrors Python's ``numbered`` arg semantics.
51 has numbered => (
52 is => 'rw',
53 3 ▶ default => sub { undef },
Subroutine __ANON__: called CC=1 SCAR=0.0
54 1 );
55  
56 has numberedBullets => (
57 is => 'rw',
58 3 ▶ default => sub { 0 },
Subroutine __ANON__: called CC=1 SCAR=0.0
59 1 );
60  
61 # ---------- BUILD: validate types of body / bullets ----------
62  
63 4 ▶sub BUILD {
Subroutine BUILD: called CC=5 SCAR=20.9
Pod undocumented
64 4 my ($self, $args) = @_;
65  
66 4 ▶ if (defined $args->{body} && ref $args->{body}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $args->{"body"} and ref $args->{"body"}) 0 4 4
Condition33%1/3
defined $args->{"body"} and ref $args->{"body"}
!ll&&!rl&&r
040
MC/DC0%0/2
defined $args->{"body"} and ref $args->{"body"}
defined $args->{"body"} ref $args->{"body"}
Truth table33%1/3
A and B
A= defined $args->{"body"}B= ref $args->{"body"}
ABresult
0X0
100
111
67 croak "body must be a string, not " . ref($args->{body})
68 0 . ". If you meant to pass a list of bullet points, use bullets parameter instead.";
69 }
70 4 ▶ if (defined $args->{bullets} && ref $args->{bullets} ne 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $args->{"bullets"} and ref $args->{"bullets"} ne "ARRAY") 0 4 4
Condition33%1/3
defined $args->{"bullets"} and ref $args->{"bullets"} ne "ARRAY"
!ll&&!rl&&r
040
MC/DC0%0/2
defined $args->{"bullets"} and ref $args->{"bullets"} ne "ARRAY"
defined $args->{"bullets"} ref $args->{"bullets"} ne "ARRAY"
Truth table33%1/3
A and B
A= defined $args->{"bullets"}B= ref $args->{"bullets"} ne "ARRAY"
ABresult
0X0
100
111
71 0 croak "bullets must be a list or undef, not " . ref($args->{bullets});
72 }
73 4 return;
74 }
75  
76 # ---------- public methods ----------
77  
78 # Replace the body text on this section. Mirrors Python's
79 # ``Section.add_body`` which is documented to "Add OR REPLACE the body
80 # text" — calling this overwrites any prior value rather than appending.
81 0 ▶sub add_body {
Subroutine add_body: not called CC=2 SCAR=17.9
Pod undocumented
82 0 my ($self, $body) = @_;
83 0 ▶ croak "body must be a string, not " . ref($body) if ref $body;
Branch: 1 branch
BranchTrueFalseTotal
if ref $body 0 0 0
84 0 $self->body($body);
85 0 return $self;
86 }
87  
88 # Append bullets to the existing list (does NOT replace).
89 0 ▶sub add_bullets {
Subroutine add_bullets: not called CC=4 SCAR=30.0
Pod undocumented
90 0 my ($self, $bullets) = @_;
91 0 ▶ croak "bullets must be a list, not " . (ref($bullets) || 'scalar')
Branch: 1 branch
BranchTrueFalseTotal
if not defined $bullets or ref $bullets ne "ARRAY" 0 0 0
Condition0%0/5
not defined $bullets or ref $bullets ne "ARRAY"
l!l&&r!l&&!r
000
ref $bullets || 'scalar'
l!l
00
MC/DC0%0/2
not defined $bullets or ref $bullets ne "ARRAY"
not defined $bullets ref $bullets ne "ARRAY"
MC/DC0%0/1
ref $bullets || 'scalar'
ref $bullets
Truth table0%0/3
not(A) or B
A= not defined $bulletsB= ref $bullets ne "ARRAY"
ABresult
1X1
011
000
Truth table0%0/2
A
A= ref $bullets
Aresult
11
00
92 if !defined $bullets || ref $bullets ne 'ARRAY';
93 0 push @{ $self->bullets }, @$bullets;
94 0 return $self;
95 }
96  
97 # Add a subsection and return the newly-created Section object so the
98 # caller can chain ``->add_body / ->add_bullets`` onto it (matching
99 # Python's return-the-Section ergonomic).
100 0 ▶sub add_subsection {
Subroutine add_subsection: not called CC=6 SCAR=37.4
Pod undocumented
101 0 my ($self, %opts) = @_;
102  
103 0 ▶ croak "Subsections must have a title" unless defined $opts{title};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $opts{"title"} 0 0 0
104  
105 my $sub = SignalWire::POM::Section->new(
106 title => $opts{title},
107 body => exists $opts{body} ? $opts{body} : '',
108 bullets => exists $opts{bullets} ? $opts{bullets} : [],
109 numbered => exists $opts{numbered} ? $opts{numbered} : 0,
110 0 ▶ numberedBullets => exists $opts{numberedBullets} ? $opts{numberedBullets} : 0,
Branch: 4 branches
BranchTrueFalseTotal
exists $opts{'body'} ? : 0 0 0
exists $opts{'bullets'} ? : 0 0 0
exists $opts{'numbered'} ? : 0 0 0
exists $opts{'numberedBullets'} ? : 0 0 0
111 );
112 0 push @{ $self->subsections }, $sub;
113 0 return $sub;
114 }
115  
116 # Convert the section to an ordered hashref for JSON/YAML emission.
117 # Key order matches Python's to_dict (title, body, bullets, subsections,
118 # numbered, numberedBullets). Empty fields are dropped — the resulting
119 # hash is suitable for `from_json` / `from_yaml` round-tripping.
120 0 ▶sub to_hash {
Subroutine to_hash: not called CC=10 SCAR=47.0
Pod undocumented
121 0 my ($self) = @_;
122 0 tie my %data, 'Tie::IxHash';
123  
124 0 ▶ if (defined $self->title) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->title) 0 0 0
125 0 $data{title} = $self->title;
126 }
127 0 ▶ if (defined $self->body && length $self->body) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->body and length $self->body) 0 0 0
Condition0%0/3
defined $self->body and length $self->body
!ll&&!rl&&r
000
MC/DC0%0/2
defined $self->body and length $self->body
defined $self->body length $self->body
Truth table0%0/3
A and B
A= defined $self->bodyB= length $self->body
ABresult
0X0
100
111
128 0 $data{body} = $self->body;
129 }
130 0 ▶ if ($self->bullets && @{ $self->bullets }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->bullets and @{$self->bullets;}) 0 0 0
Condition0%0/3
$self->bullets and @{$self->bullets;}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->bullets and @{$self->bullets;}
$self->bullets @{$self->bullets;}
Truth table0%0/3
A and B
A= $self->bulletsB= @{$self->bullets;}
ABresult
0X0
100
111
131 0 $data{bullets} = [ @{ $self->bullets } ];
132 }
133 0 ▶ if ($self->subsections && @{ $self->subsections }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->subsections and @{$self->subsections;}) 0 0 0
Condition0%0/3
$self->subsections and @{$self->subsections;}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->subsections and @{$self->subsections;}
$self->subsections @{$self->subsections;}
Truth table0%0/3
A and B
A= $self->subsectionsB= @{$self->subsections;}
ABresult
0X0
100
111
134 0 $data{subsections} = [ map { $_->to_hash } @{ $self->subsections } ];
135 }
136 0 ▶ if ($self->numbered) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->numbered) 0 0 0
137 0 $data{numbered} = JSON::PP::true();
138 }
139 0 ▶ if ($self->numberedBullets) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->numberedBullets) 0 0 0
140 0 $data{numberedBullets} = JSON::PP::true();
141 }
142  
143 0 return \%data;
144 }
145  
146 # Render this section as Markdown. ``level`` is the heading level (1=#,
147 # 2=##, ...). ``section_number`` is an arrayref of the section's
148 # position among numbered siblings (e.g. [1,2,3] for "1.2.3."). Mirrors
149 # Python's Section.render_markdown signature/output exactly.
150 0 ▶sub render_markdown {
Subroutine render_markdown: not called CC=19 SCAR=59.4
Pod undocumented
151 0 my ($self, $level, $section_number) = @_;
152 0 ▶ $level //= 2;
Condition0%0/2
$level //= 2
l!l
00
MC/DC0%0/1
$level //= 2
$level
Truth table0%0/2
A
A= $level
Aresult
11
00
153 0 ▶ $section_number //= [];
Condition0%0/2
$section_number //= []
l!l
00
MC/DC0%0/1
$section_number //= []
$section_number
Truth table0%0/2
A
A= $section_number
Aresult
11
00
154  
155 0 my @md;
156  
157 0 ▶ if (defined $self->title) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->title) 0 0 0
158 0 my $prefix = '';
159 0 ▶ if (@$section_number) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$section_number) 0 0 0
160 0 $prefix = join('.', @$section_number) . '. ';
161 }
162 0 push @md, ('#' x $level) . " ${prefix}" . $self->title . "\n";
163 }
164  
165 0 ▶ if (defined $self->body && length $self->body) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->body and length $self->body) 0 0 0
Condition0%0/3
defined $self->body and length $self->body
!ll&&!rl&&r
000
MC/DC0%0/2
defined $self->body and length $self->body
defined $self->body length $self->body
Truth table0%0/3
A and B
A= defined $self->bodyB= length $self->body
ABresult
0X0
100
111
166 0 push @md, $self->body . "\n";
167 }
168  
169 0 ▶ if ($self->bullets && @{ $self->bullets }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->bullets and @{$self->bullets;}) 0 0 0
Condition0%0/3
$self->bullets and @{$self->bullets;}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->bullets and @{$self->bullets;}
$self->bullets @{$self->bullets;}
Truth table0%0/3
A and B
A= $self->bulletsB= @{$self->bullets;}
ABresult
0X0
100
111
170 0 my $i = 0;
171 0 for my $bullet (@{ $self->bullets }) {
172 0 $i++;
173 0 ▶ if ($self->numberedBullets) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->numberedBullets) { } 0 0 0
174 0 push @md, "${i}. $bullet";
175 } else {
176 0 push @md, "- $bullet";
177 }
178 }
179 0 push @md, '';
180 }
181  
182 # If any subsection has numbered=true (truthy, not just defined),
183 # all sibling subsections that are not explicitly numbered=>0 get
184 # a number too. Matches Python's any-numbered semantics.
185 0 my $any_subsection_numbered = 0;
186 0 for my $sub (@{ $self->subsections }) {
187 0 ▶ if ($sub->numbered) { $any_subsection_numbered = 1; last; }
Branch: 1 branch
BranchTrueFalseTotal
if ($sub->numbered) 0 0 0
188 }
189  
190 0 my $i = 0;
191 0 for my $sub (@{ $self->subsections }) {
192 0 $i++;
193 0 my ($new_section_number, $next_level);
194 0 ▶ if (defined $self->title || @$section_number) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->title or @$section_number) { } 0 0 0
Condition0%0/3
defined $self->title or @$section_number
l!l&&r!l&&!r
000
MC/DC0%0/2
defined $self->title or @$section_number
defined $self->title @$section_number
Truth table0%0/3
A or B
A= defined $self->titleB= @$section_number
ABresult
1X1
011
000
195 # Python: ``if any_subsection_numbered and subsection.numbered is not False``
196 # Use defined-but-zero to mean "explicit false"; any other
197 # truthy / undef value participates in numbering.
198 0 ▶ if ($any_subsection_numbered
Branch: 1 branch
BranchTrueFalseTotal
if ($any_subsection_numbered and not defined $sub->numbered && !$sub->numbered) { } 0 0 0
Condition0%0/6
$any_subsection_numbered and not defined $sub->numbered && !$sub->numbered
!ll&&!rl&&r
000
defined $sub->numbered && !$sub->numbered
!ll&&!rl&&r
000
MC/DC0%0/3
$any_subsection_numbered and not defined $sub->numbered && !$sub->numbered
$any_subsection_numbered defined $sub->numbered !$sub->numbered
Truth table0%0/4
A and not(B && not(C))
A= $any_subsection_numberedB= defined $sub->numberedC= !$sub->numbered
ABCresult
0XX0
1110
10X1
1101
199 && !(defined $sub->numbered && !$sub->numbered)) {
200 0 $new_section_number = [ @$section_number, $i ];
201 } else {
202 0 $new_section_number = $section_number;
203 }
204 0 $next_level = $level + 1;
205 } else {
206 # Root-without-title: don't increment numbering or level.
207 0 $new_section_number = $section_number;
208 0 $next_level = $level;
209 }
210 0 push @md, $sub->render_markdown($next_level, $new_section_number);
211 }
212  
213 0 return join("\n", @md);
214 }
215  
216 # Render this section as XML. ``indent`` is the number of two-space
217 # indentation levels. ``section_number`` is the same numbering arrayref
218 # used by render_markdown. Mirrors Python's Section.render_xml exactly.
219 0 ▶sub render_xml {
Subroutine render_xml: not called CC=21 SCAR=61.4
Pod undocumented
220 0 my ($self, $indent, $section_number) = @_;
221 0 ▶ $indent //= 0;
Condition0%0/2
$indent //= 0
l!l
00
MC/DC0%0/1
$indent //= 0
$indent
Truth table0%0/2
A
A= $indent
Aresult
11
00
222 0 ▶ $section_number //= [];
Condition0%0/2
$section_number //= []
l!l
00
MC/DC0%0/1
$section_number //= []
$section_number
Truth table0%0/2
A
A= $section_number
Aresult
11
00
223  
224 0 my $indent_str = ' ' x $indent;
225 0 my @xml;
226  
227 0 push @xml, "${indent_str}<section>";
228  
229 0 ▶ if (defined $self->title) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->title) 0 0 0
230 0 my $prefix = '';
231 0 ▶ if (@$section_number) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$section_number) 0 0 0
232 0 $prefix = join('.', @$section_number) . '. ';
233 }
234 0 push @xml, "${indent_str} <title>${prefix}" . $self->title . '</title>';
235 }
236  
237 0 ▶ if (defined $self->body && length $self->body) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->body and length $self->body) 0 0 0
Condition0%0/3
defined $self->body and length $self->body
!ll&&!rl&&r
000
MC/DC0%0/2
defined $self->body and length $self->body
defined $self->body length $self->body
Truth table0%0/3
A and B
A= defined $self->bodyB= length $self->body
ABresult
0X0
100
111
238 0 push @xml, "${indent_str} <body>" . $self->body . '</body>';
239 }
240  
241 0 ▶ if ($self->bullets && @{ $self->bullets }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->bullets and @{$self->bullets;}) 0 0 0
Condition0%0/3
$self->bullets and @{$self->bullets;}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->bullets and @{$self->bullets;}
$self->bullets @{$self->bullets;}
Truth table0%0/3
A and B
A= $self->bulletsB= @{$self->bullets;}
ABresult
0X0
100
111
242 0 push @xml, "${indent_str} <bullets>";
243 0 my $i = 0;
244 0 for my $bullet (@{ $self->bullets }) {
245 0 $i++;
246 0 ▶ if ($self->numberedBullets) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->numberedBullets) { } 0 0 0
247 0 push @xml, "${indent_str} <bullet id=\"${i}\">${bullet}</bullet>";
248 } else {
249 0 push @xml, "${indent_str} <bullet>${bullet}</bullet>";
250 }
251 }
252 0 push @xml, "${indent_str} </bullets>";
253 }
254  
255 0 ▶ if ($self->subsections && @{ $self->subsections }) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->subsections and @{$self->subsections;}) 0 0 0
Condition0%0/3
$self->subsections and @{$self->subsections;}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->subsections and @{$self->subsections;}
$self->subsections @{$self->subsections;}
Truth table0%0/3
A and B
A= $self->subsectionsB= @{$self->subsections;}
ABresult
0X0
100
111
256 0 push @xml, "${indent_str} <subsections>";
257 0 my $any_subsection_numbered = 0;
258 0 for my $sub (@{ $self->subsections }) {
259 0 ▶ if ($sub->numbered) { $any_subsection_numbered = 1; last; }
Branch: 1 branch
BranchTrueFalseTotal
if ($sub->numbered) 0 0 0
260 }
261 0 my $i = 0;
262 0 for my $sub (@{ $self->subsections }) {
263 0 $i++;
264 0 my $new_section_number;
265 0 ▶ if (defined $self->title || @$section_number) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->title or @$section_number) { } 0 0 0
Condition0%0/3
defined $self->title or @$section_number
l!l&&r!l&&!r
000
MC/DC0%0/2
defined $self->title or @$section_number
defined $self->title @$section_number
Truth table0%0/3
A or B
A= defined $self->titleB= @$section_number
ABresult
1X1
011
000
266 0 ▶ if ($any_subsection_numbered
Branch: 1 branch
BranchTrueFalseTotal
if ($any_subsection_numbered and not defined $sub->numbered && !$sub->numbered) { } 0 0 0
Condition0%0/6
$any_subsection_numbered and not defined $sub->numbered && !$sub->numbered
!ll&&!rl&&r
000
defined $sub->numbered && !$sub->numbered
!ll&&!rl&&r
000
MC/DC0%0/3
$any_subsection_numbered and not defined $sub->numbered && !$sub->numbered
$any_subsection_numbered defined $sub->numbered !$sub->numbered
Truth table0%0/4
A and not(B && not(C))
A= $any_subsection_numberedB= defined $sub->numberedC= !$sub->numbered
ABCresult
0XX0
1110
10X1
1101
267 && !(defined $sub->numbered && !$sub->numbered)) {
268 0 $new_section_number = [ @$section_number, $i ];
269 } else {
270 0 $new_section_number = $section_number;
271 }
272 } else {
273 0 $new_section_number = $section_number;
274 }
275 0 push @xml, $sub->render_xml($indent + 2, $new_section_number);
276 }
277 0 push @xml, "${indent_str} </subsections>";
278 }
279  
280 0 push @xml, "${indent_str}</section>";
281  
282 0 return join("\n", @xml);
283 }
284  
285 1 1;
286  
287 __END__
« blib/lib/SignalWire/Skills/Builtin/Datasphere.pm ↑ Summary blib/lib/SignalWire/POM/PromptObjectModel.pm »