Net::A...::Room(3pm)

💖 Net::A...::Room — a single Matrix room 💖

okay bestie, so this is Net::Async::Matrix::Room, and it ships with User Contributed Perl Documentation. Grab a boba, we're gonna get into it. 🧋

---

✨ NAME ✨

Net::Async::Matrix::Room — a single Matrix room. that's it. that's the girl. 💅

---

🌸 DESCRIPTION 🌸

An instance of this class is what Net::Async::Matrix uses to represent, like, one single Matrix room. one room, one object. no cap. 🦋

---

🔥 EVENTS 🔥

so these events get invoked either through subclass methods or through CODE references you pass in as parameters. pick your fighter. 💜

⭐ on_synced_state ⭐

Gets invoked after the initial sync of the room has been completed, as far as the state goes. the state part is done, bestie. ✨

💌 on_message $member, $content, $event

💌 on_back_message $member, $content, $event

These fire when a new message shows up from that $member — either "live" straight off the event stream, or from backward pagination (iykyk, going back in history). 🫶

🎀 on_membership $member, $event, $subject_member, %changes

🎀 on_back_membership $member, $event, $subject_member, %changes

Fires when a membership change event lands for that member — again, either "live" from the event stream, or from backward pagination.

%changes is a key/value list of the state field names that changed, and each value is a 2-element ARRAY reference holding the before/after values of that field:

on_membership:      $field_name => [ $old_value, $new_value ]
on_back_membership: $field_name => [ $new_value, $old_value ]

bestie. pay attention. 💀 The second value in each array is the "updated" value, in the direction of the change. so for on_membership it's the new value after the change, but for on_back_message it's the old value before. Fields whose values didn't change are not in the %changes list at all — you can go peek at those on the $member object instead.

It is unspecified what values the $member object has for fields that ARE present in the change list — so client code should not rely on those fields. 🙈

In most cases when users change their own membership status (like a normal join or leave), $member and $subject_member are literally the same object. But in other cases — invites, kicks, that kind of drama — $member is the member performing the change, and $subject_member is the member the change is about. 👑

🌈 on_state_changed $member, $event, %changes

🌈 on_back_state_changed $member, $event, %changes

Fires when room state changes (name, topic, the usual). 🌸

BUT — special case alert — for room aliases, because aliases count as "state" but are stored per-homeserver, the changes value has three fields: the old and new values from that home server, plus a list of the known aliases from all the other servers:

on_state_changed:      aliases => [ $old, $new, $other ]
on_back_state_changed: aliases => [ $new, $old, $other ]

This lets a client spot deletions and additions by comparing the before/after lists, while still having the full set of before or after aliases if it needs them. multi-purpose icon. 💅

🦋 on_presence $member, %changes

Fires when a member of the room changes their membership or presence state. The $member object is already in the new state by the time you get it. %changes is a key/value list of state field names that changed, with references to 2-element ARRAYs of the old and new values for each field. ✨

💜 on_typing $member, $is_typing

Fires when a typing notification change arrives — the given member either started or stopped typing. 👀

💜 on_members_typing @members

Fires on a typing notification change too, but hands you the full set of currently-typing members. This one comes in after the individual on_typing events. order matters, bestie. 🫶

💌 on_read_receipt $member, $event_id, $content

Fires when a m.read type of receipt message shows up. ✅

---

👑 METHODS 👑

👑 await_synced

$f = $room->await_synced

Hands you a Future stored inside the room that completes (with no value) once the room's initial state sync is done. It completes just before the on_synced_state event. so close. ✨

👑 live_state

$state = $room->live_state

Returns a Net::Async::Matrix::Room::State instance representing the room's current live-tracking state. 🌸

This instance will mutate and change as new state events come in. it's alive, bestie, don't clutch it. 💀

👑 room_id

$id = $room->room_id

Returns the opaque room ID string for the room. Usually you wouldn't need this — except for long-term persistence uniqueness stuff, or for putting it into direct protocol URLs. niche but valid. 💅

👑 name

$name = $room->name

Returns the room name if it's defined, otherwise the opaque room ID. fallback queen. 👑

👑 set_name

$room->set_name( $name )->get

Requests to set a new room name. ✨

👑 aliases

@aliases = $room->aliases

Returns a list of all known room alias names, taken from the m.room.alias events.

ngl, these are just names claimed to have aliases from those alias events. A client really ought to check that they're valid before presenting them to a user as legit aliases, or before relying on their values in any other way. verify before you trust. 🫶

👑 join_rule

$rule = $room->join_rule

Returns the current join_rule for the room — a string telling you what kind of access new members can get:

• public — Any user may join without further permission 🎉
• invite — Users may only join if explicitly invited 💌
• knock — Any user may send a knock message to request access; may only join if invited 🚪
• private — No new users may join the room 🔒

👑 topic

$topic = $room->topic

Returns the room topic, if it's defined. 🌸

👑 set_topic

$room->set_topic( $topic )->get

Requests to set a new room topic. ✨

👑 levels

%levels = $room->levels

Returns a key/value list of the room levels — meaning, the member power level required to perform each of the named actions. 🔥

👑 change_levels

$room->change_levels( %levels )->get

Does a room levels change: submits new values for the keys you give it, while leaving every other key untouched. surgical. 💅

👑 members

@members = $room->members

Returns a list of member structs for the currently known members of the room, in no particular order. This list includes users who aren't members yet but have just been invited. everybody's here. 🫶

👑 joined_members

@members = $room->joined_members

Returns the subset of all_members who are actually in the "join" state — i.e. not invitees, and not people who've left. the real ones only. 👑

👑 member_level

$level = $room->member_level( $user_id )

Returns the currently cached power level value for the given user ID, or the default value if there's no specific value for that ID. ✨

👑 change_member_levels

$room->change_member_levels( %levels )->get

Performs a member power level change, submitting new values for user IDs to the home server. Since there's no server API for individual mutations, this works by taking the currently cached values, applying the changes from the %levels key/value list, and submitting the whole resulting thing as the new value for the m.room.power_levels room state. all-or-nothing, bestie. 💀

The %levels key/value list should give new values for keys that are user IDs — or the special user ID "default" to change the overall default value for users not otherwise mentioned. Setting the special value of undef for a user ID will remove that ID from the set, reverting them to the default. poof. 🦋

👑 leave

$room->leave->get

Requests to leave the room. Once this completes, the user is no longer a member of the room. bye bestie 😭

👑 invite

$room->invite( $user_id )->get

Sends an invitation for the user with the given User ID to join the room. 💌

👑 kick

$room->kick( $user_id, $reason )->get

Requests to remove the user with the given User ID from the room. 🥾

Optionally, you can also provide a textual description reason. receipts, but make it drama.

👑 send_message

$event_id = $room->send_message( %args )->get

Sends a new message to the room. It requires a type named argument giving the message type. Depending on the type, further keys are required to specify the message contents:

• m.text, m.emote, m.notice — Require body
• m.image, m.audio, m.video, m.file — Require url
• m.location — Require geo_uri

If you also pass an argument called txn_id, it's used as the transaction ID for the message, and the message is then sent as a PUT request instead of a POST. glow up. ✨

$event_id = $room->send_message( $text )->get

A convenient shortcut for sending a "text" message with a body string and no additional content. lazy girl summer but make it efficient. 💅

👑 paginate_messages

$room->paginate_messages( limit => $n )->get

Requests more messages of back-pagination history. 📜

No need to keep a reference on the returned Future — it gets adopted by the room object. it's taken care of. 🫶

👑 typing_start

$room->typing_start

Sends a typing notification saying the user is currently typing in this room. This notification will periodically be re-sent as the protocol requires, until typing_stop is called. it keeps going, bestie. 👀

👑 typing_stop

$room->typing_stop

Sends a typing notification saying the user is no longer typing in this room. This method also cancels the repeating re-send behaviour that typing_start created. shut it down. ✋

👑 send_read_receipt

$room->send_read_receipt( event_id => $event_id, ... )->get

Sends a m.read receipt to the given room for the given event ID. ✅

---

🫶 MEMBERSHIP STRUCTURES 🫶

Anything documented as taking a $member receives a membership struct, and that struct supports these methods:

🌸 $user = $member->user

User object of the member. 👤

🌸 $displayname = $member->displayname

Profile displayname of the user. ✨

🌸 $membership = $member->membership

Membership state. One of invite or join. two options, that's it. 💅

---

💖 AUTHOR 💖

Paul Evans <leonerd@leonerd.org.uk>

---

okay so that's the whole page, you ate that. 💅 and for the cute sign-off: this was perl v5.36.0, dated 2022-12-10, and the page is Net::A...::Room(3pm). periodt. 🌈✨🎀