imapcli 0.0.1 → 1.0.0

data/imapcli.gemspec

@@ -6,8 +6,9 @@ spec = Gem::Specification.new do |s|
   s.author = 'Daniel Kraus (bovender)'
   s.email = 'bovender@bovender.de'
   s.homepage = 'https://github.com/bovender/imapcli'
+  s.license = 'Apache-2.0'
   s.platform = Gem::Platform::RUBY
-  s.summary = 'A description of your project'
+  s.summary = 'Command-line tool to query IMAP servers'
   s.files = `git ls-files`.split("\n")
   s.require_paths << 'lib'
   s.has_rdoc = true

data/lib/imapcli.rb

@@ -2,3 +2,5 @@ require 'imapcli/version.rb'
 require 'imapcli/command.rb'
 require 'imapcli/client.rb'
 require 'imapcli/mailbox.rb'
+require 'imapcli/stats.rb'
+require 'imapcli/option_validator.rb'

data/lib/imapcli/client.rb

@@ -145,7 +145,7 @@ module Imapcli
     # * :median: Median of message sizes.
     # * :q3: Third quartile of messages sizes.
     # * :max: Size of largest message.
-    def examine(mailbox)
+    def message_sizes(mailbox)
       # Could use the EXAMINE command to get the number of messages in a mailbox,
       # but we need to retrieve an array of message indexes anyway (to compute
       # the total mailbox size), so we can save one roundtrip to the server.
@@ -153,22 +153,16 @@ module Imapcli
       # total = connection.responses['EXISTS'][0]
       # unseen = query_server { connection.search('UNSEEN') }.length
       messages = messages(mailbox)
-      count = messages.length
-      sizes = query_server { connection.fetch(messages, 'RFC822.SIZE').map { |f| f.attr['RFC822.SIZE'] }.sort }
-      {
-        count: count,
-        size: convert_bytes(sizes.sum),
-        min: convert_bytes(sizes.first),
-        q1: convert_bytes(sizes.percentile(25)),
-        median: convert_bytes(sizes.median),
-        q3: convert_bytes(sizes.percentile(75)),
-        max: convert_bytes(sizes.last)
-      }
+      if messages.length > 0
+        query_server { connection.fetch(messages, 'RFC822.SIZE').map { |f| f.attr['RFC822.SIZE'] } }
+      else
+        []
+      end
     end
 
     # Collects stats for all mailboxes recursively.
     def collect_stats
-      mailbox_tree.collect_stats(self)
+      mailbox_root.collect_stats(self)
     end
 
     # Gets a list of Net::IMAP::MailboxList items, one for each mailbox.
@@ -181,15 +175,15 @@ module Imapcli
     # Returns a tree of +Imapcli::Mailbox+ objects.
     #
     # The value is cached.
-    def mailbox_tree
-      @mailbox_tree ||= Mailbox.new(mailboxes)
+    def mailbox_root
+      @mailbox_root ||= Mailbox.new(mailboxes)
     end
 
-    # Attempts to locate a given +mailbox+ in the +mailbox_tree+.
+    # Attempts to locate a given +mailbox+ in the +mailbox_root+.
     #
     # Returns nil if the mailbox is not found.
     def find_mailbox(mailbox)
-      mailbox_tree.find_sub_mailbox(mailbox, separator)
+      mailbox_root.find_sub_mailbox(mailbox, separator)
     end
 
     private
@@ -217,10 +211,5 @@ module Imapcli
       result
     end
 
-    # Converts a number of bytes to kiB.
-    def convert_bytes(bytes)
-      bytes.fdiv(1024).round
-    end
-
   end # class Client
 end # module Imapcli

data/lib/imapcli/command.rb

@@ -1,10 +1,11 @@
 module Imapcli
+  require 'pp'
   # Provides entry points for Imapcli.
   #
   # Most of the methods in this class return
   class Command
     def initialize(client)
-      raise 'Imapcli::Client is required' unless client
+      raise ArgumentError, 'Imapcli::Client is required' unless client && client.is_a?(Imapcli::Client)
       @client = client
     end
 
@@ -16,11 +17,9 @@ module Imapcli
     end
 
     # Collects basic information about the server.
-    #
-    # The block is called repeatedly with informative messages.
-    # If login is not successful, an error will be raised.
     def info
-      perform do |output|
+      perform do
+        output = []
         output << "greeting: #{@client.greeting}"
         output << "capability: #{@client.capability.join(' ')}"
         output << "hierarchy separator: #{@client.separator}"
@@ -34,33 +33,45 @@ module Imapcli
       end
     end
 
+    # Lists all mailboxes
     def list
-      perform do |output|
-        @client.collect_stats
-        output << "mailboxes (folders) tree:"
-        output += traverse_mailbox_tree @client.mailbox_tree, 0
+      perform do
+        traverse_mailbox_tree(@client.mailbox_root)
       end
     end
 
-    def stats(mailboxes)
-      perform do |output|
-        mailboxes.each do |name|
-          if mailbox = @client.find_mailbox(name)
-            mailbox.collect_stats(@client)
-            output << [
-              mailbox.full_name,
-              mailbox.stats[:count],
-              format_kib(mailbox.stats[:size]),
-              format_kib(mailbox.stats[:min]),
-              format_kib(mailbox.stats[:q1]),
-              format_kib(mailbox.stats[:median]),
-              format_kib(mailbox.stats[:q3]),
-              format_kib(mailbox.stats[:max])
-            ]
-          else
-            output << [ self.class.unknown_mailbox_prefix + name ] + Array.new(7, '---')
+    # Collects statistics about mailboxes.
+    #
+    # If a block is given, it is called with the current mailbox count and the
+    # total mailbox count so that current progress can be computed.
+    def stats(mailbox_names = [], options = {})
+      mailbox_names = [mailbox_names] unless mailbox_names.is_a? Array
+      perform do
+        output = []
+        # Map the command line arguments to Imapcli::Mailbox objects
+        mailboxes = find_mailboxes(mailbox_names)
+        list = mailboxes.inject([]) do |ary, mailbox|
+          ary + mailbox.to_list(determine_max_level(mailbox, options))
+        end
+        raise 'mailbox not found' unless list.count > 0
+        current_count = 0
+        yield list.length if block_given?
+        total_stats = Stats.new
+        list.each do |mailbox|
+          # Since we are working on a flat list of mailboxes, set the maximum
+          # level to 0 when collecting stats.
+          mailbox.collect_stats(@client, 0) do |stats|
+            total_stats.add(stats)
+            current_count += 1
+            yield current_count if block_given?
           end
         end
+        sorted_list(list, options).each do |mailbox|
+          output << stats_to_table(mailbox.full_name, mailbox.stats)
+        end
+        # output << Array.new(8, '======')
+        output << stats_to_table('Total', total_stats) if list.length > 1
+        output
       end
     end
 
@@ -71,29 +82,85 @@ module Imapcli
     private
 
     def perform
-      output = []
       if @client.login
-        yield output
+        yield
       else
         raise 'unable to log into server'
       end
-      output
     end
 
     def traverse_mailbox_tree(mailbox, depth = 0)
-      output = []
-      if mailbox.has_children?
-        indent = ('  ' * depth) || ''
-        mailbox.children.each do |child|
-          output << indent + '- ' + child.name
-          output += traverse_mailbox_tree child, depth + 1
-        end
+      this = mailbox.is_imap_mailbox? ? ["#{'  ' * [depth - 1, 0].max}- #{mailbox.name}"] : []
+      mailbox.children.inject(this) do |ary, child|
+        ary + traverse_mailbox_tree(child, depth + 1)
+      end
+    end
+
+    def stats_to_table(first_cell, stats)
+      [
+        first_cell,
+        stats.count,
+        stats.total_size,
+        stats.min_size,
+        stats.quartile_1_size,
+        stats.median_size,
+        stats.quartile_3_size,
+        stats.max_size
+      ]
+    end
+
+    # Finds and returns mailboxes based on mailbox names.
+    def find_mailboxes(names)
+      if names && names.length > 0
+        Imapcli::Mailbox.consolidate(
+          names.map { |name| @client.find_mailbox(name) }.compact
+        )
+      else
+        [@client.mailbox_root]
+      end
+    end
+
+    # Determines the maximum level for mailbox statistics.
+    #
+    # If the mailbox is the root mailbox, the entire mailbox tree is traversed
+    # by default, unless a :depth option limits the maximum depth.
+    #
+    # If the mailbox is not the root mailbox, by default no recursion will be
+    # performed, unless a :depth option requests a particular depth.
+    #
+    # Options:
+    # * +:depth+ maximum depth of recursion
+    def determine_max_level(mailbox, options = {})
+      if mailbox.is_root?
+        options[:depth]
+      else
+        depth = options[:depth] || 0
+        depth >= 0 ? mailbox.level + depth : nil
       end
-      output
     end
 
-    def format_kib(kib)
-      kib.to_s.reverse.gsub(/...(?=.)/,'\&,').reverse + ' kiB'.freeze
+    def sorted_list(list, options = {})
+      sorted = case options[:sort]
+      when :count
+        list.sort_by { |mailbox| mailbox.stats.count }
+      when :total_size
+        list.sort_by { |mailbox| mailbox.stats.total_size }
+      when :median_size
+        list.sort_by { |mailbox| mailbox.stats.median_size }
+      when :min_size
+        list.sort_by { |mailbox| mailbox.stats.min_size }
+      when :q1
+        list.sort_by { |mailbox| mailbox.stats.q1 }
+      when :q3
+        list.sort_by { |mailbox| mailbox.stats.q3 }
+      when :max_size
+        list.sort_by { |mailbox| mailbox.stats.max_size }
+      when nil
+        list
+      else
+        raise "invalid sort option: #{options[:sort]}"
+      end
+      options[:sort_order] == :desc ? sorted.reverse : sorted
     end
 
   end

data/lib/imapcli/mailbox.rb

@@ -1,13 +1,15 @@
 module Imapcli
   # In IMAP speak, a mailbox is what one would commonly call a 'folder'
   class Mailbox
+    attr_accessor :options
     attr_reader :level, :children, :imap_mailbox_list, :name, :stats
 
     # Creates a new root Mailbox object and optionally adds sub mailboxes from
     # an array of Net::IMAP::MailboxList items.
-    def initialize(mailbox_list_items = nil)
+    def initialize(mailbox_list_items = nil, options = {})
       @level = 0
       @children = {}
+      @options = options
       add_mailbox_list(mailbox_list_items) if mailbox_list_items
     end
 
@@ -15,6 +17,37 @@ module Imapcli
       @children[mailbox]
     end
 
+    # Determines if this mailbox represents a dedicated IMAP mailbox with an
+    # associated Net::IMAP::MailboxList structure.
+    def is_imap_mailbox?
+      not imap_mailbox_list.nil?
+    end
+
+    def is_root?
+      name.respond_to?(:empty?) ? !!name.empty? : !name
+    end
+
+    # Counts all sub mailboxes recursively.
+    #
+    # The result includes the current mailbox.
+    def count(max_level = nil)
+      sum = 1
+      if max_level.nil? || level < max_level
+        @children.values.inject(sum) do |count, child|
+          count + child.count(max_level)
+        end
+      end
+    end
+
+    # Determines the maximum level in the mailbox tree
+    def get_max_level
+      if has_children?
+        @children.values.map { |child| child.get_max_level }.max
+      else
+        level
+      end
+    end
+
     def full_name
       imap_mailbox_list&.name
     end
@@ -33,9 +66,16 @@ module Imapcli
     end
 
     # Adds a sub mailbox designated by the +name+ of a Net::IMAP::MailboxList.
-    def add_mailbox(imap_mailbox_list, options = {})
+    def add_mailbox(imap_mailbox_list)
       return unless imap_mailbox_list&.name&.length > 0
-      recursive_add(0, imap_mailbox_list, imap_mailbox_list.name, options)
+      recursive_add(0, imap_mailbox_list, imap_mailbox_list.name)
+    end
+
+    # Returns true if this mailbox contains a given other mailbox.
+    def contains?(other_mailbox)
+      @children.values.any? do |child|
+        child == other_mailbox || child.contains?(other_mailbox)
+      end
     end
 
     # Attempts to locate and retrieve a sub mailbox.
@@ -45,7 +85,8 @@ module Imapcli
     def find_sub_mailbox(relative_name, delimiter)
       if relative_name
         sub_mailbox_name, subs_subs = relative_name.split(delimiter, 2)
-        if sub_mailbox = @children[sub_mailbox_name]
+        key = normalize_key(sub_mailbox_name, level)
+        if sub_mailbox = @children[key]
           sub_mailbox.find_sub_mailbox(subs_subs, delimiter)
         else
           nil # no matching sub mailbox found, stop searching the tree
@@ -55,21 +96,49 @@ module Imapcli
       end
     end
 
-    # Collects statistics for this mailbox.
+    # Collects statistics for this mailbox and the subordinate mailboxes up to
+    # a given level.
     #
-    # +connection+ must be a Net::IMAP object
-    def collect_stats(client)
+    # If level is nil, all sub mailboxes are analyzed as well.
+    #
+    # If a block is given, it is called with the Imapcli::Stats object for this
+    # mailbox.
+    def collect_stats(client, max_level = nil)
+      return if @stats
       if full_name # proceed only if this is a mailbox of its own
-        @stats = client.examine(full_name)
+        @stats = Stats.new(client.message_sizes(full_name))
+      end
+      yield @stats if block_given?
+      if max_level.nil? || level < max_level
+        @children.values.each do |child|
+          child.collect_stats(client, max_level) { |child_stats| yield child_stats}
+        end
+      end
+    end
+
+    # Converts the mailbox tree to a flat list.
+    #
+    # Mailbox objects that do not represent IMAP mailboxes (such as the root
+    # mailbox) are not included.
+    def to_list(max_level = nil)
+      me = is_imap_mailbox? ? [self] : []
+      if max_level.nil? || level < max_level
+        @children.values.inject(me) do |ary, child|
+          ary + child.to_list(max_level)
+        end.sort_by { |e| e.full_name }
+      else
+        me
       end
     end
 
-    # Collects statistics for this mailbox and all of its children.
+    # Consolidates a list of mailboxes: If a mailbox is a sub-mailbox of another
+    # one, the mailbox is removed from the list.
     #
-    # +connection+ must be a Net::IMAP object
-    def collect_stats_recursively(connection)
-      collect_stats(connection)
-      @children.values.each { |child| child.collect_stats_recursively(connection) }
+    # @param [Array] list of mailboxes
+    def self.consolidate(list)
+      list.reject do |mailbox|
+        list.any? { |parent| parent.contains? mailbox }
+      end.uniq
     end
 
     protected
@@ -82,15 +151,11 @@ module Imapcli
       @name = name
     end
 
-    def recursive_add(level, imap_mailbox_list, relative_name = nil, options = {})
+    def recursive_add(level, imap_mailbox_list, relative_name = nil)
       delimiter = options[:delimiter] || imap_mailbox_list.delim
       if relative_name
         sub_mailbox_name, subs_subs = relative_name.split(delimiter, 2)
-        if options[:case_insensitive] || (level == 0 && relative_name.upcase == 'INBOX')
-          key = sub_mailbox_name.upcase
-        else
-          key = sub_mailbox_name
-        end
+        key = normalize_key(sub_mailbox_name, level)
         # Create a new mailbox if there does not exist one by the name
         unless sub_mailbox = @children[key]
           sub_mailbox = Mailbox.new
@@ -98,11 +163,21 @@ module Imapcli
           sub_mailbox.name = sub_mailbox_name
           @children[key] = sub_mailbox
         end
-        sub_mailbox.recursive_add(level + 1, imap_mailbox_list, subs_subs, options)
+        sub_mailbox.recursive_add(level + 1, imap_mailbox_list, subs_subs)
       else # no more sub mailboxes: we've reached the last of the children
         @imap_mailbox_list = imap_mailbox_list
         self
       end
     end
+
+    # Normalizes a mailbox name for use as the key in the children hash.
+    def normalize_key(key, level)
+      if options[:case_insensitive] || (level == 0 && key.upcase == 'INBOX')
+        key.upcase
+      else
+        key
+      end
+    end
+
   end
 end