/ 
Net-Async-MPD-0.005
River stage zero No dependents
/ README.md

NAME

Net::Async::MPD - A non-blocking interface to MPD

SYNOPSIS

use Net::Async::MPD;

my $mpd = Net::Async::MPD->new(
  host => 'localhost',
  auto_connect => 1,
);

my @subsystems = qw( player mixer database );

# Register a listener
foreach my $subsystem (@subsystems) {
  $mpd->on( $subsystem => sub {
    my ($self) = @_;
    print "$subsystem has changed\n";

    # Stop listening if mixer changes
    $mpd->noidle if $subsystem eq 'mixer';
  });
}

# Send a command
my $stats = $mpd->send( 'stats' );

# Or in blocking mode
my $status = $mpd->send( 'status' )->get;

# Which is the same as
$status = $mpd->get( 'status' );

print 'Server is in ', $status->{state}, " state\n";
print 'Server has ', $stats->get->{albums}, " albums in the database\n";

# Put the client in looping idle mode
my $idle = $mpd->idle( @subsystems );

# Set the emitter in motion, until the next call to noidle
$idle->get;

DESCRIPTION

Net::Async::MPD provides a non-blocking interface to an MPD server.

Command Lists

MPD supports sending command lists to make it easier to perform a series of steps as a single one. No command is executed until all commands in the list have been sent, and then the server returns the result for all of them together. See the MPD documentation for more information.

Net::Async::MPD fully supports sending command lists, and makes it easy to structure the results received from MPD, or not to if the user so desires. See the "send" method for more information.

Error Handling

Most operations in this module return Future objects, and to keep things consistent, any errors that are encountered during processing will result in those futures being failed or canceled as appropriate.

This module also makes use of the events in Role::EventEmitter, which provides it's own method for error handling: the error event. Normally, if a class does that role, it is expected that users will register some listener to the error event to handle failures. However, since errors are alredy being handled by the Futures (one woudl hope), this distribution registers a dummy listener to the error event, and turns into one that is mostly useful for debugging and monitoring.

Of course, the author cannot really stop overly zealous users from unsubscribing the error dummy listener, but they do so at their own risk.

Server Responses

MPD normally returns results as a flat list of response lines. Net::Async::MPD tries to make it easier to provide some structure to these responses by providing pre-set parser subroutines for each command. Although the default parser will be fine in most cases, it is possible to override this with a custom parser, or to disable the parsing entirely to get the raw lines from the server. For information on how to override the parser, see the documentation for the "send" method.

By default, the results of each command are parsed independently, and passed to the Future returned by the corresponding call to "send". This is true regardless of whether those commands were sent as part of a list or not.

This means that, by default, the Future that represents a given call to "send" will receive the results of as many commands as were originall sent.

This might not be desireable when eg. sending multiple commands whose results should be aggregated. In those cases, it is possible to flatten the list by passing a false value to the list option to "send" or "get".

This means that when calling

($stats, $status) = $mpd->get(
  { list => 1 }, # This is the default
  [ 'stats', 'status' ]
);

$stats and $status will each have a hash reference with the results of their respective commands; while when calling

$combined_list = $mpd->get( { list => 0 }, [
  [ search => artist => '"Tom Waits"'   ],
  [ search => artist => '"David Bowie"' ],
]);

$combined_list will hold an array reference with the combined results of both search commands.

ATTRIBUTES

METHODS

EVENTS

Net::Async::MPD does the Role::EventEmitter role, and inherits all the methods defined therein. Please refer to that module's documentation for information on how to register subscribers to the different events.

Additional methods

Event descriptions

After calling idle, the client will be in idle mode, which means that any changes to the specified subsystems will trigger a signal. When the client receives this signal, it will fire an event named like the subsystem that fired it.

The event will be fired with the client as the first argument, and the response from the server as the second argument. This can safely be ignored, since the server response will normally just hold the name of the subsystem that changed, which you already know.

The existing events are the following, as defined by the MPD documentation.

Other events

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

This software is copyright (c) 2017-2018 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.