evoker 0.0.8 → 0.0.9

data/lib/evoker.rb

@@ -21,6 +21,7 @@ module Evoker
   #   task :default => Evoker::ENTITIES
   ENTITIES = Rake::FileList[]
 
+  # Specialized task class for downloaded entities
   class EntityTask < Rake::FileTask
     ##
     # Parsed yaml config for the task
@@ -209,10 +210,10 @@ module Evoker
   # Get smart constant's effective value
   # 
   # Effective value is:
-  # 1. `ENV[name.to_s.upcase]` if present
+  # 1. +name.to_s.upcase+ environment variable, if present
   # 2. Otherwise, user-defined top-level constant named `name.to_s.upcase`
   # 3. Otherwise, default set with {smart_const}
-  # 4. Otherwise, nil
+  # 4. Otherwise, +nil+
   # 
   # @param name [#to_s] constant's name
   def smart_const_get(name)

data/lib/evoker/local_cache.rb

@@ -11,50 +11,87 @@ module Evoker
 
   module_function
 
-  # Download a file using wget, or copy it from local cache
+  # Cache result of a file task in local directory.
+  #
+  # If cached `output_file` exists and matches the checksum (if one is
+  # given), task to copy file from cache directory to target is
+  # returned, and block is not executed.
   # 
-  # @param [#to_s] url address to download from
-  # @param [Hash] opts options (same as wget, + :checksum)
-  # @option opts [#to_s] :checksum sha256 sum of file to download
-  def cached_wget(url, opts={})
-    opts[:output_file] ||= begin
-                             require 'uri'
-                             URI.parse(url).path.split('/').last
-                           end
+  # If cached `output_file` exists but does not match the checksum, it is
+  # removed.
+  # 
+  # If `output file` does not exist or did not match the checksum,
+  # block is executed. Block should return a file task. This task will
+  # have extra code appended:
+  # 
+  # - a checksum test: if checksum is given - error is raised if
+  #   created file does not match the checksum
+  # - copying created file to cache directory
+  # 
+  # Cache directory is taken from a smart constant (see
+  # {#smart_const_get}) `:cache_path`, default is 'cache'.
+  # 
+  # @param [String] output_file File to uncache or create
+  # @param [String] checksum SHA-256 checksum of file (optional, but recommended)
+  # @yield Task to create file if not found in cache
+  # @return Task to uncache or create file
+  def cached(output_file, checksum=nil)
+    raise 'Block for Evoker::cached not provided' unless block_given?
 
     cached_path_elts = []
     cached_path_elts << smart_const_get(:cache_path)
-    cached_path_elts << opts[:checksum][0..1] if opts[:checksum]
-    cached_path_elts << opts[:checksum][2..3] if opts[:checksum]
-    cached_path_elts << File.basename(opts[:output_file])
+    cached_path_elts << checksum[0..1] if checksum
+    cached_path_elts << checksum[2..3] if checksum
+    cached_path_elts << File.basename(output_file)
     cached_path = File.join(*cached_path_elts)
 
+    if File.exists?(cached_path) &&
+        checksum &&
+        Digest::SHA256.file(cached_path).hexdigest != checksum
+      puts "WARN: checksum mismatch for cached #{File.basename(output_file)}, removing."
+      FileUtils::rm cached_path
+    end
+
     if File.exists?(cached_path)
-      if opts[:checksum] &&
-          Digest::SHA256.file(cached_path).hexdigest != opts[:checksum]
-        puts "WARN: checksum mismatch for cached #{File.basename(opts[:output_file])}, removing."
-        FileUtils::rm cached_path
-      else
-        # no checksum or checksum match, we can proceed
-        file opts[:output_file] do
-          FileUtils::cp cached_path, opts[:output_file]
-        end
+      # Cached file exists and matches the given checksum
+      rv = file output_file do
+        FileUtils::cp cached_path, output_file
       end
     else
-      wget url, opts
-      # add caching after downloading
-      task opts[:output_file] do
-        if opts[:checksum] &&
-            Digest::SHA256.file(opts[:output_file]).hexdigest != opts[:checksum]
-          raise "Checksum mismatch for downloaded #{File.basename(opts[:output_file])}."
+      # Cached file does not exist
+      rv = yield output_file
+
+      # Cache file after downloading
+      task rv do
+        if checksum &&
+            Digest::SHA256.file(output_file).hexdigest != checksum
+          raise "Checksum mismatch for downloaded #{File.basename(output_file)}."
         end
         FileUtils::mkdir_p(File.dirname(cached_path))
-        FileUtils::cp opts[:output_file], cached_path
+        FileUtils::cp output_file, cached_path
       end
     end
-    CLEAN << opts[:output_file]
+
+    CLEAN << output_file
     CLOBBER << cached_path
 
-    file opts[:output_file]
+    rv
+  end
+
+
+  # Download a file using wget, or copy it from local cache
+  # 
+  # @param [#to_s] url address to download from
+  # @param [Hash] opts options (same as wget, + :checksum)
+  # @option opts [#to_s] :checksum sha256 sum of file to download
+  def cached_wget(url, opts={})
+    opts[:output_file] ||= begin
+                             require 'uri'
+                             URI.parse(url).path.split('/').last
+                           end
+
+    cached(opts[:output_file], opts[:checksum]) do
+      wget url, opts
+    end
   end
 end

data/lib/evoker/version.rb

@@ -1,10 +1,19 @@
 module Evoker
+  # Version information
   module VERSION
+    # Major version number
     MAJOR = 0
+
+    # Minor version number
     MINOR = 0
-    TINY  = 8
+
+    # Tiny version number
+    TINY  = 9
+
+    # Full version number as string
     STRING = [MAJOR, MINOR, TINY].join('.')
 
+    # Raise an error if Evoker version is older than required.
     def VERSION.require_version(major, minor=0, tiny=0)
       unless ([MAJOR, MINOR, TINY] <=> [major, minor, tiny]) >= 0
         raise "Evoker version #{MAJOR}.#{MINOR}.#{TINY} is below required #{major}.#{minor}.#{tiny}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: evoker
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-15 00:00:00.000000000Z
+date: 2012-05-03 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70170471088160 !ruby/object:Gem::Requirement
+  requirement: &70142202183640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 0.9.2
   type: :runtime
   prerelease: false
-  version_requirements: *70170471088160
+  version_requirements: *70142202183640
 description: ! 'Evoker is an add-on to Rake to download and manage project''s external
 
   dependencied, update them as needed, cache them, etc.
@@ -64,3 +64,4 @@ signing_key:
 specification_version: 3
 summary: Rake add-on to download and manage project's external dependencies
 test_files: []
+has_rdoc: