dir_validator 0.12.0

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== 0.12.0 (2012-07-27) 
+
+Initial beta release.

data/LICENSE.rdoc

@@ -0,0 +1,28 @@
+Copyright (c) 2012 by The Board of Trustees of the Leland Stanford Junior
+University. All rights reserved.
+
+Redistribution and use of this distribution in source and binary forms, with or
+without modification, are permitted provided that:
+
+* The above copyright notice and this permission notice appear in all copies and
+  supporting documentation.
+
+* The name, identifiers, and trademarks of The Board of Trustees of the Leland
+  Stanford Junior University are not used in advertising or publicity without the
+  express prior written permission of The Board of Trustees of the Leland
+  Stanford Junior University.
+
+* Recipients acknowledge that this distribution is made available as a research
+  courtesy, "as is", potentially with defects, without any obligation on the part
+  of The Board of Trustees of the Leland Stanford Junior University to provide
+  support, services, or repair.
+
+THE BOARD OF TRUSTEES OF THE LELAND STANFORD JUNIOR UNIVERSITY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT
+LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE, AND IN NO EVENT SHALL THE BOARD OF TRUSTEES OF THE LELAND
+STANFORD JUNIOR UNIVERSITY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING NEGLIGENCE) OR STRICT
+LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+SOFTWARE.

data/README.rdoc

@@ -0,0 +1,134 @@
+= dir_validate
+
+== Synopsis
+
+  require 'dir_validator'
+  dv = DirValidator.new('some/path')
+  dv.dirs('blah', :pattern => '*').each do |subdir|
+    # More validations as needed.
+  end
+  dv.report()
+
+
+== Overview
+
+This gem provides a convenient syntax for checking whether the contents of a
+directory structure match your expectations.
+
+The best place to start is by reading the {file:tutorial/tutorial.rb tutorial script}.
+
+The public API for the gem is fairly simple. First you set up the validator by
+passing in the path to the directory structure that you want to check.
+
+  require 'dir_validator'
+  dv = DirValidator.new('some/path')
+
+Then you define your expectations regarding the content of the directory
+structure. This is done with the four methods used to declare particular
+validations:
+
+  dirs()
+  files()
+  dir()
+  file()
+
+The validation methods use this syntax:
+
+  dirs(VID, OPTS)
+
+  # where VID  = The validation identifier.
+  #              Can be any string meaningful to the user.
+  #              Used when reporting warnings.
+  #
+  #       OPTS = A hash of options to set up expectations regarding
+  #              the names of files or directory as well as their
+  #              quantity.
+
+The plural validation methods return an array of {DirValidator::Item} objects.
+The singular variants return one such object (or nil). The returned objects are
+those that (a) meet the criteria specified in the OPTS hash, and (b) have not
+been matched already by prior validations.
+
+The validation criteria defined in the OPTS hash come in three general types:
+
+* Name-related criteria affect whether a particular {DirValidator::Item} will be
+  returned (only if its file or directory name matches the criteria). You can
+  supply one of the following:
+
+    :name     # A literal string.
+    :re       # A regular expression, supplied as either a Regexp or String.
+    :pattern  # A glob-like pattern. Supports only the * and ? wildcards.
+
+              # Also see the :recurse option below.
+
+* Quantity assertions. These control the maximum number of {DirValidator::Item}
+  objects that will be returned. They also generate a warning if too few are
+  found.
+
+    :n   # A string in one of the following forms:
+         #   '*'     Zero or more.
+         #   '+'     One or more.
+         #   '?'     Zero or one.
+         #   'n+'    n or more
+         #   'n'     Exactly n.
+         #   'm-n'   m through n, inclusive.
+
+* Other attributes:
+
+    :recurse  # Boolean (default = false).
+
+              # Normally, validation methods find only the immediate
+              # children of the object upon which the method is called. If
+              # :recurse is true, items deeper in the hierarchy can be
+              # discovered.
+              
+              # For example, given this content:
+              # some/path/
+              #   foo/
+              #     bar/
+              #       foo/
+
+              # And this validator.
+              dv = DirValidator.new('some/path')
+
+              # This call would return only the 'foo' directory.
+              dv.dirs('a', :re => /foo$/)
+
+              # Whereas this call would return both 'foo' and 'foo/bar/foo'.
+              dv.dirs('a', :re => /foo$/, :recurse => true)
+
+After the validations have been defined, you can examine the results programmatically:
+
+  dv.validate()
+  dv.warnings.each do |w|
+    puts w.vid
+    puts w.opts.inspect
+  end
+
+More commonly, you can print the information contained in the warnings in the form
+of a basic CSV repot.
+
+  dv.report()
+
+The warnings and the CSV report contain the following information:
+
+  vid       # Validation identifier, as discussed above.
+  got       # The number of items found.
+  n         # A normalized version of the :n optionn discussed above.
+  base_dir  # The parent directory of the item.
+  name      # The name-related options discussed above.
+  re        #  "
+  pattern   #  "
+  path      # The path of the item.
+
+
+== Known issues
+
+Currently handles only regular files and directories.
+
+Not yet tested on Windows.
+
+
+== Copyright
+
+Copyright © 2012 Stanford University Library. See LICENSE for details.

data/lib/dir_validator/catalog.rb

@@ -0,0 +1,115 @@
+# A Validator has one Catalog, which contains all of the information
+# about the Item objects discovered in the Validator.root_dir.
+#
+# @!visibility private
+class DirValidator::Catalog
+
+  FS        = '\\' + File::SEPARATOR
+  DOTDIR    = '\.\.?\z'                      # A dotdir is . or .. at end-of-string,
+  DOTDIR_RE = / ( \A | #{FS} ) #{DOTDIR} /x  # preceded by start-of-string or file-sep.
+
+  # Takes a validator, because we need to pass the validator down
+  # to the Item objects that are created.
+  def initialize(validator)
+    # The validator and an array of all Items in the Catalog.
+    @validator = validator
+    @items = nil
+
+    # Two indexes of to boost the performance of the unmatched_items method.
+    # Both indexes contain the catalog_id values of an remaining unmatched
+    # Items. The catalog_id values also serve as indexes into the @items
+    # array. The indexes have the following structure:
+    #
+    #   @unmatched[Item.catalog_id]          = true
+    #   @bdi[Item.base_dir][Item.catalog_id] = true
+    #
+    # The @bdi index is more fined-grained and thus gives the largest
+    # performance boost. For typical uses, calls to unmatched_items()
+    # will have a base_dir, so we can use @bdi.
+    @unmatched = {}
+    @bdi       = {}
+  end
+
+  # Returns the discovered Items, loading them if needed.
+  def items
+    return @items ||= load_items()
+  end
+
+  # Scans the Validator.root_dir, creating a new Item for each file/dir
+  # found, and adding the Item to the indexes used by the Catalog.
+  def load_items
+    catalog_id = -1
+    @items     = []
+    Dir.chdir(@validator.root_path) do
+      Dir.glob('**/*', File::FNM_DOTMATCH).each do |path|
+        # We want dotfiles, but not the . and .. dirs.
+        next if path_is_dot_dir(path)
+        # Create the new Item, and give it a unique ID, which is
+        # also an index into the @items array.
+        catalog_id += 1
+        item = DirValidator::Item.new(@validator, path, catalog_id)
+        @items << item
+        # Add Item to the indexes.
+        add_to_index(item)
+      end
+    end
+    return @items
+  end
+
+  # Takes a path as a string. Returns true if it's . or .. directory.
+  def path_is_dot_dir(path)
+    return path =~ DOTDIR_RE ? true : false
+  end
+
+  # Takes an Item object and adds it to the Catalog indexes.
+  def add_to_index(item)
+    cid = item.catalog_id
+    dn  = item.dirname2
+    @bdi[dn]      ||= {}
+    @bdi[dn][cid]   = true
+    @unmatched[cid] = true
+  end
+
+  # Takes and Item and removes it from the Catalog indexes.
+  def delete_from_index(item)
+    cid = item.catalog_id
+    dn  = item.dirname2
+    @bdi[dn].delete(cid)
+    @unmatched.delete(cid)
+  end
+
+  # Returns unmatched directories from the Catalog.
+  def unmatched_dirs(base_dir = nil)
+    return unmatched_items(base_dir).select { |i| i.is_dir }
+  end
+
+  # Returns unmatched files from the Catalog.
+  def unmatched_files(base_dir = nil)
+    return unmatched_items(base_dir).select { |i| i.is_file }
+  end
+
+  # Returns unmatches files and directories from the Catalog.
+  def unmatched_items(base_dir = nil)
+    # If a base_dir is given, we'll use the @bdi index. Otherwise,
+    # we'll use the @unmatched index. When using @bdi, we also
+    # must return [] if @bdi doesn't contain base_dir as a key.
+    # We sort the catalog_id values to obtain a deterministic ordering.
+    itms = items()
+    h    = base_dir ? @bdi[base_dir] : @unmatched
+    return [] unless h
+    return h.keys.sort.map { |cid| itms[cid] }
+  end
+
+  # Takes an array of Items. Marks them as matched and removes them
+  # from the Catalog indexes. We can't do this within unmatched_items()
+  # because we don't know that time which of the returned Items will
+  # survive the validation-methods name-filtering and quantity-filtering
+  # criteria.
+  def mark_as_matched(matched_items)
+    matched_items.each do |i|
+      i.mark_as_matched
+      delete_from_index(i)
+    end
+  end
+
+end

data/lib/dir_validator/item.rb

@@ -0,0 +1,119 @@
+require 'pathname'
+
+# @!attribute [r] path
+#   @return [String]
+#   The path to the Item, omitting the root_dir of the {DirValidator::Validator}.
+#
+# @!attribute [r] dirname
+#   @return [String]
+#   The path to the parent directory of the Item, or '.' if the parent
+#   directory is the root_dir of the {DirValidator::Validator}.
+#
+# @!attribute [r] match_data
+#   @return [MatchData]
+#   The MatchData from the most recent regular expression test against the Item.
+class DirValidator::Item
+
+  attr_reader(:path, :dirname, :match_data)
+  attr_reader(:pathname, :dirname2, :catalog_id, :matched, :target, :filetype) # @!visibility private
+
+  # Returns a new Item, based on these arguments:
+  #   - Validator.
+  #   - String: path to a file or directory (omitting Validator.root_dir).
+  #   - Integer: the Catalog ID assigned by the Catalog class.
+  #
+  # @!visibility private
+  def initialize(validator, path, catalog_id)
+    @validator  = validator
+    @pathname   = Pathname.new(path).cleanpath
+    @path       = @pathname.to_s
+    @dirname    = @pathname.dirname.to_s
+    @dirname2   = @dirname == '.' ? '' : @dirname
+    @catalog_id = catalog_id
+    @matched    = false
+    @target     = nil
+    @match_data = nil
+    @filetype   = @pathname.file?      ? :file :
+                  @pathname.directory? ? :dir  : nil
+  end
+
+  # Just a front-end for Ruby's File#basename.
+  #
+  # @param args          See File#basename.
+  # @return     [String] The basename of the Item.
+  def basename(*args)
+    return @pathname.basename(*args).to_s
+  end
+
+  # @!visibility private
+  def is_dir
+    return @filetype == :dir
+  end
+
+  # @!visibility private
+  def is_file
+    return @filetype == :file
+  end
+
+  # @!visibility private
+  def mark_as_matched
+    @matched = true
+  end
+
+  # @!visibility private
+  def set_target(t)
+    @target = t
+  end
+
+  # Takes a Regexp. Trys to match Item.target against the Regexp.
+  # Stores the resulting MatchData.
+  #
+  # @!visibility private
+  def target_match(regex)
+    @match_data = regex.match(@target)
+    return @match_data
+  end
+
+  # Validation method, using a {DirValidator::Item} as the receiver.
+  # 
+  # @see DirValidator::Validator#dir
+  # @return  (see DirValidator::Validator#dir)
+  def dir(vid, opts = {})
+    return @validator.dir(vid, item_opts(opts))
+  end
+
+  # @see #dir
+  # @return  (see DirValidator::Validator#file)
+  def file(vid, opts = {})
+    return @validator.file(vid, item_opts(opts))
+  end
+
+  # @see #dir
+  # @return  (see DirValidator::Validator#dirs)
+  def dirs(vid, opts = {})
+    return @validator.dirs(vid, item_opts(opts))
+  end
+
+  # @see #dir
+  # @return  (see DirValidator::Validator#files)
+  def files(vid, opts = {})
+    return @validator.files(vid, item_opts(opts))
+  end
+
+  # Takes a validation-method opts hash.
+  # Returns a new hash of opts with the appropriate value
+  # for :base_dir. That value depends on whether the current Item
+  # is a dir or file, and whether the file has a parent dir.
+  #
+  # @!visibility private
+  def item_opts(opts)
+    if is_dir
+      return opts.merge(:base_dir => @path)
+    elsif @dirname == '.'
+      return opts
+    else
+      return opts.merge(:base_dir => @dirname)
+    end
+  end
+
+end

data/lib/dir_validator/quantity.rb

@@ -0,0 +1,59 @@
+# @!visibility private
+class DirValidator::Quantity
+
+  attr_reader(:spec, :min_n, :max_n, :max_index)
+
+  # Takes a string and returns a new DirValidator::Quantity object.
+  #   min_n       Minimum expected N of items.
+  #   max_n       Maximum N of items to be matched.
+  #   max_index   Array index corresponding to max_n
+  def initialize(spec)
+    @spec = spec
+    parse_spec
+  end
+
+  def parse_spec
+    case @spec
+    when '*'
+      # 0+.
+      @min_n     = 0
+      @max_n     = 1.0 / 0
+      @max_index = -1
+    when '+'
+      # 1+.
+      @min_n     = 1
+      @max_n     = 1.0 / 0
+      @max_index = -1
+    when '?'
+      # Zero or one.
+      @min_n     = 0
+      @max_n     = 1
+      @max_index = @max_n - 1
+    when /\A (\d+)\+ \z/x
+      # n+
+      @min_n     = $1.to_i
+      @max_n     = 1.0 / 0
+      @max_index = -1
+    when /\A (\d+) \z/x
+      # n
+      @min_n     = $1.to_i
+      @max_n     = @min_n
+      @max_index = @max_n - 1
+    when /\A (\d+) - (\d+) \z/x
+      # m-n
+      @min_n     = $1.to_i
+      @max_n     = $2.to_i
+      @max_index = @max_n - 1
+    else
+      invalid_spec()
+    end
+
+    # Sanity check min and max.
+    invalid_spec() if (@min_n > @max_n or @min_n < 0)
+  end
+
+  def invalid_spec
+    raise ArgumentError, "Invalid quantitifer: #{@spec.inspect}."
+  end
+
+end

data/lib/dir_validator/validator.rb

@@ -0,0 +1,265 @@
+# @!attribute [r] root_path
+#   @return [String]
+#   The root path of the validator.
+#
+# @!attribute [r] warnings
+#   @return [Array]
+#   The validator's {DirValidator::Warning} objects.
+class DirValidator::Validator
+
+  attr_reader(:root_path, :warnings)
+  attr_reader(:catalog, :validated)  # @!visibility private
+
+  FILE_SEP  = File::SEPARATOR        # @!visibility private
+  EXTRA_VID = '_EXTRA_'              # @!visibility private
+
+  # @param  root_path [String] Path to the directory structure to be validated.
+  def initialize(root_path)
+    @root_path = root_path
+    @catalog   = DirValidator::Catalog.new(self)
+    @warnings  = []
+    @validated = false
+  end
+
+  # Validation method. See {file:README.rdoc} for details.
+  #
+  # Plural validation methods ({#dirs} and {#files}) return an array of
+  # {DirValidator::Item} objects. Singular variants ({#dirs} and {#files})
+  # return one such object, or nil.
+  #
+  # @param vid   [String]  Validation identifier meaningful to the user.
+  # @param opts  [Hash]    Validation options.
+  #
+  # @option opts :name    [String]             Item name must match a literal string.
+  # @option opts :re      [String|Regexp]      Item name must match regular expression.
+  # @option opts :pattern [String]             Item name must match a glob-like pattern.
+  # @option opts :n       [String]             Expected number of items. Plural validation
+  #                                            methods default to '1+'. Singular variants
+  #                                            force the option to be '1'.
+  # @option opts :recurse [false|true] (false) Whether to return items other than immediate
+  #                                            children.
+  #
+  # @return   [DirValidator::Item|nil]
+  def dir(vid, opts = {})
+    opts = opts.merge({:n => '1'})
+    return dirs(vid, opts).first
+  end
+
+  # @see #dir
+  # @return   (see #dir)
+  def file(vid, opts = {})
+    opts = opts.merge({:n => '1'})
+    return files(vid, opts).first
+  end
+
+  # @see #dir
+  # @return   [Array]
+  def dirs(vid, opts = {})
+    bd = normalized_base_dir(opts, :handle_recurse => true)
+    return process_items(@catalog.unmatched_dirs(bd), vid, opts)
+  end
+
+  # @see #dir
+  # @return   [Array]
+  def files(vid, opts = {})
+    bd = normalized_base_dir(opts, :handle_recurse => true)
+    return process_items(@catalog.unmatched_files(bd), vid, opts)
+  end
+
+  # The workhorse for the the validation methods.
+  #
+  # @!visibility private
+  def process_items(items, vid, opts = {})
+    # Make sure the user did not forget to pass the validation identifier.
+    if vid.class == Hash
+      msg = "Validation identifier should not be a hash: #{vid.inspect}"
+      raise ArgumentError, msg
+    end
+
+    # Get a Quantifier object.
+    quant = DirValidator::Quantity.new(opts[:n] || '1+')
+
+    # We are given a list of unmatched Items (either files or dirs).
+    # Here we filter the list to those matching the name-related criteria.
+    items = name_filtered(items, opts)
+
+    # And here we cap the N of items to be returned. For example, if the
+    # user asked for 1-3 Items and we found 5, we will return only 3.
+    items = quantity_limited(items, quant)
+
+    # Add a warning if the N of Items is less than the user's expectation.
+    sz = items.size
+    unless sz >= quant.min_n
+      add_warning(vid, opts.merge(:got => sz))
+    end
+
+    # Mark the Items as matched so subsequent validations won't return same Items.
+    @catalog.mark_as_matched(items)
+
+    return items
+  end
+
+
+  ####
+  # Name-related filtering.
+  ####
+
+  # Takes an array of items and a validation-method opts hash.
+  # Returns the subset of those items matching the name-related
+  # criteria in the opts hash.
+  #
+  # @!visibility private
+  def name_filtered(items, opts)
+    # Filter the items to those in the base_dir.
+    # If there is no base_dir, no filtering occurs.
+    base_dir = normalized_base_dir(opts, :add_file_sep => true)
+    sz       = base_dir.size
+    items    = items.select { |i| i.path.start_with?(base_dir) } if sz > 0
+
+    # Set the item.target values, which are the values that will
+    # be subjected to the name-related test. If there is no base_dir,
+    # the target is the same as item.path.
+    items.each { |i| i.set_target(i.path[sz .. -1]) }
+
+    # Filter items to immediate children, unless user wants to recurse.
+    items = items.reject { |i| i.target.include?(FILE_SEP) } unless opts[:recurse]
+
+    # Return the items having targets matching the name regex.
+    rgx = name_regex(opts)
+    return items.select { |i| i.target_match(rgx) }
+  end
+
+  # Takes a validation-method opts hash.
+  # Returns opts[:base_dir] in a normalized form (with trailing separator).
+  # Returns nil or '' under certain conditions.
+  #
+  # @!visibility private
+  def normalized_base_dir(opts, nbd_opts = {})
+    return nil if opts[:recurse] and nbd_opts[:handle_recurse]
+    bd = opts[:base_dir]
+    return '' unless bd
+    bd.chop! while bd.end_with?(FILE_SEP)
+    bd += FILE_SEP if nbd_opts[:add_file_sep]
+    return bd
+  end
+
+  # Takes a validation-method opts hash.
+  # Returns the appropriate Regexp based on the name-related criteria.
+  #
+  # @!visibility private
+  def name_regex(opts)
+    name    = opts[:name]
+    re      = opts[:re]
+    pattern = opts[:pattern]
+    return Regexp.new(
+      name    ? name_to_re(name)       :
+      pattern ? pattern_to_re(pattern) :
+      re      ? re                     : ''
+    )
+  end
+
+  # Takes a validation-method opts[:name] value.
+  # Returns the corresponding regex-ready string:
+  #   - wrapped in start- and end- anchors
+  #   - all special characters quoted
+  #
+  # @!visibility private
+  def name_to_re(name)
+    return az_wrap(Regexp.quote(name))
+  end
+
+  # Takes a validation-method opts[:pattern] value.
+  # Returns the corresponding regex-ready string
+  #   - wrapped in start- and end- anchors
+  #   - all special regex chacters quoted except for:
+  #     * becomes .*
+  #     ? becomes .
+  #
+  # @!visibility private
+  def pattern_to_re(pattern)
+    return az_wrap(Regexp.quote(pattern).gsub(/\\\*/, '.*').gsub(/\\\?/, '.'))
+  end
+
+  # Takes a string.
+  # Returns a new string wrapped in Regexp start-of-string and end-of-string anchors.
+  #
+  # @!visibility private
+  def az_wrap(s)
+    return "\\A#{s}\\z"
+  end
+
+
+  ####
+  # Quantity filtering.
+  ####
+
+  # Takes an array of items and a DirValidator::Quantity object.
+  # Returns the subset of those items falling within the max allowed
+  # by the Quantity.
+  #
+  # @!visibility private
+  def quantity_limited(items, quant)
+    return items[0 .. quant.max_index]
+  end
+
+
+  ####
+  # Methods related validation warnings and reporting.
+  ####
+
+  # Takes a validation identifier and a validation-method opts hash.
+  # Creates and new DirValidator::Warning and adds it to the validator's
+  # array of warnings.
+  #
+  # @!visibility private
+  def add_warning(vid, opts)
+    @warnings << DirValidator::Warning.new(vid, opts)
+  end
+
+  # Adds a warning to the validator for all unmatched items in the catalog.
+  # Should be run after all validation-methods have been called, typically
+  # before producing a report.
+  #
+  # @!visibility private
+  def validate
+    return if @validated  # Run only once.
+    @catalog.unmatched_items.each do |item|
+      add_warning(EXTRA_VID, :path => item.path)
+    end
+    @validated = true
+  end
+
+  # Write a CSV report of the information contained in the validator's warnings.
+  #
+  # @param io [IO]  IO object to which the report should be written.
+  def report(io = STDOUT)
+    require 'csv'
+    validate()
+    report_data.each do |row|
+      io.puts CSV.generate_line(row)
+    end
+  end
+
+  # Returns a matrix of warning information.
+  # Used when producing the CSV report.
+  #
+  # @!visibility private
+  def report_data
+    rc = DirValidator::Validator.report_columns
+    data = [rc]
+    @warnings.each do |w|
+      cells = rc.map { |c| v = w.opts[c]; v.nil? ? '' : v }
+      cells[0] = w.vid
+      data.push(cells)
+    end
+    return data
+  end
+
+  # Column headings for the CSV report.
+  #
+  # @!visibility private
+  def self.report_columns
+    return [:vid, :got, :n, :base_dir, :name, :re, :pattern, :path]
+  end
+
+end

data/lib/dir_validator/warning.rb

@@ -0,0 +1,28 @@
+# @!attribute [r] vid
+#   @see #initialize
+#   @return [String]
+# @!attribute [r] opts
+#   @see #initialize
+#   @return [Hash]
+class DirValidator::Warning
+
+  attr_reader(:vid, :opts)
+
+  # @param  vid  [String] Validation identifier of the validation-method call
+  #                       that led to the warning.
+  # @param  opts [Hash]   Validation-method options hash, along with some additional
+  #                       information about the context in which the warning was
+  #                       generated.
+  def initialize(vid, opts)
+    @vid  = vid
+    @opts = opts
+  end
+
+  # Returns a basic representation of the information contained in the warning.
+  #
+  # @return [String]
+  def to_s
+    return "#{@vid}: #{@opts.inspect}"
+  end
+
+end

data/lib/dir_validator.rb

@@ -0,0 +1,17 @@
+module DirValidator
+
+  # Syntactic sugar: a module method for creating a new validator.
+  #
+  # @param (see DirValidator::Validator#new)
+  # @return [DirValidator::Validator]
+  def self.new(*args, &block)
+    return DirValidator::Validator.new(*args, &block)
+  end
+
+end
+
+require 'dir_validator/catalog'
+require 'dir_validator/item'
+require 'dir_validator/quantity'
+require 'dir_validator/validator'
+require 'dir_validator/warning'

data/tutorial/tutorial.rb

@@ -0,0 +1,88 @@
+#! /usr/bin/env ruby
+
+require 'rubygems'
+require 'dir_validator'
+
+# Suppose that we want to check the following directory structure.
+#
+#   spec/fixtures/tutorial/
+#       aaa/                 # Top-level sub-directories should be 3 lower-case leters.
+#           00/              # Should be three second-level directories: 00, 01, and 02.
+#               a.tif        # One or more .tif files in the 00 directory.
+#               b.tif
+#           01/
+#               a.jpg        # A parallel set of .jpg files.
+#               b.jpg
+#           02/
+#               a.jp2        # A parallel set of .jp2 files.
+#               b.jp2
+#               blort.txt    # What?!?
+#       aab/
+#           00/
+#               a.tif
+#               b.tif
+#           01/
+#               a.jpg
+#               b.jpg
+#           02/
+#               a.jp2        # Missing file.
+#       baa/
+#           00/
+#               a.tif
+#               b.tif
+#           01/
+#               a.jpg
+#               b.jpg
+#           02/
+#               a.jp2        # Missing file.
+
+# Set up the validator, passing in the starting path.
+dv = DirValidator.new('tutorial/files')
+
+# Here we set up our expectation for the top-level sub-directories. In this
+# case, we are looking for 1 or more sub-directories named with exactly 3
+# lower-case letters, as defined in the regular expression.
+dv.dirs('top-level subdir', :re => /^[a-z]{3}$/).each do |subdir|
+
+  # Within each of those top-level directories, we expect to find three
+  # numbered directories. In this case, we pass in literal names to
+  # the validation methods rather than a regular expression.
+  # Notice also that the validation method is being called on the
+  # subdirectory (subdir), not the overall dir-validator (dv).
+  d0 = subdir.dir('00', :name => '00')
+  d1 = subdir.dir('01', :name => '01')
+  d2 = subdir.dir('02', :name => '02')
+
+  # In the 00 subdirectory, we expect to see a bunch of .tif files.
+  # We could have used a regular expression, but in this case we'll
+  # resort to a simple glob-like pattern.
+  d0.files('tifs', :pattern => '*.tif').each do |tif|
+
+    # And finally, we set up the validations for the parallel .jpg
+    # and .jp2 files. Those files should reside in the 01 and 02
+    # subdirectories (which we stored in d1 and d2 above). Their
+    # file names should mirror that of the current .tif file.
+    tif_base = tif.basename('.tif')
+    d1.file('jpgs', :name => tif_base + '.jpg')
+    d2.file('jp2s', :name => tif_base + '.jp2')
+
+  end
+end
+
+# We can generate a basic CSV report that will list:
+#   - items that we not found
+#   - extra items
+#
+# The CSV output (with extra spacing here for readability):
+#   vid,      got,  n,   base_dir,  name,   re,  pattern,  path
+#   jp2s,     0,    1,   aab/02,    b.jp2,  "",  "",       ""
+#   jp2s,     0,    1,   baa/02,    b.jp2,  "",  "",       ""
+#   _EXTRA_,  "",   "",  "",        "",     "",  "",       aaa/02/blort.txt
+dv.report()
+
+# Alternatively, we could examine the results programmatically by
+# iterating over the dir-validator's warnings.
+dv.validate()
+dv.warnings.each do |w|
+  # ...
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification 
+name: dir_validator
+version: !ruby/object:Gem::Version 
+  hash: 47
+  prerelease: 
+  segments: 
+  - 0
+  - 12
+  - 0
+  version: 0.12.0
+platform: ruby
+authors: 
+- Monty Hindman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-30 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 2
+        - 6
+        version: "2.6"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: lyberteam-devel
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: awesome_print
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: looksee
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: This gem provides a convenient syntax for checking whether the contents of a directory structure match your expectations.
+email: 
+- hindman@stanford.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/dir_validator/catalog.rb
+- lib/dir_validator/item.rb
+- lib/dir_validator/quantity.rb
+- lib/dir_validator/validator.rb
+- lib/dir_validator/warning.rb
+- lib/dir_validator.rb
+- LICENSE.rdoc
+- README.rdoc
+- CHANGELOG.rdoc
+- tutorial/tutorial.rb
+homepage: https://github.com/sul-dlss
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Validate content of a directory structure.
+test_files: []
+
+has_rdoc: