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.



700
701
702
 
# File 'lib/discordrb/data.rb', line 700

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



720
721
722
 
# File 'lib/discordrb/data.rb', line 720

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



715
716
717
 
# File 'lib/discordrb/data.rb', line 715

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



709
710
711
 
# File 'lib/discordrb/data.rb', line 709

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.



703
704
705
 
# File 'lib/discordrb/data.rb', line 703

def server
  @server
end

#topic ⇒ String

Returns the channel's topic.

Returns:

  • (String) —

    the channel's topic



712
713
714
 
# File 'lib/discordrb/data.rb', line 712

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')



706
707
708
 
# File 'lib/discordrb/data.rb', line 706

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:



926
927
928
 
# File 'lib/discordrb/data.rb', line 926

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)



849
850
851
852
853
854
855
856
857
858
 
# File 'lib/discordrb/data.rb', line 849

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



808
809
810
 
# File 'lib/discordrb/data.rb', line 808

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.



891
892
893
894
 
# File 'lib/discordrb/data.rb', line 891

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



953
954
955
 
# File 'lib/discordrb/data.rb', line 953

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.



936
937
938
939
 
# File 'lib/discordrb/data.rb', line 936

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.



728
729
730
 
# File 'lib/discordrb/data.rb', line 728

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.



723
724
725
 
# File 'lib/discordrb/data.rb', line 723

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.



901
902
903
904
905
906
907
908
909
910
911
912
913
914
 
# File 'lib/discordrb/data.rb', line 901

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)



803
804
805
 
# File 'lib/discordrb/data.rb', line 803

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.



785
786
787
 
# File 'lib/discordrb/data.rb', line 785

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.



791
792
793
 
# File 'lib/discordrb/data.rb', line 791

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!



797
798
799
 
# File 'lib/discordrb/data.rb', line 797

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)



944
945
946
 
# File 'lib/discordrb/data.rb', line 944

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



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

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



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

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



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

def voice?
  @type == VOICE_TYPE
end