lib/POE/Component/Client/MPD/Time.pm

   1 #
   2 # This file is part of POE::Component::Client::MPD.
   3 # Copyright (c) 2007 Jerome Quelin, all rights reserved.
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the same terms as Perl itself.
   7 #
   8 #
   9
  10 package POE::Component::Client::MPD::Time;
  11
  12 use warnings;
  13 use strict;
  14
  15 use base qw[ Class::Accessor::Fast ];
  16 __PACKAGE__->mk_accessors
  17     ( qw[ percent sofar left total
  18           sofar_secs sofar_mins seconds_sofar
  19           total_secs total_mins seconds_total
  20           left_secs  left_mins  seconds_left
  21         ] );
  22
  23 #our ($VERSION) = '$Rev$' =~ /(\d+)/;
  24
  25
  26 #--
  27 # Constructor
  28
  29 #
  30 # my $status = POE::Component::Client::MPD::Time->new( $time )
  31 #
  32 # The constructor for the class POE::Component::Client::MPD::Time. $time is
  33 # the time value (on the "time" line) of what the output MPD server returns
  34 # to the status command.
  35 #
  36 sub new {
  37     my ($class, $time) = @_;
  38     $time ||= '0:0';
  39     my ($seconds_sofar, $seconds_total) = split /:/, $time;
  40     my $seconds_left = $seconds_total - $seconds_sofar;
  41     my $percent      = $seconds_total ? 100*$seconds_sofar/$seconds_total : 0;
  42
  43     # Parse the time so far
  44     my $sofar_mins = int( $seconds_sofar / 60 );
  45     my $sofar_secs = $seconds_sofar % 60;
  46     my $sofar = sprintf "%d:%02d", $sofar_mins, $sofar_secs;
  47
  48     # Parse the total time
  49     my $total_mins = int( $seconds_total / 60 );
  50     my $total_secs = $seconds_total % 60;
  51     my $total = sprintf "%d:%02d", $total_mins, $total_secs;
  52
  53     # Parse the time left
  54     my $left_mins = int( $seconds_left / 60 );
  55     my $left_secs = $seconds_left % 60;
  56     my $left = sprintf "%d:%02d", $left_mins, $left_secs;
  57
  58
  59     # create object
  60     my $self = {
  61         # time elapsed in seconds
  62         seconds_sofar => $seconds_sofar,
  63         seconds_left  => $seconds_left,
  64         seconds_total => $seconds_total,
  65
  66         # cooked values
  67         sofar      => $sofar,
  68         left       => $left,
  69         total      => $total,
  70         percent    => sprintf("%.1f", $percent), # 1 decimal
  71
  72         # details
  73         sofar_secs => $sofar_secs,
  74         sofar_mins => $sofar_mins,
  75         total_secs => $total_secs,
  76         total_mins => $total_mins,
  77         left_secs  => $left_secs,
  78         left_mins  => $left_mins,
  79     };
  80     bless $self, $class;
  81     return $self;
  82 }
  83
  84
  85 1;
  86
  87 __END__
  88
  89 =pod
  90
  91 =head1 NAME
  92
  93 POE::Component::Client::MPD::Time - class representing time of current song
  94
  95
  96 =head1 SYNOPSIS
  97
  98     my $time = $status->time;
  99     print $time->sofar;
 100
 101
 102 =head1 DESCRIPTION
 103
 104 C<POCOCM::Status> returns some time information with the C<time()>
 105 accessor. This information relates to the elapsed time of the current song,
 106 as well as the remaining and total time. This information is encapsulated
 107 in a C<POCOCM::Time> object.
 108
 109 Note that an C<POCOCM::Time> object does B<not> update itself regularly,
 110 and thus should be used immediately.
 111
 112
 113 =head1 METHODS
 114
 115 =head2 Constructor
 116
 117 =over 4
 118
 119 =item new( $time )
 120
 121 The C<new()> method is the constructor for the C<POCOCM::Time> class.
 122 It is called internally during the C<POCOCM::Status> object creation,
 123 with the C<time> line of the C<status> command sent to MPD server.
 124
 125 Note: one should B<never> ever instantiate an C<POCOCM::Time> object
 126 directly - use the C<time()> method of C<POCOCM::Status>.
 127
 128 =back
 129
 130
 131 =head2 Accessors
 132
 133 Once created, one can access to the following members of the object:
 134
 135 =over 4
 136
 137 =item cooked values:
 138
 139 The C<sofar()>, C<left()> and C<total()> methods return the according values
 140 under the form C<minutes:seconds>. Note the existence of a C<percent()>
 141 method returning a percentage complete. (one decimal)
 142
 143
 144 =item values in seconds:
 145
 146 The C<seconds_sofar()>, C<seconds_left()> and C<seconds_total()> return the
 147 according values in seconds.
 148
 149
 150 =item detailled values:
 151
 152 If you want to cook your own value, then the following methods can help.
 153 C<sofar_secs()> and C<sofar_mins()> return the seconds and minutes elapsed.
 154 Same for C<left_secs()> and C<left_mins()> (time remaining), C<total_secs()>
 155 and C<total_mins()>. (total song length)
 156
 157
 158 =back
 159
 160
 161 Please note that those accessors are read-only: changing a value will B<not>
 162 change the current state of MPD server. Use C<Audio::MPD> methods to alter
 163 the song playing.
 164
 165
 166 =head1 SEE ALSO
 167
 168 For all related information (bug reporting, mailing-list, pointers to
 169 MPD and POE, etc.), refer to C<POE::Component::Client::MPD>'s pod,
 170 section C<SEE ALSO>
 171
 172
 173 =head1 AUTHOR
 174
 175 Jerome Quelin, C<< <jquelin at cpan.org> >>
 176
 177
 178 =head1 COPYRIGHT & LICENSE
 179
 180 Copyright (c) 2007 Jerome Quelin, all rights reserved.
 181
 182 This program is free software; you can redistribute it and/or modify
 183 it under the same terms as Perl itself.
 184
 185 =cut