maid 0.1.2 → 0.1.3.beta.1

data/.gitignore

@@ -1,4 +1,6 @@
 *.gem
 .bundle
 .roboconf.sh
+.vagrant
+Gemfile.lock
 doc/*

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--profile
+-fs

data/.travis.yml

@@ -1,3 +1,4 @@
 rvm:
   - 1.8.7
   - 1.9.2
+  - 1.9.3

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -1,137 +1,174 @@
 # Maid
 
-[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=benjaminoakes&url=https://github.com/benjaminoakes/maid&title=maid&language=en_GB&tags=github&category=software)
-
 Be lazy!  Let Maid clean up after you, based on rules you define.
 
+[Installation](https://github.com/benjaminoakes/maid#installation) | [Tutorial](https://github.com/benjaminoakes/maid#tutorial) | [Documentation](http://rubydoc.info/gems/maid/Maid/Tools)
+
 Maid keeps files from sitting around too long, untouched.  Many of the downloads and other files you collect can easily be categorized and handled appropriately by rules you define.  Let the maid in your computer take care of the easy stuff, so you can spend more of your time on what matters.
 
 Think of it like the email filters you might already have, but for files.  Worried about things happening that you don't expect?  Maid doesn't overwrite files and actions are logged so you can tell what happened.
 
 Maid is inspired by the Mac OS X shareware program [Hazel](http://www.noodlesoft.com/hazel.php).  This tool was created on Mac OS X 10.6, but should be generally portable to other systems.  (Some of the more advanced features such as `downloaded_from` require OS X, however.)
 
-Your rules are defined in Ruby, so easy rules are easy and difficult rules are possible.
+Your rules are defined in Ruby, so easy rules are easy and difficult rules are possible.  This also makes Maid a great general-purpose **advanced file renaming tool**.
+
+## Want to help?
+
+### For Users
+
+[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=benjaminoakes&url=https://github.com/benjaminoakes/maid&title=maid&language=en_GB&tags=github&category=software)
+
+* Participate in [beta testing](https://github.com/benjaminoakes/maid/issues/10)
+* [Report an issue](https://github.com/benjaminoakes/maid/issues) (bug or feature request)
+* Read through the [wiki](https://github.com/benjaminoakes/maid/wiki)
+* Even just [share a link to Maid](https://twitter.com/intent/tweet?related=benjaminoakes&text=Be+lazy%21+Let+Maid+clean+up+after+you%2C+based+on+rules+you+define&url=https%3A%2F%2Fgithub.com%2Fbenjaminoakes%2Fmaid) :)
 
-![Still Maintained?](http://stillmaintained.com/benjaminoakes/maid.png)
-[![Build Status](http://travis-ci.org/benjaminoakes/maid.png)](http://travis-ci.org/benjaminoakes/maid)
+### For Developers
+
+[![Build Status](https://secure.travis-ci.org/benjaminoakes/maid.png)](http://travis-ci.org/benjaminoakes/maid)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/benjaminoakes/maid)
+
+* Complete an issue (easy ones [are labelled](https://github.com/benjaminoakes/maid/issues?labels=difficulty-1&page=1&state=open), and issues for future releases are [grouped by milestone](https://github.com/benjaminoakes/maid/issues/milestones)).
+* **Working on an issue?** Please leave a comment so others know.
+* See the [Contributing guide](https://github.com/benjaminoakes/maid/wiki/Contributing)
 
 ## Buzz
 
-* [OneThingWell: Maid](http://onethingwell.org/post/30455088809/maid) - August 29th, 2012
-* [Maid – Paresseux mais ordonné!](http://korben.info/maid-ruby-script.html) (FR) - August 30th, 2012
+[![OneThingWell Logo](https://raw.github.com/benjaminoakes/maid/master/resources/OneThingWell.png)](http://onethingwell.org/)
 
-<blockquote class="twitter-tweet"><p>gem install maid するとメイドさんが手に入るので Ruby 便利．<a href="https://t.co/gH6XgWJH" title="https://github.com/benjaminoakes/maid">github.com/benjaminoakes/…</a></p>&mdash; りんだん（実際犬） (@Linda_pp) <a href="https://twitter.com/Linda_pp/status/241588990166310912" data-datetime="2012-08-31T17:31:18+00:00">August 31, 2012</a></blockquote>
-<script src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
+[Maid](http://onethingwell.org/post/30455088809/maid) - August 29th, 2012
 
-<blockquote class="twitter-tweet"><p><a href="https://t.co/YnOzpwRV" title="https://github.com/benjaminoakes/maid">github.com/benjaminoakes/…</a> 這個拿來整理檔案似乎不錯.... <a href="http://t.co/rUt2f258" title="http://fb.me/1CxgLtmyq">fb.me/1CxgLtmyq</a></p>&mdash; xdite (@xdite) <a href="https://twitter.com/xdite/status/242335478626521088" data-datetime="2012-09-02T18:57:35+00:00">September 2, 2012</a></blockquote>
-<script src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
+[![Ruby5 Logo](https://raw.github.com/benjaminoakes/maid/master/resources/ruby5.gif)](http://ruby5.envylabs.com/)
 
-## Is it any good?
+[Podcast #302](http://ruby5.envylabs.com/episodes/306-episode-302-august-31st-2012) (at 2:45) - August 31st, 2012
 
-Yes.
+[More...](https://github.com/benjaminoakes/maid/wiki/In-the-Media)
 
 ## Installation
 
-Maid supports OS X and Ubuntu.  Other Unix-like operating systems may work, but are not officially supported.  (Contributions are welcome, however.)
+[![Download for Ubuntu](https://github.com/benjaminoakes/maid/raw/master/resources/download-for-ubuntu.png)](https://github.com/benjaminoakes/maid/issues/3)
 
-### OS X
+#### Offically supported:
 
-Open a terminal and run:
+* **OS:** Mac OS X, Ubuntu
+* **Ruby:** 1.8.7, 1.9.3 (preferred)
 
-    gem install maid
+(Other Ruby versions and OSes may work, but are not officially supported.  Contributions are welcome, however.)
 
-If you want to install the executable for all users, you may need to give root access:
+### Manual Installation
 
-    sudo gem install maid
+First, you need Ruby:
 
-### Ubuntu
+* **Mac OS X:** Ruby 1.8.7 comes preinstalled.
+* **Ubuntu:** Ruby is not preinstalled.  To install Ruby 1.9.3: `sudo apt-get install ruby1.9.1 # (sic)`  ([Interested in a package?](https://github.com/benjaminoakes/maid/issues/3))
 
-#### Ubuntu Software Center
+Then, you can install via RubyGems.  Open a terminal and run:
 
-[![Download for Ubuntu](https://github.com/benjaminoakes/maid/raw/master/resources/download-for-ubuntu.png)](https://github.com/benjaminoakes/maid/issues/3)
+    sudo gem install maid
 
-#### Manually
+At a later date, you can update by running:
 
-You'll need Ruby and RubyGems installed.  Open a terminal and run:
+    sudo gem update maid
 
-    sudo apt-get install ruby rubygems
+If you decide you don't want Maid installed anymore, remove it:
 
-You might also need to add the RubyGems `bin` directory to your `$PATH`.  For example, you might need to add something like this to your `~/.bashrc`:
+    sudo gem uninstall maid
 
-    export PATH="/var/lib/gems/1.8/bin:$PATH"
-    
-Then install Maid itself:
-    
-    gem install maid
+**NOTE:** This does not remove any files under `~/.maid` or crontab entries.  Please remove them at your convenience.
 
-If you want to install the executable for all users, you may need to give root access:
+### Troubleshooting
 
-    sudo gem install maid
+* Having multiple Ruby versions installed can confuse things.  If you're a Ruby developer, you may prefer to just `gem install maid` with your preferred setup.  Ruby 1.9.3 is recommended.
+* Older packages of Ruby for Ubuntu may not automatically add the RubyGems `bin` directory to your `$PATH`.  Double check your settings.
 
 ## Tutorial
 
-Maid rules are defined using Ruby, with some common operations made easier with a small DSL (Domain Specific Language).  Here's a sample:
+In a nutshell, Maid uses "rules" to define how files are handled.  Once you have rules defined, you can either test what cleaning would do (`maid clean -n`) or actually clean (`maid clean`).
 
-    Maid.rules do
-      rule 'Old files downloaded while developing/testing' do
-        dir('~/Downloads/*').each do |path|
-          if downloaded_from(path).any? {|u| u.match 'http://localhost'} && 1.week.since?(last_accessed(path))
-            trash(path)
-          end
-        end
+To generate a [sample rules file](https://github.com/benjaminoakes/maid/blob/master/lib/maid/rules.sample.rb), run:
+
+```bash
+maid sample
+```
+
+Maid rules are defined using Ruby, with some common operations made easier with a small DSL (Domain Specific Language).
+
+For example, this is a rule:
+
+```ruby
+Maid.rules do
+  rule 'Old files downloaded while developing/testing' do
+    dir('~/Downloads/*').each do |path|
+      if downloaded_from(path).any? {|u| u.match 'http://localhost'} && 1.week.since?(last_accessed(path))
+        trash(path)
       end
     end
+  end
+end
+```
+
+If you're new to Ruby and would prefer a more traditional `for` loop, you can also do this:
+
+```ruby
+Maid.rules do
+  rule 'My rule' do
+    for path in dir('~/Downloads/*')
+      # ...
+    end
+  end
+end
+```
 
 Before you start running your rules, you'll likely want to be able to test them.  Here's how:
 
-    # No actions are taken; you just see what would happen with your rules as defined.
-    maid --dry-run
-    maid --noop
-    maid -n
+```bash
+# No actions are taken; you just see what would happen with your rules as defined.
+maid clean --dry-run # Synonyms: -n, --noop
+```
 
 To run your rules on demand, you can run `maid` manually:
 
-    maid                    # Run the rules at ~/.maid/rules.rb, logging to ~/.maid/maid.log
-    maid -r some_rules.rb   # Run the rules in the file 'some_rules.rb', logging to ~/.maid/maid.log
+```bash
+maid clean                    # Run the rules at ~/.maid/rules.rb, logging to ~/.maid/maid.log
+maid clean -r some_rules.rb   # Run the rules in the file 'some_rules.rb', logging to ~/.maid/maid.log
+```
 
 So, for example, if this is `some_rules.rb`:
 
-    Maid.rules do
-      rule 'downloaded PDF books' do
-        dir('~/Downloads/*.pdf').each do |path|
-          move(path, '~/Books')
-        end
-      end
-    end
+```ruby
+Maid.rules do
+  rule 'downloaded PDF books' do
+    move(dir('~/Downloads/*.pdf'), '~/Books')
+  end
+end
+```
 
-This is the command to test, as well as some sample output:
+Then, this is the command to test, as well as some sample output:
 
-    $ maid -nr some_rules.rb
+    $ maid clean -nr some_rules.rb
     Rule: downloaded PDF books
     mv "/Users/ben/Downloads/book.pdf" "/Users/ben/Books/"
     mv "/Users/ben/Downloads/issue12.pdf" "/Users/ben/Books/"
     mv "/Users/ben/Downloads/spring2011newsletter.pdf" "/Users/ben/Books/"
 
-For more DSL helper methods, please see the documentation of [Maid::Tools](http://rubydoc.info/gems/maid/0.1.0/Maid/Tools).
+For help with command line usage, run `maid help`.  For more DSL helper methods, please see the documentation of [Maid::Tools](http://rubydoc.info/gems/maid/Maid/Tools).
 
 ### Automation
 
 Once you get a hang for what you can do with Maid, let it do its stuff automatically throughout the day.  You'll find your computer stays a little tidier with as you teach it how to handle your common files.
 
-To do this, edit your crontab in your tool of choice and have it invoke the `maid` command.  The `--silent` option is provided to keep this from emailing you, if desired.  A log of the actions taken is kept at `~/.maid/maid.log`.
+To do this, edit your crontab in your tool of choice:
 
-Example for every day at 1am:
+    crontab -e
 
-    # minute hour day_of_month month day_of_week command_to_execute
-    0 1 * * * /bin/bash -li -c "maid --silent"
+...and have it invoke the `maid clean` command.  The `--silent` option is provided to keep this from emailing you, if desired.  A log of the actions taken is kept at `~/.maid/maid.log`.
 
-Both Mac OS X and Linux support callbacks when folders are changed, and that may be a forthcoming feature in Maid.  That said, I find `cron` to take care of most of my needs.
-
-## Sample
+Example for every day at 1am:
 
-For a sample rules file, run:
+    # minute hour day_of_month month day_of_week command_to_execute
+    0 1 * * * /bin/bash -li -c "maid clean --silent"
 
-    maid sample
+Both Mac OS X and Ubuntu support callbacks when folders are changed, and that may be a forthcoming feature in Maid.  That said, I find `cron` to take care of most of my needs.
 
 ## Warranty
 

data/Rakefile

@@ -1,5 +1,4 @@
 require 'rake'
-require 'rake/rdoctask'
 require 'rspec/core/rake_task'
 require 'bundler'
 
@@ -7,10 +6,8 @@ task :default => :spec
 
 Bundler::GemHelper.install_tasks
 
-Rake::RDocTask.new do |rd|
-  rd.rdoc_dir = 'doc'
-  rd.main = 'README.rdoc'
-  rd.rdoc_files.include('README.rdoc', 'lib/**/*.rb')  
-end
-
 RSpec::Core::RakeTask.new(:spec)
+
+task :console do
+  sh 'irb -I lib -r maid'
+end

data/Vagrantfile

@@ -0,0 +1,11 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant::Config.run do |config|
+  # The base precise64 box can be found at http://files.vagrantup.com/precise64.box
+  # 
+  # For more info, please see https://github.com/benjaminoakes/maid/wiki/Contributing
+  config.vm.box = 'precise64'
+
+  config.vm.provision(:shell, :path => 'script/provision')
+end

data/lib/maid.rb

@@ -1,9 +1,14 @@
+require 'deprecated'
+Deprecated.set_action(:warn)
+
 module Maid
   autoload :App, 'maid/app'
   autoload :Maid, 'maid/maid'
   autoload :Tools, 'maid/tools'
   autoload :NumericExtensions, 'maid/numeric_extensions'
+  autoload :Platform, 'maid/platform'
   autoload :Rule, 'maid/rule'
+  autoload :TrashMigration, 'maid/trash_migration'
   autoload :VERSION, 'maid/version'
 
   class << self
@@ -23,7 +28,8 @@ module Maid
 end
 
 class Numeric
-  include Maid::NumericExtensions
+  include Maid::NumericExtensions::Time
+  include Maid::NumericExtensions::SizeToKb
 end
 
 # TODO Is there a no-conflict way of including the extensions?

data/lib/maid/app.rb

@@ -17,9 +17,17 @@ class Maid::App < Thor
   method_option :silent, :type => :boolean, :aliases => %w[-s]
   def clean
     maid = Maid::Maid.new(maid_options(options))
+
+    if Maid::TrashMigration.needed?
+      migrate_trash
+      return
+    end
+
     unless options.silent? || options.noop?
       say "Logging actions to #{maid.log_device.inspect}"
     end
+
+    maid.load_rules
     maid.clean
   end
 
@@ -47,6 +55,7 @@ class Maid::App < Thor
         h[:file_options] = {:noop => true}
 
         unless options['silent']
+          h[:logger] = false
           h[:log_device] = STDOUT
           h[:log_formatter] = lambda { |_, _, _, msg| "#{msg}\n" }
         end
@@ -59,4 +68,48 @@ class Maid::App < Thor
       h
     end
   end
+
+  private
+
+  # Migrate trash to correct directory on Linux due to a configuration bug in previous releases.
+  def migrate_trash
+    migration = Maid::TrashMigration
+    banner('Trash Migration', :yellow)
+
+    say <<-EOF
+
+You are using Linux and have a "~/.Trash" directory.  If you used Maid 0.1.2 or earlier, that directory may exist because Maid incorrectly moved trash files there.
+
+But no worries.  Maid can migrate those files to the correct place.
+
+    EOF
+
+    response = ask("Would you like Maid to move the files in #{ migration.incorrect_trash.inspect } to #{ migration.correct_trash.inspect }?", :limited_to => %w(Y N))
+
+    case response
+    when 'Y'
+      say('')
+      say('Migrating trash...')
+
+      migration.perform
+
+      say('Migrated.  See the Maid log for details.')
+    when 'N'
+      say <<-EOF
+
+Running Maid again will continue to give this warning until #{ migration.incorrect_trash.inspect } no longer exists, or the environment variable MAID_NO_MIGRATE_TRASH has a value.
+
+Exiting...
+      EOF
+
+      exit -1
+    else
+      raise "Reached 'impossible' case (response: #{ response.inspect })"
+    end
+  end
+
+  def banner(text, color = nil)
+    say(text, color)
+    say('-' * text.length, color)
+  end
 end

data/lib/maid/maid.rb

@@ -1,17 +1,18 @@
 require 'fileutils'
 require 'logger'
 
+require 'xdg'
+
 # Maid cleans up according to the given rules, logging what it does.
 class Maid::Maid
   DEFAULTS = {
     :progname     => 'Maid',
     :log_device   => File.expand_path('~/.maid/maid.log'),
     :rules_path   => File.expand_path('~/.maid/rules.rb'),
-    :trash_path   => File.expand_path('~/.Trash'),
     :file_options => {:noop => false}, # for FileUtils
   }.freeze
 
-  attr_reader :file_options, :log_device, :rules, :rules_path, :trash_path
+  attr_reader :file_options, :logger, :log_device, :rules, :rules_path, :trash_path
   include ::Maid::Tools
 
   # Make a new Maid, setting up paths for the log and trash.
@@ -23,18 +24,24 @@ class Maid::Maid
   def initialize(options = {})
     options = DEFAULTS.merge(options.reject { |k, v| v.nil? })
 
-    @log_device = options[:log_device]
-    FileUtils.mkdir_p(File.dirname(@log_device)) unless @log_device.kind_of?(IO)
+    # TODO: Refactor and simplify (see also https://github.com/benjaminoakes/maid/pull/48#discussion_r1683942)
+    @logger = unless options[:logger]
+      @log_device = options[:log_device]
+      FileUtils.mkdir_p(File.dirname(@log_device)) unless @log_device.kind_of?(IO)
+      Logger.new(@log_device)
+    else
+      options[:logger]
+    end
 
-    @logger = Logger.new(@log_device)
     @logger.progname  = options[:progname]
     @logger.formatter = options[:log_formatter] if options[:log_formatter]
 
     @rules_path   = options[:rules_path]
-    @trash_path   = options[:trash_path]
+    @trash_path   = options[:trash_path] || default_trash_path
     @file_options = options[:file_options]
 
-    # Just in case it isn't there...
+    # Just in case they aren't there...
+    FileUtils.mkdir_p(File.expand_path('~/.maid'))
     FileUtils.mkdir_p(@trash_path)
 
     @rules = []
@@ -47,7 +54,6 @@ class Maid::Maid
       @logger.info 'Started'
     end
 
-    add_rules(@rules_path)
     follow_rules
 
     unless @log_device.kind_of?(IO)
@@ -55,8 +61,10 @@ class Maid::Maid
     end
   end
 
-  # Add the rules at path.
-  def add_rules(path)
+  # Add the rules at rules_path.
+  def load_rules
+    path = @rules_path
+
     Maid.with_instance(self) do
       # Using 'Kernel' here to help with testability
       # Kernel.load must be used for non-".rb" files to be required, it seems.
@@ -100,4 +108,18 @@ private
     supported = @@supported_commands[command_name]
     @@supported_commands[command_name] = supported ? supported : !%x(which #{command_name}).empty?
   end
+
+  def default_trash_path
+    # TODO: Refactor module declaration so this can be `Platform`
+    if Maid::Platform.linux?
+      # See the [FreeDesktop.org Trash specification](http://www.ramendik.ru/docs/trashspec.html)
+      path = "#{ XDG['DATA_HOME'] }/Trash/files"
+    elsif Maid::Platform.osx?
+      path = File.expand_path('~/.Trash')
+    else
+      raise NotImplementedError, "Unknown default trash path (unsupported host OS: #{ Maid::Platform.host_os.inspect })"
+    end
+
+    "#{ path }/"
+  end
 end