Class: MatrixSdk::Room
Overview
A class for tracking the information about a room on Matrix
Instance Attribute Summary collapse
-
#aliases ⇒ Array(String)
readonly
A list of user-set aliases for the room.
-
#canonical_alias ⇒ String?
The canonical alias of the room.
-
#client ⇒ Client
readonly
The client for the room.
-
#event_history_limit ⇒ Fixnum
The limit of events to keep in the event log.
-
#events ⇒ Object
readonly
Returns the value of attribute events.
-
#guest_access ⇒ :can_join, :forbidden
The guest access for the room - either
:can_join
or:forbidden
. -
#id ⇒ String
(also: #room_id)
readonly
The internal ID of the room.
-
#join_rule ⇒ :invite, :public
The join rule for the room - either
:invite
or:public
. -
#members ⇒ Array(User)
readonly
The members of the room.
-
#name ⇒ String?
The user-provided name of the room.
-
#on_ephemeral_event ⇒ EventHandlerArray
readonly
The list of event handlers for only ephemeral events.
-
#on_event ⇒ EventHandlerArray
readonly
The list of event handlers for all events.
-
#on_state_event ⇒ EventHandlerArray
readonly
The list of event handlers for only state events.
-
#topic ⇒ String?
The user-provided topic of the room.
Instance Method Summary collapse
-
#add_alias(room_alias) ⇒ Boolean
Add an alias to the room.
-
#add_tag(tag, **data) ⇒ Object
Add a tag to the room.
- #allow_guests=(allow_guests) ⇒ Object
-
#avatar_url ⇒ Object
Gets the avatar url of the room - if any.
- #avatar_url=(avatar_url) ⇒ Object
-
#backfill_messages(reverse = false, limit = 10) ⇒ Object
Backfills messages into the room history.
-
#ban_user(user_id, reason = '') ⇒ Boolean
Bans a user from the room.
-
#display_name ⇒ String
Gets a human-readable name for the room.
-
#get_account_data(type) ⇒ Hash
Retrieves a custom entry from the room-specific account data.
-
#guest_access? ⇒ Boolean
Checks if
guest_access
is set to:can_join
. -
#initialize(client, room_id, data = {}) ⇒ Room
constructor
A new instance of Room.
-
#inspect ⇒ String
An inspect method that skips a handful of instance variables to avoid flooding the terminal with debug data.
- #invite_only=(invite_only) ⇒ Object
-
#invite_only? ⇒ Boolean
Checks if
join_rule
is set to:invite
. -
#invite_user(user_id) ⇒ Boolean
Invites a user into the room.
-
#joined_members ⇒ Object
Populates and returns the #members array.
-
#kick_user(user_id, reason = '') ⇒ Boolean
Kicks a user from the room.
-
#leave ⇒ Boolean
Requests to be removed from the room.
-
#modify_required_power_levels(events = nil, params = {}) ⇒ Boolean
Modifies the required power levels for actions in the room.
-
#modify_user_power_levels(users = nil, users_default = nil) ⇒ Boolean
Modifies the power levels of the room.
-
#redact_message(event_id, reason = nil) ⇒ Object
Redacts a message from the room.
-
#reload! ⇒ Object
(also: #refresh!)
State updates.
-
#reload_aliases! ⇒ Boolean
(also: #refresh_aliases!)
Reloads the list of aliases by an API query.
-
#reload_name! ⇒ Boolean
(also: #refresh_name!)
Reloads the name of the room.
-
#reload_topic! ⇒ Boolean
(also: #refresh_topic!)
Reloads the topic of the room.
-
#remove_tag(tag) ⇒ Object
Remove a tag from the room.
-
#send_audio(url, name, audio_info = {}) ⇒ Object
Sends a link to an audio clip to the room.
-
#send_emote(text) ⇒ Object
Sends an emote (/me) message to the room.
-
#send_file(url, name, file_info = {}) ⇒ Object
Sends a link to a generic file to the room.
-
#send_html(html, body = nil, msg_type = 'm.text') ⇒ Object
Sends a custom HTML message to the room.
-
#send_image(url, name, image_info = {}) ⇒ Object
Sends a link to an image to the room.
-
#send_location(geo_uri, name, thumbnail_url = nil, thumbnail_info = {}) ⇒ Object
Sends a location object to the room.
-
#send_notice(text) ⇒ Object
Sends a notice (bot) message to the room.
-
#send_text(text) ⇒ Object
Sends a plain-text message to the room.
-
#send_video(url, name, video_info = {}) ⇒ Object
Sends a link to a video to the room.
-
#set_account_data(type, account_data) ⇒ Object
Stores a custom entry into the room-specific account data.
-
#set_user_profile(display_name: nil, avatar_url: nil, reason: nil) ⇒ Object
Changes the room-specific user profile.
-
#tags ⇒ Response
Returns a list of the room tags.
-
#unban_user(user_id) ⇒ Boolean
Unbans a user from the room.
Methods included from Extensions
Methods included from Logging
Constructor Details
#initialize(client, room_id, data = {}) ⇒ Room
Returns a new instance of Room.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
# File 'lib/matrix_sdk/room.rb', line 61 def initialize(client, room_id, data = {}) event_initialize @client = client @id = room_id.to_s @name = nil @topic = nil @canonical_alias = nil @aliases = [] @join_rule = nil @guest_access = nil @world_readable = nil @members = [] @events = [] @members_loaded = false @event_history_limit = 10 @avatar_url = nil @prev_batch = nil data.each do |k, v| instance_variable_set("@#{k}", v) if instance_variable_defined? "@#{k}" end @name_checked = Time.new(0) logger.debug "Created room #{room_id}" end |
Instance Attribute Details
#aliases ⇒ Array(String) (readonly)
Returns a list of user-set aliases for the room.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#canonical_alias ⇒ String?
Returns the canonical alias of the room.
15 16 17 |
# File 'lib/matrix_sdk/room.rb', line 15 def canonical_alias @canonical_alias end |
#client ⇒ Client (readonly)
Returns the client for the room.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#event_history_limit ⇒ Fixnum
Returns the limit of events to keep in the event log.
15 |
# File 'lib/matrix_sdk/room.rb', line 15 attr_accessor :canonical_alias, :event_history_limit |
#events ⇒ Object (readonly)
Returns the value of attribute events.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#guest_access ⇒ :can_join, :forbidden
Returns the guest access for the room - either :can_join
or :forbidden
.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#id ⇒ String (readonly) Also known as: room_id
Returns the internal ID of the room.
43 44 45 |
# File 'lib/matrix_sdk/room.rb', line 43 def id @id end |
#join_rule ⇒ :invite, :public
Returns the join rule for the room - either :invite
or :public
.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#members ⇒ Array(User) (readonly)
Returns the members of the room.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#name ⇒ String?
Returns the user-provided name of the room.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
#on_ephemeral_event ⇒ EventHandlerArray (readonly)
Returns The list of event handlers for only ephemeral events.
51 |
# File 'lib/matrix_sdk/room.rb', line 51 events :event, :state_event, :ephemeral_event |
#on_event ⇒ EventHandlerArray (readonly)
Returns The list of event handlers for all events.
51 |
# File 'lib/matrix_sdk/room.rb', line 51 events :event, :state_event, :ephemeral_event |
#on_state_event ⇒ EventHandlerArray (readonly)
Returns The list of event handlers for only state events.
51 |
# File 'lib/matrix_sdk/room.rb', line 51 events :event, :state_event, :ephemeral_event |
#topic ⇒ String?
Returns the user-provided topic of the room.
43 |
# File 'lib/matrix_sdk/room.rb', line 43 attr_reader :id, :client, :topic, :aliases, :members, :events |
Instance Method Details
#add_alias(room_alias) ⇒ Boolean
Add an alias to the room
472 473 474 475 476 |
# File 'lib/matrix_sdk/room.rb', line 472 def add_alias(room_alias) client.api.set_room_alias(id, room_alias) @aliases << room_alias true end |
#add_tag(tag, **data) ⇒ Object
Add a tag to the room
415 416 417 418 |
# File 'lib/matrix_sdk/room.rb', line 415 def add_tag(tag, **data) client.api.add_user_tag(client.mxid, id, tag, data) true end |
#allow_guests=(allow_guests) ⇒ Object
511 512 513 514 |
# File 'lib/matrix_sdk/room.rb', line 511 def allow_guests=(allow_guests) self.guest_access = (allow_guests ? :can_join : :forbidden) @guest_access == :can_join end |
#avatar_url ⇒ Object
Gets the avatar url of the room - if any
142 143 144 145 146 147 |
# File 'lib/matrix_sdk/room.rb', line 142 def avatar_url @avatar_url ||= client.api.get_room_avatar(id).url rescue MatrixNotFoundError # No avatar has been set nil end |
#avatar_url=(avatar_url) ⇒ Object
521 522 523 524 525 526 527 |
# File 'lib/matrix_sdk/room.rb', line 521 def avatar_url=(avatar_url) avatar_url = URI(avatar_url) unless avatar_url.is_a? URI raise ArgumentError, 'Must be a valid MXC URL' unless avatar_url.is_a? URI::MATRIX client.api.set_room_avatar(id, avatar_url) @avatar_url = avatar_url end |
#backfill_messages(reverse = false, limit = 10) ⇒ Object
This will trigger the ‘on_event` events as messages are added
Backfills messages into the room history
285 286 287 288 289 290 291 292 293 294 |
# File 'lib/matrix_sdk/room.rb', line 285 def (reverse = false, limit = 10) data = client.api.(id, @prev_batch, direction: :b, limit: limit) events = data[:chunk] events.reverse! unless reverse events.each do |ev| put_event(ev) end true end |
#ban_user(user_id, reason = '') ⇒ Boolean
Bans a user from the room
323 324 325 326 327 |
# File 'lib/matrix_sdk/room.rb', line 323 def ban_user(user_id, reason = '') user_id = user_id.id if user_id.is_a? MatrixSdk::User client.api.ban_user(id, user_id, reason: reason) true end |
#display_name ⇒ String
This method will populate the #members list if it has to fall back to the member name generation.
Gets a human-readable name for the room
This will return #name or #canonical_alias if they’ve been set, otherwise it will query the API for members and generate a string from a subset of their names.
103 104 105 106 107 108 109 110 111 112 113 114 115 116 |
# File 'lib/matrix_sdk/room.rb', line 103 def display_name return name if name return canonical_alias if canonical_alias members = joined_members .reject { |m| m.user_id == client.mxid } .map(&:display_name) return members.first if members.one? return "#{members.first} and #{members.last}" if members.count == 2 return "#{members.first} and #{members.count - 1} others" if members.count > 2 'Empty Room' end |
#get_account_data(type) ⇒ Hash
Retrieves a custom entry from the room-specific account data
349 350 351 |
# File 'lib/matrix_sdk/room.rb', line 349 def get_account_data(type) client.api.get_room_account_data(client.mxid, id, type) end |
#guest_access? ⇒ Boolean
Checks if guest_access
is set to :can_join
158 159 160 |
# File 'lib/matrix_sdk/room.rb', line 158 def guest_access? guest_access == :can_join end |
#inspect ⇒ String
An inspect method that skips a handful of instance variables to avoid flooding the terminal with debug data.
56 57 |
# File 'lib/matrix_sdk/room.rb', line 56 ignore_inspect :client, :members, :events, :prev_batch, :logger, :on_event, :on_state_event, :on_ephemeral_event |
#invite_only=(invite_only) ⇒ Object
501 502 503 504 |
# File 'lib/matrix_sdk/room.rb', line 501 def invite_only=(invite_only) self.join_rule = invite_only ? :invite : :public @join_rule == :invite end |
#invite_only? ⇒ Boolean
Checks if join_rule
is set to :invite
163 164 165 |
# File 'lib/matrix_sdk/room.rb', line 163 def invite_only? join_rule == :invite end |
#invite_user(user_id) ⇒ Boolean
Invites a user into the room
303 304 305 306 307 |
# File 'lib/matrix_sdk/room.rb', line 303 def invite_user(user_id) user_id = user_id.id if user_id.is_a? MatrixSdk::User client.api.invite_user(id, user_id) true end |
#joined_members ⇒ Object
Populates and returns the #members array
119 120 121 122 123 124 125 126 127 128 129 |
# File 'lib/matrix_sdk/room.rb', line 119 def joined_members return members if @members_loaded && !members.empty? client.api.get_room_members(id)[:chunk].each do |chunk| next unless chunk [:content][:membership] == 'join' ensure_member(User.new(client, chunk[:state_key], display_name: chunk[:content].fetch(:displayname, nil))) end @members_loaded = true members end |
#kick_user(user_id, reason = '') ⇒ Boolean
Kicks a user from the room
313 314 315 316 317 |
# File 'lib/matrix_sdk/room.rb', line 313 def kick_user(user_id, reason = '') user_id = user_id.id if user_id.is_a? MatrixSdk::User client.api.kick_user(id, user_id, reason: reason) true end |
#leave ⇒ Boolean
Requests to be removed from the room
340 341 342 343 344 |
# File 'lib/matrix_sdk/room.rb', line 340 def leave client.api.leave_room(id) client.instance_variable_get(:@rooms).delete id true end |
#modify_required_power_levels(events = nil, params = {}) ⇒ Boolean
Modifies the required power levels for actions in the room
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 |
# File 'lib/matrix_sdk/room.rb', line 553 def modify_required_power_levels(events = nil, params = {}) return false if events.nil? && (params.nil? || params.empty?) data = client.api.get_power_levels(id) data.merge!(params) data.delete_if { |_k, v| v.nil? } if events data[:events] = {} unless data.key? :events data[:events].merge!(events) data[:events].delete_if { |_k, v| v.nil? } end client.api.set_power_levels(id, data) true end |
#modify_user_power_levels(users = nil, users_default = nil) ⇒ Boolean
Modifies the power levels of the room
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 |
# File 'lib/matrix_sdk/room.rb', line 533 def modify_user_power_levels(users = nil, users_default = nil) return false if users.nil? && users_default.nil? data = client.api.get_power_levels(id) data[:users_default] = users_default unless users_default.nil? if users data[:users] = {} unless data.key? :users data[:users].merge!(users) data[:users].delete_if { |_k, v| v.nil? } end client.api.set_power_levels(id, data) true end |
#redact_message(event_id, reason = nil) ⇒ Object
Redacts a message from the room
276 277 278 279 |
# File 'lib/matrix_sdk/room.rb', line 276 def (event_id, reason = nil) client.api.redact_event(id, event_id, reason: reason) true end |
#reload! ⇒ Object Also known as: refresh!
State updates
424 425 426 427 428 429 |
# File 'lib/matrix_sdk/room.rb', line 424 def reload! reload_name! reload_topic! reload_aliases! true end |
#reload_aliases! ⇒ Boolean Also known as: refresh_aliases!
The list of aliases is not sorted, ordering changes will result in alias list updates.
Reloads the list of aliases by an API query
482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 |
# File 'lib/matrix_sdk/room.rb', line 482 def reload_aliases! begin new_aliases = client.api.get_room_aliases(id).aliases rescue MatrixNotFoundError data = client.api.get_room_state(id) new_aliases = data.select { |chunk| chunk[:type] == 'm.room.aliases' && chunk.key?(:content) && chunk[:content].key?(:aliases) } .map { |chunk| chunk[:content][:aliases] } .flatten .compact end return false if new_aliases.nil? changed = new_aliases != aliases @aliases = new_aliases if changed changed end |
#reload_name! ⇒ Boolean Also known as: refresh_name!
Reloads the name of the room
439 440 441 442 443 444 445 446 447 448 |
# File 'lib/matrix_sdk/room.rb', line 439 def reload_name! data = begin client.api.get_room_name(id) rescue MatrixNotFoundError nil end changed = data[:name] != @name @name = data[:name] if changed changed end |
#reload_topic! ⇒ Boolean Also known as: refresh_topic!
Reloads the topic of the room
458 459 460 461 462 463 464 465 466 467 |
# File 'lib/matrix_sdk/room.rb', line 458 def reload_topic! data = begin client.api.get_room_topic(id) rescue MatrixNotFoundError nil end changed = data[:topic] != @topic @topic = data[:topic] if changed changed end |
#remove_tag(tag) ⇒ Object
Remove a tag from the room
407 408 409 410 |
# File 'lib/matrix_sdk/room.rb', line 407 def remove_tag(tag) client.api.remove_user_tag(client.mxid, id, tag) true end |
#send_audio(url, name, audio_info = {}) ⇒ Object
The URLs should all be of the ‘mxc://’ schema
Sends a link to an audio clip to the room
269 270 271 |
# File 'lib/matrix_sdk/room.rb', line 269 def send_audio(url, name, audio_info = {}) client.api.send_content(id, url, name, 'm.audio', extra_information: audio_info) end |
#send_emote(text) ⇒ Object
Sends an emote (/me) message to the room
197 198 199 |
# File 'lib/matrix_sdk/room.rb', line 197 def send_emote(text) client.api.send_emote(id, text) end |
#send_file(url, name, file_info = {}) ⇒ Object
The URLs should all be of the ‘mxc://’ schema
Sends a link to a generic file to the room
210 211 212 |
# File 'lib/matrix_sdk/room.rb', line 210 def send_file(url, name, file_info = {}) client.api.send_content(id, url, name, 'm.file', extra_information: file_info) end |
#send_html(html, body = nil, msg_type = 'm.text') ⇒ Object
Sends a custom HTML message to the room
184 185 186 187 188 189 190 191 192 193 |
# File 'lib/matrix_sdk/room.rb', line 184 def send_html(html, body = nil, msg_type = 'm.text') content = { body: body || html.gsub(/<\/?[^>]*>/, ''), msgtype: msg_type, format: 'org.matrix.custom.html', formatted_body: html } client.api.(id, 'm.room.message', content) end |
#send_image(url, name, image_info = {}) ⇒ Object
The URLs should all be of the ‘mxc://’ schema
Sends a link to an image to the room
231 232 233 |
# File 'lib/matrix_sdk/room.rb', line 231 def send_image(url, name, image_info = {}) client.api.send_content(id, url, name, 'm.image', extra_information: image_info) end |
#send_location(geo_uri, name, thumbnail_url = nil, thumbnail_info = {}) ⇒ Object
The thumbnail URL should be of the ‘mxc://’ schema
Sends a location object to the room
241 242 243 |
# File 'lib/matrix_sdk/room.rb', line 241 def send_location(geo_uri, name, thumbnail_url = nil, thumbnail_info = {}) client.api.send_location(id, geo_uri, name, thumbnail_url: thumbnail_url, thumbnail_info: thumbnail_info) end |
#send_notice(text) ⇒ Object
Sends a notice (bot) message to the room
216 217 218 |
# File 'lib/matrix_sdk/room.rb', line 216 def send_notice(text) client.api.send_notice(id, text) end |
#send_text(text) ⇒ Object
Sends a plain-text message to the room
173 174 175 |
# File 'lib/matrix_sdk/room.rb', line 173 def send_text(text) client.api.(id, text) end |
#send_video(url, name, video_info = {}) ⇒ Object
The URLs should all be of the ‘mxc://’ schema
Sends a link to a video to the room
257 258 259 |
# File 'lib/matrix_sdk/room.rb', line 257 def send_video(url, name, video_info = {}) client.api.send_content(id, url, name, 'm.video', extra_information: video_info) end |
#set_account_data(type, account_data) ⇒ Object
Stores a custom entry into the room-specific account data
356 357 358 359 |
# File 'lib/matrix_sdk/room.rb', line 356 def set_account_data(type, account_data) client.api.set_room_account_data(client.mxid, id, type, account_data) true end |
#set_user_profile(display_name: nil, avatar_url: nil, reason: nil) ⇒ Object
the avatar URL should be a mxc:// URI
Changes the room-specific user profile
365 366 367 368 369 370 371 372 373 374 375 376 |
# File 'lib/matrix_sdk/room.rb', line 365 def set_user_profile(display_name: nil, avatar_url: nil, reason: nil) return nil unless display_name || avatar_url data = client.api.get_membership(id, client.mxid) raise "Can't set profile if you haven't joined the room" unless data[:membership] == 'join' data[:displayname] = display_name unless display_name.nil? data[:avatar_url] = avatar_url unless avatar_url.nil? client.api.set_membership(id, client.mxid, 'join', reason || 'Updating room profile information', data) true end |
#tags ⇒ Response
Returns a list of the room tags
387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 |
# File 'lib/matrix_sdk/room.rb', line 387 def client.api.(client.mxid, id)[:tags].tap do |tag_obj| tag_obj.instance_variable_set(:@room, self) tag_obj.define_singleton_method(:room) do @room end tag_obj.define_singleton_method(:add) do |tag, **data| @room.add_tag(tag.to_s.to_sym, data) self[tag.to_s.to_sym] = data self end tag_obj.define_singleton_method(:remove) do |tag| @room.remove_tag(tag.to_s.to_sym) delete tag.to_s.to_sym end end end |