Device/Chip.pm

filter: Statementstmt 79.1% 38 / 48 Branchbran 75.0% 3 / 4 Conditioncond 50.0% 3 / 6 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 81.8% 9 / 11 Podpod 50.0% 2 / 4 totaltotal 73.6% 56 / 76 CC 6 SCAR 8.5
CC
6
Cov
76%
adapter
6.0
_parse_options
3.0
protocol
2.1
CRAP 2.3
« Test/Device/Chip/Adapter.pm ↑ Summary Device/Chip/Sensor.pm »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2015-2023 -- leonerd@leonerd.org.uk
5  
6 9 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 9 ▶use Object::Pad 0.800;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 package Device::Chip 0.27;
11 class Device::Chip :repr(HASH);
12  
13 9 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 9 ▶use Future::AsyncAwait 0.38; # async method
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 =head1 NAME
18  
19 C<Device::Chip> - an abstraction of a hardware chip IO driver
20  
21 =head1 DESCRIPTION
22  
23 =for highlighter language=perl
24  
25 =over 2
26  
27 B<Note>: this document is currently under heavy development. Details will be
28 added, changed, and evolved as it progresses. Be warned that currently
29 anything may be changed from one version to the next.
30  
31 =back
32  
33 This package describes an interface that classes can use to implement a driver
34 to talk to a specific hardware chip or module. An instance implementing this
35 interface would communicate with the actual hardware device via some instance
36 of the related interface, L<Device::Chip::Adapter>.
37  
38 The documentation in this file is aimed primarily at users of C<Device::Chip>
39 subclasses. For more information on authoring such a module, see instead
40 L<Device::Chip::Authoring>.
41  
42 =head2 USING A CHIP DRIVER
43  
44 To actually use a chip driver to talk to a specific piece of hardware that is
45 connected to the computer, an adapter must be supplied. This will be an
46 instance of some class that satisfies the L<Device::Chip::Adapter> interface.
47 The chip driver will use this adapter instance to access the underlying
48 hardware port used to electrically connect to the chip and communicate with
49 it. This is supplied by invoking the L</mount> method. For example:
50  
51 my $chip = Device::Chip::MAX7219->new;
52  
53 my $adapter = Device::Chip::Adapter::FTDI->new;
54  
55 await $chip->mount( $adapter );
56  
57 =cut
58  
59 =head1 CONSTRUCTOR
60  
61 =cut
62  
63 =head2 new
64  
65 $chip = Device::Chip->new;
66  
67 Returns a new instance of a chip driver object.
68  
69 =cut
70  
71 =head1 METHODS
72  
73 The following methods documented in an C<await> expression return L<Future>
74 instances.
75  
76 This allows them to easily be used as a simple synchronous method by using the
77 trailing L<Future/get> call. Alternatively, if the underlying adapter allows a
78 fully asynchronous mode of operation, they can be combined in the usual ways
79 for futures to provide more asynchronous use of the device.
80  
81 =cut
82  
83 9 field $_adapter;
84 method adapter
85 0 ▶{
Subroutine adapter: not called CC=2 SCAR=17.9
Pod undocumented
86 0 ▶ return $_adapter //
Condition0%0/2
$_adapter // croak("This chip has not yet been mounted on an adapter")
l!l
00
MC/DC0%0/1
$_adapter // croak("This chip has not yet been mounted on an adapter")
$_adapter
Truth table0%0/2
A
A= $_adapter
Aresult
11
00
87 croak "This chip has not yet been mounted on an adapter";
88 9 }
89  
90 9 field $_protocol;
91 method protocol
92 17 ▶{
Subroutine protocol: called CC=2 SCAR=7.6
Pod undocumented
93 17 ▶ return $_protocol //
Condition50%1/2
$_protocol // croak("This chip has not yet been connected to a protocol")
l!l
170
MC/DC0%0/1
$_protocol // croak("This chip has not yet been connected to a protocol")
$_protocol
Truth table50%1/2
A
A= $_protocol
Aresult
11
00
94 croak "This chip has not yet been connected to a protocol";
95 9 }
96  
97 =head2 mount
98  
99 $chip = await $chip->mount( $adapter, %params );
100  
101 Supplies the chip driver with the means to actually communicate with the
102 connected device, via some electrical interface connected to the computer.
103  
104 The parameters given in C<%params> will vary depending on the specific chip in
105 question, and should be documented there.
106  
107 =cut
108  
109 2 ▶async method mount ( $adapter, %params )
Subroutine mount: called CC=2 SCAR=7.1
Pod documented
110 2 {
111 2 $_adapter = $adapter;
112  
113 2 my $pname = $self->PROTOCOL;
114  
115 2 $_protocol = await $_adapter->make_protocol( $pname );
116  
117 2 ▶ my $code = $self->can( "${pname}_options" ) or
Branch: 1 branch
BranchTrueFalseTotal
my $code = $self->can("${pname}_options") or return $self 0 2 2
118 return $self;
119  
120 0 await $self->protocol->configure(
121 $self->$code( %params )
122 );
123  
124 0 return $self;
125 9 }
126  
127 # Perl 5.36+ can distinguish this; but this still works fine on older perls
128 9 ▶use constant true => (1 == 1);
Subroutine BEGIN: called CC=1 SCAR=0.0
129  
130 4 ▶sub _parse_options ( $, $str )
Subroutine _parse_options: called CC=3 SCAR=11.0
131 {
132 4 ▶ return map { m/^([^=]+)=(.*)$/ ? ( $1 => $2 ) : ( $_ => true ) }
Branch: 1 branch
BranchTrueFalseTotal
/^([^=]+)=(.*)$/u ? : 3 1 4
Condition100%2/2
$str // ""
l!l
31
MC/DC100%1/1
$str // ""
$str
Truth table100%2/2
A
A= $str
Aresult
11
00
133 split m/,/, $str // "";
134  
135 }
136  
137 =head2 mount_from_paramstr
138  
139 $chip = await $chip->mount_from_paramstr( $adapter, $paramstr );
140  
141 A variant of L</mount> that parses its options from the given string. This
142 string should be a comma-separated list of parameters, where each is given as
143 a name and value separated by equals sign. If there is no equals sign, the
144 value is implied as true, as a convenience for parameters that are simple
145 boolean flags.
146  
147 =cut
148  
149 0 ▶async method mount_from_paramstr ( $adapter, $paramstr )
Subroutine mount_from_paramstr: not called CC=1 SCAR=6.9
Pod documented
150 0 {
151 0 await $self->mount( $adapter, $self->_parse_options( $paramstr ) );
152 9 }
153  
154 =head1 AUTHOR
155  
156 Paul Evans <leonerd@leonerd.org.uk>
157  
158 =cut
159  
160 9 0x55AA;
« Test/Device/Chip/Adapter.pm ↑ Summary Device/Chip/Sensor.pm »