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