Class: Discordrb::Channel

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/discordrb/data.rb

Overview

A Discord channel, including data like the topic

Constant Summary collapse

TEXT_TYPE =

The type string that stands for a text channel

See Also:

'text'.freeze
VOICE_TYPE =

The type string that stands for a voice channel

See Also:

'voice'.freeze

Instance Attribute Summary collapse

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from IDObject

#==, #creation_time

Instance Attribute Details

#name ⇒ String

Returns this channel's name.

Returns:

  • (String) —

    this channel's name.



669
670
671
 
# File 'lib/discordrb/data.rb', line 669

def name
  @name
end

#permission_overwrites ⇒ Hash<Integer => OpenStruct> (readonly)

This channel's permission overwrites, represented as a hash of role/user ID to an OpenStruct which has the allow and deny properties which are Permissions objects respectively.

Returns:

  • (Hash<Integer => OpenStruct>) —

    the channel's permission overwrites



689
690
691
 
# File 'lib/discordrb/data.rb', line 689

def permission_overwrites
  @permission_overwrites
end

#position ⇒ Integer

Returns the channel's position on the channel list.

Returns:

  • (Integer) —

    the channel's position on the channel list



684
685
686
 
# File 'lib/discordrb/data.rb', line 684

def position
  @position
end

#recipient ⇒ Recipient? (readonly)

Returns the recipient of the private messages, or nil if this is not a PM channel.

Returns:

  • (Recipient, nil) —

    the recipient of the private messages, or nil if this is not a PM channel



678
679
680
 
# File 'lib/discordrb/data.rb', line 678

def recipient
  @recipient
end

#server ⇒ Server? (readonly)

Returns the server this channel is on. If this channel is a PM channel, it will be nil.

Returns:

  • (Server, nil) —

    the server this channel is on. If this channel is a PM channel, it will be nil.



672
673
674
 
# File 'lib/discordrb/data.rb', line 672

def server
  @server
end

#topic ⇒ String

Returns the channel's topic.

Returns:

  • (String) —

    the channel's topic



681
682
683
 
# File 'lib/discordrb/data.rb', line 681

def topic
  @topic
end

#type ⇒ String (readonly)

Returns the type of this channel (currently either 'text' or 'voice').

Returns:

  • (String) —

    the type of this channel (currently either 'text' or 'voice')



675
676
677
 
# File 'lib/discordrb/data.rb', line 675

def type
  @type
end

Instance Method Details

#await(key, attributes = {}, &block) ⇒ Object

Add an Await for a message in this channel. This is identical in functionality to adding a Events::MessageEvent await with the in attribute as this channel.

See Also:



895
896
897
 
# File 'lib/discordrb/data.rb', line 895

def await(key, attributes = {}, &block)
  @bot.add_await(key, Discordrb::Events::MessageEvent, { in: @id }.merge(attributes), &block)
end

#define_overwrite(thing, allow, deny) ⇒ Object

Defines a permission overwrite for this channel that sets the specified thing to the specified allow and deny permission sets, or change an existing one.

Examples:

Define a permission overwrite for a user that can then mention everyone and use TTS, but not create any invites

allow = Discordrb::Permissions.new
allow.can_mention_everyone = true
allow.can_send_tts_messages = true

deny = Discordrb::Permissions.new
deny.can_create_instant_invite = true

channel.define_overwrite(user, allow, deny)

Parameters:

  • thing (User, Role) —

    What to define an overwrite for.

  • allow (#bits, Permissions, Integer) —

    The permission sets that should receive an allow override (i. e. a green checkmark on Discord)

  • deny (#bits, Permissions, Integer) —

    The permission sets that should receive a deny override (i. e. a red cross on Discord)



818
819
820
821
822
823
824
825
826
827
 
# File 'lib/discordrb/data.rb', line 818

def define_overwrite(thing, allow, deny)
  allow_bits = allow.respond_to?(:bits) ? allow.bits : allow
  deny_bits = deny.respond_to?(:bits) ? deny.bits : deny

  if thing.is_a? User
    API.update_user_overrides(@bot.token, @id, thing.id, allow_bits, deny_bits)
  elsif thing.is_a? Role
    API.update_role_overrides(@bot.token, @id, thing.id, allow_bits, deny_bits)
  end
end

#delete ⇒ Object

Permanently deletes this channel



777
778
779
 
# File 'lib/discordrb/data.rb', line 777

def delete
  API.delete_channel(@bot.token, @id)
end

#history(amount, before_id = nil, after_id = nil) ⇒ Array<Message>

Retrieves some of this channel's message history.

Parameters:

  • amount (Integer) —

    How many messages to retrieve. This must be less than or equal to 100, if it is higher than 100 it will be treated as 100 on Discord's side.

  • before_id (Integer) (defaults to: nil) —

    The ID of the most recent message the retrieval should start at, or nil if it should start at the current message.

  • after_id (Integer) (defaults to: nil) —

    The ID of the oldest message the retrieval should start at, or nil if it should start as soon as possible with the specified amount.

Returns:

  • (Array<Message>) —

    the retrieved messages.



860
861
862
863
 
# File 'lib/discordrb/data.rb', line 860

def history(amount, before_id = nil, after_id = nil)
  logs = API.channel_log(@bot.token, @id, amount, before_id, after_id)
  JSON.parse(logs).map { |message| Message.new(message, @bot) }
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



922
923
924
 
# File 'lib/discordrb/data.rb', line 922

def inspect
  "<Channel name=#{@name} id=#{@id} topic=\"#{@topic}\" type=#{@type} position=#{@position} server=#{@server}>"
end

#make_invite(max_age = 0, max_uses = 0, temporary = false, xkcd = false) ⇒ Invite Also known as: invite

Creates a new invite to this channel.

Parameters:

  • max_age (Integer) (defaults to: 0) —

    How many seconds this invite should last.

  • max_uses (Integer) (defaults to: 0) —

    How many times this invite should be able to be used.

  • temporary (true, false) (defaults to: false) —

    Whether membership should be temporary (kicked after going offline).

  • xkcd (true, false) (defaults to: false) —

    Whether or not the invite should be human-readable.

Returns:

  • (Invite) —

    the created invite.



905
906
907
908
 
# File 'lib/discordrb/data.rb', line 905

def make_invite(max_age = 0, max_uses = 0, temporary = false, xkcd = false)
  response = API.create_invite(@bot.token, @id, max_age, max_uses, temporary, xkcd)
  Invite.new(JSON.parse(response), @bot)
end

#mention ⇒ String

Returns a string that will mention the channel as a clickable link on Discord.

Returns:

  • (String) —

    a string that will mention the channel as a clickable link on Discord.



697
698
699
 
# File 'lib/discordrb/data.rb', line 697

def mention
  "<##{@id}>"
end

#private? ⇒ true, false

Returns whether or not this channel is a PM channel.

Returns:

  • (true, false) —

    whether or not this channel is a PM channel.



692
693
694
 
# File 'lib/discordrb/data.rb', line 692

def private?
  @server.nil?
end

#prune(amount) ⇒ Object

Note:

Each delete request is performed in a separate thread for performance reasons, so if a large number of messages are pruned, many threads will be created.

Deletes the last N messages on this channel.

Parameters:

  • amount (Integer) —

    How many messages to delete. Must be 100 or less (Discord limitation)

Raises:

  • (ArgumentError) —

    if more than 100 messages are requested.



870
871
872
873
874
875
876
877
878
879
880
881
882
883
 
# File 'lib/discordrb/data.rb', line 870

def prune(amount)
  raise ArgumentError, "Can't prune more than 100 messages!" if amount > 100

  threads = []
  history(amount).each do |message|
    threads << Thread.new { message.delete }
  end

  # Make sure all requests have finished
  threads.each(&:join)

  # Delete the threads
  threads.map! { nil }
end

#send_file(file) ⇒ Object

Sends a file to this channel. If it is an image, it will be embedded.

Parameters:

  • file (File) —

    The file to send. There's no clear size limit for this, you'll have to attempt it for yourself (most non-image files are fine, large images may fail to embed)



772
773
774
 
# File 'lib/discordrb/data.rb', line 772

def send_file(file)
  @bot.send_file(@id, file)
end

#send_message(content, tts = false) ⇒ Message Also known as: send, message

Sends a message to this channel.

Parameters:

  • content (String) —

    The content to send. Should not be longer than 2000 characters or it will result in an error.

  • tts (true, false) (defaults to: false) —

    Whether or not this message should be sent using Discord text-to-speech.

Returns:

  • (Message) —

    the message that was sent.



754
755
756
 
# File 'lib/discordrb/data.rb', line 754

def send_message(content, tts = false)
  @bot.send_message(@id, content, tts)
end

#send_multiple(content) ⇒ Object

Sends multiple messages to a channel

Parameters:

  • content (Array<String>) —

    The messages to send.



760
761
762
 
# File 'lib/discordrb/data.rb', line 760

def send_multiple(content)
  content.each { |e| send_message(e) }
end

#split_send(content) ⇒ Object

Splits a message into chunks whose length is at most the Discord character limit, then sends them individually. Useful for sending long messages, but be wary of rate limits!



766
767
768
 
# File 'lib/discordrb/data.rb', line 766

def split_send(content)
  send_multiple(Discordrb.split_message(content))
end

#start_typing ⇒ Object

Starts typing, which displays the typing indicator on the client for five seconds. If you want to keep typing you'll have to resend this every five seconds. (An abstraction for this will eventually be coming)



913
914
915
 
# File 'lib/discordrb/data.rb', line 913

def start_typing
  API.start_typing(@bot.token, @id)
end

#text? ⇒ true, false

Returns whether or not this channel is a text channel.

Returns:

  • (true, false) —

    whether or not this channel is a text channel



741
742
743
 
# File 'lib/discordrb/data.rb', line 741

def text?
  @type == TEXT_TYPE
end

#users ⇒ Array<Member>

The list of users currently in this channel. This is mostly useful for a voice channel, for a text channel it will just return the users on the server that are online.

Returns:

  • (Array<Member>) —

    the users in this channel



842
843
844
845
846
847
848
849
850
 
# File 'lib/discordrb/data.rb', line 842

def users
  if @type == 'text'
    @server.members.select { |u| u.status != :offline }
  else
    @server.members.select do |user|
      user.voice_channel.id == @id if user.voice_channel
    end
  end
end

#voice? ⇒ true, false

Returns whether or not this channel is a voice channel.

Returns:

  • (true, false) —

    whether or not this channel is a voice channel



746
747
748
 
# File 'lib/discordrb/data.rb', line 746

def voice?
  @type == VOICE_TYPE
end