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>