DESIGN

   1 Poe::Component::Client::MPD is a poe component to interact with mpd (Music
   2 Player Daemon) servers.
   3
   4 it can be created with the following:
   5     POE::Component::Client::MPD->spawn;
   6
   7
   8 upon creation, it will spawn two things:
   9  - a private session $_HUB that will act as an internal dispatcher
  10  - a session $COMMANDS to send general commands
  11  - a session $PLAYLIST to handle playlist events
  12  - a session $COLLECTION to search through it
  13  - a private poe::component::client::tcp that will handle the communication
  14    with the mpd server
  15
  16 you aren't allowed, under any circumstance, to try to communicate with the
  17 private components.
  18
  19
  20 here are some examples of how it works internally:
  21
  22 moving an item in the playlist
  23 - you send a 'move' event to $PLAYLIST
  24 - caught by $_HUB::_onpub_default
  25 - create a pococm-message and yields a '_dispatch' event with the message
  26 - caught by $COLLECTION::_onpriv_dispatch
  27 - yelding a _onpub_move event with the message
  28 - caught by $COLLECTION::_onpub_move
  29 - completes the message and posts a _send event to $_HUB
  30 - caught by $_HUB::_onpriv_send
  31 - which sends the pococm-message to the tcp session
  32 - sending things over the wires
  33 - when answer comes, it sends back a _mpd_data event
  34 - caught by $_HUB::_onprot_mpd_data
  35 - transforming it to stats or whatever if needed
  36 - calling a post-event if needed, going back to _dispatch with the completed event
  37 - otherwise, returns data (or nothing if no answer awaited)
  38
  39
  40
  41 regarding naming scheme:
  42  - since there's no public subs / methods to be called, all subs will begin
  43    with an underscore ('_'). this will have the added benefit that tests for
  44    pod coverage will be happy. ;)
  45  - events that are internal to pococ-mpd (ie, sent from within the same poco)
  46    are referred to as private.
  47         event:   _<event_name>
  48         hanlder: _onpriv_<event_name>()
  49  - events that travel between pococ-mpd and pococ-tcp are refered to as
  50    protected.
  51         event:   _<event_name>
  52         hanlder: _onprot_<event_name>()
  53  - events that form the api of pococ-mpd are so-called public events.
  54         even:    <event_name>
  55         handler: _onpub_<event_name>()
  56