batch-kit 0.3

data/lib/batch-kit/configurable.rb

@@ -0,0 +1,68 @@
+require_relative 'config'
+
+
+class BatchKit
+
+    # Adds a configure class method that can be used to load a configuration file
+    # and make it available to the class and instances of it.
+    module Configurable
+
+        # Defines the methods that are to be added as class methods to the class
+        # that includes the Configurable module.
+        module ClassMethods
+
+            # Configure the class by loading the configuration files specifed.
+            # If the last argument passed to this method is a Hash, it is
+            # treated an options hash, which is passed into {BatchKit::Config}.
+            #
+            # @param cfg_files [Array<String>] Path(s) to the configuration
+            #   file(s) to be loaded into a single {BatchKit::Config} object.
+            # @option cfg_files [String] :decryption_key The master key for
+            #   decrypting any encrypted values in the configuration files.
+            def configure(*cfg_files)
+                options = cfg_files.last.is_a?(Hash) ? cfg_files.pop.clone : {}
+                if defined?(BatchKit::Events)
+                    Events.publish(self, 'config.pre-load', config, cfg_files)
+                end
+                config.decryption_key = options.delete(:decryption_key) if options[:decryption_key]
+                config.merge!(options)
+                cfg_files.each do |cfg_file|
+                    config.load(cfg_file, options)
+                end
+                if defined?(BatchKit::Events)
+                    Events.publish(self, 'config.post-load', config)
+                end
+                config
+            end
+
+
+            # Returns the {BatchKit::Config} object produced when loading the
+            # configuration files (or creates a new instance if no files were
+            # loaded).
+            def config
+                @config ||= Config.new
+            end
+
+        end
+
+
+        # Used to extend the including class with the class methods defined in
+        # {ClassMethods}.
+        def self.included(base)
+            base.extend(ClassMethods)
+        end
+
+
+        # Each object instance gets its own copy of the class configuration, so
+        # that any modifications they make are local to the object instance.
+        #
+        # @return [BatchKit::Config] a copy of the class configuration specific
+        #   to this instance.
+        def config
+            @config ||= self.class.config.clone
+        end
+
+    end
+
+end
+

data/lib/batch-kit/core_ext/enumerable.rb

@@ -0,0 +1,97 @@
+require 'thread'
+
+
+# Re-opens the Ruby standard Enumerable module to add some additional utility
+# methods to all enumerables.
+module Enumerable
+
+    # Maps each item in the Enumerable, surrounding it with the +left+ and +right+
+    # strings. If +right+ is not specified, it is set to the same string as +left+,
+    # which in turn is defaulted to the double-quote character.
+    #
+    # @param left [String] The character to precede each item with.
+    # @param right [String] The character to follow each item with.
+    def surround(left = '"', right = left)
+        self.map{ |item| "#{left}#{item}#{right}" }
+    end
+
+
+    # Surrounds each item in the Enumerable with single quotes.
+    def squote
+        self.surround("'")
+    end
+
+
+    # Surrounds each item in the Enumerable with double quotes.
+    def dquote
+        self.surround('"')
+    end
+
+
+    # Convenience function for spawning multiple threads to do a common task,
+    # driven by the contents of this enumerable. Each entry in self will be
+    # be yielded to a new thread, which will then call the supplied block with
+    # the element.
+    #
+    # @param options [Hash] An options hash.
+    # @option options [Boolean] :abort_on_exception If true, and any thread
+    #   throws an exception during processing, abort processing of the
+    #   collection immediately.
+    # @option options [Integer] :threads The number of threads to use to
+    #   process the collection. Default is no more than 4 (less if the
+    #   collection contains fewer than 4 items).
+    def concurrent_each(options = {}, &blk)
+        if self.count < 2
+            self.each(&blk)
+        else
+            abort_opt = options.fetch(:abort_on_exception, true)
+            Thread.abort_on_exception = abort_opt
+
+            # Push items onto a queue from which work items can be removed by
+            # threads in the pool
+            queue = Queue.new
+            self.each{ |it| queue << it }
+
+            # Setup thread pool to iterate over work queue
+            thread_count = options.fetch(:threads, [4, self.count].min)
+            threads = []
+
+            # Launch each worker thread, which loops extracting work items from
+            # the queue until it is empty
+            (0...thread_count).each do |i|
+                threads << Thread.new do
+                    begin
+                        while work_item = queue.pop(true)
+                            if abort_opt
+                                # Raise exception on main thread
+                                begin
+                                    yield work_item
+                                rescue Exception => ex
+                                    Thread.main.raise ex
+                                end
+                            else
+                                # Exceptions will be picked up below when main thread joins
+                                yield work_item
+                            end
+                        end
+                    rescue ThreadError
+                        # Work queue is empty, so exit loop
+                    end
+                end
+            end
+
+            # Now wait for all threads in pool to complete
+            ex = nil
+            threads.each do |th|
+                begin
+                    th.join
+                rescue Exception => t
+                    ex = t unless ex
+                end
+            end
+            raise ex if ex
+        end
+    end
+
+end
+

data/lib/batch-kit/core_ext/file.rb

@@ -0,0 +1,69 @@
+class BatchKit
+
+    module FileExtensions
+
+        module ClassMethods
+
+            # Return just the name (without any extension) of a path.
+            def nameonly(path)
+                File.basename(path, File.extname(path))
+            end
+
+        end
+
+
+        def self.included(cls)
+            cls.extend(ClassMethods)
+        end
+
+    end
+
+end
+
+
+File.class_eval do
+
+    include BatchKit::FileExtensions
+
+    class << self
+
+        unless method_defined?(:open_without_bom)
+
+            # Add support for writing a BOM if the +mode_string+ includes 'bom',
+            # and the mode is write.
+            alias_method :open_without_bom, :open
+            def open(*args, &blk)
+                if args.length >= 2 && (mode_string = args[1]).is_a?(String) &&
+                    mode_string =~ /^(w|a):(.*)bom/i
+                    write_mode = $1.downcase == 'w'
+                    args[1] = mode_string.sub(/bom\||[\-|]bom/, '')
+                    f = open_without_bom(*args)
+                    bom_hex = case mode_string
+                    when /utf-?8/i
+                        "\xEF\xBB\xBF"
+                    when /utf-16be/i
+                        "\xFE\xFF"
+                    when /utf-16le/i
+                        "\xFF\xFE"
+                    when /utf-32be/i
+                        "\x00\x00\xFE\xFF"
+                    when /utf-32le/i
+                        "\xFE\xFF\x00\x00"
+                    end
+                    f << bom_hex.force_encoding(f.external_encoding) if write_mode
+                    if block_given?
+                        yield f
+                        f.close
+                    else
+                        f
+                    end
+                else
+                    open_without_bom(*args, &blk)
+                end
+            end
+
+        end
+
+    end
+
+end

data/lib/batch-kit/core_ext/file_utils.rb

@@ -0,0 +1,103 @@
+require 'fileutils'
+require 'date'
+
+
+# Re-opens the FileUtils module in the Ruby standard library to add new
+# functionality.
+module FileUtils
+
+    # Set the default archive directory for use on subsequent calls to #archive.
+    attr_accessor :archive_dir
+    module_function :archive_dir, :archive_dir=
+
+
+    # Archive existing files at +paths+, where +paths+ is one or more
+    # Dir#glob patterns. Archiving consists of renaming files to include a
+    # timestamp in the file name. This permits multiple copies of the same
+    # file to exist in a single directory. The timestamp is created from
+    # the last modification date of the file being archived.
+    #
+    # The last argument passed may be an options Hash, which can be used
+    # to change the default behaviour. Valid options are:
+    # @param paths [Array<String|Hash>] A list of paths to be archived. If
+    #   the last item passed to the method is a Hahs, it is treated as an
+    #   an options hash.
+    # @option paths [String] :archive_dir The directory in which to place
+    #   archived files. If not specified, archived files are placed in the
+    #   same directory.
+    # @option paths [Fixnum] :archive_days The number of days for which to
+    #   keep archived files. Defaults to nil, meaning there is no maximum
+    #   number of days.
+    # @option paths [Fixnum] :archive_copies The maximum number of copies
+    #   to keep of an archived file. Defaults to 10.
+    def archive(*paths)
+        if paths.last.is_a?(Hash)
+            options = paths.pop
+        else
+            options = {archive_copies: 10}
+        end
+        archive_dir = options[:archive_dir] || @archive_dir
+        archive_copies = options[:archive_copies]
+        if archive_copies && 1 > archive_copies
+            raise ArgumentError, ":archive_copies option must be positive"
+        end
+        archive_days = options[:archive_days]
+        if archive_days && 1 > archive_days
+            raise ArgumentError, ":archive_days option must be positive"
+        end
+        cutoff_date = archive_days && (Date.today - archive_days)
+
+        FileUtils.mkdir_p(archive_dir) rescue nil if archive_dir
+
+        # Create archives of files that match the patterns in +paths+
+        archive_count = 0
+        Dir[*paths].each do |file_name|
+            next if file_name =~ /\d{8}.\d{6}(?:\.[^.]+)?$/
+            File.rename(file_name, '%s/%s.%s%s' % [
+                            archive_dir || File.dirname(file_name),
+                            File.basename(file_name, File.extname(file_name)),
+                            File.mtime(file_name).strftime('%Y%m%d.%H%M%S'),
+                            File.extname(file_name)
+                        ]) rescue next
+            archive_count += 1
+        end
+
+        if archive_copies || cutoff_date
+            # Find all copies of each unique file matching +paths+
+            purge_sets = Hash.new{ |h, k| h[k] = [] }
+            folders = archive_dir ? [archive_dir] : paths.map{ |path| File.dirname(path) }.uniq
+            folders.each do |folder|
+                Dir["#{folder}/*.????????.??????.*"].each do |path|
+                    if path =~ /^(.+)\.\d{8}\.\d{6}(\.[^.]+)?$/
+                        purge_sets["#{$1}#{$2}"] << path
+                    end
+                end
+            end
+
+            # Now purge the oldest archives, such that we keep a maximum of
+            # +archive_copies+, and no file older than +cutoff_date+.
+            purge_sets.each do |orig_name, old_files|
+                old_files.sort!
+                old_size = old_files.size
+                purge_files = []
+                if archive_copies && old_size > archive_copies
+                    purge_files = old_files.slice!(0, old_size - archive_copies)
+                end
+                if cutoff_date
+                    vold_files = old_files.reject! do |path|
+                        path =~ /(\d{4})(\d{2})(\d{2})\.\d{6}(?:\.[^.]+)?$/
+                        file_date = Date.new($1.to_i, $2.to_i, $3.to_i)
+                        file_date >= cutoff_date
+                    end
+                    purge_files.concat(vold_files) if vold_files
+                end
+                if purge_files.size > 0
+                    FileUtils.rm_f(purge_files) rescue nil
+                end
+            end
+        end
+        archive_count
+    end
+    module_function :archive
+
+end

data/lib/batch-kit/core_ext/hash.rb

@@ -0,0 +1,17 @@
+class BatchKit
+
+    module HashExtensions
+
+        # Converts a Hash object to a BatchKit::Config object
+        def to_cfg
+            self.is_a?(BatchKit::Config) ? self : BatchKit::Config.new(self)
+        end
+
+    end
+
+end
+
+
+Hash.class_eval do
+    include BatchKit::HashExtensions
+end

data/lib/batch-kit/core_ext/numeric.rb

@@ -0,0 +1,17 @@
+class BatchKit
+
+    module NumericExtensions
+
+        # Converts an integer to a comma-separated string, e.g. 1024 becomes "1,024"
+        def with_commas
+            self.to_s.gsub(/(\d)(?=(\d{3})+(?!\d))/, "\\1,")
+        end
+
+    end
+
+end
+
+
+Numeric.class_eval do
+    include BatchKit::NumericExtensions
+end

data/lib/batch-kit/core_ext/string.rb

@@ -0,0 +1,88 @@
+class BatchKit
+
+    module StringExtensions
+
+        unless String.instance_methods.include?(:titleize)
+
+            # A very simple #titleize method to capitalise the first letter of
+            # each word, and replace underscores with spaces. Nowhere near as
+            # powerful as ActiveSupport#titleize, so we only define it if no
+            # existing #titleize method is found on String.
+            def titleize
+                self.gsub(/_/, ' ').gsub(/\b([a-z])/){ $1.upcase }
+            end
+
+        end
+
+
+        # Wraps the text in +self+ to lines no longer than +width+.
+        #
+        # The algorithm uses the following variables:
+        #   - end_pos is the last non-space character in self
+        #   - start is the position in self of the start of the next line to be
+        #     processed.
+        #   - nl_pos is the location of the next new-line character after start.
+        #   - ws_pos is the location of the last space character between start and
+        #     start + width.
+        #   - wb_pos is the location of the last word-break character between start
+        #     and start + width - 1.
+        #
+        # @param width [Fixnum] The maximum number of characters in each line.
+        def wrap_text(width)
+            if width > 0 && (self.length > width || self.index("\n"))
+                lines = []
+                start, nl_pos, ws_pos, wb_pos, end_pos = 0, 0, 0, 0, self.rindex(/[^\s]/)
+                while start < end_pos
+                    last_start = start
+                    nl_pos = self.index("\n", start)
+                    ws_pos = self.rindex(/ +/, start + width)
+                    wb_pos = self.rindex(/[\-,.;#)}\]\/\\]/, start + width - 1)
+                    ### Debug code ###
+                    #STDERR.puts self
+                    #ind = ' ' * end_pos
+                    #ind[start] = '('
+                    #ind[start+width < end_pos ? start+width : end_pos] = ']'
+                    #ind[nl_pos] = 'n' if nl_pos
+                    #ind[wb_pos] = 'b' if wb_pos
+                    #ind[ws_pos] = 's' if ws_pos
+                    #STDERR.puts ind
+                    ### End debug code ###
+                    if nl_pos && nl_pos <= start + width
+                        lines << self[start...nl_pos].strip
+                        start = nl_pos + 1
+                    elsif end_pos < start + width
+                        lines << self[start..end_pos]
+                        start = end_pos
+                    elsif ws_pos && ws_pos > start && ((wb_pos.nil? || ws_pos > wb_pos) ||
+                          (wb_pos && wb_pos > 5 && wb_pos - 5 < ws_pos))
+                        lines << self[start...ws_pos]
+                        start = self.index(/[^\s]/, ws_pos + 1)
+                    elsif wb_pos && wb_pos > start
+                        lines << self[start..wb_pos]
+                        start = wb_pos + 1
+                    else
+                        lines << self[start...(start+width)]
+                        start += width
+                    end
+                    if start <= last_start
+                        # Detect an infinite loop, and just return the original text
+                        STDERR.puts "Inifinite loop detected at #{__FILE__}:#{__LINE__}"
+                        STDERR.puts "  width: #{width}, start: #{start}, nl_pos: #{nl_pos}, " +
+                                    "ws_pos: #{ws_pos}, wb_pos: #{wb_pos}"
+                        return [self]
+                    end
+                end
+                lines
+            else
+                [self]
+            end
+        end
+
+    end
+
+end
+
+
+String.class_eval do
+   include BatchKit::StringExtensions
+end