sequin 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+test

data/CHANGELOG

@@ -0,0 +1,5 @@
+v2.1. newest change
+
+v2. older change
+
+v1.9. oldest change

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in sequin.gemspec
+gemspec

data/README.md

@@ -0,0 +1,210 @@
+
+
+Sequin
+======
+
+Description
+--------
+
+Sequin is a collection of thor tasks that allow you to list, test and modify sequences of files on disk.
+
+Installation
+--------
+
+    $ gem install sequin
+
+or 
+
+    $ sudo gem install sequin
+
+Usage
+--------
+
+The command is seq, followed by a task:
+
+Tasks
+
+*  seq list [FILES]                     # List files as sequences.
+*  seq match [FILES] -r, --regex=REGEX  # Match filename naming conventions using a regular expression.
+*  seq check [SIGNATURE]                # Check the existence of files defined by a sequence signature.
+*  seq generate [NAME]                  # Generate a seq config file containing regular expression definitions used in the seq match task.
+*  seq help [TASK]                      # Describe available tasks or one specific task.
+*  seq usage                            # Print the usage banner.
+
+All tasks have a single letter alias. Use m instead of match, c instead of check etc.
+
+
+### List Sequences
+
+    seq list [FILES]
+
+List the given files as sequences where possible. 
+
+Options: 
+
+* -v, [--verbose=N] Specify how verbose to be when listing missing frames.
+
+  * 0 Dont mention missing frames
+  * 1 show missing frame count
+  * 2 list missing frame numbers
+  * Default: 1
+
+Each line of output from this task is a **sequence signature.** It consists of a **filename template**: a filename where the sequence digits replaced with "#"s, followed by a **range spec**: start, end, and by frames in square brackets. 
+
+For example: `../test/a/op_063_8900.####.jpg [0 to 25 by 1]`
+
+
+
+If any frames are missing, the range spec will be colored red in the output, as will other information about the missing frames according to the verbose options.
+
+    $ seq l * -v 2
+    h264_960x540_film.mov
+    mjpega_1920x1080.mov
+    #### [1 to 30 by 1]
+    006_057_s3d_lf_r04.####.dpx [1 to 30 by 1]
+    006_057_s3d_lf_r05.#.dpx [1 to 30 by 1] - missing: [ 11,14,15,18,22 ]
+    006_057_s3d_lf_r06.#.dpx [1 to 30 by 1]
+    008_055_s3d_lf_r04.####.dpx [1 to 50 by 1]
+    fn_by_three.#.jpg [1 to 25 by 3] - missing: [ 19 ]
+    fn_by_two.#.jpg [1 to 29 by 2]
+    
+    $ seq l 006* -v 1
+    006_057_s3d_lf_r04.####.dpx [1 to 30 by 1]
+    006_057_s3d_lf_r05.#.dpx [1 to 30 by 1] - missing: [ 5 frames ]
+    006_057_s3d_lf_r06.#.dpx [1 to 30 by 1]
+
+
+### Match
+
+    seq match [FILES] -r, --regex=REGEX
+
+Make sure filenames conform to file naming conventions by testing them against a regular expression.
+
+Options:
+
+*  -r, --regex=REGEX     # Specify a regular expression literally, or by reference to one listed in ~/.seq.yml
+*  -m, [--show-matched]  # List files that match the regex, in green
+*  -f, [--show-failed]   # List files that failed to match the regex, in red
+*  -a, [--show-all]      # List all the files in order with color coding.
+
+Normally you wouldn't want to type lengthy regular expressions on the command line, so instead they can be stored in a yaml file and referred to by the keys in the yaml data structure. The keys would typically represent projects and filetypes. 
+
+The yaml file looks something like this:
+
+        potter: 
+          dpx: ^[0-9]{3}_[0-9]{3}_s3d_(rt|lf)_r[0-9]{2}\.[0-9]{4}\.dpx$
+          mcx: ^[0-9]{3}_[0-9]{3}_ver[0-9]{2,3}\.[0-9]{4}\.xml$
+        conan: 
+          dpx: ^[a-z]{2}_[0-9]{3}_[0-9]{4}_(L|R|C)\.[0-9]{4,5}\.dpx$
+          mov: ^[a-z]{2}_h264_[0-9]{3,4}x[0-9]{3,4}_(film|pal|ntsc)\.mov$
+
+The regular expression can then be referred to on the command line with `--regex potter:dpx` and so on.
+
+    $ seq m * -r potter:dpx
+    Testing against regular expression: /^[0-9]{3}_[0-9]{3}_s3d_(rt|lf)_r[0-9]{2}\.[0-9]{4}\.dpx$/
+    h264_960x540_film.mov FAILED
+    mjpega_1920x1080.mov FAILED
+    #### [1 to 30 by 1] (0 MATCHED, 30 FAILED)
+    006_057_s3d_lf_r04.####.dpx [1 to 30 by 1] (30 MATCHED)
+    006_057_s3d_lf_r05.#.dpx [1 to 30 by 1] (0 MATCHED, 25 FAILED)
+    006_057_s3d_lf_r06.#.dpx [1 to 30 by 1] (0 MATCHED, 30 FAILED)
+    008_055_s3d_lf_r04.####.dpx [1 to 50 by 1] (50 MATCHED)
+    fn_by_three.#.jpg [1 to 28 by 3] (0 MATCHED, 10 FAILED)
+    fn_by_two.#.jpg [1 to 29 by 2] (0 MATCHED, 15 FAILED)
+    op_063_8900.####.jpg [0 to 25 by 1] (0 MATCHED, 26 FAILED)
+
+
+
+
+### Check membership
+
+    seq check [SIGNATURE]
+
+Check the existence of files defined by a sequence signature. 
+
+Options:
+
+* -f, [--show-found]    # List files from the signature that are on disk.
+* -m, [--show-missing]  # List files from the signature that are missing on disk.
+* -e, [--show-extra]    # List files that are on disk but not in the signature.
+* -a, [--show-all]      # List the union of all files on disk or in the signature.
+    
+
+Files may either be found, missing, or extra. Extra means the file exists on disk but not in the signature. With no flags, the output will be just a single line showing the number of found, missing or extra. By using the flags, you can list the individual files in the sequence with color coding and and in order. 
+
+    $ seq c 006_057_s3d_lf_r04.####.dpx [1 to 30 by 1]
+    006_057_s3d_lf_r04.####.dpx [found: 30] [missing: 0] [extra: 0]
+    
+    $  seq c 006_057_s3d_lf_r04.####.dpx [5 to 35 by 1]
+    006_057_s3d_lf_r04.####.dpx [found: 26] [missing: 5] [extra: 4]
+    
+	$  seq c 006_057_s3d_lf_r04.####.dpx [5 to 35 by 2] -m
+	006_057_s3d_lf_r04.####.dpx [found: 13] [missing: 3] [extra: 17]
+	006_057_s3d_lf_r04.0031.dpx
+	006_057_s3d_lf_r04.0033.dpx
+	006_057_s3d_lf_r04.0035.dpx
+
+### Generate
+
+    seq generate [NAME]
+
+Generate the .sequin config file in your home directory ~/.seq.yml
+
+Options:
+* -f, [--force]  # Overwrite the file if it exists.
+
+Currently, NAME must be config. This file contains regular expression definitions used in the `seq match` task.
+
+    $  seq g config
+    Skipping write of /Users/julianmann/.seq.yml because it exists. Use --force to remove it.
+
+    $  seq g config -f
+    Generating /Users/julianmann/.seq.yml
+
+How Sequin finds sequences
+-------
+
+The goal of the sequence listing algorithm is to find sequences without the need
+for the user to specify where the numbers are in the filenames, or what characters
+delimit the numbers. This can be tricky because a filename may contain many parts 
+containing numbers. Here's a real world example: `004_055_s3d_lf_r04.0001.dpx` 
+How can we know which number part correctly represents the sequence? 
+It could be any of the following
+
+    ###_055_s3d_lf_r04.0001.dpx
+    004_###_s3d_lf_r04.0001.dpx
+    004_055_s#d_lf_r04.0001.dpx
+    004_055_s3d_lf_r##.0001.dpx
+    004_055_s3d_lf_r04.####.dpx
+
+The strategy we employ is to use the number part that causes the file to be in the largest sequence.
+
+Consider the files:
+
+    file.04.0001.ext
+    file.04.0002.ext
+    file.04.0003.ext
+    file.05.0001.ext
+    file.05.0002.ext
+    file.05.0003.ext
+
+There are 5 possible sequences here. Each file could be in 2 of them, one containing 2 files, one containing 3.
+
+    file.04.0001.ext could be in file.##.0001.ext or file.04.####.ext
+    
+There are more files in `file.04.####.ext` than `file.##.0001.ext`, so we resolve to `file.04.####.ext` for this file.
+
+
+To Do
+-------
+
+* Add support for listing recursively 
+* Add modifier tasks such as pad, offset, replace etc.
+* Test colors in shells other than bash.
+* Test on Ruby 1.8.7. Currently works under Ruby 1.9.2
+
+
+License
+-------
+
+See the LICENSE file for further details. 

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/bin/seq

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'sequin'
+
+Sequin::Seq.start

data/lib/listing.rb

@@ -0,0 +1,334 @@
+#!/usr/bin/env ruby
+require 'pp'
+require 'fileutils'
+
+# add colors to String class
+class String
+  def colorize(code)
+  "\e[0;#{code.to_s}m#{self}\e[0m"
+    
+    #  self
+  end
+
+  # I tried to put "define_method" in a loop but it was having none of it
+  # Please accept my humble apologies
+  def red; self.colorize(31);end  
+  def green; self.colorize(32);end  
+  def yellow; self.colorize(33);end  
+  def blue; self.colorize(34);end  
+  def purple; self.colorize(35);end  
+  def cyan; self.colorize(36);end  
+end
+
+
+
+module Sequin
+
+  class Sequin::Listing
+
+    # The goal of this sequence listing algorithm is to find sequences without the need
+    # for the user to specify where the numbers are in the filenames, or what characters
+    # delimit the numbers. This can be tricky because a filename may contain many parts 
+    # containing numbers. Here's a real world example: 004_055_s3d_lf_r04.0001.dpx 
+    # How can we know which number part correctly represents the sequence? 
+    # It could be any of the following
+    # ###_055_s3d_lf_r04.0001.dpx
+    # 004_###_s3d_lf_r04.0001.dpx
+    # 004_055_s#d_lf_r04.0001.dpx
+    # 004_055_s3d_lf_r##.0001.dpx
+    # 004_055_s3d_lf_r04.####.dpx
+    #
+    # The strategy we employ is to use the number part that causes the file to be in the largest sequence.
+
+    # Consider the files:
+    # file.04.0001.ext
+    # file.04.0002.ext
+    # file.04.0003.ext
+    # file.05.0001.ext
+    # file.05.0002.ext
+    # file.05.0003.ext
+    #
+    # There are 5 possible sequences here. Each file could be in 2 of them, one containing 2 files, one containing 3.
+    # file.04.0001.ext could be in file.##.0001.ext or file.04.####.ext
+    # There are more files in file.04.####.ext than file.##.0001.ext, so we use that sequence for this file.
+
+
+
+    def initialize(files)
+      @sequences = Hash.new  
+
+      # make a hash containing a signature key for all possible sequences
+      all_seqs = all_possible_sequences files
+
+      # now select from that hash the best sequences according
+      # to the strategy outlined above
+      select_best_sequences(all_seqs, files)
+
+      # we need to make a note of the padding because
+      # we will be converting the number part to integers
+      each_sequence { |k,v| v[:padding] = v[:numbers].min.length } 
+
+      # convert the number part to integers and sort them
+      # so we can figure out the range, by_frame, and missing frames
+      each_sequence { |k,v| v[:numbers].collect! {|el| el.to_i} } 
+      each_sequence { |k,v| v[:numbers].sort! } 
+
+      # find the by_frame so that we can figure out which
+      # frames are missing, if any. If we don't get 
+      # the by_frame for a sequence that is by 2 for example, we would
+      # think that every other frame was missing.
+      each_sequence {|k,v| v[:by] = calc_by_frame v[:numbers]}
+
+      # now we know the by frame, we can find out which frames 
+      # are missing because the user will want to know this. 
+      each_sequence do |k,v| 
+        range =  v[:numbers].min..v[:numbers].max
+        v[:missing] = []
+        range.step(v[:by]) do |val| 
+          v[:missing]  << val unless  v[:numbers].include? val
+        end    
+      end
+
+      # we no longer need the filenames. We have enough info to
+      # recreate them if necessary
+      each_sequence {|k,v| v.delete(:names) }
+
+      # here we change the hash sequence keys (which are arrays). We make the number slot
+      # represent the padding. This is so we can create a sequence key 
+      # by simply calling join on the array elements
+      each_sequence { |k,v|  k[v[:numbers_index]] = ("#" *v[:padding]) } 
+    end
+
+
+    # for debugging
+    def inspect
+      pp @sequences
+    end
+
+
+
+    # a sequence string describes the sequence like so.
+    # filename [ <start> to <end> by <by_frame> ] - missing [ <missing frames> ]
+    # This is what gets printed out in a listing, and can also be used as input 
+    # to other seq commands such as seq pad, seq renumber, seq substitute
+    # The missing frames section is optional. When a sequence_signature is used as input
+    # the missing frames will be determined by seq internally. 
+    def sequence_signature(k,v,verbose=1)
+      range_str= "[#{v[:numbers].min} to #{v[:numbers].max} by #{v[:by]}]"
+      unless v[:missing].empty? 
+        range_str = "#{range_str} - missing: [ #{v[:missing].count} frames ]" if  verbose == 1
+        range_str = "#{range_str} - missing: [ #{v[:missing].join(",")} ]"if  verbose == 2
+        range_str = range_str.red
+      else
+        range_str = range_str.green
+      end
+      str = "#{k.join()} #{range_str}"
+    end
+
+
+
+    # simple listing of single files and sequences
+    def list(verbose=1)
+      each_single {|f| puts f}
+      
+      each_sequence do |k,v|
+        str = sequence_signature(k,v,verbose)
+        puts str
+      end
+    end
+
+
+    # match a sequence against a regex.
+    # create an array where 
+    # each element is a sub array of the form    
+    # ["filename", <:matched|:failed>, frame_number]
+    #
+    # The sequence is more managable as a single 
+    # array as it can be sorted.
+    def self.match_matrix(regex, key , seq)
+      prefix, suffix = key.join().split(/#+/)
+      matrix = [] 
+      seq[:numbers].each do |n|
+        fn =  [prefix , ("%0#{seq[:padding]}d" % n)  , suffix].join()
+        unless regex.match(File.basename(fn)).nil?
+          matrix << [fn,:matched,n]
+        else
+          matrix << [fn,:failed,n]
+        end
+      end
+      matrix.sort! { |a,b|  a[2] <=> b[2] }
+    end
+
+
+
+
+
+    # make a one line message describing the result of this 
+    # matching a regex against all files in a sequence. Most of
+    # the info we need is in the fn_matrix array, but we also
+    # need the sequence key/value pair to create the signature.
+    def assessment_message(fn_matrix,k,v)
+      matched = fn_matrix.count { |el| el[1] == :matched }
+      failed = fn_matrix.count - matched
+
+      msg = "#{matched} MATCHED"
+      msg = "#{msg}, #{failed} FAILED" if failed > 0
+      msg = "(#{msg})"
+      msg = "#{msg} / #{fn_matrix.count} files" if failed > 0 &&  matched > 0
+
+      if failed == 0
+        msg = msg.green
+      elsif matched == 0    
+        msg = msg.red
+      else
+        msg = msg.yellow
+      end
+
+      fn = sequence_signature(k,v,0)
+      message = "#{fn} #{msg}"
+    end
+    
+    
+
+    # this proc is called from the main script. Matches a regex against 
+    # all single files and all sequences in the @sequences object and outputs
+    # information according to verbosity options
+    def match(the_regex, options ={})
+      re = Regexp.new(the_regex)
+      puts "Testing against regular expression: /#{the_regex}/".cyan
+
+      each_single do |f| 
+        msg = re.match(File.basename(f)).nil? ? 'FAILED'.red : 'PASSED'.green
+        puts "#{f} #{msg}"
+      end
+
+      each_sequence do |k,v| 
+        fn_matrix = Sequin::Listing.match_matrix(re, k,v)
+        puts "#{assessment_message(fn_matrix,k,v)}"
+        unless  options["show_all"].nil? &&  options["show_matched"].nil? &&  options["show_failed"].nil?
+          fn_matrix.each do  |el|
+            key =  "show_#{el[1].to_s}" 
+            puts el[0].send(Sequin::Listing.alert_colors[el[1]]) unless options[key].nil? && options["show_all"].nil?
+          end
+        end
+      end
+
+    end
+
+
+    # takes a block and iterates through sequence 
+    # keys, ignoring single files
+    def each_sequence
+      @sequences.each do |k,v|
+        yield(k,v)  unless k == :single   
+      end
+    end
+
+    # takes a block and iterates through single 
+    # files, ignoring . and .. and  sequences
+    def each_single
+      @sequences.each do |k,v|
+        if k == :single   
+          v.each  { |f|  yield(f) unless( f =="." || f == "..") }
+        end
+      end
+    end
+
+
+    private
+
+
+    def all_possible_sequences(files)
+      h = Hash.new
+      files.each do |f|
+
+        # an array containing the number parts in the odd slots: [1] [3] etc.
+        parts = f.split(/([0-9]+)/) 
+
+        # If there are an even number of parts, half of them are numbers
+        # If there are an odd number of parts, there are more not-numbers than numbers
+        # By dividing by 2 and relying on integer rounding, we get the right answer in both cases 
+        number_count = parts.count / 2 
+
+        # For every number position, make our hash key from the remaining parts
+        # and make the hash value another hash containing the filenames, numbers, and other info
+        (0...number_count).each do |i|
+          number_part_index = (i*2)+1
+          key =[]
+          (0...parts.count).each do |part_index|
+            key  <<  (part_index == number_part_index  ? "#" : parts[part_index] )
+          end
+
+          h[key] ||= {}  
+          (h[key][:names] ||= []) <<  f
+          (h[key][:numbers] ||= []) <<  parts[number_part_index]   
+          h[key][:numbers_index] = number_part_index   
+        end 
+      end
+      h
+    end
+
+
+    # Find the best sequence that each file belongs to.
+    # As mentioned above, the best sequence is the one with 
+    # the most files out of the set of all sequences that 
+    # this file is in.
+    def select_best_sequences(all_seqs, files)
+      files.each do |f|
+        most_frames = 0
+        best_hash = {}
+        best_key = nil
+
+        all_seqs.each do |k,v|
+          curr_frames = all_seqs[k][:numbers].count
+          if curr_frames > most_frames
+            if all_seqs[k][:names].include?(f)
+              best_hash = all_seqs[k]
+              best_key = k
+              most_frames = curr_frames
+            end
+          end
+        end
+        if best_key.nil? || most_frames < 2
+          ( @sequences[:single] ||= [] ) << f
+        else 
+          @sequences[best_key] = best_hash
+        end
+      end
+    end
+
+    # to determine the by_frame, we calculate the greatest common factor of
+    # all the gaps between successive frames. If the gap gets to 1, then break
+    # because we don't consider fractional frame numbers. 1 is the smallest gap allowed.
+    # Note: with this method, we can still know the by_frame even if some frames
+    # are missing 
+    def calc_by_frame(frames)
+      gcf = frames.max - frames.min
+      last = frames.min
+      frames.each do |n|
+        if n !=  frames.min
+          new_gcf = greatest_common_factor(gcf, n - last)
+          gcf = new_gcf if new_gcf < gcf
+          break if gcf == 1
+          last = n
+        end
+      end
+      gcf
+    end
+
+
+    # recursive GCF
+    def greatest_common_factor(n1, n2) 
+      return ( n1 % n2==0 ) ? n2 : greatest_common_factor(n2, n1 % n2 ) 
+    end 
+
+    def self.alert_colors
+      {  :matched =>"green",  :failed =>"red"  }
+    end
+
+
+
+  end
+
+
+end

data/lib/membership.rb

@@ -0,0 +1,83 @@
+
+
+module Sequin
+
+  
+  class Membership
+    
+    # Membership
+    # In order to give information about files in relation to
+    # the sequence signature, we need to collect all the filenames 
+    # the user asks for, and all the filenames on disk that 
+    # match the sequence mask (the filename part of the sequence signature). 
+    # Thewn we can determine whether the file was (found), (misssing), 
+    # or (extra) i.e. existing but not asked for
+    #
+    # Each element in the array returned by this method is a 
+    # 3 element sub array that has the following form:
+    # ["filename", <:found|:missing|:extra>, frame_number]
+    # 
+    # It is sorted on the frame_number, which is an integer
+    def initialize(fn_template, options={} )
+
+      @fn_template = fn_template
+      @fn_matrix = Dir.glob(fn_template.gsub(/#+/, "*")).to_a
+      prefix, suffix = @fn_template.split(/#+/)
+
+      @fn_matrix.collect! { |f| [f, :extra] }
+
+      range =  options[:start_frame]..options[:end_frame]
+      range.step(options[:by_frame] || 1) do |val| 
+
+        filename = fn_template.gsub(/#+/,  ("%0#{options[:padding]}d" % val) )
+        
+        el = @fn_matrix.find {|e| e[0] == filename }
+        if el.nil?
+          @fn_matrix << [filename , :missing ]
+        else
+          el[1] = :found
+        end
+      end
+      @fn_matrix.each  { |el|   el[2] = el[0].sub(prefix,'').sub(suffix,'').to_i }
+      @fn_matrix.sort! { |a,b|  a[2] <=> b[2] }
+    end
+
+    # generate a message from the filename matrix - something like this:
+    # ../test/a/006_057_s3d_lf_r06.#.dpx [found: 13] [missing: 3] [extra: 17]
+    # where the found missing and extra sections are color coded according
+    # to whether there were files present with that attribute
+    def assessment_message
+      message = @fn_template
+      [:found, :missing, :extra].each do |t|
+       num_present = @fn_matrix.count { |el| el[1] == t }
+        m = "[#{t.to_s}: #{num_present}]" 
+        m = (num_present > 0) ? m.send(Sequin::Membership.alert_colors[t][:present]) :  m.send(Sequin::Membership.alert_colors[t][:absent]) 
+        message = "#{message} #{m}"
+      end
+      message
+    end
+
+    # output a brief assessment message and optionally list files
+    # that are found, missing, and/or extra
+    def output(options={})
+      puts "#{assessment_message}"
+      @fn_matrix.each do |el|
+        key =  "show_#{el[1].to_s}" 
+        puts el[0].send(Sequin::Membership.alert_colors[el[1]][:present]) unless options[key].nil? && options["show_all"].nil?
+      end
+      
+    end
+
+    private
+
+    def self.alert_colors
+      {
+        :found => {:present => "green", :absent => "red"} , 
+        :missing => {:present =>"red",  :absent => "green"} , 
+        :extra => {:present =>"yellow",  :absent => "green"}
+      }
+    end
+
+  end
+
+end

data/lib/sequin.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+require 'pp'
+require "thor"
+require 'fileutils'
+require 'yaml'
+require  File.expand_path(File.dirname(__FILE__)  + '/listing')
+require  File.expand_path(File.dirname(__FILE__)  + '/membership')
+
+module Sequin
+
+  class Seq < Thor
+
+
+    no_tasks do
+      # Some typical regular expressions for use by seq:match.
+      # When seq:generate config is called, this hash is dumped to a yaml file
+      def regex_hash
+        h = 
+        {'project1' =>  
+          {'dpx' => '^[0-9]{3}_[0-9]{3}_s3d_(rt|lf)_r[0-9]{2}\.[0-9]{4}\.dpx$',
+          'jpg' => '^[0-9]{3}_[0-9]{3}_s3d_r[0-9]{2}\.[0-9]{4}\.jpg$',
+          'mcx' => '^[0-9]{3}_[0-9]{3}_ver[0-9]{2,3}\.[0-9]{4}\.xml$'},
+          'project2' =>  
+          { 'dpx' => '^[a-z]{2}_[0-9]{3}_[0-9]{4}_(L|R|C)\.[0-9]{4,5}\.dpx$',
+          'jpg' => '^[a-z]{2}_[0-9]{3}_[0-9]{4}_(L|R|C)\.[0-9]{4,5}\.jpg$',
+          'mov' => '^[a-z]{2}_h264_[0-9]{3,4}x[0-9]{3,4}_(film|pal|ntsc)\.mov$' }
+        }
+      end
+
+      def regex_comments
+        <<-COMMENTS
+        #------------------------------------------------------------------------------------
+        #
+        # ~/.seq.yml 
+        #
+        # The regular expressions in this file represent naming conventions for various 
+        # projects and file_types. By matching filenames against these regexes, you can 
+        # quickly determine if they conform to the desired naming convention.
+        #
+        # The regexes are accessed on the command line using the hash keys separated by
+        # ":". i.e. seq match <files> --regex project1:dpx
+        #
+        # For regex newbies, here are some disections:
+        # ^[a-z]+_[0-9]{3}_s3d_(rt|lf)_r[0,1][0-9]\.[0-9]{4}\.dpx$
+        # ^           : the next character must be at the start of the string
+        # [a-z]+_     : one or more lower case letters followed by an underscore
+        # [0-9]{3}_   : exactly 3 numbers
+        # _s3d_       : "_s3d_"  
+        # (rt|lf)     : "rt" or "lf"
+        # r[0,1][0-9] : "r" followed by a 2 digit number between 00 and 19
+        # \.          : "." It must be escaped
+        # [0-9]{4}    : 4 padded number
+        # \.dpx       : ".dpx" extension. 
+        # $           : The preceding character must be the last character. "x" in this case.
+        #------------------------------------------------------------------------------------
+
+        COMMENTS
+      end
+
+    end
+
+
+    # When the user types seq and gives no task, we want to show
+    # the default help with our own mods added. 
+    default_task :usage
+
+    desc "usage", "Print the usage banner"
+    def usage
+      help  # default Task descriptions
+
+      puts <<-BANNER
+      ------------------------------------------------------------------------------------
+      Seq is a collection of commands to help deal with sequences on disk
+      
+      More help here
+      
+      BANNER
+
+    end
+
+
+
+
+
+
+
+    # map "i" => :inspect   
+    # desc "inspect [FILES]", "inspect raw sequence hash for debugging purposes"
+    # def inspect(*files)
+    #   files = Dir.new(".").entries if files.count == 0 
+    #   l = Sequin::Listing.new(files)
+    #   l.inspect
+    # end
+
+
+    map "l" => :list   
+    desc "list [FILES]", "list files as sequences"
+    method_option :verbose,:type => :numeric, :default => 1, :aliases => "-v", :desc => "0 => dont mention missing frames, 1 => show missing frame count, 2 => list missing frame numbers"
+    def list(*files)
+      unless files.count == 0 
+        l = Sequin::Listing.new(files)
+        l.list(options[:verbose])
+      else
+        msg = "No files."
+        puts msg.red
+        help :list
+        return
+      end
+    end
+
+
+
+
+    map "g" => :generate
+    desc "generate [NAME]", "Generate a seq config file containing regular expression definitions used in the seq:match command. Currently, NAME must be config"
+    method_option :force, :type => :boolean, :aliases => "-f", :desc => "Overwrite the file if it exists.", :default => false
+
+    def generate(name)
+      if name.downcase == "config"
+        yml = File.join(ENV['HOME'],".seq.yml")
+        FileUtils.rm(yml) if options[:force] && File.exists?(yml)
+        if File.exists?(yml)
+          msg = "Skipping write of #{yml} because it exists. Use --force to remove it."
+          puts msg.red
+          help :generate
+          return
+        else
+          puts "Generating #{yml}"
+          File.open(yml , 'w') do |f|
+            f.write(regex_comments)
+            YAML.dump(regex_hash, f)
+          end
+        end
+      else
+        msg = "Error: #{name} is not recognized."
+        puts msg.red
+        help :generate
+        return
+      end
+    end
+
+    map "c" => :check   
+    desc "check [SIGNATURE]", "Check the existence of files defined by a sequence signature."
+    method_option :show_missing, :type => :boolean, :aliases => "-m", :desc => "List files from the signature that are missing on disk"
+    method_option :show_extra, :type => :boolean, :aliases => "-e", :desc => "List files that are on disk but not in the signature"
+    method_option :show_found, :type => :boolean, :aliases => "-f", :desc => "List files from the signature that are on disk"
+    method_option :show_all, :type => :boolean, :aliases => "-a", :desc => "List the union of all files on disk and in the signature."
+    def check(*args)
+      signature = args.join(" ")
+
+      chunks = signature.split(/\[|\]/)
+      if chunks.count < 2
+        display_str = (signature.length > 60) ? "#{signature[0, 60]}..." : signature
+        msg = "Error: #{display_str} is not a valid sequence signature."
+        puts msg.red
+        help :check
+        return
+      end
+
+      fn_template = chunks[0].strip  
+      numbers = chunks[1].split(/([0-9]+)/) 
+
+      if numbers.count < 4
+        display_str = (signature.length > 60) ? "#{signature[0, 60]}..." : signature
+        msg = "Error: #{display_str} is not a valid sequence signature. Should have [<start> to <end> [by <by_frame>]]. "
+        puts msg.red
+        help :check
+        return
+      end
+
+
+      match = /#+/.match(fn_template)
+      if match.nil?  
+        msg = "Error: #{fn_template} has no # characters so does not represent a sequence."
+        puts msg.red
+        help :check
+        return
+      end
+
+      range_spec=Hash.new
+      range_spec[:padding] = match[0].length
+      range_spec[:start_frame] = numbers[1].to_i
+      range_spec[:end_frame] = numbers[3].to_i
+      range_spec[:by_frame] = numbers[5].to_i || 1
+
+      if range_spec[:start_frame].nil? || range_spec[:end_frame].nil? || ( range_spec[:start_frame] >= range_spec[:end_frame] )    
+        msg = "Error: start_frame #{start_frame} must be less than end_frame #{end_frame}."
+        puts msg.red
+        help :check
+        return
+      end
+
+      # range_spec.merge!(options)
+      membership =Sequin::Membership.new(fn_template, range_spec) 
+      
+      membership.output(options)
+
+    end
+
+
+
+
+    map "m" => :match   
+    desc "match [FILES]", "Match filename naming conventions using a regular expression."
+    method_option :regex, :type => :string, :aliases => "-r", :required => true, :desc => "Specify a regular expression literally, or by reference to one listed in ~/.seq.yml"
+    method_option :show_matched, :type => :boolean, :aliases => "-m", :desc => "List files that matched the regex in green"
+    method_option :show_failed, :type => :boolean, :aliases => "-f", :desc => "List files that failed to match the regex in red"
+    method_option :show_all, :type => :boolean, :aliases => "-a", :desc => "List all the files in order with color coding."
+    def match(*files)
+      keys =  options[:regex].split(":")
+      if keys.count != 2
+        the_regex = options[:regex]
+      else
+
+        begin
+          yml = File.join(ENV['HOME'],".seq.yml")
+          regexp_hash = YAML::load_file(yml)
+        rescue
+          msg = "Error: opening file #{yml} - please check the file exists and is valid YAML.\nIf it doesn't exist, run: seq generate config."
+          puts msg.red
+          help :match
+          return
+        end
+
+        unless regexp_hash.has_key?(keys[0]) 
+          msg = "Error: #{keys[0]} not in #{yml} - please check the file is valid YAML and has a top level key: #{keys[0]}."
+          puts msg.red
+          help :match
+          return
+        end
+
+        unless regexp_hash[keys[0]].has_key?(keys[1]) 
+          msg = "Error: #{keys[1]} not in #{yml} - please check the file is valid YAML and has a second level key: #{keys[1]}."
+          puts msg.red
+          help :match
+          return
+        end
+
+        the_regex = regexp_hash[keys[0]][keys[1]]
+
+      end
+
+      unless the_regex.nil?
+        l = Sequin::Listing.new(files)
+        l.match(the_regex, options) 
+      else
+        msg = "Error: No valid regular expression."
+        puts msg.red
+        help :match
+        return
+      end
+
+    end
+
+  end
+
+
+end

data/lib/sequin/version.rb

@@ -0,0 +1,3 @@
+module Sequin
+  VERSION = "0.0.1"
+end

data/sequin.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "sequin/version"
+
+Gem::Specification.new do |s|
+  s.name        = "sequin"
+  s.version     = Sequin::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Julian Mann"]
+  s.email       = ["julian.mann@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Tools to deal with file sequences.}
+  s.description = %q{Sequin is a collection of commands to list, test and modify sequences of files on disk.}
+  s.add_dependency('thor')
+  s.rubyforge_project = "sequin"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: sequin
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Julian Mann
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-21 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thor
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Sequin is a collection of commands to list, test and modify sequences of files on disk.
+email: 
+- julian.mann@gmail.com
+executables: 
+- seq
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/seq
+- lib/listing.rb
+- lib/membership.rb
+- lib/sequin.rb
+- lib/sequin/version.rb
+- sequin.gemspec
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: sequin
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Tools to deal with file sequences.
+test_files: []
+