lib/Audio/MPD/Collection.pm

   1 #
   2 # This program is free software; you can redistribute it and/or modify
   3 # it under the terms of the GNU General Public License as published by
   4 # the Free Software Foundation; either version 2 of the License, or
   5 # (at your option) any later version.
   6 #
   7 # This program is distributed in the hope that it will be useful,
   8 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 # GNU General Public License for more details.
  11 #
  12 # You should have received a copy of the GNU General Public License
  13 # along with this program; if not, write to the Free Software
  14 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  15 #
  16 #
  17
  18 package Audio::MPD::Collection;
  19
  20 use strict;
  21 use warnings;
  22 use Audio::MPD::Item::Directory;
  23 use Audio::MPD::Item::Song;
  24 use Scalar::Util qw[ weaken ];
  25
  26 use base qw[ Class::Accessor::Fast ];
  27 __PACKAGE__->mk_accessors( qw[ _mpd ] );
  28
  29
  30 our ($VERSION) = '$Rev$' =~ /(\d+)/;
  31
  32 #--
  33 # Constructor
  34
  35 #
  36 # my $collection = Audio::MPD::Collection->new( $mpd );
  37 #
  38 # This will create the object, holding a back-reference to the Audio::MPD
  39 # object itself (for communication purposes). But in order to play safe and
  40 # to free the memory in time, this reference is weakened.
  41 #
  42 # Note that you're not supposed to call this constructor yourself, an
  43 # Audio::MPD::Collection is automatically created for you during the creation
  44 # of an Audio::MPD object.
  45 #
  46 sub new {
  47     my ($pkg, $mpd) = @_;
  48
  49     my $self = { _mpd => $mpd };
  50     weaken( $self->{_mpd} );
  51     return $self;
  52 }
  53
  54
  55 #--
  56 # Public methods
  57
  58 # -- Collection: retrieving songs & directories
  59
  60 #
  61 # my @items = $collection->all_items( [$path] );
  62 #
  63 # Return *all* Audio::MPD::Items (both songs & directories) currently known
  64 # by mpd.
  65 #
  66 # If $path is supplied (relative to mpd root), restrict the retrieval to
  67 # songs and dirs in this directory.
  68 #
  69 sub all_items {
  70     my ($self, $path) = @_;
  71     $path ||= '';
  72
  73     my @lines = $self->_send_command( qq[listallinfo "$path"\n] );
  74     my (@list, %param);
  75
  76     # parse lines in reverse order since "file:" comes first.
  77     # therefore, let's first store every other parameter, and
  78     # the "file:" line will trigger the object creation.
  79     # of course, since we want to preserve the playlist order,
  80     # this means that we're going to unshift the objects.
  81     foreach my $line (reverse @lines) {
  82         next unless $line =~ /^([^:]+):\s+(.+)$/;
  83         $param{$1} = $2;
  84         next unless $1 eq 'file' || $1 eq 'directory'; # last param of item
  85         unshift @list, Audio::MPD::Item->new(%param);
  86         %param = ();
  87     }
  88     return @list;
  89 }
  90
  91
  92 #
  93 # my @items = $collection->all_items_simple( [$path] );
  94 #
  95 # Return *all* Audio::MPD::Items (both songs & directories) currently known
  96 # by mpd.
  97 #
  98 # If $path is supplied (relative to mpd root), restrict the retrieval to
  99 # songs and dirs in this directory.
 100 #
 101 # /!\ Warning: the Audio::MPD::Item::Song objects will only have their tag
 102 # file filled. Any other tag will be empty, so don't use this sub for any
 103 # other thing than a quick scan!
 104 #
 105 sub all_items_simple {
 106     my ($self, $path) = @_;
 107     $path ||= '';
 108
 109     my @lines = $self->_send_command( qq[listall "$path"\n] );
 110     my (@list, %param);
 111
 112     # parse lines in reverse order since "file:" comes first.
 113     # therefore, let's first store every other parameter, and
 114     # the "file:" line will trigger the object creation.
 115     # of course, since we want to preserve the playlist order,
 116     # this means that we're going to unshift the objects.
 117     foreach my $line (reverse @lines) {
 118         next unless $line =~ /^([^:]+):\s+(.+)$/;
 119         $param{$1} = $2;
 120         next unless $1 eq 'file' || $1 eq 'directory'; # last param of item
 121         unshift @list, Audio::MPD::Item->new(%param);
 122         %param = ();
 123     }
 124     return @list;
 125 }
 126
 127
 128 #
 129 # my @items = $collection->items_in_dir( [$path] );
 130 #
 131 # Return the items in the given $path. If no $path supplied, do it on mpd's
 132 # root directory.
 133 #
 134 # Note that this sub does not work recusrively on all directories.
 135 #
 136 sub items_in_dir {
 137     my ($self, $path) = @_;
 138     $path ||= '';
 139
 140     my @lines = $self->_send_command( qq[lsinfo "$path"\n] );
 141     my (@list, %param);
 142
 143     # parse lines in reverse order since "file:" comes first.
 144     # therefore, let's first store every other parameter, and
 145     # the "file:" line will trigger the object creation.
 146     # of course, since we want to preserve the playlist order,
 147     # this means that we're going to unshift the objects.
 148     foreach my $line (reverse @lines) {
 149         next unless $line =~ /^([^:]+):\s+(.+)$/;
 150         $param{$1} = $2;
 151         next unless $1 eq 'file' || $1 eq 'directory'; # last param of item
 152         unshift @list, Audio::MPD::Item->new(%param);
 153         %param = ();
 154     }
 155     return @list;
 156 }
 157
 158
 159
 160 # -- Collection: retrieving the whole collection
 161
 162 #
 163 # my @albums = $collection->all_albums;
 164 #
 165 # Return the list of all albums (strings) currently known by mpd.
 166 #
 167 sub all_albums {
 168     my ($self) = @_;
 169     return
 170         map { /^Album: (.+)$/ ? $1 : () }
 171         $self->_mpd->_send_command( "list album\n" );
 172 }
 173
 174
 175 #
 176 # my @artists = $collection->all_artists;
 177 #
 178 # Return the list of all artists (strings) currently known by mpd.
 179 #
 180 sub all_artists {
 181     my ($self) = @_;
 182     return
 183         map { /^Artist: (.+)$/ ? $1 : () }
 184         $self->_mpd->_send_command( "list artist\n" );
 185 }
 186
 187
 188 #
 189 # my @titles = $collection->all_titles;
 190 #
 191 # Return the list of all titles (strings) currently known by mpd.
 192 #
 193 sub all_titles {
 194     my ($self) = @_;
 195     return
 196         map { /^Title: (.+)$/ ? $1 : () }
 197         $self->_mpd->_send_command( "list title\n" );
 198 }
 199
 200
 201 #
 202 # my @pathes = $collection->all_pathes;
 203 #
 204 # Return the list of all pathes (strings) currently known by mpd.
 205 #
 206 sub all_pathes {
 207     my ($self) = @_;
 208     return
 209         map { /^File: (.+)$/ ? $1 : () }
 210         $self->_mpd->_send_command( "list filename\n" );
 211 }
 212
 213
 214 # -- Collection: songs, albums & artists relations
 215
 216 #
 217 # my @albums = albums_from_artist($artist);
 218 #
 219 # Return all albums performed by $artist or where $artist participated.
 220 #
 221 sub albums_from_artist {
 222     my ($self, $artist) = @_;
 223     return
 224         map { /^Album: (.+)$/ ? $1 : () }
 225         $self->_mpd->_send_command( qq[list album "$artist"\n] );
 226 }
 227
 228
 229
 230 1;
 231
 232 __END__
 233
 234
 235 =head1 NAME
 236
 237 Audio::MPD::Collection - an object to query MPD's collection
 238
 239
 240 =head1 SYNOPSIS
 241
 242     my $song = $mpd->collection->random_song;
 243
 244
 245 =head1 DESCRIPTION
 246
 247 C<Audio::MPD::Collection> is a class meant to access & query MPD's
 248 collection. You will be able to use those high-level methods instead
 249 of using the low-level methods provided by mpd itself.
 250
 251
 252 =head1 PUBLIC METHODS
 253
 254 =head2 Constructor
 255
 256 =over 4
 257
 258 =item new( $mpd )
 259
 260 This will create the object, holding a back-reference to the C<Audio::MPD>
 261 object itself (for communication purposes). But in order to play safe and
 262 to free the memory in time, this reference is weakened.
 263
 264 Note that you're not supposed to call this constructor yourself, an
 265 C<Audio::MPD::Collection> is automatically created for you during the creation
 266 of an C<Audio::MPD> object.
 267
 268 =back
 269
 270
 271 =head2 Retrieving songs & directories
 272
 273 =over 4
 274
 275 =item all_items( [$path] )
 276
 277 Return B<all> C<Audio::MPD::Item>s (both songs & directories) currently known
 278 by mpd.
 279
 280 If C<$path> is supplied (relative to mpd root), restrict the retrieval to
 281 songs and dirs in this directory.
 282
 283
 284 =item all_items_simple( [$path] )
 285
 286 Return B<all> C<Audio::MPD::Item>s (both songs & directories) currently known
 287 by mpd.
 288
 289 If C<$path> is supplied (relative to mpd root), restrict the retrieval to
 290 songs and dirs in this directory.
 291
 292 B</!\ Warning>: the C<Audio::MPD::Item::Song> objects will only have their
 293 tag file filled. Any other tag will be empty, so don't use this sub for any
 294 other thing than a quick scan!
 295
 296
 297 =item items_in_dir( [$path] )
 298
 299 Return the items in the given C<$path>. If no C<$path> supplied, do it on
 300 mpd's root directory.
 301
 302 Note that this sub does not work recusrively on all directories.
 303
 304
 305 =back
 306
 307
 308 =head2 Retrieving the whole collection
 309
 310 =over 4
 311
 312 =item all_albums()
 313
 314 Return the list of all albums (strings) currently known by mpd.
 315
 316
 317 =item all_artists()
 318
 319 Return the list of all artists (strings) currently known by mpd.
 320
 321
 322 =item all_titles()
 323
 324 Return the list of all song titles (strings) currently known by mpd.
 325
 326
 327 =item all_pathes()
 328
 329 Return the list of all pathes (strings) currently known by mpd.
 330
 331
 332 =back
 333
 334
 335 =head2 Songs, albums & artists relations
 336
 337 =over 4
 338
 339 =item albums_from_artist( $artist )
 340
 341 Return all albums performed by $artist or where $artist participated.
 342
 343
 344 =back
 345
 346
 347 =head1 SEE ALSO
 348
 349 You can find more information on the mpd project on its homepage at
 350 L<http://www.musicpd.org>, or its wiki L<http://mpd.wikia.com>.
 351
 352 Regarding this Perl module, you can report bugs on CPAN via
 353 L<http://rt.cpan.org/Public/Bug/Report.html?Queue=Audio-MPD>.
 354
 355 Audio::MPD development takes place on <audio-mpd@googlegroups.com>: feel free
 356 to join us. (use L<http://groups.google.com/group/audio-mpd> to sign in). Our
 357 subversion repository is located at L<https://svn.musicpd.org>.
 358
 359
 360 =head1 AUTHORS
 361
 362 Jerome Quelin <jquelin@cpan.org>
 363
 364
 365 =head1 COPYRIGHT AND LICENSE
 366
 367 Copyright (c) 2007 Jerome Quelin <jquelin@cpan.org>
 368
 369
 370 This program is free software; you can redistribute it and/or modify
 371 it under the terms of the GNU General Public License as published by
 372 the Free Software Foundation; either version 2 of the License, or
 373 (at your option) any later version.
 374
 375 This program is distributed in the hope that it will be useful,
 376 but WITHOUT ANY WARRANTY; without even the implied warranty of
 377 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 378 GNU General Public License for more details.
 379
 380 =cut