NAME

Net::Async::Matrix - use Matrix with IO::Async

SYNOPSIS

 TODO

DESCRIPTION

This module allows an program to interact with a Matrix homeserver as a connected user client.

EVENTS

The following events are invoked, either using subclass methods or CODE references in parameters:

on_log $message

A request to write a debugging log message. This is provided temporarily for development and debugging purposes, but will at some point be removed when the code has reached a certain level of stability.

on_presence $user, %changes

Invoked on receipt of a user presence change event from the homeserver. %changes will map user state field names to 2-element ARRAY references, each containing the old and new values of that field.

on_room_add $room

Invoked when a new room has completed its initial sync, either because of the client's initial sync, or because it was just created or joined. Note that if default on_room_* event handlers are defined, these may have already been invoked before on_room_add.

Passed an instance of Net::Async::Matrix::Room.

on_room_del $room

Invoked when the user has now left a room.

PARAMETERS

The following named parameters may be passed to new or configure. In addition, CODE references for event handlers using the event names listed above can also be given.

user_id => STRING

access_token => STRING

Optional login details to use for logging in as an existing user if an access token is already known. For registering a new user, see instead the register method.

server => STRING

Hostname and port number to contact the homeserver at. Given in the form

 $hostname:$port

This string will be interpolated directly into HTTP request URLs.

on_room_member, on_room_message => CODE

Optional. Sets default event handlers on new room objects.

METHODS

The following methods documented with a trailing call to ->get return Future instances.

$f = $matrix->start

Performs the initial IMSync on the server, and starts the event stream to begin receiving events.

While this method does return a Future it is not required that the caller keep track of this; the object itself will store it. It will complete when the initial IMSync has fininshed, and the event stream has started.

If the initial sync has already been requested, this method simply returns the future it returned the last time, ensuring that you can await the client starting up simply by calling it; it will not start a second time.

$matrix->stop

Stops the event stream. After calling this you will need to use start again to continue receiving events.

$user = $matrix->myself

Returns the user object representing the connected user.

( $user_id, $access_token ) = $matrix->register( $localpart )->get

Sends a user account registration request to the Matrix homeserver to create a new account. On successful completion, the returned user ID and token are stored by the object itself and the event stream is started.

$name = $matrix->get_displayname->get

$matrix->set_displayname( $name )->get

Accessor and mutator for the user account's "display name" profile field.

( $state, $msg ) = $matrix->get_presence->get

$matrix->set_presence( $state, $msg )->get

Accessor and mutator for the user's current presence state and optional status message string.

( $room, $room_alias ) = $matrix->create_room( $alias_localpart )->get

Requests the creation of a new room and associates a new alias with the given localpart on the server. The returned Future will return an instance of Net::Async::Matrix::Room and a string containing the full alias that was created.

$matrix->join_room( $room_alias_or_id )->get

Requests to join an existing room with the given alias name or plain room ID.

$syncdata = $matrix->initial_sync->get( %args )

Performs an IMSync operation, fetching the set of rooms the user is a member of, their current state, and an optional snapshot of the latest messages there.

Takes the following named arguments:

limit => INT

Optional number of messages per room to return. Defaults to zero; fetching only the list of rooms and their state, without any message snapshots.

USER STRUCTURES

Parameters documented as $user receive a user struct, which supports the following methods:

$user_id = $user->user_id

User ID of the user.

$displayname = $user->displayname

Profile displayname of the user.

$state = $user->state

Presence state. One of offline, unavailable or online.

$presence_mtime = $user->presence_mtime

Epoch time that the presence state last changed.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Net::Async::Matrix

perl -MCPAN -e shell
install Net::Async::Matrix