discordrb 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1318b8f7407048d6ba422c2d3732ed9536fdb56d
-  data.tar.gz: d7f68a7d482a60a961c61c96c23c3a34592014e6
+  metadata.gz: ad6998ddf964b9fbb9898312e7d41d503a207bff
+  data.tar.gz: c2bfb298aacd612fee0800f8f1ff434fc0cfe90c
 SHA512:
-  metadata.gz: 8063043dce37200550f85b17d8a521e5da6f9f16c31d2663d5d7d0a2b64ac918644d7124e00a19e5acc50fc6a6fe00b537adae056a0e3b2b72b40395a26c6eb5
-  data.tar.gz: 5b2719cfb5f73cffe7b34957d9ca957766d7c277f57d951ffe2ad9af8ec1fc95af54c193032a4f7a4c0c832475f2227a1410e6351b37ddf22ac4d53f63e993dc
+  metadata.gz: cfcf66d6d21815e39b66b9dfdc1508abfd2f22e11e0d435073aa9d7de45dec0dcef62fb6a50f1921d28ddadd3e8e5c4972364e70a65813bb2284859f305b685d
+  data.tar.gz: f43645f7d126eda651ee82027eb829b7b66e6661b4fe81a6283d81b7935bcb7305e66a7d7614c03af4355a5b6e6b05f71396aae1c720f949a1c36fd20a2c4311

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/discordrb.gemspec

@@ -23,6 +23,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'rest-client'
   spec.add_dependency 'activesupport'
 
+  spec.required_ruby_version = '>= 2.1.0'
+
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rake', '~> 10.0'
 end

data/lib/discordrb/api.rb

@@ -3,6 +3,7 @@ require 'json'
 
 # List of methods representing endpoints in Discord's API
 module Discordrb::API
+  # The base URL of the Discord REST API.
   APIBASE = 'https://discordapp.com/api'
 
   module_function

data/lib/discordrb/await.rb

@@ -1,8 +1,29 @@
 module Discordrb
-  # Class that represents an await to wait for a further event
+  # Awaits are a way to register new, temporary event handlers on the fly. Awaits can be
+  # registered using {Bot#add_await}, {User#await}, {Message#await} and {Channel#await}.
+  #
+  # Awaits contain a block that will be called before the await event will be triggered.
+  # If this block returns anything that is not `false` exactly, the await will be deleted.
+  # If no block is present, the await will also be deleted. This is an easy way to make
+  # temporary events that are only temporary under certain conditions.
+  #
+  # Besides the given block, an {AwaitEvent} will also be executed with the key and
+  # the type of the await that was triggered. It's possible to register multiple events
+  # that trigger on the same await.
   class Await
-    attr_reader :key, :type, :attributes
+    # The key that uniquely identifies this await.
+    # @return [Symbol] The unique key.
+    attr_reader :key
 
+    # The class of the event that this await listens for.
+    # @return [Class] The event class.
+    attr_reader :type
+
+    # The attributes of the event that will be listened for.
+    # @return [Hash] A hash of attributes.
+    attr_reader :attributes
+
+    # Makes a new await. For internal use only.
     def initialize(bot, key, type, attributes, block = nil)
       @bot = bot
       @key = key
@@ -11,6 +32,10 @@ module Discordrb
       @block = block
     end
 
+    # Checks whether the await can be triggered by the given event, and if it can, execute the block
+    # and return its result along with this await's key.
+    # @param event [Event] An event to check for.
+    # @return [Array] This await's key and whether or not it should be deleted. If there was no match, both are nil.
     def match(event)
       dummy_handler = @bot.handler_class(@type).new(@attributes, @bot)
       return [nil, nil] unless dummy_handler.matches?(event)

data/lib/discordrb/bot.rb

@@ -28,9 +28,43 @@ module Discordrb
   class Bot
     include Discordrb::Events
 
-    attr_reader :bot_user, :token, :users, :servers, :event_threads, :profile
+    # The user that represents the bot itself. This version will always be identical to
+    # the user determined by {#user} called with the bot's ID.
+    # @return [User] The bot user.
+    attr_reader :bot_user
+
+    # The Discord API token received when logging in. Useful to explicitly call
+    # {API} methods.
+    # @return [String] The API token.
+    attr_reader :token
+
+    # The list of users the bot shares a server with.
+    # @return [Array<User>] The users.
+    attr_reader :users
+
+    # The list of servers the bot is currently in.
+    # @return [Array<Server>] The servers.
+    attr_reader :servers
+
+    # The list of currently running threads used to parse and call events.
+    # The threads will have a local variable `:discordrb_name` in the format of `et-1234`, where
+    # "et" stands for "event thread" and the number is a continually incrementing number representing
+    # how many events were executed before.
+    # @return [Array<Thread>] The threads.
+    attr_reader :event_threads
+
+    # The bot's user profile. This special user object can be used
+    # to edit user data like the current username (see {Profile#username=}).
+    # @return [Profile] The bot's profile that can be used to edit data.
+    attr_reader :profile
+
+    # Whether or not the bot should parse its own messages. Off by default.
     attr_accessor :should_parse_self
 
+    # Makes a new bot with the given email and password. It will be ready to be added event handlers to and can eventually be run with {#run}.
+    # @param email [String] The email for your (or the bot's) Discord account.
+    # @param password [String] The valid password that should be used to log in to the account.
+    # @param debug [Boolean] Whether or not the bug should run in debug mode, which gives increased console output.
     def initialize(email, password, debug = false)
       # Make sure people replace the login details in the example files...
       if email.end_with? 'example.com'
@@ -57,6 +91,12 @@ module Discordrb
       @current_thread = 0
     end
 
+    # Runs the bot, which logs into Discord and connects the WebSocket. This prevents all further execution unless it is executed with `async` = `:async`.
+    # @param async [Symbol] If it is `:async`, then the bot will allow further execution.
+    #   It doesn't necessarily have to be that, anything truthy will work,
+    #   however it is recommended to use `:async` for code readability reasons.
+    #   If the bot is run in async mode, make sure to eventually run {#sync} so
+    #   the script doesn't stop prematurely.
     def run(async = false)
       run_async
       return if async
@@ -93,14 +133,20 @@ module Discordrb
       debug('Confirmation received! Exiting run.')
     end
 
+    # Prevents all further execution until the websocket thread stops (e. g. through a closed connection).
     def sync
       @ws_thread.join
     end
 
+    # Kills the websocket thread, stopping all connections to Discord.
     def stop
       @ws_thread.kill
     end
 
+    # Gets a channel given its ID. This queries the internal channel cache, and if the channel doesn't
+    # exist in there, it will get the data from Discord.
+    # @param id [Integer] The channel ID for which to search for.
+    # @return [Channel] The channel identified by the ID.
     def channel(id)
       debug("Obtaining data for channel with id #{id}")
       return @channels[id] if @channels[id]
@@ -110,6 +156,11 @@ module Discordrb
       @channels[id] = channel
     end
 
+    # Creates a private channel for the given user ID, or if one exists already, returns that one.
+    # It is recommended that you use {User#pm} instead, as this is mainly for internal use. However,
+    # usage of this method may be unavoidable if only the user ID is known.
+    # @param id [Integer] The user ID to generate a private channel for.
+    # @return [Channel] A private channel for that user.
     def private_channel(id)
       debug("Creating private channel with user id #{id}")
       return @private_channels[id] if @private_channels[id]
@@ -119,31 +170,61 @@ module Discordrb
       @private_channels[id] = channel
     end
 
+    # Gets the code for an invite.
+    # @param invite [String, Invite] The invite to get the code for. Possible formats are:
+    #
+    #    * An {Invite} object
+    #    * The code for an invite
+    #    * A fully qualified invite URL (e. g. `https://discordapp.com/invite/0A37aN7fasF7n83q`)
+    #    * A short invite URL with protocol (e. g. `https://discord.gg/0A37aN7fasF7n83q`)
+    #    * A short invite URL without protocol (e. g. `discord.gg/0A37aN7fasF7n83q`)
+    # @return [String] Only the code for the invite.
     def resolve_invite_code(invite)
       invite = invite.code if invite.is_a? Discordrb::Invite
       invite = invite[invite.rindex('/') + 1..-1] if invite.start_with?('http') || invite.start_with?('discord.gg')
       invite
     end
 
+    # Makes the bot join an invite to a server.
+    # @param invite [String, Invite] The invite to join. For possible formats see {#resolve_invite_code}.
     def join(invite)
       invite = resolve_invite_code(invite)
       resolved = JSON.parse(API.resolve_invite(@token, invite))['code']
       API.join_server(@token, resolved)
     end
 
+    # Revokes an invite to a server. Will fail unless you have the *Manage Server* permission.
+    # It is recommended that you use {Invite#delete} instead.
+    # @param code [String, Invite] The invite to revoke. For possible formats see {#resolve_invite_code}.
     def delete_invite(code)
       invite = resolve_invite_code(code)
       API.delete_invite(@token, invite)
     end
 
+    # Gets a user by its ID.
+    # @note This can only resolve users known by the bot (i.e. that share a server with the bot).
+    # @param id [Integer] The user ID that should be resolved.
+    # @return [User, nil] The user identified by the ID, or `nil` if it couldn't be found.
     def user(id)
       @users[id]
     end
 
+    # Gets a server by its ID.
+    # @note This can only resolve servers the bot is currently in.
+    # @param id [Integer] The server ID that should be resolved.
+    # @return [Server, nil] The server identified by the ID, or `nil` if it couldn't be found.
     def server(id)
       @servers[id]
     end
 
+    # Finds a channel given its name and optionally the name of the server it is in. If the threshold
+    # is not 0, it will use a Levenshtein distance function to find the channel in a fuzzy way, which
+    # allows slight misspellings.
+    # @param channel_name [String] The channel to search for.
+    # @param server_name [String] The server to search for, or `nil` if only the channel should be searched for.
+    # @param threshold [Integer] The threshold for the Levenshtein algorithm. The larger
+    #   the threshold is, the more misspellings will be allowed.
+    # @return [Array<Channel>] The array of channels that were found. May be empty if none were found.
     def find(channel_name, server_name = nil, threshold = 0)
       require 'levenshtein'
 
@@ -165,23 +246,51 @@ module Discordrb
       results
     end
 
+    # Sends a text message to a channel given its ID and the message's content.
+    # @param channel_id [Integer] The ID that identifies the channel to send something to.
+    # @param content [String] The text that should be sent as a message. It is limited to 2000 characters (Discord imposed).
+    # @return [Message] The message that was sent.
     def send_message(channel_id, content)
       debug("Sending message to #{channel_id} with content '#{content}'")
       response = API.send_message(@token, channel_id, content)
       Message.new(JSON.parse(response), self)
     end
 
+    # Sends a file to a channel. If it is an image, it will automatically be embedded.
+    # @note This executes in a blocking way, so if you're sending long files, be wary of delays.
+    # @param channel_id [Integer] The ID that identifies the channel to send something to.
+    # @param file [File] The file that should be sent.
     def send_file(channel_id, file)
       API.send_file(@token, channel_id, file)
     end
 
+    # Add an await the bot should listen to. For information on awaits, see {Await}.
+    # @param key [Symbol] The key that uniquely identifies the await for {AwaitEvent}s to listen to (see {#await}).
+    # @param type [Class] The event class that should be listened for.
+    # @param attributes [Hash] The attributes the event should check for. The block will only be executed if all attributes match.
+    # @yield Is executed when the await is triggered.
+    # @yieldparam event [Event] The event object that was triggered.
+    # @return [Await] The await that was created.
     def add_await(key, type, attributes = {}, &block)
       fail "You can't await an AwaitEvent!" if type == Discordrb::Events::AwaitEvent
       await = Await.new(self, key, type, attributes, block)
       @awaits[key] = await
     end
 
-    # Regions: :london, :amsterdam, :frankfurt, :us-east, :us-west, :singapore, :sydney
+    # Creates a server on Discord with a specified name and a region.
+    # @note Discord's API doesn't directly return the server when creating it, so this method
+    #   waits until the data has been received via the websocket. This may make the execution take a while.
+    # @param name [String] The name the new server should have. Doesn't have to be alphanumeric.
+    # @param region [Symbol] The region where the server should be created. Possible regions are:
+    #
+    #   * `:london`
+    #   * `:amsterdam`
+    #   * `:frankfurt`
+    #   * `:us-east`
+    #   * `:us-west`
+    #   * `:singapore`
+    #   * `:sydney`
+    # @return [Server] The server that was created.
     def create_server(name, region = :london)
       response = API.create_server(@token, name, region)
       id = JSON.parse(response)['id'].to_i
@@ -191,12 +300,18 @@ module Discordrb
       server
     end
 
+    # Gets the user from a mention of the user.
+    # @param mention [String] The mention, which should look like <@12314873129>.
+    # @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
       user(id)
     end
 
+    # Sets the currently playing game to the specified game.
+    # @param name_or_id [String, Fixnum] The name or the ID of the game to be played.
+    # @return [Game] The game object that is being played now.
     def game=(name_or_id)
       game = Discordrb::Games.find_game(name_or_id)
       @game = game
@@ -213,6 +328,7 @@ module Discordrb
       game
     end
 
+    # Sets debug mode. If debug mode is on, many things will be outputted to STDOUT.
     attr_writer :debug
 
     ##     ##    ###    ##    ## ########  ##       ######## ########   ######
@@ -223,6 +339,21 @@ module Discordrb
     ##     ## ##     ## ##   ### ##     ## ##       ##       ##    ##  ##    ##
     ##     ## ##     ## ##    ## ########  ######## ######## ##     ##  ######
 
+    # This **event** is raised when a message is sent to a text channel the bot is currently in.
+    # @param attributes [Hash] The event's attributes.
+    # @option attributes [String, Regexp] :start_with Matches the string the message starts with.
+    # @option attributes [String, Regexp] :end_with Matches the string the message ends with.
+    # @option attributes [String, Regexp] :contains Matches a string the message contains.
+    # @option attributes [String, Integer, Channel] :in Matches the channel the message was sent in.
+    # @option attributes [String, Integer, User] :from Matches the user that sent the message.
+    # @option attributes [String] :content Exactly matches the entire content of the message.
+    # @option attributes [String] :content Exactly matches the entire content of the message.
+    # @option attributes [Time] :after Matches a time after the time the message was sent at.
+    # @option attributes [Time] :before Matches a time before the time the message was sent at.
+    # @option attributes [Boolean] :private Matches whether or not the channel is private.
+    # @yield The block is executed when the event is raised.
+    # @yieldparam event [MessageEvent] The event that was raised.
+    # @return [MessageEventHandler] The event handler that was registered.
     def message(attributes = {}, &block)
       register_event(MessageEvent, attributes, block)
     end
@@ -308,6 +439,14 @@ module Discordrb
       register_event(GuildDeleteEvent, attributes, block)
     end
 
+    # This **event** is raised when an {Await} is triggered. It provides an easy way to execute code
+    # on an await without having to rely on the await's block.
+    # @param attributes [Hash] The event's attributes.
+    # @option attributes [Symbol] :key Exactly matches the await's key.
+    # @option attributes [Class] :type Exactly matches the event's type.
+    # @yield The block is executed when the event is raised.
+    # @yieldparam event [AwaitEvent] The event that was raised.
+    # @return [AwaitEventHandler] The event handler that was registered.
     def await(attributes = {}, &block)
       register_event(AwaitEvent, attributes, block)
     end

data/lib/discordrb/commands/command_bot.rb

@@ -22,7 +22,8 @@ module Discordrb::Commands
         help_command: attributes[:help_command] || :help,
 
         # The message to display for when a command doesn't exist, %command% to get the command name in question and nil for no message
-        command_doesnt_exist_message: attributes[:command_doesnt_exist_message] || "The command `%command%` doesn't exist!",
+        # No default value here because it may not be desired behaviour
+        command_doesnt_exist_message: attributes[:command_doesnt_exist_message],
 
         # All of the following need to be one character
         # String to designate previous result in command chain
@@ -129,7 +130,7 @@ module Discordrb::Commands
           debug("Parsing command chain #{chain}")
           result = (@attributes[:advanced_functionality]) ? CommandChain.new(chain, self).execute(event) : simple_execute(chain, event)
           result = event.saved_message + (result || '')
-          event.respond result if result
+          event.respond result unless result.nil? || result.empty?
         rescue => e
           log_exception(e)
         ensure

data/lib/discordrb/events/await.rb

@@ -2,11 +2,18 @@ require 'discordrb/events/generic'
 require 'discordrb/await'
 
 module Discordrb::Events
-  # Event raised when an await is triggered
+  # @see Bot#await
   class AwaitEvent
-    attr_reader :await, :event
+    # The await that was triggered.
+    # @return [Await] The await
+    attr_reader :await
+
+    # The event that triggered the await.
+    # @return [Event] The event
+    attr_reader :event
     delegate :key, :type, :attributes, to: :await
 
+    # For internal use only
     def initialize(await, event, bot)
       @await = await
       @event = event
@@ -14,7 +21,7 @@ module Discordrb::Events
     end
   end
 
-  # Event handler for AwaitEvent
+  # Event handler for {AwaitEvent}
   class AwaitEventHandler < EventHandler
     def matches?(event)
       # Check for the proper event type

data/lib/discordrb/version.rb

@@ -1,4 +1,4 @@
 # Discordrb and all its functionality, in this case only the version.
 module Discordrb
-  VERSION = '1.4.0'
+  VERSION = '1.4.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: discordrb
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - meew0
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-04 00:00:00.000000000 Z
+date: 2015-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faye-websocket
@@ -91,6 +91,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -142,7 +143,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="