vrobot4/source/server.rb

# Module for vrobot4 server interfaces.
module Vrobot4::Server
   require "./modules/base.rb"

   # Generic user information. May be extended.
   class User
      attr_reader :name  # @return [String] plaintext name of the user
      attr_reader :roles # @return [String] list of user's roles
      attr_reader :id    # @return [Integer] unique identifier for the user
   end

   # Generic channel information. May be extended.
   class Channel
      attr_reader :name # @return [String] plaintext name of the channel
      attr_reader :id   # @return [Integer] unique identifier for the channel
   end

   # Generic event information. May not be extended.
   class Message
      attr_reader :msg  # @return [String] plaintext of message
      attr_reader :user # @return [User] user that triggered this message
      attr_reader :chan # @return [Channel] channel this message was sent to
      attr_reader :serv # @return [Server] server this message was sent to

      # @param info [Hash] A hash containing message info. Keys may be omitted.
      #  [:msg]     Plaintext of message.
      #  [:user]    User that triggered this message.
      #  [:chan]    Channel that this message was sent to.
      #  [:serv]    Server this message was sent to.
      #  [:reply]   Method that sends a message to the specified channel.
      #  [:reply_b] Method that sends a large message to the specified channel.
      def initialize(**info)
         @msg     = info[:msg]
         @user    = info[:user]
         @chan    = info[:chan]
         @serv    = info[:serv]
         @reply   = info[:reply]
         @reply_b = info[:reply_b]
      end

      # Sends a message to the originating channel.
      # @param args [Array<String>] the text to send
      # @return [void]
      def reply *args
         @reply.call args.join(?\s)
      end

      # Sends a large message to the originating channel.
      # @param args [Array<String>] the text to send
      # @return [void]
      def reply_b *args
         @reply_b.call args.join(?\s)
      end
   end

   # Generic server interface.
   class Server
      attr_reader :mprm # @return [Hash] module permissions for this server
      attr_reader :id   # @return [Integer] unique identifier for the server
      attr_reader :bot  # @return [Vrobot4::Robots::Bot] the bot we belong to

      # @param info [Hash] arbitrary extra information for this server
      # @param bot [Vrobot4::Robots::Bot] the bot we belong to
      def initialize info, bot
         @bot = bot
         @info = info
         @modules = [Mod_Base.new(nil)]
         load_permissions info["permissions"]
      end

      # Loads and initializes a module into the load list.
      # @param mod [Vrobot4::Module::Module]
      # @return [void]
      def load_mod mod
         mt = Vrobot4::Module.get_module_type(mod)
         if mt[:server]    and mt[:server]    != self.class.type or
            mt[:servflags] and mt[:servflags] !~ flags then
            raise ArgumentError, "Module #{mod} is not valid for this server"
         end
         @modules << mt[:type].new(@info[mod])
      end

      # Drops a module from the load list.
      # @param mod [Vrobot4::Module::Module]
      # @return [void]
      def drop_mod mod
         mt = Vrobot4::Module.get_module_type(mod)
         @modules.each_index do |i|
            @modules.delete_at i if @modules[i].is_a? mt[:type]
         end
      end

      # Yields for every module loaded in the server.
      # @yieldparam mod [Vrobot4::Module::Module] an individual module
      # @return [void]
      def each_mod
         @modules.each do |mod|
            yield mod
         end
      end

      # (see Vrobot4::Module::Module#on_message)
      # This function passes information to all modules.
      def on_message m
         @modules.each do |mod|
            break if mod.class.usable_in? m and mod.on_message m
         end
      end

      # (see Vrobot4::Module::Module#on_command)
      # This function passes information to all modules.
      def on_command m, cnam, argv
         @modules.each do |mod|
            break if mod.class.usable_in? m and mod.on_command m, cnam, argv
         end
      end

      # Connect to the server.
      # @abstract
      # @return [void]
      def connect
         raise NotImplementedError, "Server#connect not implemented"
      end

      # Flags for this server.
      # [A] Server has audio capabilities and inherits from
      #     {Vrobot4::Server::AudioServer}.
      # [L] Server cannot support large text dumps
      #     (code should assume <=4 lines, 240 characters per as maximum)
      # @return [String] all available flags
      def flags
         ""
      end

      # Checks if the message starts with +.+ and splits the command from the
      # arguments, then emits an {#on_command} event. Otherwise, it will emit
      # an {#on_message} event.
      # @param m [Vrobot4::Server::Message] the message to parse and emit
      # @return [void]
      def handle_text_cmd m
         if m.msg.start_with? ?.
            arg = m.msg.split(?\s, 2)
            on_command m, arg[0][1 .. -1], arg[1] || ""
         else
            on_message m
         end
      end

      protected

      # Implementation defined permission loader.
      # Loads information into +@mprm+.
      # @abstract
      # @param pinf [Hash] arbitrary permissions information
      # @return [void]
      def load_permissions pinf
         raise NotImplementedError, "Server#load_permissions not implemented"
      end
   end

   # Basis for an audio-enabled server interface.
   class AudioServer < Server
      # (see Vrobot4::Server::Server#flags)
      def flags
         ?A
      end

      # Quit using voice channels.
      # @abstract
      # @param m [Vrobot4::Server::Message] message for context
      # @return [void]
      def voice_quit m
         raise NotImplementedError, "AudioServer#voice_quit not implemented"
      end

      # Plays an audio file by name into the current voice channel.
      # @abstract
      # @param m [Vrobot4::Server::Message] message for context
      # @param fname [String] file name
      # @return [void]
      def voice_play m, fname
         raise NotImplementedError, "AudioServer#voice_play not implemented"
      end

      # Plays an audio I/O stream into the current voice channel.
      # @abstract
      # @param m [Vrobot4::Server::Message] message for context
      # @param io [IO] io stream
      # @return [void]
      def voice_play_io m, io
         raise NotImplementedError, "AudioServer#voice_play_io not implemented"
      end
   end
end

## EOF