z_build 1.1.0

data/lib/z_build.rb

@@ -0,0 +1,765 @@
+require 'tempfile'
+
+# @author Shaun Bruno <shaun.bruno@gmail.com>
+# @copyright Copyright 2013 Shaun Bruno
+#
+# Z'Build module is a collection of commonly used functions for creating 
+# light-weight build processes, written in Ruby. This library was authored in my spare time
+# for {https://zoosk.com Zoosk} with a desire for more easily maintainable build processes, 
+# with a love for Ruby, and with a strong dislike for PHING/ANT and XML builds systems. 
+# At it's core the Z'Build suite is intended to be minimal, sufficient, and transparent. 
+# If there is some aspect of your existing build that cannot be translated or mimicked 
+# with a series of Z'Build functions, then there may well be a missing feature, or 
+# otherwise there might be an opportunity to simplify your processes. However, it is 
+# expected that custom needs will require specialized code and as a library Z'Build is 
+# designed to be easily extended and works very well in conjuncation with build tools 
+# such as Ruby Rake.  It is not meant to be a stand-alone build replacement - Rake/Thor/etc 
+# already do that very well. Here's to hoping Z'Build makes your builds faster, 
+# your code simpler, and your life easier!
+# 
+# @example
+#   # This simple example build requires a repository checkout and
+#   # a file system copy with file token replacement.
+#
+#   require 'z_build'
+#   include ZBuild  # brings module functions into global scope
+#
+#   clock 'Starting Build' do
+#     set_deploy_dir '/path/to/release'
+#     run 'git clone https://github.com/your_organization/project.git'
+#     deploy_cp 'project/', '', :recurse => true, :tokens => props_to_hash('templates/props.txt')
+#   end
+module ZBuild
+  
+  # Run shell commands
+  # 
+  # @example
+  #   run 'mysql -h127.0.0.1 -uroot -psomethingsupersecret', :regex_mask => /-p[a-z]*/, :mask_replace => '-p<BET YOU WISH YOU KNEW>'
+  #   => [INFO] Running Command: mysql -h127.0.0.1 -uroot -p<BET YOU WISH YOU KNEW>
+  #
+  # @param [String] shell_command 
+  # @param [Hash] opts options used for execution
+  # @option opts [String] :desc ('Running Command') description of command being run
+  # @option opts [bool] :quiet (false) true to supress description output of command
+  # @option opts [Regexp|String] :regex_mask when :quiet => false, mask output description 
+  #   of the characters captured by this regex or string
+  # @option opts [String] :mask_replace ('xxxx') mask used when :regex_mask => true
+  # @option opts [bool] :check_return (false) true to raise error when result of
+  #   shell command ran is non-empty
+  # @return [String] resultant output from running shell command
+  # @raise [RuntimeError] when :check_return => true and shell command exec has a non empty result
+  def run(shell_command, opts={})
+    desc = opts[:desc] ? opts[:desc].to_s : "Running Command"
+    if !opts[:quiet]
+      output = "#{desc}: #{shell_command}"
+      
+      if opts[:regex_mask]
+        mask_replace = opts[:mask_replace] ? opts[:mask_replace] : 'xxxx'
+        output.gsub! opts[:regex_mask], mask_replace       
+      end
+      
+      self.info output
+    end
+    
+    result = `#{shell_command}`
+    
+    if opts[:check_return] && !result.empty?
+      raise "run failed for shell command: #{shell_command}"
+    end
+   
+    result
+  end
+  
+  # Writes the content string to the specified file path.
+  #
+  # @param [String] path file path to write content string to relative to the set deploy path
+  # @param [String] str content string to write
+  # @param [Fixnum] perm the permissions for the file created
+  def deploy_write(path, str, perm=0750)
+    deploy_path = self.deploy_path path
+    
+    File.open(deploy_path, 'w', perm) do |f|
+      f.write str
+    end
+  end
+  
+  # Create all directories at the specified deploy path.
+  #
+  # @param [String] path directory path to create relative to the set deploy path
+  # @param [Fixnum] perm the permissions for the directory/directories created
+  # @note this function works like the shell mkdir -p, so that /multiple/paths/deep will create all
+  #   directories in the path
+  def deploy_mkdir(path, perm=0750)
+    deploy_path = self.deploy_path path
+    
+    # only create when does not already exist
+    if !File.exist? deploy_path
+      FileUtils.mkdir_p deploy_path, :mode => perm
+    end  
+  end
+  
+  # Copy files from the working directory to deploy path. When the recurse flag is set,
+  # contents from first directory's contents are always copied as content to the second directory.
+  # If the intended behavior is to copy the first directory itself (in unix shell cp -r 
+  # /path/dir dest/ vs cp -r /path/dir/ dest/), then one should instead call 
+  # deploy_mkdir prior to a deploy_copy. This simplistic behavior is to make the calls 
+  # more explicit and consequences less subtle than in a standard shell. The best way
+  # to conceptualzie this behavior is <b>deploy_cp always copies directory content, 
+  # and only sub-directories (as content) when the recurse flag is set</b>.
+  # 
+  # @example
+  #   # this call required once for all subsequent calls
+  #   set_deploy_dir '/Users/myname/Dropbox'
+  #
+  #   # will copy file to /Users/myname/Dropbox/text_file.txt
+  #   deploy_cp '/Users/myname/Documents/text_file.txt', ''
+  #
+  #   # will copy file and rename to /Users/myname/Dropbox/new_name.txt
+  #   deploy_cp '/Users/myname/Documents/text_file.txt', 'new_name.txt'
+  #
+  #   # prior example with token replacement
+  #   deploy_cp '/Users/myname/Documents/text_file.txt', 'new_name.txt', :tokens => {:DOG_TYPE => 'Chihuahua'}
+  #
+  #   # will copy all txt files to /Users/myname/Dropbox/
+  #   deploy_cp '/Users/myname/Documents/*.txt', './'
+  #
+  #   # will copy all txt files to /Users/myname/Dropbox/, excluding text_file.txt
+  #   deploy_cp '/Users/myname/Documents/*.txt', './', :exclude => '/Users/myname/Documents/text_file.txt'
+  #
+  #   # working directory set allows for less vebose copying
+  #   set_working_dir '/Users/myname/Documents/'
+  #   deploy_cp '*.txt', './', :exclude => 'text_file.txt'
+  #
+  #   # working directory set not required for use
+  #   reset_working_dir
+  #   # will recursively copy all files and directories within Documents/ to /Users/myname/Dropbox/
+  #   deploy_cp '/Users/myname/Documents/', './', :recurse => true
+  #
+  #   # prior example with token replacement on every file copied
+  #   deploy_cp '/Users/myname/Documents/', './', :recurse => true, :tokens => {:DOG_TYPE => 'Chihuahua'}
+  #
+  # @param [String] from path to copy from working directory, may be a glob when :recurse => false,
+  #   must be a directory when :recurse => true
+  # @param [String] to destination path to copy file/files, may be a file when :recurse => false,
+  #   must be a directory when :recurse => true
+  # @param [Hash] opts options for copy operation
+  # @option opts [String] :recurse (FalseClass) recursively copy from to deploy path
+  #   retaining all original file and directory names 
+  # @option opts [Array] :exclude list of files and directories to exclude from copying,
+  #   specified by paths relative to the currently set working directory
+  # @option opts [Hash] :tokens has with tokens keyed to their replacements to use on every file copied
+  # @option opts [String] :token_prefix when :tokens are set consider prefix for every replacement
+  # @option opts [String] :token_suffix when :tokens are set consider suffix for every replacement
+  #
+  # @raise [RuntimeError] on attempting to copy a directory as [from] when :recurse => false
+  # @raise [RuntimeError] when :recurse => true and [from] and [to] paths are not both directories
+  #
+  # @see #set_working_dir
+  # @see #set_deploy_dir
+  #
+  def deploy_cp(from, to, opts={})
+    working_path_given    = self.working_path from
+    deploy_path_given     = self.deploy_path to
+    queued_dirs           = []
+    queued_files          = {}
+    working_exclude       = opts[:exclude] ? opts[:exclude].to_a : []
+         
+    if opts[:recurse]
+      
+      if !File.directory? from
+        raise "Working path must be a directory when :recurse => true, given: #{working_path_given}"
+      end
+      
+      if !File.directory? deploy_path_given
+        raise "Deploy path must be a directory when :recurse => true, given: #{deploy_path_given}"
+      end
+      
+			if !opts[:tokens] && !opts[:exclude]
+        # when no token replacement and no exclusion is required, faster to do system copy
+        # always join path to /. so that the contents will always be copied, and never the 
+        # directory itself - this maintains consistent behavior for the function
+        # FileUtils requires the slash-dot /. whereas shell only requires either / or /*
+				FileUtils.cp_r File.join(working_path_given, '/').concat('.'), deploy_path_given
+				return
+      end
+      
+      # from - the directory relative to working dir
+      # deploy_path_given - the directory relative to the deploy dir
+    
+      self.walk_path(from) do |f_path, is_dir|
+        if working_exclude.include? f_path.sub('./','') # glob prefixes ./ relative to root
+          # ignore files or directories marked for exclusion
+          next
+        end
+        
+        if is_dir
+          # deploy_mkdir already creates relative to deploy path, so enqueue relative path
+          queued_dirs.push File.join to, f_path.sub(from, '')
+          next
+        end
+        
+        # when recurse is invoked always copy the actual file name to the deploy dir given
+        queued_files[f_path] = File.join deploy_path_given, f_path.sub(from, '')
+      end
+    else
+      if File.directory? self.working_path(from)
+        raise "Path given is a directory - not copied: #{self.working_path(from)}"
+      end
+    
+      if !opts[:tokens] && !opts[:exclude]
+        # when no token replacement and no exclusion is required, faster to do system copy
+        if working_path_given.include? '*'
+					FileUtils.cp Dir.glob(working_path_given), deploy_path_given
+				else
+					FileUtils.cp working_path_given, deploy_path_given
+				end
+				return
+      end
+    
+      self.glob(from) do |f_path, is_dir|
+        if working_exclude.include? f_path.sub('./','') # glob prefixes ./ relative to root
+          # ignore files or directories marked for exclusion
+          next
+        end
+        
+        if File.directory? deploy_path_given
+          # given dir, so retain name of original file
+          dest_path = File.join(deploy_path_given, File.basename(f_path))
+        else 
+          # deploy_path given is an actual file target
+          dest_path = deploy_path_given
+        end 
+        
+        # f_path provided is relative to working dir - dest is absolute to deploy target
+        queued_files[f_path] = dest_path
+      end
+    end
+
+    # all directories queued are relative to deploy target
+    queued_dirs.each do |d|
+      self.deploy_mkdir d
+    end
+
+    queued_files.each do |relative_src, absolute_dest|
+      File.open(absolute_dest, 'w') do |fh|
+        if opts[:tokens].is_a? Hash
+          fh.write self.token_replace_file(relative_src, opts[:tokens], opts[:token_prefix].to_s, opts[:token_suffix].to_s)
+        else
+          fh.write self.file_to_str(relative_src)
+        end
+      end
+    end
+  end
+  
+  # Specify a deploy directory - with a deploy directory set all functions requiring
+  # absolute paths for deploy parameters will become relative to the deploy directory set.
+  # This is not to be confused with the working directory - (see set_working_dir)
+  #
+  # @param [String] path the directory to set as the deploy directory.
+  # @return [String] the path set
+  # @raise [RuntimeError] when specified path is not a valid directory
+  # @see #set_working_dir
+  #
+  # @note When deploy dir is set all function paramaters for the deploy directory will
+  #   be assumed relative as well.
+  #
+  def set_deploy_dir(path)
+    if !File.directory? path
+      raise "Specified path is not a directory: #{path}"
+    end
+    
+    @deploy_dir = path
+  end
+  
+  # Clears the deploy directory variable - requiring ZBuild specified deploy paths to be absolute.
+  # By default all specified deploy paths must be absolute, however when a deploy 
+  # directory is set, invoking this method requires them to be absolute again.
+  #
+  # @see #set_deploy_dir
+  #
+  def reset_deploy_dir
+    @deploy_dir = nil
+  end
+  
+  # Specify a working directory - with a working directory set all functions requiring
+  # absolute paths will become relative to the working directory. The exception is
+  # paths meant for deploy function parameters - (see set_deploy_dir)
+  #
+  # @example
+  #   str1 = file_to_str '/absolute/path/to/file.txt'
+  #
+  #   set_working_dir '/absolute'
+  #   str2 = file_to_str 'path/to/file.txt'
+  #
+  #   str1 == str2
+  #   => true
+  #
+  # @param [String] path the directory to set as the working directory.
+  # @return [String] the path set
+  # @raise [RuntimeError] when specified path is not a valid directory
+  # @see #set_deploy_dir
+  # @note When working dir is set all paths yielded by blocks will be relative as well.
+  # @note When working dir is set all function paramaters for the working directory will
+  #  be assumed relative as well.
+  #
+  def set_working_dir(path)
+    if !File.directory? path
+      raise "Specified path is not a directory: #{path}"
+    end
+    
+    @working_dir = path
+  end
+  
+  # Clears the working directory variable - requiring ZBuild specified paths to be absolute. 
+  # By default all specified paths must be absolute, however when a working directory is
+  # set, invoking this method requires them to be absolute again.
+  #
+  # @see #set_working_dir
+  #
+  def reset_working_dir
+    @working_dir = nil
+  end
+  
+  # Retrieve a path relative to the set working directory.
+  #
+  # @example
+  #   working_path 'user_name/logs'
+  #   => user_name/logs
+  #
+  #   set_working_path '/tmp/user_name'
+  #   working_path 'logs'
+  #   => /tmp/user_name/logs
+  #
+  # @param [String] path file path
+  # @return [String] the path specified, relative to the set working dir
+  # @see #set_working_dir
+  #
+  def working_path(path)
+    working_dir = self.working_dir
+    working_dir.empty? ? path : File.join(working_dir, path)
+  end
+  
+  # Retrieve a path relative to the set deploy directory.
+  # 
+  # @param [String] path file path
+  # @return [String] the path specified, relative to the set working dir
+  # @raise [RuntimeError] when deploy path has not been set
+  # @see #working_path
+  def deploy_path(path)
+    deploy_dir = self.deploy_dir
+    if deploy_dir.empty?
+      raise 'Deploy directory not set - set_deploy_dir must be invoked before deploy function use'
+    end
+    
+    File.join(deploy_dir, path)
+  end
+  
+  # @return [String] the set working directory, or empty string if not set
+  # @see #set_working_dir
+  def working_dir
+    @working_dir ||= ''
+  end
+  
+  # @return [String] the set deploy directory, or empty string if not set
+  # @see #set_deploy_dir  
+  def deploy_dir
+    @deploy_dir ||= ''
+  end
+  
+  # Perform token replacement on the specified string, with optionally specified token
+  # prefix and suffixes.
+  #
+  # @example
+  #   str  = "##HELLO##, World"
+  #   hash = {:HELLO => 'Greetings'}
+  #
+  #   token_replace_str(str, hash, '##', '##)
+  #   => Greetings, World
+  #
+  # @param [String] str the string to perform token replacmeent on
+  # @param [Hash] token_to_replacement_hash hash keyed by tokens mapped to values for replacement
+  # @param [String] token_prefix prefix present on every token within str, but omitted from
+  #   token_to_replacement hash keys
+  # @param [String] token_suffix suffix present to every token within str, but omitted from
+  #   token_to_replacement hash keys
+  # @return [String] the given str with tokens replaced by their respectively mapped values
+  #
+  def token_replace_str(str, token_to_replacement_hash, token_prefix='', token_suffix='')
+    token_to_replacement_hash.each do |token, replacement|
+			str = str.gsub "#{token_prefix}#{token}#{token_suffix}", replacement.to_s
+		end
+		
+		str
+  end
+  
+  # Shortcut function to combine file_to_str + token_replace_str.
+  #
+  # @param [String] file the file to read and perform token replacmeent on
+  # @param [Hash] token_to_replacement_hash hash keyed by tokens mapped to values for replacement
+  # @param [String] token_prefix prefix present on every token within str, but omitted from
+  #   token_to_replacement hash keys
+  # @param [String] token_suffix suffix present to every token within str, but omitted from
+  #   token_to_replacement hash keys
+  # @return [String] the given str with tokens replaced by their respectively mapped values
+  #
+  # @see #file_to_str
+  # @see #token_replace_str
+  #
+  def token_replace_file(file, token_to_replacement_hash, token_prefix='', token_suffix='')
+    # file_to_str accepts the path relative to working dir
+		str = file_to_str file
+
+		token_to_replacement_hash.each do |token, replacement|
+			str = str.gsub "#{token_prefix}#{token}#{token_suffix}", replacement.to_s
+		end
+
+		str
+	end
+  
+  # Reads the specified file and returns contents as a string.
+  #
+  # @example
+  #   str = file_to_str '/path/to/your/file.txt' 
+  #
+  # @param [String] file file to read into a string
+  # @return [String] string content of the file
+  # @raise [RuntimeError] when specified file does not exist
+  #
+  def file_to_str(file)
+		str = ''
+
+    working_path = File.join self.working_dir, file
+
+		if !File.file? working_path
+      raise "Specified file does not exist: #{working_path}"
+    end 
+
+		File.open(working_path) do |fh|
+			fh.each do |line|
+				str += line
+			end
+		end
+
+		str
+	end
+  
+  # Given a specified path glob, yields the files and directories
+  # matching the glob pattern.
+  # 
+  # @param [String] pattern file glob pattern
+  # @yield [file_path, is_dir] path of the file and bool as to whether it is a directory 
+  # 
+  def glob(pattern)
+    relative_dir = File.dirname(pattern)
+    working_dir  = self.working_path pattern
+
+    Dir.glob working_dir do |file_path|
+      file_name = File.basename file_path
+      is_dir    = File.directory?(file_path)
+      
+      yield File.join(relative_dir, file_name), is_dir
+    end
+  end
+  
+  # Walk to maxiumum depth the directory structure provided.
+  #
+  # @example
+  #   walk_path '/mount/dev' do |path, is_dir|
+  #     puts "#{is_dir ? 'Dir' : 'File'} #{path}"
+  #   end
+  #   => ........
+  #   => File /mount/dev/branch/docs/doc/top-level-namespace.html
+  #   => File /mount/dev/branch/docs/doc/ZDatabase.html
+  #   => Dir /mount/dev/branch/docs/doc
+  #   => Dir /mount/dev/branch/docs 
+  #   => ........
+  #
+  # @param [String] path the directory path to traverse, if a file is provided the file's
+  #   directory will be used instead
+  # @yield [file_path, is_dir] path of the file and bool as to whether it is a directory 
+  #
+  def walk_path(path, &block)
+    self.glob(File.join(path, '*')) do |f, is_dir|
+          
+      if is_dir
+        self.walk_path f, &block
+      end
+
+      yield f, is_dir
+    end
+  end
+  
+  # Clock the time required to perform the operations within the given
+  # block. This function will also keep track of the number of nested
+  # clocks, and for easy-reading indent accordingly.
+  # 
+	# @example
+	#  clock "Performing some super cool operation" do 
+	#    info "Like just printing a message and going to sleep."
+	#    sleep(1)
+	#  end
+	#
+	#  => Performing some super cool operation
+	#  =>   [INFO] Like just printing a message and going to sleep.
+  #  => Done [1 sec]
+  #  => 1
+  #
+  # @param [String] desc the description of the operation being clocked
+  # @yield to provided block
+  # @return [Fixnum] the number of seconds recorded for the clocked operation
+  #
+  def clock(desc='Clocking Operation', &block)
+		@clock_count ||=0
+		@clock_count += 1
+		
+		indent = "  " * [0,@clock_count - 1].max
+		
+		puts "#{indent}#{desc}"
+		t = Time.now.to_i
+		yield
+		run_time_sec = Time.now.to_i - t
+		
+		if run_time_sec < 60
+		  run_time_str = "#{run_time_sec} sec"
+	  elsif run_time_sec < 3600
+	    run_time_str = "#{run_time_sec / 60} min #{run_time_sec % 60} sec"
+	  else
+	    run_time_str = "#{run_time_sec / 3600} hr #{run_time_sec % 3600 / 60} min #{run_time_sec % 60} sec"
+	  end
+		
+		puts "#{indent}Done [#{run_time_str}]\n"
+		
+		@clock_count -= 1
+		
+		run_time_sec
+	end
+  
+  # Short form of open_temp_file - writes content string immediately to temp file
+  # and yields the generated path. The temp file will be automatically deleted
+  # from the file system at the completion of the block.
+  # 
+  # @example
+  #   temp_file sql_content_str, 'Sql file' do |path|
+  #     `myqsl < #{path}`
+  #   end
+  #   => /var/folders/path/to/temp/z_build_sql_file_136487088920130401-7393-18ynao0-0
+  #
+  # @param [String] content to write to the temporary file
+  # @param [String] desc description of the temporary file created or purpose for creation
+  # @yield [f_path] temporary file's associated path
+  # @note on yield the file has already been closed and the path is ready for reading/use
+  # @return [String] fully qualified path of the file created (and destroyed following the block)
+  # @see #open_temp_file
+  #
+  def temp_file(content, desc='', &block)
+    f_path = ''
+    
+    self.open_temp_file do |f_handle, path|
+      f_path = path
+      f_handle.write content
+      f_handle.close
+      yield path
+    end
+    		
+		f_path
+  end
+  
+  # Creates a temporary file and returns generated path and file handle to the provided 
+  # block. The file will be automatically deleted from the file system at the 
+  # completion of the block. This function is useful in distinction from self.temp_file
+  # in that the temp file may be written to incrementally, rather than at once with a 
+  # single string parameter, which under circumstance could cause a memory buffer error.
+  # 
+  # @example
+  #   open_temp_file 'Sql file' do |f_handle, path|
+  #     f.write my_sql_string_defined_previously
+  #
+  #     # must close before the file may be read from the path
+  #     f.close   
+  #
+  #     `myqsl < #{path}`
+  #   end
+  #   => /var/folders/path/to/temp/z_build_sql_file_136487088920130401-7393-18ynao0-0
+  #
+  # @param [String] desc description of the temporary file created or purpose for creation
+  # @yield [f_handle, f_path] temporary file's handle and associated path
+  # @return [String] fully qualified path of the file created (and destroyed following the block)
+  # @see #temp_file
+  #
+  def open_temp_file(desc='', &block)
+    desc = desc.empty? ? '' : desc.to_s.match(/[a-zA-Z\s\d]*/).to_s.downcase.gsub(' ', '_')
+
+    f_handle = Tempfile.new ['z_build', desc, Time.now.to_i].join('_')
+    f_path   = f_handle.path
+		begin    
+      yield f_handle, f_handle.path
+      
+      if !f_handle.closed?
+   			f_handle.close
+			end
+		ensure
+			f_handle.unlink
+		end
+		
+		f_path
+  end
+  
+  # Sends to stdout the warning message provided.
+  # Will indent relative to the number of clocked operations. 
+  #
+  # @example
+  #   clock 'Usage Example' do
+  #     warn 'Testing Warning'
+  #   end
+  #
+  #   => Usage Example
+  #   =>   [WARN] Testing Warning
+  #   => Done [0 sec]
+  # 
+  # @param [String] message 
+  def warn(message)
+    puts "#{self.clock_indent}[WARN] #{message}"
+  end
+  
+  # Sends to stdout the message provided.
+  # Will indent relative to the number of clocked operations. 
+  #
+  # @param [String] message 
+  def info(message)
+    puts "#{self.clock_indent}[INFO] #{message}"
+  end
+
+  # @todo add a no_merge option
+  # 
+	# Converts all KEY=VALUE pairs in the specified file to a hash and perform $\{var} 
+	# replacement.
+	# Lines starting with ruby comments '#' will be ignored.
+	# Comments trailing a KEY=VALUE pair will be stripped.
+	#
+	# Variables must be surrounded by a dollars with parenthesis e.g. $\{var} and
+	# the variable must be alpha or alpha-numeric and may contain dashes or underscores.
+	#
+	# Variables may also be defined NOT using TOP-DOWN ordering, <b>though this is strongly 
+	# discouraged.</b> See below an example of top-down and bottom-up 
+	# ordering working correctly:
+	#
+	# @example 
+	#   == /path/to/example.txt
+	# 
+	#   # comment lines will be ignored
+  #   NAME=Bruno
+	#   GREETING=Hello, ${NAME}.     # side comments will also be discarded
+	#
+	#   HERO=super${SPECIES}
+	#   SPECIES=man
+	#   
+	#   == irb
+	#
+	#   require 'z_build'
+	#
+	#   props_to_hash '/path/to/example.txt'
+	#   => {"SPECIES"=>"man", "GREETING"=>"Hello, Bruno.", "HERO"=>"superman", "NAME"=>"Bruno"}
+	#
+	# @param [String] file fully qualified file path containing the file to read
+	# @param [Hash] hash hash to combine with - keys read from file will overwrite keys
+	#   found in this hash, and the combined hash will be used to resolve 
+  #   variables specified in the dollar-sign block syntax $\{var} in the value field.
+  #   Only values may be variable replaced; keys in the file will not be variable replaced.
+  #   For efficiency the hash parameter will not be copied, therefore if the desired 
+  #   behavior is to not overwrite the hash given (during combination with file 
+  #   key/values), hash.clone should be passed as the function parameter.
+	#
+	# @return [Hash] containing key/value pairs found in the specified file path, 
+	#   combined with the hash parameter
+	#
+	# @raise [RuntimeError] when specified file does not exist
+	#
+	def props_to_hash(file, hash={})
+	  file_path      = self.working_path file
+		reprocess_keys = []
+		var_regex      = /\$\{([a-zA-Z|\-|_|\d]+)\}/
+    
+    if !File.file? file_path
+      raise "Specified file does not exist: #{file_path}"
+    end 
+    
+		File.open(file_path) do |f|
+			f.each do |line|
+				line.to_s.strip!
+
+				if line.empty? then next; end
+				if line.start_with? '#' then next; end
+
+				key, value = line.split '='
+				key        = key.to_s.strip.to_s
+				value      = value.to_s.gsub(/#.*/, '').strip.to_s
+
+				hash[key]  = value
+
+				# replace variable values defined by prior k,v pairs
+				value.scan(var_regex).flatten.each do |var|
+					if hash[var] == nil
+						# key is expected but is not yet defined
+						# mark key for re-visitation post processing
+						reprocess_keys.push key
+						next
+					end
+         
+          # variable was found in hash - update keyed value with var replacement
+					hash[key] = value.gsub("${#{var}}", hash[var])
+				end
+			end
+		end
+
+		# final pass var replacement for variables not defined using TOP-DOWN ordering
+		reprocess_keys.each do |key|
+			hash[key].scan(var_regex).flatten.each do |var|
+				if hash[var] == nil
+				  # key is expected but is not yet defined - will not reprocess this variable
+				  self.warn "Failed to replace variable[#{var}] mapped to key[#{key}] found in file[#{file_path}]"
+					next
+				end
+
+				hash[key] = hash[key].gsub("${#{var}}", hash[var])
+			end
+		end
+
+		hash
+	end
+
+  # N-ary alternative to props_to_hash. Takes n-property files, merges their key/value
+  # pairs into a hash in FIFO ordering, while performing variable replacement
+  #
+  # @example
+  #   hash = props_list_to_hash file1, file2, file3, file4
+  #
+  # @param [Array] files list of files to read key/value pairs into a combined hash 
+  # @raise [RuntimeError] when one of the specified files does not exist
+  # @see #props_to_hash
+  #
+  def props_list_to_hash(*files)
+    h = {}
+    files.each do |f|
+      h = self.props_to_hash f, h
+    end
+    
+    h
+  end
+
+  protected
+  
+  # Module method
+  def self.included(base)
+    # also add these methods to the class object including ZBuild
+    base.extend self
+  end
+  
+  def clock_count
+    @clock_count ? @clock_count : 0
+  end
+  
+  def clock_indent
+    # use soft tabs
+    "  " * self.clock_count
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: z_build
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 1
+  - 0
+  version: 1.1.0
+platform: ruby
+authors: 
+- Shaun Bruno
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-03-31 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Ditch your unweildy and heavyset build. Use Z'Build module with Rake/Thor/etc and make a light-weight alternative, written in pure Ruby.
+email: shaun.bruno@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/z_build.rb
+has_rdoc: true
+homepage: https://github.com/shaunbruno/z_build
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Z'Build Module
+test_files: []
+