jinx 2.1.1

data/lib/jinx/active_support/inflector.rb

@@ -0,0 +1,398 @@
+# encoding: utf-8
+require 'singleton'
+require 'iconv'
+
+module ActiveSupport
+  # The Inflector transforms words from singular to plural, class names to table names, modularized class names to ones without,
+  # and class names to foreign keys. The default inflections for pluralization, singularization, and uncountable words are kept
+  # in inflections.rb.
+  #
+  # The Rails core team has stated patches for the inflections library will not be accepted
+  # in order to avoid breaking legacy applications which may be relying on errant inflections.
+  # If you discover an incorrect inflection and require it for your application, you'll need
+  # to correct it yourself (explained below).
+  module Inflector
+    extend self
+
+    # A singleton instance of this class is yielded by {Inflector#inflections}, which can then be used to specify additional
+    # inflection rules. Examples:
+    #
+    #   ActiveSupport::Inflector.inflections do |inflect|
+    #     inflect.plural /^(ox)$/i, '\12en'
+    #     inflect.singular /^(ox)en/i, '1'
+    #
+    #     inflect.irregular 'octopus', 'octopi'
+    #
+    #     inflect.uncountable "equipment"
+    #   end
+    #
+    # New rules are added at the top. So in the example above, the irregular rule for octopus will now be the first of the
+    # pluralization and singularization rules that is runs. This guarantees that your rules run before any of the rules that may
+    # already have been loaded.
+    class Inflections
+      include Singleton
+
+      attr_reader :plurals, :singulars, :uncountables, :humans
+
+      def initialize
+        @plurals, @singulars, @uncountables, @humans = [], [], [], []
+      end
+
+      # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression.
+      # The replacement should always be a string that may include references to the matched data from the rule.
+      def plural(rule, replacement)
+        @uncountables.delete(rule) if String === rule
+        @uncountables.delete(replacement)
+        @plurals.insert(0, [rule, replacement])
+      end
+
+      # Specifies a new singularization rule and its replacement. The rule can either be a string or a regular expression.
+      # The replacement should always be a string that may include references to the matched data from the rule.
+      def singular(rule, replacement)
+        @uncountables.delete(rule) if String === rule
+        @uncountables.delete(replacement)
+        @singulars.insert(0, [rule, replacement])
+      end
+
+      # Specifies a new irregular that applies to both pluralization and singularization at the same time. This can only be used
+      # for strings, not regular expressions. You simply pass the irregular in singular and plural form.
+      #
+      # @example
+      #   irregular 'octopus', 'octopi'
+      #   irregular 'person', 'people'
+      def irregular(singular, plural)
+        @uncountables.delete(singular)
+        @uncountables.delete(plural)
+        if singular[0,1].upcase == plural[0,1].upcase
+          plural(Regexp.new("(#{singular[0,1]})#{singular[1..-1]}$", "i"), '\1' + plural[1..-1])
+          singular(Regexp.new("(#{plural[0,1]})#{plural[1..-1]}$", "i"), '\1' + singular[1..-1])
+        else
+          plural(Regexp.new("#{singular[0,1].upcase}(?i)#{singular[1..-1]}$"), plural[0,1].upcase + plural[1..-1])
+          plural(Regexp.new("#{singular[0,1].downcase}(?i)#{singular[1..-1]}$"), plural[0,1].downcase + plural[1..-1])
+          singular(Regexp.new("#{plural[0,1].upcase}(?i)#{plural[1..-1]}$"), singular[0,1].upcase + singular[1..-1])
+          singular(Regexp.new("#{plural[0,1].downcase}(?i)#{plural[1..-1]}$"), singular[0,1].downcase + singular[1..-1])
+        end
+      end
+
+      # Add uncountable words that shouldn't be attempted inflected.
+      #
+      # @example
+      #   uncountable "money"
+      #   uncountable "money", "information"
+      #   uncountable %w( money information rice )
+      def uncountable(*words)
+        (@uncountables << words).flatten!
+      end
+
+      # Specifies a humanized form of a string by a regular expression rule or by a string mapping.
+      # When using a regular expression based replacement, the normal humanize formatting is called after the replacement.
+      # When a string is used, the human form should be specified as desired (example: 'The name', not 'the_name')
+      #
+      # @example
+      #   human /_cnt$/i, '1_count'
+      #   human "legacy_col_person_name", "Name"
+      def human(rule, replacement)
+        @humans.insert(0, [rule, replacement])
+      end
+
+      # Clears the loaded inflections within a given scope (default is <tt>:all</tt>).
+      # Give the scope as a symbol of the inflection type, the options are: <tt>:plurals</tt>,
+      # <tt>:singulars</tt>, <tt>:uncountables</tt>, <tt>:humans</tt>.
+      #
+      # @example
+      #   clear :all
+      #   clear :plurals
+      def clear(scope = :all)
+        case scope
+          when :all
+            @plurals, @singulars, @uncountables = [], [], []
+          else
+            instance_variable_set "@#{scope}", []
+        end
+      end
+    end
+
+    # Yields a singleton instance of Inflector::Inflections so you can specify additional
+    # inflector rules.
+    #
+    # Example:
+    #   ActiveSupport::Inflector.inflections do |inflect|
+    #     inflect.uncountable "rails"
+    #   end
+    def inflections
+      if block_given?
+        yield Inflections.instance
+      else
+        Inflections.instance
+      end
+    end
+
+    # Returns the plural form of the word in the string.
+    #
+    # @example
+    #   "post".pluralize             #=>"posts"
+    #   "octopus".pluralize          #=>"octopi"
+    #   "sheep".pluralize            #=>"sheep"
+    #   "words".pluralize            #=>"words"
+    #   "CamelOctopus".pluralize     #=>"CamelOctopi"
+    def pluralize(word)
+      result = word.to_s.dup
+
+      if word.empty? || inflections.uncountables.include?(result.downcase)
+        result
+      else
+        inflections.plurals.each {  |(rule, replacement)| break if result.gsub!(rule, replacement)  }
+        result
+      end
+    end
+
+    # The reverse of +pluralize+, returns the singular form of a word in a string.
+    #
+    # @example
+    #   "posts".singularize            #=>"post"
+    #   "octopi".singularize           #=>"octopus"
+    #   "sheep".singluarize            #=>"sheep"
+    #   "word".singularize             #=>"word"
+    #   "CamelOctopi".singularize      #=>"CamelOctopus"
+    def singularize(word)
+      result = word.to_s.dup
+
+      if inflections.uncountables.include?(result.downcase)
+        result
+      else
+        inflections.singulars.each {  |(rule, replacement)| break if result.gsub!(rule, replacement)  }
+        result
+      end
+    end
+
+    # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+
+    # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase.
+    #
+    # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces.
+    #
+    # @example
+    #   "active_record".camelize                #=>"ActiveRecord"
+    #   "active_record".camelize(:lower)        #=>"activeRecord"
+    #   "active_record/errors".camelize         #=>"ActiveRecord::Errors"
+    #   "active_record/errors".camelize(:lower) #=>"activeRecord::Errors"
+    def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
+      if first_letter_in_uppercase
+        lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase }" }.gsub(/(?:^|_)(.)/) { $1.upcase  }
+      else
+        # FL - fixed bug: String doesn't have a first method
+        #lower_case_and_underscored_word.first.downcase + camelize(lower_case_and_underscored_word)[1..-1]
+        lower_case_and_underscored_word[0, 1].downcase + camelize(lower_case_and_underscored_word)[1..-1]
+      end
+    end
+
+    # Capitalizes all the words and replaces some characters in the string to create
+    # a nicer looking title. +titleize+ is meant for creating pretty output. It is not
+    # used in the Rails internals.
+    #
+    # +titleize+ is also aliased as as +titlecase+.
+    #
+    # Examples:
+    #   "man from the boondocks".titleize #=>"Man From The Boondocks"
+    #   "x-men: the last stand".titleize  #=>"X Men: The Last Stand"
+    def titleize(word)
+      humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize  }
+    end
+
+    # The reverse of +camelize+. Makes an underscored, lowercase form from the expression in the string.
+    #
+    # Changes '::' to '/' to convert namespaces to paths.
+    #
+    # Examples:
+    #   "ActiveRecord".underscore         #=>"active_record"
+    #   "ActiveRecord::Errors".underscore #=>active_record/errors
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+
+    # Replaces underscores with dashes in the string.
+    #
+    # Example:
+    #   "puni_puni" #=>"puni-puni"
+    def dasherize(underscored_word)
+      underscored_word.gsub(/_/, '-')
+    end
+
+    # Capitalizes the first word and turns underscores into spaces and strips a
+    # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output.
+    #
+    # Examples:
+    #   "employee_salary" #=>"Employee salary"
+    #   "author_id"       #=>"Author"
+    def humanize(lower_case_and_underscored_word)
+      result = lower_case_and_underscored_word.to_s.dup
+
+      inflections.humans.each {  |(rule, replacement)| break if result.gsub!(rule, replacement)  }
+      result.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+    end
+
+    # Removes the module part from the expression in the string.
+    #
+    # Examples:
+    #   "ActiveRecord::CoreExtensions::String::Inflections".demodulize #=>"Inflections"
+    #   "Inflections".demodulize                                       #=>"Inflections"
+    def demodulize(class_name_in_module)
+      class_name_in_module.to_s.gsub(/^.*::/, '')
+    end
+
+    # Replaces special characters in a string so that it may be used as part of a 'pretty' URL.
+    #
+    # ==== Examples
+    #
+    #   class Person
+    #     def to_param
+    #       "#{id}-#{name.parameterize}"
+    #     end
+    #   end
+    #
+    #   @person = Person.find(1)
+    #   #=>#<Person id: 1, name: "Donald E. Knuth">
+    #
+    #   <%= link_to(@person.name, person_path %>
+    #   #=><a href="/person/1-donald-e-knuth">Donald E. Knuth</a>
+    def parameterize(string, sep = '-')
+      re_sep = Regexp.escape(sep)
+      # replace accented chars with ther ascii equivalents
+      parameterized_string = transliterate(string)
+      # Turn unwanted chars into the seperator
+      parameterized_string.gsub!(/[^a-z0-9\-_\+]+/i, sep)
+      # No more than one of the separator in a row.
+      parameterized_string.squeeze!(sep)
+      # Remove leading/trailing separator.
+      parameterized_string.gsub!(/^#{re_sep}|#{re_sep}$/i, '')
+      parameterized_string.downcase
+    end
+
+    # Replaces accented characters with their ascii equivalents.
+    def transliterate(string)
+      Iconv.iconv('ascii//ignore//translit', 'utf-8', string).to_s
+    end
+
+    # The iconv transliteration code doesn't function correctly
+    # on some platforms, but it's very fast where it does function.
+    if "foo" != Inflector.transliterate("föö")
+      undef_method :transliterate
+      def transliterate(string)
+        string.mb_chars.normalize(:kd). # Decompose accented characters
+          gsub(/[^\x00-\x7F]+/, '')     # Remove anything non-ASCII entirely (e.g. diacritics).
+      end
+    end
+
+    # Create the name of a table like Rails does for models to table names. This method
+    # uses the +pluralize+ method on the last word in the string.
+    #
+    # Examples
+    #   "RawScaledScorer".tableize #=>"raw_scaled_scorers"
+    #   "egg_and_ham".tableize     #=>"egg_and_hams"
+    #   "fancyCategory".tableize   #=>"fancy_categories"
+    def tableize(class_name)
+      pluralize(underscore(class_name))
+    end
+
+    # Create a class name from a plural table name like Rails does for table names to models.
+    # Note that this returns a string and not a Class. (To convert to an actual class
+    # follow +classify+ with +constantize+.)
+    #
+    # Examples:
+    #   "egg_and_hams".classify #=>"EggAndHam"
+    #   "posts".classify        #=>"Post"
+    #
+    # Singular names are not handled correctly:
+    #   "business".classify     #=>"Busines"
+    def classify(table_name)
+      # strip out any leading schema name
+      camelize(singularize(table_name.to_s.sub(/.*\./, '')))
+    end
+
+    # Creates a foreign key name from a class name.
+    # +separate_class_name_and_id_with_underscore+ sets whether
+    # the method should put '_' between the name and 'id'.
+    #
+    # Examples:
+    #   "Message".foreign_key        #=>"message_id"
+    #   "Message".foreign_key(false) #=>"messageid"
+    #   "Admin::Post".foreign_key    #=>"post_id"
+    def foreign_key(class_name, separate_class_name_and_id_with_underscore = true)
+      underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id")
+    end
+
+    # Ruby 1.9 introduces an inherit argument for {Module#const_get} and
+    # #const_defined? and changes their default behavior.
+    if Module.method(:const_get).arity == 1
+      # Tries to find a constant with the name specified in the argument string:
+      #
+      #   "Module".constantize     #=>Module
+      #   "Test::Unit".constantize #=>Test::Unit
+      #
+      # The name is assumed to be the one of a top-level constant, no matter whether
+      # it starts with "::" or not. No lexical context is taken into account:
+      #
+      #   C = 'outside'
+      #   module M
+      #     C = 'inside'
+      #     C               #=>'inside'
+      #     "C".constantize #=>'outside', same as ::C
+      #   end
+      #
+      # NameError is raised when the name is not in CamelCase or the constant is
+      # unknown.
+      def constantize(camel_cased_word)
+        names = camel_cased_word.split('::')
+        names.shift if names.empty? || names.first.empty?
+
+        constant = Object
+        names.each do |name|
+          constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+        end
+        constant
+      end
+    else
+      def constantize(camel_cased_word) #:nodoc:
+        names = camel_cased_word.split('::')
+        names.shift if names.empty? || names.first.empty?
+
+        constant = Object
+        names.each do |name|
+          constant = constant.const_get(name, false) || constant.const_missing(name)
+        end
+        constant
+      end
+    end
+
+    # Turns a number into an ordinal string used to denote the position in an
+    # ordered sequence such as 1st, 2nd, 3rd, 4th.
+    #
+    # Examples:
+    #   ordinalize(1)     #=>"1st"
+    #   ordinalize(2)     #=>"2nd"
+    #   ordinalize(1002)  #=>"1002nd"
+    #   ordinalize(1003)  #=>"1003rd"
+    def ordinalize(number)
+      if (11..13).include?(number.to_i % 100)
+        "#{number}th"
+      else
+        case number.to_i % 10
+          when 1; "#{number}st"
+          when 2; "#{number}nd"
+          when 3; "#{number}rd"
+          else    "#{number}th"
+        end
+      end
+    end
+  end
+end
+
+# in case jinx/active_support/inflector is required without the rest of active_support
+require 'jinx/active_support/inflections'
+require 'jinx/active_support/core_ext/string/inflections'
+unless String.included_modules.include?(ActiveSupport::CoreExtensions::String::Inflections)
+  String.send :include, ActiveSupport::CoreExtensions::String::Inflections
+end

data/lib/jinx/cli/application.rb

@@ -0,0 +1,36 @@
+require 'logger'
+
+module Jinx
+  module CLI
+    # Extends the standard Logger::Application to use the {Log} and add start
+    # functionality.
+    class Application < Logger::Application
+      # @param [String] appname the application name
+      def initialize(appname=nil)
+        super(appname)
+        # set the application logger
+        @log = logger
+        @log.progname = @appname
+        @level = @log.level
+      end
+      
+      # Overrides Logger::Application start with the following enhancements:
+      # * pass arguments and a block to the application run method
+      # * improve the output messages
+      # * print an exception to stderr as well as the log
+      def start(*args, &block)
+        status = 1
+        begin
+          status = run(*args, &block)
+        rescue
+          log(FATAL, "#{@appname} detected an exception: #{$!}\n#{$@.qp}")
+          msg = "#{@appname} was unsuccessful: #{$!}."
+          msg += "\nSee the log #{Log.instance.file} for more information." if Log.instance.file
+          $stderr.puts msg
+        ensure
+          log(INFO, "#{@appname} completed with status #{status}.")
+        end
+      end
+    end
+  end
+end

data/lib/jinx/cli/command.rb

@@ -0,0 +1,214 @@
+require 'optparse'
+require 'jinx/helpers/log'
+require 'jinx/cli/application'
+
+module Jinx
+  module CLI
+    # Open the log file before start-up.
+    log_ndx = ARGV.index("--log") || ARGV.index("-l")
+    log_file = log_ndx ? ARGV[log_ndx + 1] : ENV['LOG']
+    debug = ARGV.include?('--debug') || ENV['DEBUG'] =~ /true/i
+    Log.instance.open(log_file, :debug => debug) if log_file or debug
+
+    # Command-line parsing errors.
+    class CommandError < StandardError; end
+      
+    # Command-line parser and executor.
+    class Command < Application
+      # Command line application wrapper.
+      # The specs parameter is an array of command line option and argument
+      # specifications as follows:
+      #
+      # The option specification has format:
+      #
+      # [_option_, _short_, _long_, _class_, _description_]
+      #
+      # where:
+      # * _option_ is the option symbol, e.g. +:output+
+      # * _short_ is the short option form, e.g. "-o"
+      # * _long_ is the long option form, e.g. "--output FILE"
+      # * _class_ is the option value class, e.g. Integer
+      # * _description_ is the option usage, e.g. "Output file"
+      # The _option_, _long_ and _description_ items are required; the _short_
+      # and _class_ items can be omitted.
+      #
+      # The argument specification is an array in the form:
+      #
+      # [_arg_, _text_]
+      #
+      # where:
+      # * _arg_ is the argument symbol, e.g. +:input+
+      # * _text_ is the usage message text, e.g. 'input', '[input]' or 'input ...' 
+      # Both _arg_ and _text_ are required.
+      #
+      # Built-in options include the following:
+      # * +--help+ : print the help message and exit
+      # * +--verbose+ : print additional information to the console
+      # * +--log FILE+ : log file
+      # * +--debug+ : print debug messages to the log
+      # * +--file FILE+: file containing other options
+      # * +--quiet+: suppress printing messages to stdout
+      #
+      # This class processes these built-in options. Subclasses are responsible for
+      # processing any remaining options.
+      #
+      # @param [<(Symbol, String, String, Class, String), (Symbol, String)>, nil] specs
+      #   the command line argument specifications
+      # @yield (see #run)
+      # @yieldparam (see #run)
+      def initialize(specs=Array::EMPTY_ARRAY, &executor)
+        @executor = executor
+        # Validate the specifications.
+        unless Array === specs then
+          raise ArgumentError.new("Command-line specification is not an array: #{specs.qp}")
+        end
+        invalid = specs.detect { |spec| spec.size < 2 }
+        if invalid then
+          raise ArgumentError.new("Command-line argument specification is missing text: #{invalid.qp}")
+        end
+        # Options start with a dash, arguments are whatever is left.
+        @opt_specs, @arg_specs = specs.partition { |spec| spec[1][0, 1] == '-' }
+        # Add the default option specifications.
+        @opt_specs.concat(DEF_OPTS)
+        # The application name is the command.
+        super(File.basename($0, ".bat"))
+      end
+  
+      # Runs this command by calling the block given to this method, if provided,
+      # otherwise the block given to {#initialize}
+      # option or argument symbol => value hash.
+      # @yield [hash] the command execution block
+      # @yieldparam [{Symbol => Object}] hash the argument and option symbol => value hash
+      def run
+        # the option => value hash
+        opts = get_opts
+        # this base class's options
+        handle_options(opts)
+        # add the argument => value hash
+        opts.merge!(get_args)
+        # call the block
+        log(INFO, "Starting #{@appname}...")
+        block_given? ? yield(opts) : call_executor(opts)
+      end
+  
+      private
+      
+      # The default options that apply to all commands.
+      DEF_OPTS = [
+        [:help, "-h", "--help", "Display this help message"],
+        [:file, "--file FILE", "Configuration file containing other options"],
+        [:log, "--log FILE", "Log file"],
+        [:debug, "--debug", "Display debug log messages"],
+        [:quiet, "-q", "--quiet", "Suppress printing messages to stdout"],
+        [:verbose, "-v", "--verbose", "Print additional messages to stdout"]
+      ]
+
+      # @param [{Symbol => Object}] opts the option => value hash
+      def call_executor(opts)
+         if @executor.nil? then Jinx.fail(CommandError, "Command #{self} does not have an execution block") end
+         @executor.call(opts)
+      end
+      
+      # Collects the command line options.
+      #
+      # @return [{Symbol => Object}] the option => value hash 
+      def get_opts
+        # the options hash
+        opts = {}
+        # the option parser
+        OptionParser.new do |parser|
+          # The help argument string is comprised of the argument specification labels.
+          arg_s = @arg_specs.map { |spec| spec[1] }.join(' ')
+          # Build the usage message.
+          parser.banner = "Usage: #{parser.program_name} [options] #{arg_s}"
+          parser.separator ""
+          parser.separator "Options:"
+          # parse the options
+          opts = parse(parser)
+          # grab the usage message
+          @usage = parser.help
+        end
+        opts
+      end
+  
+      # Collects the non-option command line arguments.
+      #
+      # @return [{Symbol => Object}] the argument => value hash 
+      def get_args
+        return Hash::EMPTY_HASH if ARGV.empty?
+        if @arg_specs.empty? then too_many_arguments end
+        # Collect the arguments from the command line.
+        args = {}
+        # The number of command line arguments or all but the last argument specifications,
+        # whichever is less. The last argument can have more than one value, indicated by
+        # the argument specification form '...', so it is processed separately below.
+        n = [ARGV.size, @arg_specs.size - 1].min
+        # the single-valued arguments
+        n.times { |i| args[@arg_specs[i].first] = ARGV[i] }
+        # Process the last argument.
+        if n < ARGV.size then
+          spec = @arg_specs.last
+          arg, form = spec[0], spec[1]
+          # A multi-valued last argument is the residual command argument array.
+          # A single-valued last argument is the last value, if there is exactly one.
+          # Otherwise, there are too many arguments.
+          if form.index('...') then
+            args[arg] = ARGV[n..-1]
+          elsif @arg_specs.size == ARGV.size then
+            args[arg] = ARGV[n]
+          else
+            too_many_arguments
+          end
+        end
+        args
+      end
+      
+      def too_many_arguments
+        halt("Too many arguments - expected #{@arg_specs.size}, found: #{ARGV.join(' ')}.", 1)
+      end
+      
+      # @param [OptionParser] parser the option parser
+      # @return [{Symbol => Object}] the option => value hash
+      def parse(parser)
+        opts = {}
+        @opt_specs.each do |opt, *spec|
+          parser.on_tail(*spec) { |v| opts[opt] = v }
+        end
+        # build the option => value hash 
+        parser.parse!
+        opts
+      end
+      
+      # Processes the built-in options as follows:
+      # * +:help+ - print the usage message and exit
+      # * +:file+ FILE - load the options specified in the given file
+      #
+      # @param [{Symbol => Object}] the option => value hash
+      def handle_options(opts)
+        # if help, then print usage and exit
+        if opts[:help] then halt end
+        # If there is a file option, then load additional options from the file.
+        file = opts.delete(:file)
+        if file then
+          fopts = File.open(file).map { |line| line.chomp }.split(' ').flatten
+          ARGV.concat(fopts)
+          OptionParser.new do |p|
+            opts.merge!(parse(p)) { |ov, nv| ov ? ov : nv }
+          end
+        end
+      end
+      
+      # Prints the given error message and the program usage, then exits with status 1.
+      def fail(message=nil)
+        halt(message, 1)
+      end
+  
+      # Prints the given message and program usage, then exits with the given status.
+      def halt(message=nil, status=0)
+        puts(message) if message
+        puts(@usage)
+        exit(status)
+      end
+    end
+  end
+end