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( $path );
 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 C<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 C<Audio::MPD::Collection> is automatically created for you during the creation
 344 of an C<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> C<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> C<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 C<Audio::MPD::Common::Item::Song> objects will only have
 371 their tag file filled. Any other tag will be empty, so don't use this sub for
 372 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> C<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 C<Audio::MPD::Common::Item::Song> which correspond to C<$path>.
 433
 434
 435 =item $coll->songs_with_filename_partial( $path )
 436
 437 Return the C<Audio::MPD::Common::Item::Song>s containing $string in their path.
 438
 439
 440 =back
 441
 442
 443 =head2 Songs, albums & artists relations
 444
 445 =over 4
 446
 447 =item $coll->albums_by_artist( $artist )
 448
 449 Return all albums (strings) performed by C<$artist> or where C<$artist>
 450 participated.
 451
 452
 453 =item $coll->songs_by_artist( $artist )
 454
 455 Return all C<Audio::MPD::Common::Item::Song>s performed by C<$artist>.
 456
 457
 458 =item $coll->songs_by_artist_partial( $string )
 459
 460 Return all C<Audio::MPD::Common::Item::Song>s performed by an artist with
 461 C<$string> in her name.
 462
 463
 464 =item $coll->songs_from_album( $album )
 465
 466 Return all C<Audio::MPD::Common::Item::Song>s appearing in C<$album>.
 467
 468
 469 =item $coll->songs_from_album_partial( $string )
 470
 471 Return all C<Audio::MPD::Common::Item::Song>s appearing in album containing C<$string>.
 472
 473
 474 =item $coll->songs_with_title( $title )
 475
 476 Return all C<Audio::MPD::Common::Item::Song>s which title is exactly C<$title>.
 477
 478
 479 =item $coll->songs_with_title_partial( $string )
 480
 481 Return all C<Audio::MPD::Common::Item::Song>s where C<$string> is part of the title.
 482
 483
 484 =back
 485
 486
 487 =head1 SEE ALSO
 488
 489 For all related information (bug reporting, mailing-list, pointers to
 490 MPD, etc.), refer to C<Audio::MPD>'s pod, section C<SEE ALSO>
 491
 492
 493 =head1 AUTHOR
 494
 495 Jerome Quelin, C<< <jquelin@cpan.org> >>
 496
 497
 498 =head1 COPYRIGHT & LICENSE
 499
 500 Copyright (c) 2007-2009 Jerome Quelin, all rights reserved.
 501
 502 This program is free software; you can redistribute it and/or modify
 503 it under the same terms as Perl itself.
 504
 505 =cut