lib/Bit/MorseSignals.pm

   1 package Bit::MorseSignals;
   2
   3 use strict;
   4 use warnings;
   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(
  25      done => sub { print $_[1], "\n" },
  26     );
  27
  28     $deuce->post('HLAGH') for 1 .. 3;
  29     $pants->push while defined ($_ = $deuce->pop);
  30
  31 =head1 DESCRIPTION
  32
  33 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.
  34
  35 An actual implementation is also provided :
  36
  37 =over 4
  38
  39 =item *
  40
  41 L<Bit::MorseSignals::Emitter> is a base class for emitters ;
  42
  43 =item *
  44
  45 L<Bit::MorseSignals::Receiver> is a base class for receivers.
  46
  47 =back
  48
  49 Go to those pages if you just want the stuff done and don't care about how it gets there.
  50
  51 =head1 PROTOCOL
  52
  53 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.
  54
  55 The header is composed of three bits (lowest weight coming first) :
  56
  57 =over 4
  58
  59 =item *
  60
  61 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<Storable> object. See also the L</CONSTANTS> section ;
  62
  63 =item *
  64
  65 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.
  66
  67 =back
  68
  69 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 :
  70
  71 =over 4
  72
  73 =item *
  74
  75 If m > n, we take n+1 times 1 followed by one 0 ;
  76
  77 =item *
  78
  79 Otherwise, we take m+1 times 0 followed by one 1.
  80
  81 =back
  82
  83 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).
  84
  85     a ... a b | t0 t1 r | ... data ... | b a ... a
  86     signature | header  |     data     | reversed signature
  87
  88 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.
  89
  90 =head1 CONSTANTS
  91
  92 =cut
  93
  94 use constant {
  95  BM_DATA_AUTO     => -1,
  96  BM_DATA_PLAIN    => 0,
  97  BM_DATA_UTF8     => 1,
  98  BM_DATA_STORABLE => 2,
  99 };
 100
 101 =head2 C<BM_DATA_AUTO>
 102
 103 Default for non-references messages. Try to guess if the given scalar is an UTF-8 string with C<Encode::is_utf8>.
 104
 105 =head2 C<BM_DATA_PLAIN>
 106
 107 Treats the data as a plain string. No extra mangling in done.
 108
 109 =head2 C<BM_DATA_UTF8>
 110
 111 Treats the data as an UTF-8 string. The string is C<Encode::encode_utf8>'d in a binary string before sending, and C<Encode::decode_utf8>'d by the receiver.
 112
 113 =head2 C<BM_DATA_STORABLE>
 114
 115 The scalar, array or hash reference given is C<Storable::freeze>'d by the sender and C<Storable::thaw>'d by the receiver.
 116
 117 =head1 EXPORT
 118
 119 The constants L</BM_DATA_AUTO>, L</BM_DATA_PLAIN>, L</BM_DATA_UTF8> and L</BM_DATA_STORABLE> are only exported on request, either by specifying their names or the C<':consts'> tag.
 120
 121 =cut
 122
 123 use base qw<Exporter>;
 124
 125 our @EXPORT         = ();
 126 our %EXPORT_TAGS    = (
 127  'consts' => [ qw<BM_DATA_AUTO BM_DATA_PLAIN BM_DATA_UTF8 BM_DATA_STORABLE> ]
 128 );
 129 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
 130 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
 131
 132 =head1 DEPENDENCIES
 133
 134 L<Carp> (standard since perl 5), L<Encode> (since perl 5.007003), L<Storable> (idem).
 135
 136 =head1 SEE ALSO
 137
 138 L<Bit::MorseSignals::Emitter>, L<Bit::MorseSignals::Receiver>.
 139
 140 =head1 AUTHOR
 141
 142 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 143
 144 You can contact me by mail or on C<irc.perl.org> (vincent).
 145
 146 =head1 BUGS
 147
 148 Please report any bugs or feature requests to C<bug-bit-morsesignals at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bit-MorseSignals>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 149
 150 =head1 SUPPORT
 151
 152 You can find documentation for this module with the perldoc command.
 153
 154     perldoc Bit::MorseSignals
 155
 156 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Bit-MorseSignals>.
 157
 158 =head1 COPYRIGHT & LICENSE
 159
 160 Copyright 2008 Vincent Pit, all rights reserved.
 161
 162 This program is free software; you can redistribute it and/or modify it
 163 under the same terms as Perl itself.
 164
 165 =cut
 166
 167 1; # End of Bit::MorseSignals