README

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