discordrb 2.0.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 86b237c8122ce65285f26a72379d063594d64468
-  data.tar.gz: 676f4b7428f7f01a670eff05c85d7a14092affab
+  metadata.gz: e61613220092ee639a9cd4db8f5fad0d7485b5a8
+  data.tar.gz: 008902a804d2938eff3d369bb500d6a755ccb605
 SHA512:
-  metadata.gz: 0f18865d96e89381d9aad624558331915f90bfe622f9ed0e280d7c04a3702676548e0ab093b38523fb620aef0212c5415dd39e8d14428950d38ce923d706bc10
-  data.tar.gz: 54533279a8439c4dbadefe1bb2e70f6c660565f10dcb544fa6aa389e9ccaf7b0611857a5f8bd1055e771fc11b555b05ab030d11b4ad9c837752e0fd851cfce73
+  metadata.gz: fedc89d8c0ccb3229425382413e2ce4bb946e676924542092290985f4ba11b2d5e402ce210df590fbeb29393536593ef8e09d5189cd795f225b40156fa052e55
+  data.tar.gz: 9793bdc3c7ed44daa090145e0bf693c0ab12070ebe1e73f89204a0c8423c6d7e734461caef25b461fee1a0893a1c9717c7fda6dc2fbc7badbe458eeed44e2038

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.1.0
+
+- API support for the April 29 Discord update, which was the first feature update in a while with more than a few additions to the API, was added. This includes: ([#111](https://github.com/meew0/discordrb/pull/111))
+  - Members' nicknames can now be set and read (`Member#nick`) and updates to them are being tracked.
+  - Roles now have a `mentionable?` property and a `mention` utility method.
+  - `Message` now tracks a message's role mentions.
+- The internal REST rate limit handler was updated:
+  - It now tracks message rate limits server wide to properly handle new bot account rate limits. ([#100](https://github.com/meew0/discordrb/issues/100))
+  - It now keeps track of all requests, even those that are known not to be rate limited (it just won't do anything to them). This allows for more flexibility should future rate limits be added.
+- Guild sharding is now supported using the optional `shard_id` and `num_shards` to bot initializers. Read about it here: https://github.com/hammerandchisel/discord-api-docs/issues/17 ([#98](https://github.com/meew0/discordrb/issues/98))
+- Commands can now require users to have specific action permissions to be able to execute them using the `:required_permissions` attribute. ([#104](https://github.com/meew0/discordrb/issues/104) / [#112](https://github.com/meew0/discordrb/pull/112))
+- A `heartbeat` event was added that gets triggered every now and then to allow for roughly periodic actions. ([#110](https://github.com/meew0/discordrb/pull/110))
+- Prefixes are now more flexible in the format they can have - arrays and callables are now allowed as well. Read the documentation for more info.([#107](https://github.com/meew0/discordrb/issues/107) / [#109](https://github.com/meew0/discordrb/pull/109))
+
 ## 2.0.4
 
 - Added a utility method `Invite#url` ([#86](https://github.com/meew0/discordrb/issues/86)/[#101](https://github.com/meew0/discordrb/pull/101), thanks @PoVa)

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 meew0
+Copyright (c) 2015-2016 meew0
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/discordrb.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
-unless ENV['DISCORDRB_V2_MESSAGE']
-  puts "You're using version 2 of discordrb which has some breaking changes!"
-  puts "Don't worry if your bot crashes, you can find a list and migration advice here:"
-  puts ' https://github.com/meew0/discordrb/blob/master/CHANGELOG.md#200'
-  puts 'This message will go away in version 2.1 or can be disabled by setting the DISCORDRB_V2_MESSAGE environment variable.'
-end
-
 require 'discordrb/version'
 require 'discordrb/bot'
 require 'discordrb/commands/command_bot'

data/lib/discordrb/api.rb

@@ -43,9 +43,7 @@ module Discordrb::API
 
   # Resets all rate limit mutexes
   def reset_mutexes
-    @mutexes = {
-      message: Mutex.new
-    }
+    @mutexes = {}
   end
 
   # Performs a RestClient request.
@@ -68,6 +66,8 @@ module Discordrb::API
 
     begin
       if key
+        @mutexes[key] = Mutex.new unless @mutexes[key]
+
         # Lock and unlock, i. e. wait for the mutex to unlock and don't do anything with it afterwards
         @mutexes[key].lock
         @mutexes[key].unlock
@@ -106,7 +106,7 @@ module Discordrb::API
   # Ban a user from a server and delete their messages from the last message_days days
   def ban_user(token, server_id, user_id, message_days)
     request(
-      nil,
+      __method__,
       :put,
       "#{api_base}/guilds/#{server_id}/bans/#{user_id}?delete-message-days=#{message_days}",
       nil,
@@ -117,7 +117,7 @@ module Discordrb::API
   # Unban a user from a server
   def unban_user(token, server_id, user_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/guilds/#{server_id}/bans/#{user_id}",
       Authorization: token
@@ -127,7 +127,7 @@ module Discordrb::API
   # Kick a user from a server
   def kick_user(token, server_id, user_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/guilds/#{server_id}/members/#{user_id}",
       Authorization: token
@@ -137,7 +137,7 @@ module Discordrb::API
   # Move a user to a different voice channel
   def move_user(token, server_id, user_id, channel_id)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/guilds/#{server_id}/members/#{user_id}",
       { channel_id: channel_id }.to_json,
@@ -146,10 +146,22 @@ module Discordrb::API
     )
   end
 
+  # Change a user's nickname on a server
+  def change_nickname(token, server_id, user_id, nick)
+    request(
+      __method__,
+      :patch,
+      "#{api_base}/guilds/#{server_id}/members/#{user_id}",
+      { nick: nick }.to_json,
+      Authorization: token,
+      content_type: :json
+    )
+  end
+
   # Get a server's banned users
   def bans(token, server_id)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/guilds/#{server_id}/bans",
       Authorization: token
@@ -159,7 +171,7 @@ module Discordrb::API
   # Login to the server
   def login(email, password)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/auth/login",
       email: email,
@@ -170,7 +182,7 @@ module Discordrb::API
   # Logout from the server
   def logout(token)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/auth/logout",
       nil,
@@ -181,7 +193,7 @@ module Discordrb::API
   # Create an OAuth application
   def create_oauth_application(token, name, redirect_uris)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/oauth2/applications",
       { name: name, redirect_uris: redirect_uris }.to_json,
@@ -193,7 +205,7 @@ module Discordrb::API
   # Change an OAuth application's properties
   def update_oauth_application(token, name, redirect_uris, description = '', icon = nil)
     request(
-      nil,
+      __method__,
       :put,
       "#{api_base}/oauth2/applications",
       { name: name, redirect_uris: redirect_uris, description: description, icon: icon }.to_json,
@@ -205,7 +217,7 @@ module Discordrb::API
   # Create a server
   def create_server(token, name, region = :london)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/guilds",
       { name: name, region: region.to_s }.to_json,
@@ -217,7 +229,7 @@ module Discordrb::API
   # Update a server
   def update_server(token, server_id, name, region, icon, afk_channel_id, afk_timeout)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/guilds/#{server_id}",
       { name: name, region: region, icon: icon, afk_channel_id: afk_channel_id, afk_timeout: afk_timeout }.to_json,
@@ -229,7 +241,7 @@ module Discordrb::API
   # Transfer server ownership
   def transfer_ownership(token, server_id, user_id)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/guilds/#{server_id}",
       { owner_id: user_id }.to_json,
@@ -241,7 +253,7 @@ module Discordrb::API
   # Delete a server
   def delete_server(token, server_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/guilds/#{server_id}",
       Authorization: token
@@ -251,7 +263,7 @@ module Discordrb::API
   # Leave a server
   def leave_server(token, server_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/users/@me/guilds/#{server_id}",
       Authorization: token
@@ -261,7 +273,7 @@ module Discordrb::API
   # Get a channel's data
   def channel(token, channel_id)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/channels/#{channel_id}",
       Authorization: token
@@ -271,7 +283,7 @@ module Discordrb::API
   # Get a server's data
   def server(token, server_id)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/guilds/#{server_id}",
       Authorization: token
@@ -281,7 +293,7 @@ module Discordrb::API
   # Get a member's data
   def member(token, server_id, user_id)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/guilds/#{server_id}/members/#{user_id}",
       Authorization: token
@@ -291,7 +303,7 @@ module Discordrb::API
   # Create a channel
   def create_channel(token, server_id, name, type)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/guilds/#{server_id}/channels",
       { name: name, type: type }.to_json,
@@ -303,7 +315,7 @@ module Discordrb::API
   # Update a channel's data
   def update_channel(token, channel_id, name, topic, position = 0)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/channels/#{channel_id}",
       { name: name, position: position, topic: topic }.to_json,
@@ -315,7 +327,7 @@ module Discordrb::API
   # Delete a channel
   def delete_channel(token, channel_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/channels/#{channel_id}",
       Authorization: token
@@ -325,7 +337,7 @@ module Discordrb::API
   # Join a server using an invite
   def join_server(token, invite_code)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/invite/#{invite_code}",
       nil,
@@ -336,7 +348,7 @@ module Discordrb::API
   # Resolve an invite
   def resolve_invite(token, invite_code)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/invite/#{invite_code}",
       Authorization: token
@@ -346,7 +358,7 @@ module Discordrb::API
   # Create a private channel
   def create_private(token, bot_user_id, user_id)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/users/#{bot_user_id}/channels",
       { recipient_id: user_id }.to_json,
@@ -360,7 +372,7 @@ module Discordrb::API
   # Create an instant invite from a server or a channel id
   def create_invite(token, channel_id, max_age = 0, max_uses = 0, temporary = false, xkcd = false)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/channels/#{channel_id}/invites",
       { max_age: max_age, max_uses: max_uses, temporary: temporary, xkcdpass: xkcd }.to_json,
@@ -372,7 +384,7 @@ module Discordrb::API
   # Delete an invite by code
   def delete_invite(token, code)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/invites/#{code}",
       Authorization: token
@@ -380,9 +392,9 @@ module Discordrb::API
   end
 
   # Send a message to a channel
-  def send_message(token, channel_id, message, mentions = [], tts = false)
+  def send_message(token, channel_id, message, mentions = [], tts = false, guild_id = nil)
     request(
-      :message,
+      "message-#{guild_id}".to_sym,
       :post,
       "#{api_base}/channels/#{channel_id}/messages",
       { content: message, mentions: mentions, tts: tts }.to_json,
@@ -396,7 +408,7 @@ module Discordrb::API
   # Delete a message
   def delete_message(token, channel_id, message_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/channels/#{channel_id}/messages/#{message_id}",
       Authorization: token
@@ -420,7 +432,7 @@ module Discordrb::API
   # so this is an easy way to catch up on messages
   def acknowledge_message(token, channel_id, message_id)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/channels/#{channel_id}/messages/#{message_id}/ack",
       nil,
@@ -431,7 +443,7 @@ module Discordrb::API
   # Send a file as a message to a channel
   def send_file(token, channel_id, file)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/channels/#{channel_id}/messages",
       { file: file },
@@ -442,7 +454,7 @@ module Discordrb::API
   # Create a role (parameters such as name and colour will have to be set by update_role afterwards)
   def create_role(token, server_id)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/guilds/#{server_id}/roles",
       nil,
@@ -456,7 +468,7 @@ module Discordrb::API
   # connecting to voice, speaking and voice activity (push-to-talk isn't mandatory)
   def update_role(token, server_id, role_id, name, colour, hoist = false, packed_permissions = 36_953_089)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/guilds/#{server_id}/roles/#{role_id}",
       { color: colour, name: name, hoist: hoist, permissions: packed_permissions }.to_json,
@@ -468,7 +480,7 @@ module Discordrb::API
   # Delete a role
   def delete_role(token, server_id, role_id)
     request(
-      nil,
+      __method__,
       :delete,
       "#{api_base}/guilds/#{server_id}/roles/#{role_id}",
       Authorization: token
@@ -478,7 +490,7 @@ module Discordrb::API
   # Update a user's roles
   def update_user_roles(token, server_id, user_id, roles)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/guilds/#{server_id}/members/#{user_id}",
       { roles: roles }.to_json,
@@ -490,7 +502,7 @@ module Discordrb::API
   # Update a user's permission overrides in a channel
   def update_user_overrides(token, channel_id, user_id, allow, deny)
     request(
-      nil,
+      __method__,
       :put,
       "#{api_base}/channels/#{channel_id}/permissions/#{user_id}",
       { type: 'member', id: user_id, allow: allow, deny: deny }.to_json,
@@ -502,7 +514,7 @@ module Discordrb::API
   # Update a role's permission overrides in a channel
   def update_role_overrides(token, channel_id, role_id, allow, deny)
     request(
-      nil,
+      __method__,
       :put,
       "#{api_base}/channels/#{channel_id}/permissions/#{role_id}",
       { type: 'role', id: role_id, allow: allow, deny: deny }.to_json,
@@ -514,7 +526,7 @@ module Discordrb::API
   # Get the gateway to be used
   def gateway(token)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/gateway",
       Authorization: token
@@ -524,7 +536,7 @@ module Discordrb::API
   # Validate a token (this request will fail if the token is invalid)
   def validate_token(token)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/auth/login",
       {}.to_json,
@@ -536,7 +548,7 @@ module Discordrb::API
   # Start typing (needs to be resent every 5 seconds to keep up the typing)
   def start_typing(token, channel_id)
     request(
-      nil,
+      __method__,
       :post,
       "#{api_base}/channels/#{channel_id}/typing",
       nil,
@@ -547,7 +559,7 @@ module Discordrb::API
   # Get user data
   def user(token, user_id)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/users/#{user_id}",
       Authorization: token
@@ -557,7 +569,7 @@ module Discordrb::API
   # Get profile data
   def profile(token)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/users/@me",
       Authorization: token
@@ -567,7 +579,7 @@ module Discordrb::API
   # Get information about a user's connections
   def connections(token)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/users/@me/connections",
       Authorization: token
@@ -577,7 +589,7 @@ module Discordrb::API
   # Update user data
   def update_user(token, email, password, new_username, avatar, new_password = nil)
     request(
-      nil,
+      __method__,
       :patch,
       "#{api_base}/users/@me",
       { avatar: avatar, email: email, new_password: new_password, password: password, username: new_username }.to_json,
@@ -589,7 +601,7 @@ module Discordrb::API
   # Get the servers a user is connected to
   def servers(token)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/users/@me/guilds",
       Authorization: token
@@ -599,7 +611,7 @@ module Discordrb::API
   # Get a list of messages from a channel's history
   def channel_log(token, channel_id, amount, before = nil, after = nil)
     request(
-      nil,
+      __method__,
       :get,
       "#{api_base}/channels/#{channel_id}/messages?limit=#{amount}#{"&before=#{before}" if before}#{"&after=#{after}" if after}",
       Authorization: token

data/lib/discordrb/bot.rb

@@ -109,6 +109,9 @@ module Discordrb
     # same codebase. Not required but I recommend setting it anyway.
     attr_accessor :name
 
+    # @return [Array(Integer, Integer)] the current shard key
+    attr_reader :shard_key
+
     include EventContainer
     include Cache
 
@@ -145,10 +148,15 @@ module Discordrb
     #   Useful for very large bots running in debug or verbose log_mode.
     # @param parse_self [true, false] Whether the bot should react on its own messages. It's best to turn this off
     #   unless you really need this so you don't inadvertently create infinite loops.
+    # @param shard_id [Integer] The number of the shard this bot should handle. See
+    #   https://github.com/hammerandchisel/discord-api-docs/issues/17 for how to do sharding.
+    # @param num_shards [Integer] The total number of shards that should be running. See
+    #   https://github.com/hammerandchisel/discord-api-docs/issues/17 for how to do sharding.
     def initialize(
         email: nil, password: nil, log_mode: :normal,
         token: nil, application_id: nil,
-        type: nil, name: '', fancy_log: false, suppress_ready: false, parse_self: false)
+        type: nil, name: '', fancy_log: false, suppress_ready: false, parse_self: false,
+        shard_id: nil, num_shards: nil)
       # Make sure people replace the login details in the example files...
       if email.is_a?(String) && email.end_with?('example.com')
         puts 'You have to replace the login details in the example files with your own!'
@@ -172,6 +180,8 @@ module Discordrb
 
       @name = name
 
+      @shard_key = num_shards ? [shard_id, num_shards] : nil
+
       LOGGER.fancy = fancy_log
       @prevent_ready = suppress_ready
 
@@ -390,11 +400,11 @@ module Discordrb
     # @param content [String] The text that should be sent as a message. It is limited to 2000 characters (Discord imposed).
     # @param tts [true, false] Whether or not this message should be sent using Discord text-to-speech.
     # @return [Message] The message that was sent.
-    def send_message(channel_id, content, tts = false)
+    def send_message(channel_id, content, tts = false, server_id = nil)
       channel_id = channel_id.resolve_id
       debug("Sending message to #{channel_id} with content '#{content}'")
 
-      response = API.send_message(token, channel_id, content, [], tts)
+      response = API.send_message(token, channel_id, content, [], tts, server_id)
       Message.new(JSON.parse(response), self)
     end
 
@@ -433,7 +443,7 @@ module Discordrb
     end
 
     # Creates a new application to do OAuth authorization with. This allows you to use OAuth to authorize users using
-    # Discord. For information how to use this, see this example: https://github.com/vishnevskiy/discord-oauth2-example
+    # Discord. For information how to use this, see the docs: https://discordapp.com/developers/docs/topics/oauth2
     # @param name [String] What your application should be called.
     # @param redirect_uris [Array<String>] URIs that Discord should redirect your users to after authorizing.
     # @return [Array(String, String)] your applications' client ID and client secret to be used in OAuth authorization.
@@ -457,7 +467,7 @@ module Discordrb
     # @return [User] The user identified by the mention, or `nil` if none exists.
     def parse_mention(mention)
       # Mention format: <@id>
-      return nil unless /<@(?<id>\d+)>?/ =~ mention
+      return nil unless /<@!?(?<id>\d+)>?/ =~ mention
       user(id.to_i)
     end
 
@@ -724,6 +734,7 @@ module Discordrb
 
       member = server.member(data['user']['id'].to_i)
       member.update_roles(data['roles'])
+      member.update_nick(data['nick'])
     end
 
     # Internal handler for GUILD_MEMBER_DELETE
@@ -1095,7 +1106,7 @@ module Discordrb
         return if message.from_bot? && !should_parse_self
 
         unless message.author
-          LOGGER.warn("Edited a message with nil author! Content: #{message.content.inspect}, channel: #{message.channel.inspect}")
+          LOGGER.debug("Edited a message with nil author! Content: #{message.content.inspect}, channel: #{message.channel.inspect}")
           return
         end
 
@@ -1296,6 +1307,9 @@ module Discordrb
         }
       }
 
+      # Discord is very strict about the existence of the shard parameter, so only add it if it actually exists
+      packet[:d][:shard] = @shard_key if @shard_key
+
       @ws.send(packet.to_json)
     end
 
@@ -1343,6 +1357,9 @@ module Discordrb
 
     def send_heartbeat(sequence = nil)
       sequence ||= @sequence
+
+      raise_event(HeartbeatEvent.new(self))
+
       LOGGER.out("Sending heartbeat with sequence #{sequence}")
       data = {
         op: Opcodes::HEARTBEAT,

data/lib/discordrb/commands/command_bot.rb

@@ -23,9 +23,18 @@ module Discordrb::Commands
     # Creates a new CommandBot and logs in to Discord.
     # @param attributes [Hash] The attributes to initialize the CommandBot with.
     # @see {Discordrb::Bot#initialize} for other attributes that should be used to create the underlying regular bot.
-    # @option attributes [String] :prefix The prefix that should trigger this bot's commands. Can be any string (including the empty
-    #   string), but note that it will be literal - if the prefix is "hi" then the corresponding trigger string for
-    #   a command called "test" would be "hitest". Don't forget to put spaces in if you need them!
+    # @option attributes [String, Array<String>, #call] :prefix The prefix that should trigger this bot's commands. It
+    #   can be:
+    #
+    #   * Any string (including the empty string). This has the effect that if a message starts with the prefix, the
+    #     prefix will be stripped and the rest of the chain will be parsed as a command chain. Note that it will be
+    #     literal - if the prefix is "hi" then the corresponding trigger string for a command called "test" would be
+    #     "hitest". Don't forget to put spaces in if you need them!
+    #   * An array of prefixes. Those will behave similarly to setting one string as a prefix, but instead of only one
+    #     string, any of the strings in the array can be used.
+    #   * Something Proc-like (responds to :call) that takes a string as an argument (the message) and returns either
+    #     the command chain in raw form or `nil` if the given string shouldn't be parsed. This can be used to make more
+    #     complicated dynamic prefixes, or even something else entirely (suffixes, or most adventurous, infixes).
     # @option attributes [true, false] :advanced_functionality Whether to enable advanced functionality (very powerful
     #   way to nest commands into chains, see https://github.com/meew0/discordrb/wiki/Commands#command-chain-syntax
     #   for info. Default is true.
@@ -62,7 +71,9 @@ module Discordrb::Commands
         name: attributes[:name],
         fancy_log: attributes[:fancy_log],
         suppress_ready: attributes[:suppress_ready],
-        parse_self: attributes[:parse_self])
+        parse_self: attributes[:parse_self],
+        shard_id: attributes[:shard_id],
+        num_shards: attributes[:num_shards])
 
       @prefix = attributes[:prefix]
       @attributes = {
@@ -150,7 +161,8 @@ module Discordrb::Commands
         event.respond @attributes[:command_doesnt_exist_message].gsub('%command%', name.to_s) if @attributes[:command_doesnt_exist_message]
         return
       end
-      if permission?(event.user, command.attributes[:permission_level], event.server)
+      if permission?(event.user, command.attributes[:permission_level], event.server) &&
+         required_permissions?(event.author, command.attributes[:required_permissions], event.channel)
         event.command = command
         result = command.call(event, arguments, chained)
         stringify(result)
@@ -205,8 +217,8 @@ module Discordrb::Commands
 
       event = CommandEvent.new(message, self)
 
-      return unless message.content.start_with? @prefix
-      chain = message.content[@prefix.length..-1]
+      chain = trigger?(message.content)
+      return unless chain
 
       # Don't allow spaces between the prefix and the command
       if chain.start_with?(' ') && !@attributes[:spaces_allowed]
@@ -222,6 +234,28 @@ module Discordrb::Commands
       execute_chain(chain, event)
     end
 
+    # Check whether a message should trigger command execution, and if it does, return the raw chain
+    def trigger?(message)
+      if @prefix.is_a? String
+        standard_prefix_trigger(message, @prefix)
+      elsif @prefix.is_a? Array
+        @prefix.map { |e| standard_prefix_trigger(message, e) }.reduce { |a, e| a || e }
+      elsif @prefix.respond_to? :call
+        @prefix.call(message)
+      end
+    end
+
+    def standard_prefix_trigger(message, prefix)
+      return nil unless message.start_with? prefix
+      message[prefix.length..-1]
+    end
+
+    def required_permissions?(member, required, channel = nil)
+      required.reduce(true) do |a, action|
+        a && member.permission?(action, channel)
+      end
+    end
+
     def execute_chain(chain, event)
       t = Thread.new do
         @event_threads << t

data/lib/discordrb/commands/container.rb

@@ -9,6 +9,9 @@ module Discordrb::Commands
   module CommandContainer
     include RateLimiter
 
+    # @return [Array<Command>] the list of commands this container has.
+    attr_reader :commands
+
     # Adds a new command to the container.
     # @param name [Symbol] The name of the command to add.
     # @param attributes [Hash] The attributes to initialize the command with.
@@ -17,6 +20,8 @@ module Discordrb::Commands
     # @option attributes [String, false] :permission_message Message to display when a user does not have sufficient
     #   permissions to execute a command. %name% in the message will be replaced with the name of the command. Disable
     #   the message by setting this option to false.
+    # @option attributes [Array<Symbol>] :required_permissions Discord action permissions (e.g. `:kick_members`) that
+    #   should be required to use this command. See {Discordrb::Permissions::Flags} for a list.
     # @option attributes [true, false] :chain_usable Whether this command is able to be used inside of a command chain
     #   or sub-chain. Typically used for administrative commands that shouldn't be done carelessly.
     # @option attributes [true, false] :help_available Whether this command is visible in the help command. See the

data/lib/discordrb/commands/parser.rb

@@ -19,6 +19,9 @@ module Discordrb::Commands
         # Message to display when a user does not have sufficient permissions to execute a command
         permission_message: (attributes[:permission_message].is_a? FalseClass) ? nil : (attributes[:permission_message] || "You don't have permission to execute command %name%!"),
 
+        # Discord action permissions required to use this command
+        required_permissions: attributes[:required_permissions] || [],
+
         # Whether this command is usable in a command chain
         chain_usable: attributes[:chain_usable].nil? ? true : attributes[:chain_usable],
 

data/lib/discordrb/container.rb

@@ -56,6 +56,21 @@ module Discordrb
       register_event(DisconnectEvent, attributes, block)
     end
 
+    # This **event** is raised every time the bot sends a heartbeat over the galaxy. This happens roughly every 40
+    # seconds, but may happen at a lower rate should Discord change their interval. It may also happen more quickly for
+    # periods of time, especially for unstable connections, since discordrb rather sends a heartbeat than not if there's
+    # a choice. (You shouldn't rely on all this to be accurately timed.)
+    #
+    # All this makes this event useful to periodically trigger something, like doing some API request every hour,
+    # setting some kind of uptime variable or whatever else. The only limit is yourself.
+    # @param attributes [Hash] Event attributes, none in this particular case
+    # @yield The block is executed when the event is raised.
+    # @yieldparam event [HeartbeatEvent] The event that was raised.
+    # @return [HeartbeatEventHandler] The event handler that was registered.
+    def heartbeat(attributes = {}, &block)
+      register_event(HeartbeatEvent, attributes, block)
+    end
+
     # This **event** is raised when somebody starts typing in a channel the bot is also in. The official Discord
     # client would display the typing indicator for five seconds after receiving this event. If the user continues
     # typing after five seconds, the event will be re-raised.

data/lib/discordrb/data.rb

@@ -229,6 +229,10 @@ module Discordrb
     # @return [Time] when this member joined the server.
     attr_reader :joined_at
 
+    # @return [String, nil] the nickname this member has, or nil if it has none.
+    attr_reader :nick
+    alias_method :nickname, :nick
+
     # @return [Array<Role>] the roles this member has.
     attr_reader :roles
 
@@ -342,6 +346,8 @@ module Discordrb
       # Initialize the roles by getting the roles from the server one-by-one
       update_roles(data['roles'])
 
+      @nick = data['nick']
+
       @deaf = data['deaf']
       @mute = data['mute']
       @joined_at = data['joined_at'] ? Time.parse(data['joined_at']) : nil
@@ -379,6 +385,23 @@ module Discordrb
       API.update_user_roles(@bot.token, @server.id, @user.id, new_role_ids)
     end
 
+    # Sets or resets this member's nickname. Requires the Change Nickname permission for the bot itself and Manage
+    # Nicknames for other users.
+    # @param nick [String, nil] The string to set the nickname to, or nil if it should be reset.
+    def nick=(nick)
+      # Discord uses the empty string to signify 'no nickname' so we convert nil into that
+      nick ||= ''
+
+      API.change_nickname(@bot.token, @server.id, @user.id, nick)
+    end
+
+    alias_method :nickname=, :nick=
+
+    # @return [String] the name the user displays as (nickname if they have one, username otherwise)
+    def display_name
+      nickname || username
+    end
+
     # Update this member's roles
     # @note For internal use only.
     # @!visibility private
@@ -388,6 +411,13 @@ module Discordrb
       end
     end
 
+    # Update this member's nick
+    # @note For internal use only.
+    # @!visibility private
+    def update_nick(nick)
+      @nick = nick
+    end
+
     # Update this member's voice state
     # @note For internal use only.
     # @!visibility private
@@ -540,6 +570,10 @@ module Discordrb
     # @return [true, false] whether or not this role should be displayed separately from other users
     attr_reader :hoist
 
+    # @return [true, false] whether this role can be mentioned using a role mention
+    attr_reader :mentionable
+    alias_method :mentionable?, :mentionable
+
     # @return [ColourRGB] the role colour
     attr_reader :colour
 
@@ -567,10 +601,18 @@ module Discordrb
       @permissions = Permissions.new(data['permissions'], RoleWriter.new(self, @bot.token))
       @name = data['name']
       @id = data['id'].to_i
+
       @hoist = data['hoist']
+      @mentionable = data['mentionable']
+
       @colour = ColourRGB.new(data['color'])
     end
 
+    # @return [String] a string that will mention this role, if it is mentionable.
+    def mention
+      "<@&#{@id}>"
+    end
+
     # Updates the data cache from another Role object
     # @note For internal use only
     # @!visibility private
@@ -853,7 +895,7 @@ module Discordrb
     # @param tts [true, false] Whether or not this message should be sent using Discord text-to-speech.
     # @return [Message] the message that was sent.
     def send_message(content, tts = false)
-      @bot.send_message(@id, content, tts)
+      @bot.send_message(@id, content, tts, @server && @server.id)
     end
 
     # Sends multiple messages to a channel
@@ -963,9 +1005,11 @@ module Discordrb
       JSON.parse(logs).map { |message| Message.new(message, @bot) }
     end
 
-    # Deletes the last N messages on this channel.
-    # @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. 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.
+    # @note As of the April 29 update, the message delete request is rate limited, which means this method will take
+    #   a long time. It will eventually be updated to use batch deletes once those are released, but that will be in the
+    #   far future.
     # @param amount [Integer] How many messages to delete. Must be 100 or less (Discord limitation)
     # @raise [ArgumentError] if more than 100 messages are requested.
     def prune(amount)
@@ -1097,6 +1141,9 @@ module Discordrb
     # @return [Array<User>] the users that were mentioned in this message.
     attr_reader :mentions
 
+    # @return [Array<Role>] the roles that were mentioned in this message.
+    attr_reader :role_mentions
+
     # @return [Array<Attachment>] the files attached to this message.
     attr_reader :attachments
 
@@ -1129,6 +1176,15 @@ module Discordrb
         @mentions << bot.ensure_user(element)
       end if data['mentions']
 
+      @role_mentions = []
+
+      # Role mentions can only happen on public servers so make sure we only parse them there
+      unless @channel.private?
+        data['mention_roles'].each do |element|
+          @role_mentions << @channel.server.role(element.to_i)
+        end if data['mention_roles']
+      end
+
       @attachments = []
       @attachments = data['attachments'].map { |e| Attachment.new(e, self, @bot) } if data['attachments']
     end

data/lib/discordrb/events/lifetime.rb

@@ -22,4 +22,10 @@ module Discordrb::Events
 
   # Event handler for {DisconnectEvent}
   class DisconnectEventHandler < TrueEventHandler; end
+
+  # @see Discordrb::EventContainer#heartbeat
+  class HeartbeatEvent < LifetimeEvent; end
+
+  # Event handler for {HeartbeatEvent}
+  class HeartbeatEventHandler < TrueEventHandler; end
 end

data/lib/discordrb/permissions.rb

@@ -32,7 +32,9 @@ module Discordrb
       22 => :mute_members,         # 4194304
       23 => :deafen_members,       # 8388608
       24 => :move_members,         # 16777216
-      25 => :use_voice_activity    # 33554432
+      25 => :use_voice_activity,   # 33554432
+      26 => :change_nickname,      # 67108864
+      27 => :manage_nicknames      # 134217728
     }.freeze
 
     Flags.each do |position, flag|

data/lib/discordrb/version.rb

@@ -3,5 +3,5 @@
 # Discordrb and all its functionality, in this case only the version.
 module Discordrb
   # The current version of discordrb.
-  VERSION = '2.0.4'.freeze
+  VERSION = '2.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: discordrb
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 2.1.0
 platform: ruby
 authors:
 - meew0
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-19 00:00:00.000000000 Z
+date: 2016-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client