File Coverage

blib/lib/Bit/MorseSignals.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Bit::MorseSignals;
2              
3 13     13   45140 use strict;
  13         28  
  13         498  
4 13     13   69 use warnings;
  13         25  
  13         914  
5              
6             =head1 NAME
7              
8             Bit::MorseSignals - The MorseSignals protocol.
9              
10             =head1 VERSION
11              
12             Version 0.08
13              
14             =cut
15              
16             our $VERSION = '0.08';
17              
18             =head1 SYNOPSIS
19              
20             use Bit::MorseSignals::Emitter;
21             use Bit::MorseSignals::Receiver;
22              
23             my $deuce = Bit::MorseSignals::Emitter->new;
24             my $pants = Bit::MorseSignals::Receiver->new(done => sub { print $_[1], "\n" });
25              
26             $deuce->post('HLAGH') for 1 .. 3;
27             $pants->push while defined ($_ = $deuce->pop);
28              
29             =head1 DESCRIPTION
30              
31             In unidirectionnal communication channels (such as networking or IPC), the main issue is often to know the length of the message. Some possible solutions are fixed-length messages (which is quite cumbersome) or a special ending sequence (but it no longer can appear in the data). This module proposes another solution, by using a begin/end signature specialized for each message.
32              
33             An actual implementation is also provided :
34              
35             =over 4
36              
37             =item L is a base class for emitters ;
38              
39             =item L is a base class for receivers.
40              
41             =back
42              
43             Go to those pages if you just want the stuff done and don't care about how it gets there.
44              
45             =head1 PROTOCOL
46              
47             Each byte of the data string is converted into its bits sequence, with bits of lowest weight coming first. All those bits sequences are put into the same order as the characters occur in the string.
48              
49             The header is composed of three bits (lowest weight coming first) :
50              
51             =over 4
52              
53             =item - The 2 first ones denote the data type : a value of 0 is used for a plain string, 1 for an UTF-8 encoded string, and 2 for a L object. See also the L section ;
54              
55             =item - The third one is reserved. For compatibility reasons, the receiver should for now enforce the message data type to plain when this bit is lit.
56              
57             =back
58              
59             The emitter computes then the longuest sequence of successives 0 (say, m) and 1 (n) in the concatenation of the header and the data. A signature is then chosen :
60              
61             =over 4
62              
63             =item - If m > n, we take n+1 times 1 followed by one 0 ;
64              
65             =item - Otherwise, we take m+1 times 0 followed by one 1.
66              
67             =back
68              
69             The signal is then formed by concatenating the signature, the header, the data bits and the reversed signature (i.e. the bits of the signature in the reverse order).
70              
71             a ... a b | t0 t1 r | ... data ... | b a ... a
72             signature | header | data | reversed signature
73              
74             The receiver knows that the signature has been sent when it has catched at least one 0 and one 1. The signal is completely transferred when it has received for the first time the whole reversed signature.
75              
76             =head1 CONSTANTS
77              
78             =cut
79              
80             use constant {
81 13         1307 BM_DATA_AUTO => -1,
82             BM_DATA_PLAIN => 0,
83             BM_DATA_UTF8 => 1,
84             BM_DATA_STORABLE => 2,
85 13     13   67 };
  13         32  
86              
87             =head2 C
88              
89             Default for non-references messages. Try to guess if the given scalar is an UTF-8 string with C.
90              
91             =head2 C
92              
93             Treats the data as a plain string. No extra mangling in done.
94              
95             =head2 C
96              
97             Treats the data as an UTF-8 string. The string is C'd in a binary string before sending, and C'd by the receiver.
98              
99             =head2 C
100              
101             The scalar, array or hash reference given is C'd by the sender and C'd by the receiver.
102              
103             =head1 EXPORT
104              
105             The constants L, L, L and L are only exported on request, either by specifying their names or the C<':consts'> tag.
106              
107             =cut
108              
109 13     13   86 use base qw;
  13         29  
  13         2570  
110              
111             our @EXPORT = ();
112             our %EXPORT_TAGS = (
113             'consts' => [ qw ]
114             );
115             our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
116             $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
117              
118             =head1 DEPENDENCIES
119              
120             L (standard since perl 5), L (since perl 5.007003), L (idem).
121              
122             =head1 SEE ALSO
123              
124             L, L.
125              
126             =head1 AUTHOR
127              
128             Vincent Pit, C<< >>, L.
129              
130             You can contact me by mail or on C (vincent).
131              
132             =head1 BUGS
133              
134             Please report any bugs or feature requests to C, or through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
135              
136             =head1 SUPPORT
137              
138             You can find documentation for this module with the perldoc command.
139              
140             perldoc Bit::MorseSignals
141              
142             Tests code coverage report is available at L.
143              
144             =head1 COPYRIGHT & LICENSE
145              
146             Copyright 2008 Vincent Pit, all rights reserved.
147              
148             This program is free software; you can redistribute it and/or modify it
149             under the same terms as Perl itself.
150              
151             =cut
152              
153             1; # End of Bit::MorseSignals