discorb 0.3.1 → 0.5.0

data/docs/cli.md

@@ -18,4 +18,9 @@ Currently, discorb has the following commands:
 |---------|-------------|
 | {file:docs/cli/init.md `init`} | Create a new project. |
 | {file:docs/cli/irb.md `irb`} | Start an interactive Ruby shell with connected client. |
-| `show` | Show your environment. |
+| {file:docs/cli/run.md `run`} | Run a client. |
+| {file:docs/cli/setup.md `setup`} | Setup application commands. |
+| `show` | Show your environment. (No document) |
+| `about` | Show discorb's information. (No document) |
+
+Click the command name to see the document.

data/docs/tutorial.md

@@ -0,0 +1,194 @@
+# @title Tutorial
+
+# Tutorial
+
+Welcome to discorb! This lib allows you to create a discord bot with ease. So, let's get started!
+
+## Requirements
+
+- Ruby 3.0.0+
+- Basic knowledge of ruby  
+    These documents will help you:
+    - [Ruby in Twenty Minutes](https://www.ruby-lang.org/en/documentation/quickstart/)
+    - [Ruby from other languages](https://www.ruby-lang.org/en/documentation/ruby-from-other-languages/)
+    - [Try ruby!](https://try.ruby-lang.org/)
+
+### Recommended
+
+- Good editor  
+    They are recommended:
+    - [VSCode](https://code.visualstudio.com/)
+    - [Atom](https://atom.io/)
+    - [Sublime Text](https://www.sublimetext.com/)
+    - [Brackets](https://brackets.io/)
+    - [Notepad++](https://notepad-plus-plus.org/)
+- Git
+- Bundler
+
+Once you have all of these, you can start coding!
+
+## Start creating your bot
+
+### Create a Bot account
+
+You must have a bot account to use this lib. First, go to [Discord Developer Portal](https://discord.com/developers/applications) and click on `New Application`.  
+![](./assets/01_new_app.png)
+
+And then type a name for your bot, and click `Create`.  
+![](./assets/02_bot_name.png)
+
+You will be redirected to the `General Information` page.
+Then, click `Bot` and then `Add Bot` and then `Yes, do it!`.  
+![](./assets/03_add_bot.png)
+
+You will see bot information, and click `Copy` button in TOKEN section.  
+![](./assets/04_token_copy.png)
+
+**DO NOT SHARE THIS TOKEN, OR YOUR BOT BAN EVERYONE IN EVERY SERVER!**
+This is serious security risk.
+
+Click `Regenerate` button to regenerate your token. Do this immediately when you accidentally share your token.
+
+You did it! Now, you have a bot account.
+
+#### Invite your bot to a server
+
+Go to `OAuth2` page and scroll down, and check `bot` and `applications.commands` permissions.  
+![](./assets/05_oauth.png)
+Then, click `Copy` button and paste it to your browser.
+Choose a server you want to invite your bot to, and follow the instructions.
+
+### Code your bot
+
+#### Install gems
+
+Open terminal and type:
+
+```
+gem install bundler discorb
+```
+
+#### Setup files
+
+Create a new directory and go to it.
+Open terminal and type:
+
+```
+discorb init
+```
+
+Specify `--git` if you want to use git.
+
+You will get some files in your directory.
+
+- `main.rb`: The main file of your bot.
+- `.env`: The environment variables of your bot. **You must keep this file secret!**
+- `Gemfile`: Gemfile for bundler.
+- `Gemfile.lock`: Gemfile.lock for bundler.
+
+You will get other files if you specify `--git`.
+{file:docs/cli/init.md Learn more here}.
+
+#### Start your bot
+
+Open `main.rb`, you will see the following code:
+
+```ruby
+require "discorb"
+require "dotenv"
+
+Dotenv.load  # Loads .env file
+
+client = Discorb::Client.new  # Create client for connecting to Discord
+
+client.once :ready do
+  puts "Logged in as #{client.user}"  # Prints username of logged in user
+end
+
+client.run ENV["TOKEN"]  # Starts client
+```
+
+Open `.env`, you will see:
+
+```
+TOKEN=Y0urB0tT0k3nHer3.Th1sT0ken.W0ntWorkB3c4useItH4sM34n1ng
+```
+
+Replace `Y0urB0tT0k3nHer3.Th1sT0ken.W0ntWorkB3c4useItH4sM34n1ng` with your bot token.
+Remember to keep this file secret!
+
+Open terminal and type:
+
+```sh
+bundle exec ruby main.rb
+# or
+bundle exec discorb run main.rb
+```
+
+Yay! Your bot is online!  
+![](./assets/06_online.png)
+
+But your bot won't do anything.
+So add your bot some greetings!
+`Ctrl + C` to stop your bot.
+
+#### Add a greeting
+
+You can do some action on message by typing like this:
+
+```ruby
+client.on :message do |message|
+  # ...
+end
+```
+
+`message` is a {Discorb::Message} object. It contains information about the message.
+You can get the message content by {Discorb::Message#content}.
+Add `if` statement, and reply to the message with {Discorb::Message#reply}.
+
+```ruby
+client.on :message do |message|
+  if message.content.downcase.include? "hello"
+    message.reply "Hello!"
+  end
+end
+```
+
+Save your bot and restart it.
+
+You can see your bot's response by typing `hello` in your server...  
+
+![](./assets/07_hello_infinite.png)
+
+Oh no! Your bot is responding to bot's messages, and it doesn't stop!
+
+Terminate your bot by typing `Ctrl + C` in terminal.
+
+#### Ignore bot's messages
+
+You can access author information by {Discorb::Message#author}, and it has {Discorb::User#bot?}.
+So, you can ignore bot's messages by adding `if` statement:
+
+```ruby
+client.on :message do |message|
+  next if message.author.bot?
+
+  # ...
+end
+```
+
+Note you must use `next` to exit the block.
+
+Save your bot and start it.
+
+![](./assets/08_hello_once.png)
+
+You did it! Your bot won't respond to bot's messages anymore.
+
+## Finally
+
+This is the end of tutorial.
+
+To learn more, check out the [documentation](https://discorb-lib.github.io/).
+
+We hope you enjoy this lib! Thanks for reading!

data/exe/discorb

@@ -17,6 +17,9 @@ if script.nil?
     puts "\e[90m#{name.rjust(max_length)}\e[m - #{description}"
   end
 
+  puts "\e[94m\nTo run a tool, type:\e[m\n" +
+         "\e[34m  discorb [script]\e[m"
+
   exit 1
 end
 

data/lib/discorb/client.rb

@@ -60,12 +60,11 @@ module Discorb
     # @param [Boolean] colorize_log Whether to colorize the log.
     # @param [:debug, :info, :warn, :error, :critical] log_level The log level.
     # @param [Boolean] wait_until_ready Whether to delay event dispatch until ready.
-    # @param [Boolean] overwrite_application_commands Whether to overwrite application commands on ready.
     #
     def initialize(
       allowed_mentions: nil, intents: nil, message_caches: 1000,
       log: nil, colorize_log: false, log_level: :info,
-      wait_until_ready: true, overwrite_application_commands: true
+      wait_until_ready: true
     )
       @allowed_mentions = allowed_mentions || AllowedMentions.new(everyone: true, roles: true, users: true)
       @intents = (intents or Intents.default)
@@ -86,7 +85,6 @@ module Discorb
       @tasks = []
       @conditions = {}
       @commands = []
-      @overwrite_application_commands = overwrite_application_commands
       @status = :initialized
     end
 
@@ -384,11 +382,69 @@ module Discorb
 
     #
     # Starts the client.
+    # @note This method behavior will change by CLI.
+    # @see file:docs/cli.md
     #
     # @param [String] token The token to use.
     #
     def run(token)
+      case ENV["DISCORB_CLI_FLAG"]
+      when nil
+        start_client(token)
+      when "run"
+        require "json"
+        options = JSON.parse(ENV["DISCORB_CLI_OPTIONS"], symbolize_names: true)
+        Process.daemon if options[:daemon]
+        setup_commands(token) if options[:setup]
+        if options[:log_level]
+          if options[:log_level] == "none"
+            @log.out = nil
+          else
+            @log.out = case options[:log_file]
+              when nil, "stderr"
+                $stderr
+              when "stdout"
+                $stdout
+              else
+                ::File.open(options[:log_file], "a")
+              end
+            @log.level = options[:log_level].to_sym
+            @log.colorize_log = case options[:log_color]
+              when nil
+                if @log.out == $stdout || @log.out == $stderr
+                  true
+                else
+                  false
+                end
+              when true, false
+                options[:log_color]
+              end
+          end
+        end
+        start_client(token)
+      when "setup_command"
+        setup_commands(token)
+      end
+    end
+
+    #
+    # Stops the client.
+    #
+    def close!
+      @connection.send_close
+      @tasks.each(&:stop)
+      @status = :closed
+      @close_condition.signal
+    end
+
+    private
+
+    def start_client(token)
       Async do |task|
+        trap(:SIGINT) {
+          @log.info "SIGINT received, closing..."
+          close!
+        }
         @token = token.to_s
         @close_condition = Async::Condition.new
         main_task = Async do
@@ -403,15 +459,5 @@ module Discorb
         main_task.stop
       end
     end
-
-    #
-    # Stops the client.
-    #
-    def close!
-      @connection.send_close
-      @tasks.each(&:stop)
-      @status = :closed
-      @close_condition.signal
-    end
   end
 end

data/lib/discorb/command.rb

@@ -92,7 +92,6 @@ module Discorb
 
       #
       # Setup commands.
-      # @note This method is called automatically if overwrite_application_commands is set to true.
       # @see Client#initialize
       #
       # @param [String] token Bot token.

data/lib/discorb/common.rb

@@ -4,7 +4,7 @@ module Discorb
   # @return [String] The API base URL.
   API_BASE_URL = "https://discord.com/api/v9"
   # @return [String] The version of discorb.
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
   # @return [String] The user agent for the bot.
   USER_AGENT = "DiscordBot (https://github.com/discorb-lib/discorb #{VERSION}) Ruby/#{RUBY_VERSION}"
 

data/lib/discorb/error.rb

@@ -35,6 +35,7 @@ module Discorb
 
   #
   # Represents a HTTP error.
+  # @abstract
   #
   class HTTPError < DiscorbError
     # @return [String] the HTTP response code.
@@ -78,6 +79,20 @@ module Discorb
   class NotFoundError < HTTPError
   end
 
+  #
+  # Represents a error because of a cloudflare ban.
+  #
+  class CloudFlareBanError < HTTPError
+    def initialize(resp, client)
+      @client = client
+      @client.close!
+      DiscorbError.instance_method(:initialize).bind(self).call(<<~MESSAGE)
+        The client is banned from CloudFlare.
+        Hint: Try to increase the number of requests per second, e.g. Use sleep in between requests.
+      MESSAGE
+    end
+  end
+
   #
   # Represents a error in client-side.
   #

data/lib/discorb/exe/about.rb

@@ -0,0 +1,15 @@
+# description: Show information of discorb.
+
+puts "  disco\e[31mrb\e[m -  A new Discord API wrapper in Ruby.  \n\n"
+
+informations = {
+  "GitHub" => "https://github.com/discorb-lib/discorb",
+  "Documentation" => "https://discorb-lib.github.io",
+  "RubyGems" => "https://rubygems.org/gems/discorb",
+  "Changelog" => "https://discorb-lib.github.io/file.Changelog.html",
+  "License" => "MIT License",
+}
+
+informations.each do |key, value|
+  puts "\e[90m#{key}:\e[m #{value}"
+end

data/lib/discorb/exe/init.rb

@@ -1,6 +1,7 @@
 # description: Make files for the discorb project.
 
 require "optparse"
+require "discorb"
 require_relative "../utils/colored_puts"
 
 $path = Dir.pwd
@@ -11,15 +12,15 @@ FILES = {
     require "discorb"
     require "dotenv"
 
-    Dotenv.load
+    Dotenv.load  # Loads .env file
 
-    client = Discorb::Client.new
+    client = Discorb::Client.new  # Create client for connecting to Discord
 
     client.once :ready do
-      puts "Logged in as #{client.user}"
+      puts "Logged in as #{client.user}"  # Prints username of logged in user
     end
 
-    client.run ENV["%<token>s"]
+    client.run ENV["%<token>s"]  # Starts client
   RUBY
   ".env" => <<~BASH,
     %<token>s=Y0urB0tT0k3nHer3.Th1sT0ken.W0ntWorkB3c4useItH4sM34n1ng
@@ -90,9 +91,9 @@ FILES = {
 
     source "https://rubygems.org"
 
-    git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+    git_source(:github) { |repo_name| "https://github.com/\#{repo_name}" }
 
-    gem "discorb", "~> 0.2.5"
+    gem "discorb", "~> #{Discorb::VERSION}"
     gem "dotenv", "~> 2.7"
   RUBY
 }
@@ -141,7 +142,7 @@ opt = OptionParser.new <<~BANNER
 
 $values = {
   bundle: true,
-  git: true,
+  git: false,
   force: false,
   token: "TOKEN",
 }
@@ -150,7 +151,7 @@ opt.on("--[no-]bundle", "Whether to use bundle. Default to true.") do |v|
   $values[:bundle] = v
 end
 
-opt.on("--[no-]git", "Whether to initialize git. Default to true.") do |v|
+opt.on("--[no-]git", "Whether to initialize git. Default to false.") do |v|
   $values[:git] = v
 end
 

data/lib/discorb/exe/irb.rb

@@ -9,10 +9,16 @@ require "optparse"
 intents_value = Discorb::Intents.all.value
 token_file = "token"
 
-opt = OptionParser.new
+ARGV.delete_at 0
+
+opt = OptionParser.new <<~BANNER
+                         This command will start an interactive Ruby shell with connected client.
+
+                         Usage: discorb irb [options]
+                       BANNER
 opt.on("-i", "--intents", "intents to use, default to all") { |v| intents_value = v }
 opt.on("-t", "--token-file", "token file to load, default to \"token\"") { |v| token_file = v }
-opt.parse(ARGV)
+opt.parse!(ARGV)
 
 client = Discorb::Client.new(intents: Discorb::Intents.from_value(intents_value))
 $messages = []
@@ -30,7 +36,7 @@ client.on :ready do
            This is a debug client for Discord.
            \e[90mmessage\e[m to get latest message.
 
-           \e[36mhttps://rubydoc.info/gems/discorb/file/docs/discord_irb.md\e[m for more information.
+           \e[36mhttps://discorb-lib.github.io/#{Discorb::VERSION}/file.irb.html\e[m for more information.
          EOS
   end