Simplified and documented the Print hook

lib/weechat.rb

@@ -13,6 +13,32 @@ def self.included(other)
     other.__send__(:include, Weechat::Helper)
   end
 
+  # Details about a single line that has been printed in a buffer.
+  # Used by the Hooks::Print hook
+  class PrintedLine
+    def initialize(buffer, date, tags, displayed, highlight, prefix, message)
+      @buffer, @date, @tags, @displayed, @highlight = buffer, date, tags, displayed, highlight
+      @prefix, @message = prefix, message
+    end
+
+    # @return [Buffer] The buffer the line was printed on
+    attr_reader :buffer
+    # @return [Time] The date the line was printed
+    attr_reader :date
+    # @return [Array<String>] The tags the line has TODO what is this?
+    attr_reader :tags
+    # @return [Boolean] True if line was displayed, false if it was filtered
+    attr_reader :displayed
+    # @return [Boolean] Whether the line was highlighted
+    attr_reader :highlight
+
+    # @return [String] The prefix of the message TODO give example
+    attr_reader :prefix
+
+    # @return [String] The message text
+    attr_reader :message
+  end
+
   module Helper
     def command_callback(id, buffer, args)
       Weechat::Command.find_by_id(id).call(Weechat::Buffer.from_ptr(buffer), args)
@@ -48,7 +74,8 @@ def print_callback(id, buffer, date, tags, displayed, highlight, prefix, message
       tags      = tags.split(",")
       displayed = Weechat.integer_to_bool(displayed)
       highlight = Weechat.integer_to_bool(highlight)
-      Weechat::Hooks::Print.find_by_id(id).call(buffer, date, tags, displayed, highlight, prefix, message)
+      line = PrintedLine.new(buffer, date, tags, displayed, highlight, prefix, message)
+      Weechat::Hooks::Print.find_by_id(id).call(line)
     end
 
     # TODO add IRC parser

lib/weechat/hooks/print.rb

@@ -1,8 +1,27 @@
 module Weechat
   module Hooks
+    # Hooks for adding behaviour when a line is printed out on a buffer
     class Print < Hook
-      def initialize(buffer='*', tags = [], message = '', strip_colors = false, &callback)
+      # Creates a new Print hook. By default it will be called for every printed
+      # line in every buffer. Set the :buffer, :tags and :message options
+      # to only respond to a subset of messages
+      # @param [Hash] opts Options to determine when and how the Print hook is called
+      # @option opts [Buffer] :buffer If supplied, only printed lines from this Buffer
+      #   will be printed. Default nil
+      # @option opts [Array<String>] :tags Tags for the message TODO how does this filter
+      # @option opts [String] :message TODO how does this filter
+      # @option opts [Boolean] :strip_colors whether color chars should be filtered
+      #   before being sent to the hook
+      #
+      # @yield (line) The callback that should handle the line
+      # @yieldparam [PrintedLine] line
+      def initialize(opts = {}, &callback)
         super
+        buffer = opts[:buffer] || "*"
+        tags = opts[:tags] || []
+        message = opts[:message] || ''
+        strip_colors = opts[:strip_colors] || false
+
         buffer = buffer.ptr if buffer.respond_to?(:ptr)
         tags = tags.join(",")
         strip_colors = Weechat.bool_to_integer(strip_colors)