NAME

Mastodon::Listener - Access the streaming API of a Mastodon server

SYNOPSIS

  # From Mastodon::Client
  my $listener = $client->stream( 'public' );

  # Or use it directly
  my $listener = Mastodon::Listener->new(
    url => 'https://mastodon.cloud/api/v1/streaming/public',
    access_token => $token,
    coerce_entities => 1,
  )

  $listener->on( update => sub {
    my ($listener, $status) = @_;
    printf "%s said: %s\n",
      $status->account->display_name,
      $status->content;
  });

  $listener->start;

DESCRIPTION

A Mastodon::Listener object is created by calling the stream method from a Mastodon::Client, and it exists for the sole purpose of parsing a stream of events from a Mastodon server.

Mastodon::Listener objects inherit from AnyEvent::Emitter. Please refer to their documentation for details on how to register callbacks for the different events.

Once callbacks have been registered, the listener can be set in motion by calling its start method, which takes no arguments and never returns. The stop method can be called from within callbacks to disconnect from the stream.

ATTRIBUTES

access_token

The OAuth2 access token of your application, if authorization is needed. This is not needed for streaming from public timelines.

api_version

The API version to use. Defaults to 1.

coerce_entities

Whether JSON responses should be coerced into Mastodon::Entity objects. Currently defaults to false (but this will likely change in v0.01).

instance

The instance to use, as a Mastodon::Entity::Instance object. Will be coerced from a URL, and defaults to mastodon.social.

stream

The stream to use. Current valid streams are public, user, and tag timelines. To access a tag timeline, the argument to this value should begin with a hash character (#).

url

The full streaming URL to use. By default, it is constructed from the values in the instance, api_version, and stream attributes.

EVENTS

update

A new status has appeared. Callback will be called with the listener and the new status.

notification

A new notification has appeared. Callback will be called with the listener and the new notification.

delete

A status has been deleted. Callback will be called with the listener and the ID of the deleted status.

heartbeat

A new :thump has been received from the server. This is mostly for debugging purposes.

error

Inherited from AnyEvent::Emitter, will be emitted when an error was found. The callback will be called with the same arguments as the on_error callback for AnyEvent::Handle: the handle of the current connection, a fatal flag, and an error message.

AUTHOR

• José Joaquín Atria <jjatria@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.