WDM: API design choice

gistfile1.rb

# The repo: https://github.com/Maher4Ever/wdm

# Initial setup
require 'wdm'
monitor = WDM::Monitor.new

# Simple usage:
monitor.watch('C:\Users\Maher\Desktop\test') do |change|
  puts "#{change.type.to_s.upcase}: '#{change.file}'" # => Ex.: MODIFIED: 'C:\Users\Maher\Desktop\test\file.txt'
end

# Advenced usage (passing flags):
# @note: Flags description can be found on: http://msdn.microsoft.com/en-us/library/windows/desktop/aa365465(v=vs.85).aspx
monitor.watch('C:\Users\Maher\Desktop\test',
  :files, :directories, :attributes, :size, :last_write, :last_access, :creation, :security
) do |change|
  puts "#{change.type.to_s.upcase}: '#{change.file}'"
end

# --------------------------------------------------------------------
# How to enable watching subdirectories?
# --------------------------------------------------------------------

# Option 1: Use a flag for subdirectories
monitor.watch('C:\Users\Maher\Desktop\test', :default, :recursive) do |change|
  puts "#{change.type.to_s.upcase}: '#{change.file}'"
end

# Advantages:
#   - rb-inotify already uses this approach, so it could be familiar for developers.
#
# Disadvantages: 
#   - Always need to add the ':default' flag, otherwise we can't know which type of changes to report
#   - The second parameter is for change types, but ':recursive' is not really a type of change, but then again.. ':files' and ':directories' aren't either!

# --------------------------------------------------------------------

# Option 2: Use a flag for subdirectories
monitor.watch_recursively('C:\Users\Maher\Desktop\test') do |change|
  puts "#{change.type.to_s.upcase}: '#{change.file}'"
end

# Advantages:
#   - It keeps the API for calling the method without options simple
#   - The option is easier to spot in code
#   - No need for ':default'
#
# Disadvantages: 
#   - Extra method for the user

# --------------------------------------------------------------------