tap 0.12.4 → 0.17.0

data/lib/tap/root/utils.rb

@@ -0,0 +1,220 @@
+require 'tap/root/versions'
+autoload(:FileUtils, 'fileutils')
+
+module Tap
+  class Root
+  
+    # A variety of utility methods for working with paths.
+    module Utils
+      include Versions
+    
+      # Regexp to match a windows-style root path.
+      WIN_ROOT_PATTERN = /^[A-z]:\//
+    
+      module_function
+    
+      # Returns the path of 'path' relative to dir.  Both dir and path will
+      # be expanded to dir_string, if specified, before the relative path is
+      # determined.  Returns nil if the path is not relative to dir.
+      #
+      #   relative_path('dir', "dir/path/to/file.txt")  # => "path/to/file.txt"
+      #
+      def relative_path(dir, path, dir_string=Dir.pwd)
+        if dir_string
+          dir = File.expand_path(dir, dir_string)
+          path = File.expand_path(path, dir_string)
+        end
+        return nil unless Utils.relative?(dir, path, false)
+    
+        # use dir.length + 1 to remove a leading '/'.   If dir.length + 1 >= expanded.length 
+        # as in: relative_path('/path', '/path') then the first arg returns nil, and an 
+        # empty string is returned
+        path[(dir.chomp("/").length + 1)..-1] || ""
+      end
+    
+      # Generates a target path translated from the source_dir to the
+      # target_dir. Raises an error if the path is not relative to the
+      # source_dir.    
+      #
+      #    translate("/path/to/file.txt", "/path", "/another/path")  # => '/another/path/to/file.txt'
+      #
+      def translate(path, source_dir, target_dir)
+        unless relative_path = relative_path(source_dir, path)
+          raise ArgumentError, "\n#{path}\nis not relative to:\n#{source_dir}"
+        end
+        File.join(target_dir, relative_path)
+      end
+    
+      # Returns the path, exchanging the extension with extname.  Extname may
+      # optionally omit the leading period.
+      #
+      #   exchange('path/to/file.txt', '.html')  # => 'path/to/file.html'
+      #   exchange('path/to/file.txt', 'rb')     # => 'path/to/file.rb'
+      #
+      def exchange(path, extname)
+        "#{path.chomp(File.extname(path))}#{extname[0] == ?. ? '' : '.'}#{extname}"
+      end
+  
+      # Lists all unique paths matching the input glob patterns.  
+      def glob(*patterns)
+        Dir[*patterns].uniq
+      end
+  
+      # Lists all unique versions of path matching the glob version patterns. If
+      # no patterns are specified, then all versions of path will be returned.
+      def version_glob(path, *vpatterns)
+        paths = []
+      
+        vpatterns << "*" if vpatterns.empty?
+        vpatterns.each do |vpattern| 
+          paths.concat Dir.glob(version(path, vpattern)) 
+  
+          # extra work to include the default version path for any version
+          paths << path if vpattern == "*" && File.exists?(path)
+        end
+      
+        paths.uniq
+      end
+    
+      # Path suffix glob.  Globs along the paths for the specified suffix
+      # pattern.
+      def suffix_glob(suffix_pattern, *paths)
+        paths.collect! {|path| File.join(path, suffix_pattern) }
+        Dir[*paths].uniq
+      end
+    
+      # Like Dir.chdir but makes the directory, if necessary, when mkdir is 
+      # specified. chdir raises an error for non-existant directories, as well
+      # as non-directory inputs.
+      def chdir(dir, mkdir=false, &block)
+        dir = File.expand_path(dir)
+      
+        unless File.directory?(dir)
+          if !File.exists?(dir) && mkdir
+            FileUtils.mkdir_p(dir)
+          else
+            raise ArgumentError, "not a directory: #{dir}"
+          end
+        end
+      
+        Dir.chdir(dir, &block)
+      end
+    
+      # Prepares the input path by making the parent directory for path. If a
+      # block is given, a file is created at path and passed to it; in this
+      # way files with non-existant parent directories are readily made.
+      #
+      # Returns path.
+      def prepare(path)
+        dirname = File.dirname(path)
+        FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
+        File.open(path, "w") {|io| yield(io) } if block_given?
+        path
+      end
+    
+      # The path root type indicating windows, *nix, or some unknown style of
+      # paths (:win, :nix, :unknown).
+      def path_root_type
+        @path_root_type ||= case
+        when RUBY_PLATFORM =~ /mswin/ && File.expand_path(".") =~ WIN_ROOT_PATTERN then :win 
+        when File.expand_path(".")[0] == ?/ then :nix
+        else :unknown
+        end
+      end
+    
+      # Returns true if the input path appears to be an expanded path, based on
+      # path_root_type.  
+      #
+      # If root_type == :win returns true if the path matches WIN_ROOT_PATTERN.
+      #
+      #   expanded?('C:/path')  # => true
+      #   expanded?('c:/path')  # => true
+      #   expanded?('D:/path')  # => true
+      #   expanded?('path')     # => false
+      #
+      # If root_type == :nix, then expanded? returns true if the path begins
+      # with '/'.
+      #
+      #   expanded?('/path')  # => true
+      #   expanded?('path')   # => false
+      #
+      # Otherwise expanded? always returns nil.
+      def expanded?(path, root_type=path_root_type)
+        case root_type
+        when :win 
+          path =~ WIN_ROOT_PATTERN ? true : false
+        when :nix  
+          path[0] == ?/
+        else
+          nil
+        end
+      end
+    
+      # Returns true if path is relative to dir.  Both path and dir will be
+      # expanded relative to dir_string, if specified.
+      def relative?(dir, path, dir_string=Dir.pwd)
+        if dir_string
+          dir = File.expand_path(dir, dir_string)
+          path = File.expand_path(path, dir_string)
+        end
+      
+        path.rindex(dir, 0) == 0
+      end
+    
+      # Trivial indicates when a path does not have content to load.  Returns
+      # true if the file at path is empty, non-existant, a directory, or nil.
+      def trivial?(path)
+        path == nil || !File.file?(path) || File.size(path) == 0
+      end
+    
+      # Empty returns true when dir is an existing directory that has no files.
+      def empty?(dir)
+        File.directory?(dir) && (Dir.entries(dir) - ['.', '..']).empty?
+      end
+    
+      # Returns the path segments for the given path, splitting along the path 
+      # divider.  Env paths are always represented by a string, if only an 
+      # empty string.
+      #
+      #   os          divider    example
+      #   windows     '\'        split('C:\path\to\file')  # => ["C:", "path", "to", "file"]
+      #   *nix        '/'        split('/path/to/file')    # => ["", "path", "to", "file"]
+      # 
+      # The path is always expanded relative to the expand_dir; so '.' and
+      # '..' are resolved.  However, unless expand_path == true, only the
+      # segments relative to the expand_dir are returned.  
+      #
+      # On windows (note that expanding paths allows the use of slashes or
+      # backslashes):
+      #
+      #   Dir.pwd                                          # => 'C:/'
+      #   split('path\to\..\.\to\file')                    # => ["C:", "path", "to", "file"]
+      #   split('path/to/.././to/file', false)             # => ["path", "to", "file"]
+      #
+      # On *nix (or more generally systems with '/' roots):
+      #
+      #   Dir.pwd                                          # => '/'
+      #   split('path/to/.././to/file')                    # => ["", "path", "to", "file"]
+      #   split('path/to/.././to/file', false)             # => ["path", "to", "file"]
+      #
+      def split(path, expand_path=true, expand_dir=Dir.pwd)
+        path = if expand_path
+          File.expand_path(path, expand_dir)
+        else
+          # normalize the path by expanding it, then
+          # work back to the relative path as needed
+          expanded_dir = File.expand_path(expand_dir)
+          expanded_path = File.expand_path(path, expand_dir)
+          expanded_path.index(expanded_dir) != 0 ? expanded_path : relative_path(expanded_dir, expanded_path)
+        end
+
+        segments = path.scan(/[^\/]+/)
+
+        # add back the root path as needed on *nix 
+        segments.unshift "" if path[0] == ?/
+        segments
+      end
+    
+    end
+  end
+end

data/lib/tap/{support → root}/versions.rb

@@ -1,15 +1,14 @@
 module Tap
-  module Support
-    
+  class Root    
     # Version provides methods for adding, removing, and incrementing versions
-    # at the end of filepaths.  Versions are all formatted like:
-    # 'filepath-version.extension'.
+    # at the end of paths.  Versions are all formatted like:
+    # 'path-version.extension'.
     #
     module Versions
-      
-      # Adds a version to the filepath.  Versioned filepaths follow the format: 
-      # 'path-version.extension'.  If no version is specified, then the filepath 
-      # is returned.
+    
+      # Adds a version to the path.  Versioned paths follow the format:
+      # 'path-version.extension'.  If no version is specified, then the
+      # path is returned.
       #
       #   version("path/to/file.txt", 1.0)            # => "path/to/file-1.0.txt"
       #
@@ -22,15 +21,15 @@ module Tap
           path.chomp(extname) + '-' + version + extname
         end
       end
-      
-      # Increments the version of the filepath by the specified increment.  
+    
+      # Increments the version of the path by the specified increment.  
       #
       #   increment("path/to/file-1.0.txt", "0.0.1")  # => "path/to/file-1.0.1.txt"
       #   increment("path/to/file.txt", 1.0)          # => "path/to/file-1.0.txt"
       #
       def increment(path, increment)
         path, version = deversion(path)
-        
+      
         # split the version and increment into integer arrays of equal length
         increment, version = [increment, version].collect do |vstr| 
           begin
@@ -39,8 +38,11 @@ module Tap
             raise "Bad version or increment: #{vstr}"
           end
         end
-        version.concat Array.new(increment.length - version.length, 0) if increment.length > version.length
-
+      
+        if increment.length > version.length
+          version.concat Array.new(increment.length - version.length, 0)
+        end
+      
         # add the increment to version
         0.upto(version.length-1) do |i|
           version[i] += (increment[i] || 0)
@@ -48,9 +50,10 @@ module Tap
 
         self.version(path, version.join("."))
       end
-      
-      # Splits the version from the input path, then returns the path and version.  
-      # If no version is specified, then the returned version will be nil.
+    
+      # Splits the version from the input path, then returns the path and
+      # version. If no version is specified, then the returned version will be
+      # nil.
       #
       #   deversion("path/to/file-1.0.txt")           # => ["path/to/file.txt", "1.0"]
       #   deversion("path/to/file.txt")               # => ["path/to/file.txt", nil]
@@ -60,8 +63,8 @@ module Tap
         extname = '' if extname =~ /^\.\d+$/
         path =~ /^(.*)-(\d(\.?\d)*)#{extname}$/ ? [$1 + extname, $2] : [path, nil]
       end
-      
-      # A <=> comparison for versions.  compare_versions can take strings, 
+    
+      # A <=> comparison for versions.  compare_versions can take strings,
       # integers, or even arrays representing the parts of a version.
       #
       #   compare_versions("1.0.0", "0.9.9")          # => 1
@@ -69,17 +72,17 @@ module Tap
       #   compare_versions([0,9], [0,9,1])            # => -1
       def compare_versions(a,b)
         a, b = [a,b].collect {|item| to_integer_array(item) }
-        
+      
         # equalize the lengths of the integer arrays
         d = b.length - a.length
         case 
         when d < 0 then b.concat Array.new(-d, 0)
         when d > 0 then a.concat Array.new(d, 0)
         end 
-      
+    
         a <=> b
       end
-      
+    
       # Version unique.  Select the latest or earliest versions of each file
       # in the array.  For paths that have no version, vniq considers any
       # version to beat no version.  The order of paths is preserved by
@@ -104,25 +107,25 @@ module Tap
           base, version = deversion(path)
           (unique[base] ||= []) << version
         end
-        
+      
         results = []
         unique.each_pair do |base, versions|
           versions = versions.sort {|a, b| compare_versions(a,b) }
           winner = earliest ? versions.shift : versions.pop
           results << version(base, winner)
         end
-        
+      
         results = results.sort_by do |path|
           array.index(path)
         end if preserve_order
-        
+      
         results
       end
-      
+    
       private
-      
-      # Converts an input argument (typically a string or an array) 
-      # to an array of integers.  Splits version string on "."
+    
+      # Converts an input argument (typically a string or an array) to an
+      # array of integers.  Splits version string on "."
       def to_integer_array(arg)
         arr = case arg
         when Array then arg
@@ -130,7 +133,6 @@ module Tap
         end
         arr.collect {|i| i.to_i}
       end
-      
     end
   end
 end

data/lib/tap/schema.rb

@@ -0,0 +1,248 @@
+require 'tap/schema/utils'
+require 'tap/schema/parser'
+
+module Tap
+  class Schema
+    class << self
+      def load(str)
+        new(YAML.load(str) || {})
+      end
+      
+      def load_file(path)
+        load(File.read(path))
+      end
+    end
+    
+    include Utils
+    
+    # A hash of task schema describing individual tasks in a workflow.  Tasks
+    # only require a class, but may contain configurations and even arguments
+    # for enque.  Individual tasks may be a hash or an array.  The tasks are
+    # resolved if they take one of these forms:
+    #
+    #   tasks:
+    #     key: {:class: TaskClass, ...}
+    #     key: [TaskClass, ...]
+    #   
+    attr_reader :tasks
+    
+    # An array of join schema that describe how to join tasks together.  Joins
+    # have arrays of inputs and outputs that reference task keys.  Individual
+    # joins may be a hash or an array.  The joins are resolved if they take
+    # one of these forms:
+    #
+    #   joins:
+    #   - [[inputs], [outputs], {:class: JoinClass, ...}]
+    #   - [[inputs], [outputs], [JoinClass, ...]]
+    #
+    attr_reader :joins
+    
+    # An array of [key, [args]] data that indicates the tasks and arguments
+    # to be added to an application during build.  If args are not specified,
+    # then the arguments specified in the task schema are used.
+    #
+    #   queue:
+    #   - key                  # uses tasks[key] arguments
+    #   - [key, [1, 2, 3]]     # enques tasks[key] with [1, 2, 3]
+    #
+    attr_reader :queue
+    
+    # An array of middleware to build onto the app.
+    attr_reader :middleware
+    
+    def initialize(schema={})
+      @tasks = hashify(schema['tasks'] || {})
+      
+      @joins = dehashify(schema['joins'] || []).collect do |join|
+        inputs, outputs, join = dehashify(join)
+        [inputs, outputs, join]
+      end
+      
+      @queue = dehashify(schema['queue'] || []).collect do |queue|
+        dehashify(queue)
+      end
+      
+      @middleware = dehashify(schema['middleware'] || [])
+    end
+    
+    def resolve!
+      tasks.dup.each_pair do |key, task|
+        task ||= {}
+        tasks[key] = resolve(task) do |id, data|
+          yield(:task, id || key, data)
+        end
+      end
+      
+      joins.collect! do |inputs, outputs, join|
+        join ||= {}
+        join = resolve(join) do |id, data|
+          yield(:join, id || 'join', data)
+        end
+        [inputs, outputs, join]
+      end
+      
+      middleware.collect! do |m|
+        resolve(m) do |id, data|
+          yield(:middleware, id, data)
+        end
+      end
+      
+      self
+    end
+    
+    def validate!
+      errors = []
+      tasks.each do |key, task|
+        unless resolved?(task)
+          errors << "unknown task: #{task}"
+        end
+      end
+      
+      joins.each do |inputs, outputs, join|
+        unless resolved?(join)
+          errors << "unknown join: #{join}"
+        end
+        
+        inputs.each do |key| 
+          unless tasks.has_key?(key)
+            errors << "missing join input: #{key}"
+          end
+        end
+        
+        outputs.each do |key| 
+          unless tasks.has_key?(key)
+            errors << "missing join output: #{key}"
+          end
+        end
+      end
+      
+      # queue.each do |(key, args)| 
+      #   unless tasks.has_key?(key)
+      #     errors << "missing task: #{key}"
+      #   end
+      # end
+      
+      middleware.each do |m|
+        unless resolved?(m)
+          errors << "unknown middleware: #{m}"
+        end
+      end
+      
+      unless errors.empty?
+        prefix = if errors.length > 1
+          "#{errors.length} build errors\n"
+        else
+           ""
+        end
+
+        raise "#{prefix}#{errors.join("\n")}\n"
+      end
+      
+      self
+    end
+    
+    def cleanup!
+      joins.delete_if do |inputs, outputs, join|
+        
+        # remove missing inputs
+        inputs.delete_if  {|key| !tasks.has_key?(key) }
+        
+        # remove missing outputs
+        outputs.delete_if {|key| !tasks.has_key?(key) }
+        
+        # remove orphan joins
+        inputs.empty? || outputs.empty?
+      end
+      
+      # remove inputs without a task
+      queue.delete_if do |(key, inputs)|
+        !tasks.has_key?(key)
+      end
+      
+      self
+    end
+    
+    def scrub!
+      tasks.each do |key, task|
+        yield(task)
+      end
+      
+      joins.each do |inputs, outputs, join|
+        yield(join)
+      end
+    end
+    
+    def build(app)
+      # instantiate tasks
+      tasks = {}
+      arguments = {}
+      self.tasks.each_pair do |key, task|
+        instance, args = instantiate(task, app)
+      
+        tasks[key] = instance
+        arguments[key] = args
+      end
+      
+      # build the workflow
+      self.joins.each do |inputs, outputs, join|
+        inputs = inputs.collect {|key| tasks[key] }
+        outputs = outputs.collect {|key| tasks[key] }
+        instantiate(join, app).join(inputs, outputs)
+      end
+      
+      # utilize middleware
+      self.middleware.each do |middleware|
+        instantiate(middleware, app)
+      end
+      
+      # enque tasks
+      queue.each do |(key, inputs)|
+        unless inputs
+          inputs = arguments[key]
+        end
+        
+        app.enq(tasks[key], *inputs) if inputs
+      end
+      
+      tasks
+    end
+    
+    def traverse
+      map = {}
+      self.tasks.each_pair do |key, task|
+        map[key] = [[],[]]
+      end
+      
+      index = 0
+      self.joins.each do |inputs, outputs, join|
+        inputs.each do |key|
+          map[key][1] << index
+        end
+        
+        outputs.each do |key|
+          map[key][0] << index
+        end
+        
+        index += 1
+      end
+      
+      map.keys.sort.collect do |key|
+        [key, *map[key]]
+      end
+    end
+    
+    # Creates an hash dump of self.
+    def to_hash
+      { 'tasks' => tasks, 
+        'joins' => joins, 
+        'queue' => queue, 
+        'middleware' => middleware
+      }
+    end
+    
+    # Converts self to a hash and serializes it to YAML.
+    def dump(io=nil)
+      YAML.dump(to_hash, io)
+    end
+  end
+end