lib_discord 0.1.3 → 1.0.1

data/lib/lib_discord/formatter.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "lib_discord/maps"
+
+module LibDiscord
+  module Formatter
+    ##
+    # Format a user ID for use in a message.
+    #
+    # @param user_id [#to_s] User ID
+    # @return [String] Formatted string
+    #
+    # @example
+    #   LibDiscord.formatter.user(1234) # => "<@1234>"
+    def self.user(user_id) = "<@#{user_id}>"
+
+    ##
+    # Format a channel ID for use in a message.
+    #
+    # @param channel_id [#to_s] Channel ID
+    # @return [String] Formatted string
+    #
+    # @example
+    #   LibDiscord.formatter.channel(1234) # => "<#1234>"
+    def self.channel(channel_id) = "<##{channel_id}>"
+
+    ##
+    # Format a role ID for use in a message.
+    #
+    # @param role_id [#to_s] Role ID
+    # @return [String] Formatted string
+    #
+    # @example
+    #   LibDiscord.formatter.role(1234) # => "<@&1234>"
+    def self.role(role_id) = "<@&#{role_id}>"
+
+    # TODO: figure out how to do this one
+    # def self.slash_command
+    # end
+
+    # TODO: write me
+    # def self.custom_emoji(name, id, animated: false)
+    # end
+
+    ##
+    # Format a Unix timestamp for use in a message.
+    #
+    # @param unix_ts [#to_i] Unix timestamp
+    # @param style [String] Single character denoting presentation style.
+    # @return [String] Formatted string
+    # @raise [RuntimeError] if +style+ is not an acceptable timestamp
+    #   presentation style.
+    #
+    # @example
+    #   LibDiscord.formatter.timestamp(0) # => "<t:0>"
+    # @example Set a style
+    #   last_week = Date.today.to_time.to_i - (60 * 60 * 24 * 7)
+    #   LibDiscord.formatter.timestamp(last_week, "R") # => "<t:1747972800:R>"
+    #
+    # @see https://discord.com/developers/docs/reference#message-formatting-timestamp-styles
+    #   Discord documentation "Timestamp Styles"
+    # @see https://en.wikipedia.org/wiki/Unix_time
+    #   Wikipedia "Unix time"
+    def self.timestamp(unix_ts, style = nil)
+      ts = unix_ts.to_i
+      return "<t:#{ts}>" unless style
+
+      accepted = MAPS.fetch(:TimestampStyles).values
+      unless accepted.include?(style)
+        raise "Unknown timestamp style: #{style}"
+      end
+
+      "<t:#{ts}:#{style}>"
+    end
+
+    ##
+    # Format a Guild navigation link for use in a message.
+    #
+    # @param type [#to_s] Guild Navigation Type
+    # @return [String] Formatted string
+    # @raise [RuntimeError] if +type+ is not an acceptable guild navigation
+    #   type.
+    #
+    # @see https://discord.com/developers/docs/reference#message-formatting-guild-navigation-types
+    #   Discord documentation "Guild Navigation Types"
+    def self.guild_navigation(type)
+      accepted = MAPS.fetch(:GuildNavigationTypes).values
+      unless accepted.include?(type)
+        raise "Unknown guild navigation type: #{type}"
+      end
+
+      "<id:#{type}>"
+    end
+  end
+
+  ##
+  # Get a reference to {Formatter}.
+  #
+  # @return [Formatter]
+  #
+  # @example
+  #   fmt = LibDiscord.formatter
+  #   fmt.user(12345678) # => "<@12345678>"
+  #
+  # @see https://discord.com/developers/docs/reference#message-formatting
+  #   Discord documentation "Message Formatting"
+  def self.formatter = Formatter
+end