X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=lib%2Fcommon%2Frunner.rb;h=b6fa2e86cafb0d5131bcc687f9edd7e387063814;hp=32f2b3ecf8bb0354408fb7fbe46596155e2baf3a;hb=ef77e919fa61bb5ba7924d49a171dc3a05410a33;hpb=483d14dc8228a81d12fb109d3ed6510e2d2b03c1;ds=sidebyside

diff --git a/lib/common/runner.rb b/lib/common/runner.rb
index 32f2b3e..b6fa2e8 100644
--- a/lib/common/runner.rb
+++ b/lib/common/runner.rb
@@ -1,9 +1,70 @@
+# Methods inherited by the various runner classes ({PruneRunner},
+# {MvRunner}, {RmRunner}).
+#
 module Runner
 
-  def run(plugin, targets)
+
+  # The main thing a runner does is <tt>run()</tt>. Each runner will
+  # actually take a different number of arguments, so their
+  # <tt>run()</tt> signatures will differ. This stub is only here to
+  # let you know that it needs to be implemented.
+  #
+  # @param args [Array<Object>] whatever arguments the real implementation
+  #   would take.
+  #
+  def run(*args)
     raise NotImplementedError
   end
 
+
+  # When we're describing a user or domain, we often want to output
+  # some additional description of it. But then, sometimes that
+  # additional description is pointless, like when it's exactly the
+  # same as the username that we're already outputting. This function
+  # determines whether or not *desc* is pointless for *target*.
+  #
+  # @param target [User,Domain] the user or domain described by *desc*.
+  #
+  # @param desc [String] a string description of *target*.
+  #
+  # @return [Boolean] true if *desc* is a pointless description of
+  #   *target* and false otherwise.
+  #
+  def pointless?(target, desc)
+    return (desc.nil? or desc.empty? or desc == target.to_s())
+  end
+
+
+  # If *desc* is not a pointless description of *target*, return the
+  # string representation of *target* followed by *desc* in
+  # parentheses. If *desc* is pointless, we return only the string
+  # representation of *target*
+  #
+  # @param target [User,Domain] the user or domain we want to describe
+  #   as a string.
+  #
+  # @param desc [String] a string description of *target*.
+  #
+  # @return [String] the string representation of *target*, possibly
+  #   followed by the non-pointless description *desc*.
+  #
+  def add_description(target, desc)
+    if pointless?(target, desc)
+      return target.to_s()
+    else
+      return target.to_s() + " (#{desc})"
+    end
+  end
+
+
+  # Report a message from the given *plugin*. All this does is prefix
+  # the message with the plugin name and then print it to stdout.
+  #
+  # @param plugin [Object] t plugin object that generated the message
+  #   we're reporting.
+  #
+  # @param msg [String] the message to report.
+  #
   def report(plugin, msg)
     print "#{plugin.class.to_s()} - "
     puts msg