maid 0.1.2 → 0.1.3.beta.1

data/lib/maid/numeric_extensions.rb

@@ -1,89 +1,127 @@
-# From https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/numeric/time.rb, with some modifications since active_support ruins Logger by overriding its functionality.
 module Maid::NumericExtensions
-  # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years.
-  #
-  # These methods use Time#advance for precise date calculations when using from_now, ago, etc.
-  # as well as adding or subtracting their results from a Time object. For example:
-  #
-  #   # equivalent to Time.now.advance(:months => 1)
-  #   1.month.from_now
-  #
-  #   # equivalent to Time.now.advance(:years => 2)
-  #   2.years.from_now
-  #
-  #   # equivalent to Time.now.advance(:months => 4, :years => 5)
-  #   (4.months + 5.years).from_now
-  #
-  # While these methods provide precise calculation when used as in the examples above, care
-  # should be taken to note that this is not true if the result of `months', `years', etc is
-  # converted before use:
-  #
-  #   # equivalent to 30.days.to_i.from_now
-  #   1.month.to_i.from_now
-  #
-  #   # equivalent to 365.25.days.to_f.from_now
-  #   1.year.to_f.from_now
-  #
-  # In such cases, Ruby's core
-  # Date[http://stdlib.rubyonrails.org/libdoc/date/rdoc/index.html] and
-  # Time[http://stdlib.rubyonrails.org/libdoc/time/rdoc/index.html] should be used for precision
-  # date and time arithmetic
-  def seconds
-    self
-  end
-  alias :second :seconds
+  # From https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/numeric/time.rb, with some modifications since active_support ruins Logger by overriding its functionality.
+  module Time
+    # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years.
+    #
+    # These methods use Time#advance for precise date calculations when using from_now, ago, etc.
+    # as well as adding or subtracting their results from a Time object. For example:
+    #
+    #   # equivalent to Time.now.advance(:months => 1)
+    #   1.month.from_now
+    #
+    #   # equivalent to Time.now.advance(:years => 2)
+    #   2.years.from_now
+    #
+    #   # equivalent to Time.now.advance(:months => 4, :years => 5)
+    #   (4.months + 5.years).from_now
+    #
+    # While these methods provide precise calculation when used as in the examples above, care
+    # should be taken to note that this is not true if the result of `months', `years', etc is
+    # converted before use:
+    #
+    #   # equivalent to 30.days.to_i.from_now
+    #   1.month.to_i.from_now
+    #
+    #   # equivalent to 365.25.days.to_f.from_now
+    #   1.year.to_f.from_now
+    #
+    # In such cases, Ruby's core
+    # Date[http://stdlib.rubyonrails.org/libdoc/date/rdoc/index.html] and
+    # Time[http://stdlib.rubyonrails.org/libdoc/time/rdoc/index.html] should be used for precision
+    # date and time arithmetic
+    def seconds
+      self
+    end
+    alias :second :seconds
 
-  def minutes
-    self * 60
-  end
-  alias :minute :minutes
+    def minutes
+      self * 60
+    end
+    alias :minute :minutes
 
-  def hours
-    self * 3600
-  end
-  alias :hour :hours
+    def hours
+      self * 3600
+    end
+    alias :hour :hours
 
-  def days
-    self * 24.hours
-  end
-  alias :day :days
+    def days
+      self * 24.hours
+    end
+    alias :day :days
 
-  def weeks
-    self * 7.days
-  end
-  alias :week :weeks
+    def weeks
+      self * 7.days
+    end
+    alias :week :weeks
 
-  def fortnights
-    self * 2.weeks
-  end
-  alias :fortnight :fortnights
+    def fortnights
+      self * 2.weeks
+    end
+    alias :fortnight :fortnights
 
-  # Reads best without arguments:  10.minutes.ago
-  def ago(time = ::Time.now)
-    time - self
-  end
+    # Reads best without arguments:  10.minutes.ago
+    def ago(time = ::Time.now)
+      time - self
+    end
+
+    # Reads best with argument:  10.minutes.until(time)
+    alias :until :ago
+
+    # Reads best with argument:  10.minutes.since(time)
+    def since(time = ::Time.now)
+      time + self
+    end
+
+    # Reads best without arguments:  10.minutes.from_now
+    alias :from_now :since
+
+    ######################
+    ### Maid additions ###
+    ######################
 
-  # Reads best with argument:  10.minutes.until(time)
-  alias :until :ago
+    # TODO find a better place for these to live?
 
-  # Reads best with argument:  10.minutes.since(time)
-  def since(time = ::Time.now)
-    time + self
+    # Reads well in a case like:
+    #
+    #   1.week.since? accessed_at('filename')
+    def since?(other_time)
+      other_time < self.ago
+    end
   end
+  module SizeToKb
+    # Enables Computer disk size conversion into kilobytes.
+    #
+    # Can convert megabytes, gigabytes and terabytes.
+    # Handles full name (megabyte), plural (megabytes) and symobl (mb/mB).
+    #
+    #   1.megabyte = 1024 kilobytes
 
-  # Reads best without arguments:  10.minutes.from_now
-  alias :from_now :since
+    def kb
+      self
+    end
+    alias :kilobytes :kb
+    alias :kilobyte :kb
+    alias :kB :kb
 
-  ######################
-  ### Maid additions ###
-  ######################
+    def mb
+      self * 1024 ** 1
+    end
+    alias :megabytes :mb
+    alias :megabyte :mb
+    alias :mB :mb
 
-  # TODO find a better place for these to live?
+    def gb
+      self * 1024 ** 2
+    end
+    alias :gigabytes :gb
+    alias :gigabyte :gb
+    alias :gB :gb
 
-  # Reads well in a case like:
-  #
-  #   1.week.since? last_accessed('filename')
-  def since?(other_time)
-    other_time < self.ago
+    def tb
+      self * 1024 ** 3
+    end
+    alias :terabytes :tb
+    alias :terabyte :tb
+    alias :tB :tb
   end
 end

data/lib/maid/platform.rb

@@ -0,0 +1,17 @@
+require 'rbconfig'
+
+module Maid::Platform
+  class << self
+    def host_os
+      RbConfig::CONFIG['host_os']
+    end
+
+    def linux?
+      !!(host_os =~ /linux/i)
+    end
+
+    def osx?
+      !!(host_os =~ /darwin/i)
+    end
+  end
+end

data/lib/maid/rules.sample.rb

@@ -1,62 +1,71 @@
-# Sample Maid rules file -- a sampling to get you started.
+# Sample Maid rules file -- some ideas to get you started.
 #
-# To use, remove ".sample" from the filename.  Test using:
+# To use, remove ".sample" from the filename, and modify as desired.  Test using:
 #
-#     maid -n
+#     maid clean -n
 #
-# For more help on Maid:
+# **NOTE:** It's recommended you just use this as a template; if you run these rules on your machine without knowing what they do, you might run into unwanted results!
+#
+# Don't forget, it's just Ruby!  You can define custom methods and use them below:
+# 
+#     def magic(*)
+#       # ...
+#     end
+# 
+# If you come up with some cool tools of your own, please send me a pull request on GitHub!
 #
-#   * Run `maid help`
-#   * Read the README at http://github.com/benjaminoakes/maid
-#   * For more DSL helper methods, please see the documentation of Maid::Tools at http://rubydoc.info/gems/maid/0.1.0/Maid/Tools
-#   * Come up with some cool tools of your own?  Fork, make your changes, and send me a pull request on GitHub!
-#   * Ask me a question over email (hello@benjaminoakes.com) or Twitter (@benjaminoakes)
+# For more help on Maid:
 #
+# * Run `maid help`
+# * Read the README, tutorial, and documentation at https://github.com/benjaminoakes/maid#maid
+# * Ask me a question over email (hello@benjaminoakes.com) or Twitter (@benjaminoakes)
+
 Maid.rules do
-  # NOTE: Currently, only Mac OS X supports `duration_s`.
-  rule 'MP3s likely to be music' do
-    dir('~/Downloads/*.mp3').each do |path|
-      if duration_s(path) > 30.0
-        move(path, '~/Music/iTunes/iTunes Media/Automatically Add to iTunes/')
-      end
-    end
-  end
-  
-  # NOTE: Currently, only Mac OS X supports `downloaded_from`.
-  rule 'Old files downloaded while developing/testing' do
-    dir('~/Downloads/*').each do |path|
-      if downloaded_from(path).any? {|u| u.match 'http://localhost' || u.match('http://staging.yourcompany.com') } && 1.week.since?(last_accessed(path))
-        trash(path)
-      end
-    end
-  end
+  # **NOTE:** It's recommended you just use this as a template; if you run these rules on your machine without knowing what they do, you might run into unwanted results!
 
   rule 'Linux ISOs, etc' do
-    dir('~/Downloads/*.iso').each { |p| trash p }
+    trash(dir('~/Downloads/*.iso'))
   end
 
   rule 'Linux applications in Debian packages' do
-    dir('~/Downloads/*.deb').each { |p| trash p }
+    trash(dir('~/Downloads/*.deb'))
   end
 
   rule 'Mac OS X applications in disk images' do
-    dir('~/Downloads/*.dmg').each { |p| trash p }
+    trash(dir('~/Downloads/*.dmg'))
   end
 
   rule 'Mac OS X applications in zip files' do
-    dir('~/Downloads/*.zip').select do |path|
-      candidates = zipfile_contents(path)
-      candidates.any? { |c| c.match(/\.app$/) }
-    end.each { |p| trash p }
+    found = dir('~/Downloads/*.zip').select { |path|
+      zipfile_contents(path).any? { |c| c.match(/\.app$/) }
+    }
+
+    trash(found)
   end
 
   rule 'Misc Screenshots' do
     dir('~/Desktop/Screen shot *').each do |path|
-      if 1.week.since?(last_accessed(path))
+      if 1.week.since?(accessed_at(path))
         move(path, '~/Documents/Misc Screenshots/')
       end
     end
   end
 
-  # Add your own rules here.
+  # NOTE: Currently, only Mac OS X supports `duration_s`.
+  rule 'MP3s likely to be music' do
+    dir('~/Downloads/*.mp3').each do |path|
+      if duration_s(path) > 30.0
+        move(path, '~/Music/iTunes/iTunes Media/Automatically Add to iTunes/')
+      end
+    end
+  end
+  
+  # NOTE: Currently, only Mac OS X supports `downloaded_from`.
+  rule 'Old files downloaded while developing/testing' do
+    dir('~/Downloads/*').each do |path|
+      if downloaded_from(path).any? { |u| u.match('http://localhost') || u.match('http://staging.yourcompany.com') } && 1.week.since?(accessed_at(path))
+        trash(path)
+      end
+    end
+  end
 end

data/lib/maid/tools.rb

@@ -8,6 +8,8 @@ require 'time'
 #
 # Some methods are not available on all platforms.  An <tt>ArgumentError</tt> is raised when a command is not available.  See tags: [Mac OS X]
 module Maid::Tools
+  include Deprecated
+
   # Move from <tt>from</tt> to <tt>to</tt>.
   #
   # The path is not moved if a file already exists at the destination with the same name.  A warning is logged instead.
@@ -15,53 +17,139 @@ module Maid::Tools
   # This method delegates to FileUtils.  The instance-level <tt>file_options</tt> hash is passed to control the <tt>:noop</tt> option.
   #
   #   move('~/Downloads/foo.zip', '~/Archive/Software/Mac OS X/')
-  def move(from, to)
-    from = File.expand_path(from)
-    to = File.expand_path(to)
-    target = File.join(to, File.basename(from))
-
-    unless File.exist?(target)
-      @logger.info "mv #{from.inspect} #{to.inspect}"
-      FileUtils.mv(from, to, @file_options)
-    else
-      @logger.warn "skipping #{from.inspect} because #{target.inspect} already exists"
+  # 
+  # This method can handle multiple from paths.
+  #
+  #   move(['~/Downloads/foo.zip', '~/Downloads/bar.zip'], '~/Archive/Software/Mac OS X/')
+  #   move(dir('~/Downloads/*.zip'), '~/Archive/Software/Mac OS X/')
+  def move(froms, to)
+    Array(froms).each do |from|
+      from = File.expand_path(from)
+      to = File.expand_path(to)
+      target = File.join(to, File.basename(from))
+
+      unless File.exist?(target)
+        @logger.info "mv #{from.inspect} #{to.inspect}"
+        FileUtils.mv(from, to, @file_options)
+      else
+        @logger.warn "skipping #{from.inspect} because #{target.inspect} already exists"
+      end
     end
   end
 
   # Move the given path to the trash (as set by <tt>trash_path</tt>).
   #
   # The path is moved if a file already exists in the trash with the same name.  However, the current date and time is appended to the filename.
+  # 
+  # Note: the OS native "restore" or "put back" functionality for trashed files is not currently supported.  However, they can be restored manually, and the Maid log can help assist with this.
+  # 
+  # Options:
+  #
+  # - :remove_over => Fixnum (e.g. 1.gigabyte, 1024.megabytes)
+  #     Remove files over the given size rather than moving to the trash.
+  #     See also Maid::NumericExtensions::SizeToKb
   #
   #   trash('~/Downloads/foo.zip')
-  def trash(path)
-    target = File.join(@trash_path, File.basename(path))
-    safe_trash_path = File.join(@trash_path, "#{File.basename(path)} #{Time.now.strftime('%Y-%m-%d-%H-%M-%S')}")
+  # 
+  # This method can also handle multiple paths.
+  #
+  #   trash(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
+  #   trash(dir('~/Downloads/*.zip'))
+  def trash(paths, options = {})
+    # ## Implementation Notes
+    #
+    # Trashing files correctly is surprisingly hard.  What Maid ends up doing is one the easiest, most foolproof solutions:  moving the file.
+    #
+    # Unfortunately, that means it's not possile to restore files automatically in OSX or Ubuntu.  The previous location of the file is lost.
+    #
+    # OSX support depends on AppleScript or would require a not-yet-written C extension to interface with the OS.  The AppleScript solution is less than ideal: the user has to be logged in, Finder has to be running, and it makes the "trash can sound" every time a file is moved.
+    #
+    # Ubuntu makes it easy to implement, and there's a Python library for doing so (see `trash-cli`).  However, there's not a Ruby equivalent yet.
 
-    if File.exist?(target)
-      move(path, safe_trash_path)
-    else
-      move(path, @trash_path)
+    Array(paths).each do |path|
+      target = File.join(@trash_path, File.basename(path))
+      safe_trash_path = File.join(@trash_path, "#{File.basename(path)} #{Time.now.strftime('%Y-%m-%d-%H-%M-%S')}")
+
+      if options[:remove_over] &&
+          File.exist?(path) &&
+          disk_usage(path) > options[:remove_over]
+        remove(path)
+      end
+
+      if File.exist?(path)
+        if File.exist?(target)
+          move(path, safe_trash_path)
+        else
+          move(path, @trash_path)
+        end
+      end
     end
   end
 
-  # Give all files matching the given glob.
+  # Remove the given path recursively.
+  # 
+  # Options:
   #
-  # Delgates to Dir.
+  # - :force => boolean
+  # - :secure => boolean (See FileUtils.remove_entry_secure for further details)
+  #
+  #   remove('~/Downloads/foo.zip')
+  #
+  # This method can handle multiple remove paths.
+  #
+  #   remove(['~/Downloads/foo.zip', '~/Downloads/bar.zip'])
+  #   remove(dir('~/Downloads/*.zip'))
+  def remove(paths, options = {})
+    Array(paths).each do |path|
+      path = File.expand_path(path)
+      options = @file_options.merge(options)
+
+      @logger.info "Removing #{path.inspect}"
+      FileUtils.rm_r(path,options)
+    end
+  end
+
+  # Give all files matching the given glob.
   #
   #   dir('~/Downloads/*.zip')
   def dir(glob)
     Dir[File.expand_path(glob)]
   end
 
+  # Creates a directory and all its parent directories.
+  #
+  # Options:
+  #
+  # - :mode,  the symbolic and absolute mode both can be used.
+  #           eg. 0700, 'u=wr,go=rr'
+  #
+  #   mkdir('~/Downloads/Music/Pink.Floyd/', :mode => 0644)
+  def mkdir(path, options = {})
+    FileUtils.mkdir_p(File.expand_path(path), options)
+  end
+
   # Find matching files, akin to the Unix utility <tt>find</tt>.
   #
-  # Delegates to Find.find.
+  # If no block is given, it will return an array.
+  #
+  #   find '~/Downloads/' # => [...]
+  #
+  # or delegates to Find.find.
   #
   #   find '~/Downloads/' do |path|
   #     # ...
   #   end
+  #
   def find(path, &block)
-    Find.find(File.expand_path(path), &block)
+    expanded_path = File.expand_path(path)
+
+    if block.nil?
+      files = []
+      Find.find(expanded_path) { |file_path| files << file_path }
+      files
+    else
+      Find.find(expanded_path, &block)
+    end
   end
 
   # [Mac OS X] Use Spotlight to locate all files matching the given filename.
@@ -99,27 +187,93 @@ module Maid::Tools
 
   # Calculate disk usage of a given path.
   #
+  # FIXME: This reports in kilobytes, but should probably report in bytes.
+  #
   #   disk_usage('foo.zip') # => 136
   def disk_usage(path)
     raw = cmd("du -s #{path.inspect}")
-    raw.split(/\s+/).first.to_i
+    usage_kb = raw.split(/\s+/).first.to_i
+   
+    if usage_kb.zero?
+      raise "Stopping pessimistically because of unexpected value from du (#{raw.inspect})"
+    else
+      usage_kb
+    end
+  end
+
+  # In Unix speak, "ctime".
+  #
+  #   created_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  def created_at(path)
+    File.ctime(File.expand_path(path))
   end
 
   # In Unix speak, "atime".
   #
-  #   last_accessed('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
-  def last_accessed(path)
+  #   accessed_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  def accessed_at(path)
     File.atime(File.expand_path(path))
   end
 
+  alias :last_accessed :accessed_at
+  deprecated :last_accessed, :accessed_at
+
+  # In Unix speak, "mtime".
+  #
+  #   modified_at('foo.zip') # => Sat Apr 09 10:50:01 -0400 2011
+  def modified_at(path)
+    File.mtime(File.expand_path(path))
+  end
+
   # Pulls and pushes the given git repository.
   #
-  # You might also be interested in SparkleShare (http://sparkleshare.org/), a great git-based file syncronization project.
+  # Since this is deprecated, you might also be interested in SparkleShare (http://sparkleshare.org/), a great git-based file syncronization project.
   #
   #   git_piston('~/code/projectname')
+  #
+  # @deprecated
   def git_piston(path)
     full_path = File.expand_path(path)
     stdout = cmd("cd #{full_path.inspect} && git pull && git push 2>&1")
     @logger.info "Fired git piston on #{full_path.inspect}.  STDOUT:\n\n#{stdout}"
   end
+
+  deprecated :git_piston, 'SparkleShare (http://sparkleshare.org/)'
+
+  # [Rsync] Simple sync of two files/folders using rsync.
+  #
+  # See rsync man page for a detailed description.
+  # 
+  # Options:
+  #
+  # - :delete => boolean
+  # - :verbose => boolean
+  # - :archive => boolean (default true)
+  # - :update => boolean (default true)
+  # - :exclude => string EXE :exclude => ".git" or :exclude => [".git", ".rvmrc"]
+  # - :prune_empty => boolean
+  #
+  #   sync('~/music', '/backup/music')
+  def sync(from, to, options = {})
+    # expand path removes trailing slash
+    # cannot use str[-1] due to ruby 1.8.7 restriction
+    from = File.expand_path(from) + (from.end_with?('/') ? '/' : '')
+    to = File.expand_path(to) + (to.end_with?('/') ? '/' : '')
+    # default options
+    options = { :archive => true, :update => true }.merge(options)
+    ops = []
+    ops << '-a' if options[:archive]
+    ops << '-v' if options[:verbose]
+    ops << '-u' if options[:update]
+    ops << '-m' if options[:prune_empty]
+    ops << '-n' if @file_options[:noop]
+
+    Array(options[:exclude]).each do |path|
+      ops << "--exclude=#{path.inspect}"
+    end
+
+    ops << '--delete' if options[:delete]
+    stdout = cmd("rsync #{ops.join(' ')} #{from.inspect} #{to.inspect} 2>&1")
+    @logger.info "Fired sync from #{from.inspect} to #{to.inspect}.  STDOUT:\n\n#{stdout}"
+  end
 end