lib/Audio/MPD/Collection.pm

   1 #
   2 # This file is part of Audio::MPD
   3 # Copyright (c) 2007-2009 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 Audio::MPD::Collection;
  11
  12 use strict;
  13 use warnings;
  14 use Scalar::Util qw[ weaken ];
  15
  16 use base qw[ Class::Accessor::Fast ];
  17 __PACKAGE__->mk_accessors( qw[ _mpd ] );
  18
  19
  20 #our ($VERSION) = '$Rev: 5284 $' =~ /(\d+)/;
  21
  22
  23 #--
  24 # Constructor
  25
  26 #
  27 # my $collection = Audio::MPD::Collection->new( $mpd );
  28 #
  29 # This will create the object, holding a back-reference to the Audio::MPD
  30 # object itself (for communication purposes). But in order to play safe and
  31 # to free the memory in time, this reference is weakened.
  32 #
  33 # Note that you're not supposed to call this constructor yourself, an
  34 # Audio::MPD::Collection is automatically created for you during the creation
  35 # of an Audio::MPD object.
  36 #
  37 sub new {
  38     my ($pkg, $mpd) = @_;
  39
  40     my $self = { _mpd => $mpd };
  41     weaken( $self->{_mpd} );
  42     bless $self, $pkg;
  43     return $self;
  44 }
  45
  46
  47 #--
  48 # Public methods
  49
  50 # -- Collection: retrieving songs & directories
  51
  52 #
  53 # my @items = $collection->all_items( [$path] );
  54 #
  55 # Return *all* AMC::Items (both songs & directories) currently known
  56 # by mpd.
  57 #
  58 # If $path is supplied (relative to mpd root), restrict the retrieval to
  59 # songs and dirs in this directory.
  60 #
  61 sub all_items {
  62     my ($self, $path) = @_;
  63     $path ||= '';
  64     $path =~ s/"/\\"/g;
  65
  66     return $self->_mpd->_cooked_command_as_items( qq[listallinfo "$path"\n] );
  67 }
  68
  69
  70 #
  71 # my @items = $collection->all_items_simple( [$path] );
  72 #
  73 # Return *all* AMC::Items (both songs & directories) currently known
  74 # by mpd.
  75 #
  76 # If $path is supplied (relative to mpd root), restrict the retrieval to
  77 # songs and dirs in this directory.
  78 #
  79 # /!\ Warning: the AMC::Item::Song objects will only have their tag
  80 # file filled. Any other tag will be empty, so don't use this sub for any
  81 # other thing than a quick scan!
  82 #
  83 sub all_items_simple {
  84     my ($self, $path) = @_;
  85     $path ||= '';
  86     $path =~ s/"/\\"/g;
  87
  88     return $self->_mpd->_cooked_command_as_items( qq[listall "$path"\n] );
  89 }
  90
  91
  92 #
  93 # my @items = $collection->items_in_dir( [$path] );
  94 #
  95 # Return the items in the given $path. If no $path supplied, do it on mpd's
  96 # root directory.
  97 #
  98 # Note that this sub does not work recusrively on all directories.
  99 #
 100 sub items_in_dir {
 101     my ($self, $path) = @_;
 102     $path ||= '';
 103     $path =~ s/"/\\"/g;
 104
 105     return $self->_mpd->_cooked_command_as_items( qq[lsinfo "$path"\n] );
 106 }
 107
 108
 109
 110 # -- Collection: retrieving the whole collection
 111
 112 #
 113 # my @songs = $collection->all_songs( [$path] );
 114 #
 115 # Return *all* AMC::Item::Songs currently known by mpd.
 116 #
 117 # If $path is supplied (relative to mpd root), restrict the retrieval to
 118 # songs and dirs in this directory.
 119 #
 120 sub all_songs {
 121     my ($self, $path) = @_;
 122     return grep { $_->isa('Audio::MPD::Common::Item::Song') } $self->all_items($path);
 123 }
 124
 125
 126 #
 127 # my @albums = $collection->all_albums;
 128 #
 129 # Return the list of all albums (strings) currently known by mpd.
 130 #
 131 sub all_albums {
 132     my ($self) = @_;
 133     return $self->_mpd->_cooked_command_strip_first_field( "list album\n" );
 134 }
 135
 136
 137 #
 138 # my @artists = $collection->all_artists;
 139 #
 140 # Return the list of all artists (strings) currently known by mpd.
 141 #
 142 sub all_artists {
 143     my ($self) = @_;
 144     return $self->_mpd->_cooked_command_strip_first_field( "list artist\n" );
 145 }
 146
 147
 148 #
 149 # my @titles = $collection->all_titles;
 150 #
 151 # Return the list of all titles (strings) currently known by mpd.
 152 #
 153 sub all_titles {
 154     my ($self) = @_;
 155     return $self->_mpd->_cooked_command_strip_first_field( "list title\n" );
 156 }
 157
 158
 159 #
 160 # my @pathes = $collection->all_pathes;
 161 #
 162 # Return the list of all pathes (strings) currently known by mpd.
 163 #
 164 sub all_pathes {
 165     my ($self) = @_;
 166     return $self->_mpd->_cooked_command_strip_first_field( "list filename\n" );
 167 }
 168
 169
 170 #
 171 # my @items = $collection->all_playlists;
 172 #
 173 # Return the list of playlists (strings) currently known by mpd.
 174 #
 175 sub all_playlists {
 176     my ($self) = @_;
 177
 178     return
 179         map { /^playlist: (.*)$/ ? ($1) : () }
 180         $self->_mpd->_send_command( "lsinfo\n" );
 181 }
 182
 183
 184
 185 # -- Collection: picking songs
 186
 187 #
 188 # my $song = $collection->song( $path );
 189 #
 190 # Return the AMC::Item::Song which correspond to $path.
 191 #
 192 sub song {
 193     my ($self, $what) = @_;
 194     $what =~ s/"/\\"/g;
 195
 196     my ($item) = $self->_mpd->_cooked_command_as_items( qq[find filename "$what"\n] );
 197     return $item;
 198 }
 199
 200
 201 #
 202 # my $song = $collection->songs_with_filename_partial( $string );
 203 #
 204 # Return the AMC::Item::Songs containing $string in their path.
 205 #
 206 sub songs_with_filename_partial {
 207     my ($self, $what) = @_;
 208     $what =~ s/"/\\"/g;
 209
 210     return $self->_mpd->_cooked_command_as_items( qq[search filename "$what"\n] );
 211 }
 212
 213
 214 # -- Collection: songs, albums & artists relations
 215
 216 #
 217 # my @albums = $collection->albums_by_artist($artist);
 218 #
 219 # Return all albums (strings) performed by $artist or where $artist
 220 # participated.
 221 #
 222 sub albums_by_artist {
 223     my ($self, $artist) = @_;
 224     $artist =~ s/"/\\"/g;
 225     return $self->_mpd->_cooked_command_strip_first_field( qq[list album "$artist"\n] );
 226 }
 227
 228
 229 #
 230 # my @songs = $collection->songs_by_artist( $artist );
 231 #
 232 # Return all AMC::Item::Songs performed by $artist.
 233 #
 234 sub songs_by_artist {
 235     my ($self, $what) = @_;
 236     $what =~ s/"/\\"/g;
 237
 238     return $self->_mpd->_cooked_command_as_items( qq[find artist "$what"\n] );
 239 }
 240
 241
 242 #
 243 # my @songs = $collection->songs_by_artist_partial( $string );
 244 #
 245 # Return all AMC::Item::Songs performed by an artist with $string
 246 # in her name.
 247 #
 248 sub songs_by_artist_partial {
 249     my ($self, $what) = @_;
 250     $what =~ s/"/\\"/g;
 251
 252     return $self->_mpd->_cooked_command_as_items( qq[search artist "$what"\n] );
 253 }
 254
 255
 256 #
 257 # my @songs = $collection->songs_from_album( $album );
 258 #
 259 # Return all AMC::Item::Songs appearing in $album.
 260 #
 261 sub songs_from_album {
 262     my ($self, $what) = @_;
 263     $what =~ s/"/\\"/g;
 264
 265     return $self->_mpd->_cooked_command_as_items( qq[find album "$what"\n] );
 266 }
 267
 268
 269 #
 270 # my @songs = $collection->songs_from_album_partial( $string );
 271 #
 272 # Return all AMC::Item::Songs appearing in album containing $string.
 273 #
 274 sub songs_from_album_partial {
 275     my ($self, $what) = @_;
 276     $what =~ s/"/\\"/g;
 277
 278     return $self->_mpd->_cooked_command_as_items( qq[search album "$what"\n] );
 279 }
 280
 281
 282 #
 283 # my @songs = $collection->songs_with_title( $title );
 284 #
 285 # Return all AMC::Item::Songs which title is exactly $title.
 286 #
 287 sub songs_with_title {
 288     my ($self, $what) = @_;
 289     $what =~ s/"/\\"/g;
 290
 291     return $self->_mpd->_cooked_command_as_items( qq[find title "$what"\n] );
 292 }
 293
 294
 295 #
 296 # my @songs = $collection->songs_with_title_partial( $string );
 297 #
 298 # Return all AMC::Item::Songs where $string is part of the title.
 299 #
 300 sub songs_with_title_partial {
 301     my ($self, $what) = @_;
 302     $what =~ s/"/\\"/g;
 303
 304     return $self->_mpd->_cooked_command_as_items( qq[search title "$what"\n] );
 305 }
 306
 307
 308 1;
 309
 310 __END__
 311
 312
 313 =head1 NAME
 314
 315 Audio::MPD::Collection - an object to query MPD's collection
 316
 317
 318 =head1 SYNOPSIS
 319
 320     my $song = $mpd->collection->random_song;
 321
 322
 323 =head1 DESCRIPTION
 324
 325 C<Audio::MPD::Collection> is a class meant to access & query MPD's
 326 collection. You will be able to use those high-level methods instead
 327 of using the low-level methods provided by mpd itself.
 328
 329
 330 =head1 PUBLIC METHODS
 331
 332 =head2 Constructor
 333
 334 =over 4
 335
 336 =item new( $mpd )
 337
 338 This will create the object, holding a back-reference to the L<Audio::MPD>
 339 object itself (for communication purposes). But in order to play safe and
 340 to free the memory in time, this reference is weakened.
 341
 342 Note that you're not supposed to call this constructor yourself, an
 343 L<Audio::MPD::Collection> is automatically created for you during the creation
 344 of an L<Audio::MPD> object.
 345
 346 =back
 347
 348
 349 =head2 Retrieving songs & directories
 350
 351 =over 4
 352
 353 =item $coll->all_items( [$path] )
 354
 355 Return B<all> L<Audio::MPD::Common::Item>s (both songs & directories)
 356 currently known by mpd.
 357
 358 If C<$path> is supplied (relative to mpd root), restrict the retrieval to
 359 songs and dirs in this directory.
 360
 361
 362 =item $coll->all_items_simple( [$path] )
 363
 364 Return B<all> L<Audio::MPD::Common::Item>s (both songs & directories)
 365 currently known by mpd.
 366
 367 If C<$path> is supplied (relative to mpd root), restrict the retrieval to
 368 songs and dirs in this directory.
 369
 370 B</!\ Warning>: the L<Audio::MPD::Common::Item::Song> objects will only
 371 have their tag C<file> filled. Any other tag will be empty, so don't use
 372 this sub for any other thing than a quick scan!
 373
 374
 375 =item $coll->items_in_dir( [$path] )
 376
 377 Return the items in the given C<$path>. If no C<$path> supplied, do it on
 378 mpd's root directory.
 379
 380 Note that this sub does not work recusrively on all directories.
 381
 382
 383 =back
 384
 385
 386 =head2 Retrieving the whole collection
 387
 388 =over 4
 389
 390 =item $coll->all_songs( [$path] )
 391
 392 Return B<all> L<Audio::MPD::Common::Item::Song>s currently known by mpd.
 393
 394 If C<$path> is supplied (relative to mpd root), restrict the retrieval to
 395 songs and dirs in this directory.
 396
 397
 398 =item $coll->all_albums()
 399
 400 Return the list of all albums (strings) currently known by mpd.
 401
 402
 403 =item $coll->all_artists()
 404
 405 Return the list of all artists (strings) currently known by mpd.
 406
 407
 408 =item $coll->all_titles()
 409
 410 Return the list of all song titles (strings) currently known by mpd.
 411
 412
 413 =item $coll->all_pathes()
 414
 415 Return the list of all pathes (strings) currently known by mpd.
 416
 417
 418 =item $coll->all_playlists()
 419
 420 Return the list of all playlists (strings) currently known by mpd.
 421
 422
 423 =back
 424
 425
 426 =head2 Picking a song
 427
 428 =over 4
 429
 430 =item $coll->song( $path )
 431
 432 Return the L<Audio::MPD::Common::Item::Song> which correspond to C<$path>.
 433
 434
 435 =item $coll->songs_with_filename_partial( $string )
 436
 437 Return the L<Audio::MPD::Common::Item::Song>s containing C<$string> in
 438 their path.
 439
 440
 441 =back
 442
 443
 444 =head2 Songs, albums & artists relations
 445
 446 =over 4
 447
 448 =item $coll->albums_by_artist( $artist )
 449
 450 Return all albums (strings) performed by C<$artist> or where C<$artist>
 451 participated.
 452
 453
 454 =item $coll->songs_by_artist( $artist )
 455
 456 Return all L<Audio::MPD::Common::Item::Song>s performed by C<$artist>.
 457
 458
 459 =item $coll->songs_by_artist_partial( $string )
 460
 461 Return all L<Audio::MPD::Common::Item::Song>s performed by an artist
 462 with C<$string> in her name.
 463
 464
 465 =item $coll->songs_from_album( $album )
 466
 467 Return all L<Audio::MPD::Common::Item::Song>s appearing in C<$album>.
 468
 469
 470 =item $coll->songs_from_album_partial( $string )
 471
 472 Return all L<Audio::MPD::Common::Item::Song>s appearing in album
 473 containing C<$string>.
 474
 475
 476 =item $coll->songs_with_title( $title )
 477
 478 Return all L<Audio::MPD::Common::Item::Song>s which title is exactly
 479 C<$title>.
 480
 481
 482 =item $coll->songs_with_title_partial( $string )
 483
 484 Return all L<Audio::MPD::Common::Item::Song>s where C<$string> is part
 485 of the title.
 486
 487
 488 =back
 489
 490
 491 =head1 SEE ALSO
 492
 493 For all related information (bug reporting, mailing-list, pointers to
 494 MPD, etc.), refer to L<Audio::MPD>'s pod, section C<SEE ALSO>
 495
 496
 497 =head1 AUTHOR
 498
 499 Jerome Quelin, C<< <jquelin@cpan.org> >>
 500
 501
 502 =head1 COPYRIGHT & LICENSE
 503
 504 Copyright (c) 2007-2009 Jerome Quelin, all rights reserved.
 505
 506 This program is free software; you can redistribute it and/or modify
 507 it under the same terms as Perl itself.
 508
 509 =cut