rsmart_toolbox 0.5 → 0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2e7e3f98bbbd519f2f57c8c5a9da33cca0a3de3
-  data.tar.gz: c90a54912dc4d9c536337697a13c028bbdfb8011
+  metadata.gz: 27fabd26f64bc774e3d4bbfefd30d7cc519bd561
+  data.tar.gz: 888167314f2c75e27f67461cdf8592f9f394440f
 SHA512:
-  metadata.gz: 34892dcd8adf786319d6d4261fc291bda5cdeb4903c78ed8fcc74b0de74cc734c192886ce809b2c9a91e40f7916b21941214be55a32c7832787dbccc92a56b05
-  data.tar.gz: 6ec1f8e88e4a45aee20efb607c05169dee3994262093367915abc8a25ca138f850aa043672fa353d2c33a3b90db41ac208043d22e4cfdbfb36fc235831bb2065
+  metadata.gz: e75b6da705654223a6ff1b8f36eb9d049c46511448d7eb8da9d2512f27b82b63f4c006d15dc85c03c592b7e713e7ec41687da6156581eba30754d4719294cb79
+  data.tar.gz: 3fc723d8d3595c88425cf35fdcd2a518f5c67bf2f71153ce9702a097660f84c75522a40ea7f8d20e2a35bf87041567bf57d33527e538df34e5bcf42505979597

data/lib/rsmart_toolbox/etl.rb

@@ -21,7 +21,8 @@ module Rsmart::ETL
   class TextParseError < StandardError
   end
 
-  # Responds to String or Exception.
+  # @param [String, Exception] e the error to handle
+  # @return [Exception] an Exception with a message formatted with $INPUT_LINE_NUMBER.
   def self.error(e)
     if e.kind_of? String
       # default to TextParseError
@@ -33,7 +34,8 @@ module Rsmart::ETL
     raise ArgumentError, "Unsupported error type: #{e.class}"
   end
 
-  # Responds to String or Exception.
+  # @param [String, Exception] e the warning to handle
+  # @return [Exception] an Exception with a message formatted with $INPUT_LINE_NUMBER.
   def self.warning(e)
     if e.kind_of? String
       # default to TextParseError
@@ -45,7 +47,14 @@ module Rsmart::ETL
     raise ArgumentError, "Unsupported error type: #{e.class}"
   end
 
-  # Test to see if subject is a member of valid_values Array
+  # @param [String, #match] subject used for validity checking.
+  # @param [Array<Object>, Regexp] valid_values all of the possible valid values.
+  # @option opt [Boolean] :case_sensitive performs case sensitive matching
+  # @return [Boolean] true if the subject matches valid_values.
+  #   FYI valid_values must respond to #casecmp.
+  # @raise [ArgumentError] if valid_values is nil or empty.
+  # @raise [ArgumentError] case sensitive matching only works for objects
+  #   that respond to #casecmp; primarily String objects.
   def self.valid_value(subject, valid_values, opt={})
     raise ArgumentError, "valid_values must not be nil!" if valid_values.nil?
     if valid_values.kind_of? Regexp
@@ -54,7 +63,7 @@ module Rsmart::ETL
     if valid_values.kind_of? Array
       raise ArgumentError, "valid_values must have at least one element!" unless valid_values.length > 0
       if opt[:case_sensitive] == false # case insensitive comparison requested
-        raise ArgumentError, "case_sensitive only supported for Strings!" unless subject.kind_of?(String)
+        raise ArgumentError, "Object must respond to #casecmp" unless subject.respond_to? 'casecmp'
         valid_values.each do |valid_value|
           return true if valid_value.casecmp(subject) == 0
         end
@@ -64,6 +73,10 @@ module Rsmart::ETL
     return false
   end
 
+  # @param [String] str String to be matched against well known boolean patterns.
+  # @option opt [Boolean] :default the default return value if str is empty.
+  # @return [Boolean] the result of matching the str input against well known boolean patterns.
+  # @raise [TextParseError] if none of the known boolean patterns could be matched.
   def self.parse_boolean(str, opt={})
     return true  if str == true
     return false if str == false
@@ -79,22 +92,34 @@ module Rsmart::ETL
     raise Rsmart::ETL::error TextParseError.new "invalid value for Boolean: '#{str}'"
   end
 
-  # Simply here to help ensure we consistently apply the same encoding options.
-  def self.encode(str, opt={} )
+  # @param [String] str the String to be encoded and invalid characters replaced with valid characters.
+  # @option opt [String] :encoding the character encoding to use.
+  # @return [String] the result of encoding the String and replacing invalid characters with valid characters.
+  def self.encode(str, opt={ encoding: "UTF-8" } )
     opt[:encoding] = "UTF-8" if opt[:encoding].nil?
     str.encode( opt[:encoding], :invalid => :replace,
                 :undef => :replace, :replace => "" )
   end
 
-  # Matches MRI CSV specification:
+  # Matches the MRI CSV specification:
   # The header String is downcased, spaces are replaced with underscores,
   # non-word characters are dropped, and finally to_sym() is called.
+  # @param [String] str the String to be symbolized.
+  # @return [Symbol] String is downcased, spaces are replaced with underscores,
+  #   non-word characters are dropped
+  # @raise [ArgumentError] if str is nil or empty.
   def self.to_symbol(str)
     raise ArgumentError, "Illegal symbol name: '#{str}'" if str.nil? || str.empty?
     encode( str.downcase.gsub(/\s+/, "_").gsub(/\W+/, "") ).to_sym
   end
 
-  # DRY up some common string manipulation
+  # Mutates insert_str and values_str with column_name and value respectively.
+  # Proper SQL value quoting will be performed based on object type.
+  # @param [String] insert_str the left side of the insert statement (i.e. columns)
+  # @param [String] column_name the column name to append to insert_str.
+  # @param [String] values_str the right side of the insert statement (i.e. values)
+  # @param [Object] value the value to append to values_str. Must respond to #to_s.
+  # @return [void]
   def self.mutate_sql_stmt!(insert_str, column_name, values_str, value)
     insert_str.concat "#{column_name.upcase},"
     # TODO what are all of the valid types that should not be quoted?
@@ -103,8 +128,13 @@ module Rsmart::ETL
     else
       values_str.concat "'#{value}',"
     end
+    return nil
   end
 
+  # Prepares a String for a SQL statement where single quotes need to be escaped.
+  # @param [String] str the String to be escaped.
+  # @return [String, nil] the resulting String with single quotes escaped with a backslash.
+  #   If a nil is passed, nil is returned.
   def self.escape_single_quotes(str)
     if str.nil?
       return nil
@@ -112,14 +142,31 @@ module Rsmart::ETL
     return str.to_s.gsub("'", "\\\\'")
   end
 
-  def self.parse_string(str, opt={})
-    opt[:strict]   = true if opt[:strict].nil?
+  # @param [String] str the String to be parsed.
+  # @option opt [String, #to_s] :default the default return value if str is empty. Must respond to #to_s
+  # @option opt [Boolean] :escape_single_quotes escape single quote characters.
+  # @option opt [Integer] :length raise a TextParseError if str.length > :length.
+  # @option opt [String] :name the name of the field being parsed. Used only for error handling.
+  # @option opt [Boolean] :required raise a TextParseError if str is empty.
+  # @option opt [Boolean] :strict strict length checking will produce errors instead of warnings.
+  # @option opt [Array<Object>, Regexp] :valid_values all of the possible valid values.
+  # @return [String] the parsed results. nil or empty inputs will return the empty String by default(i.e. '').
+  # @raise [TextParseError] if the field is :required and found to be empty.
+  # @raise [TextParseError] if str.length > :length && :strict
+  # @raise [TextParseError] if str does not match :valid_values
+  # @example nil or empty inputs will return the empty String by default
+  #   '' == parse_string(nil) && '' == parse_string('')
+  # @see valid_value
+  # @see escape_single_quotes
+  def self.parse_string(str, opt={ strict: true, required: false, escape_single_quotes: true })
+    opt[:strict] = true if opt[:strict].nil?
+    opt[:escape_single_quotes] = true if opt[:escape_single_quotes].nil?
     retval = encode str.to_s.strip
     if opt[:required] && retval.empty?
       raise Rsmart::ETL::error TextParseError.new "Required data element '#{opt[:name]}' not found: '#{str}'"
     end
     if opt[:default] && retval.empty?
-      retval = opt[:default]
+      retval = opt[:default].to_s
     end
     if opt[:length] && retval.length > opt[:length].to_i
       detail = "#{opt[:name]}.length > #{opt[:length]}: '#{str}'-->'#{str[0..(opt[:length] - 1)]}'"
@@ -131,15 +178,36 @@ module Rsmart::ETL
     if opt[:valid_values] && ! valid_value(retval, opt[:valid_values], opt)
       raise Rsmart::ETL::error TextParseError.new "Illegal #{opt[:name]}: value '#{str}' not found in: #{opt[:valid_values]}"
     end
-    return escape_single_quotes retval
+    if opt[:escape_single_quotes]
+      retval = escape_single_quotes retval
+    end
+    return retval
   end
 
+  # Helper method which finds the value by column :name and mutates the SQL statement accordingly.
+  # @param [CSV::Row] row the CSV Row being parsed
+  # @param [String] insert_str the left side of the insert statement (i.e. columns)
+  # @param [String] values_str the right side of the insert statement (i.e. values)
+  # @param [Hash] opt options Hash will be passed through to #parse_string.
+  # @option opt [String] :name the name of the field being parsed. Required.
+  # @return [void]
+  # @raise [ArgumentError] :name is required.
+  # @see parse_string
+  # @see mutate_sql_stmt!
   def self.parse_string!(row, insert_str, values_str, opt={})
     raise ArgumentError, "opt[:name] is required!" unless opt[:name]
     str = parse_string( row[ to_symbol( opt[:name] ) ], opt )
     mutate_sql_stmt! insert_str, opt[:name], values_str, str
   end
 
+  # Parse an Integer from a String.
+  # @note Note the behavioral difference versus #to_i.
+  # @param [String] str the String to be parsed.
+  # @param [Hash] opt options Hash will be passed through to #parse_string.
+  # @return [Integer, nil] the parsed Integer. nil or empty inputs will return nil by default.
+  # @example Unlike #to_i, nil or empty inputs will return nil by default
+  #   nil == parse_integer(nil) && nil == parse_integer('') && 0 != parse_integer(nil)
+  # @see parse_string
   def self.parse_integer(str, opt={})
     s = parse_string str, opt
     if s.empty?
@@ -149,12 +217,30 @@ module Rsmart::ETL
     end
   end
 
+  # Helper method which finds the value by column :name and mutates the SQL statement accordingly.
+  # @param [CSV::Row] row the CSV Row being parsed
+  # @param [String] insert_str the left side of the insert statement (i.e. columns)
+  # @param [String] values_str the right side of the insert statement (i.e. values)
+  # @param [Hash] opt options Hash will be passed through to #parse_integer.
+  # @option opt [String] :name the name of the field being parsed. Required.
+  # @return [void]
+  # @raise [ArgumentError] :name is required.
+  # @see parse_integer
+  # @see mutate_sql_stmt!
   def self.parse_integer!(row, insert_str, values_str, opt={})
     raise ArgumentError, "opt[:name] is required!" unless opt[:name]
     i = parse_integer( row[ to_symbol( opt[:name] ) ], opt )
     mutate_sql_stmt! insert_str, opt[:name], values_str, i
   end
 
+  # Parse a Float from a String.
+  # @note Note the behavioral difference versus #to_f.
+  # @param [String] str the String to be parsed.
+  # @param [Hash] opt options Hash will be passed through to #parse_string.
+  # @return [Float, nil] the parsed Float. nil or empty inputs will return nil by default.
+  # @example Unlike #to_f, nil or empty inputs will return nil by default
+  #   nil == parse_float(nil) && nil == parse_float('') && 0.0 != parse_float(nil)
+  # @see parse_string
   def self.parse_float(str, opt={})
     s = parse_string str, opt
     if s.empty?
@@ -164,9 +250,14 @@ module Rsmart::ETL
     end
   end
 
-  # Useful for parsing "flag" like values. Always returns upcase for consistency.
-  # Assumes :strict :length of 1 by default.
-  def self.parse_flag(str, opt={})
+  # Useful for parsing "flag" like values; i.e. usually single characters.
+  # @param [String] str the String to be parsed.
+  # @param [Hash] opt options Hash will be passed through to #parse_string.
+  # @option opt [Integer] :length the maximum supported length of the field.
+  # @option opt [Boolean] :upcase if true upcase the results.
+  # @return [String] the parsed "flag".
+  # @see parse_string
+  def self.parse_flag(str, opt={ length: 1, upcase: true })
     opt[:length] = 1 if opt[:length].nil?
     opt[:upcase] = true if opt[:upcase].nil?
     retval = parse_string str, opt
@@ -174,32 +265,22 @@ module Rsmart::ETL
     return retval
   end
 
-  # Designed specifically for actv_ind, but could be used on *any*
-  # fields that matches /^(Y|N)$/i.
-  def self.parse_actv_ind(str, opt={})
-    #   `ACTV_IND` varchar(1) COLLATE utf8_bin DEFAULT 'Y',
-    opt[:name]         = "actv_ind" if opt[:name].nil?
-    opt[:default]      = "Y" if opt[:default].nil?
-    opt[:valid_values] = /^(Y|N)$/i if opt[:valid_values].nil?
-    return parse_flag str, opt
-  end
-
-  # Designed specifically for actv_ind, but could be used on *any*
-  # fields that matches /^(Y|N)$/i.
-  def self.parse_actv_ind!(row, insert_str, values_str, opt={})
-    #   `ACTV_IND` varchar(1) COLLATE utf8_bin DEFAULT 'Y',
-    opt[:name] = "actv_ind" if opt[:name].nil?
-    actv_ind = Rsmart::ETL::parse_actv_ind row[ to_symbol( opt[:name] ) ]
-    Rsmart::ETL::mutate_sql_stmt! insert_str, opt[:name], values_str, actv_ind
-  end
-
   # Parse common command line options for CSV --> SQL transformations.
+  # @param [String] executable the name of the script from which we are executing. See example.
+  # @param [Array<String>] args the command line args.
+  # @option opt [String] :csv_filename the input file from which the CSV will be read.
+  #   Defaults to the first element of args Array.
+  # @option opt [String] :sql_filename the output file to which the SQL will be written.
+  # @option opt [Hash] :csv_options the options that will be used by the CSV parser.
+  # @return [Hash] a Hash containing the parsed command line results.
+  # @example The most common usage:
+  #   opt = Rsmart::ETL.parse_csv_command_line_options (File.basename $0), ARGF.argv
   def self.parse_csv_command_line_options(
       executable, args, opt={ csv_options: { headers: :first_row,
                                              header_converters: :symbol,
                                              skip_blanks: true,
-                                             col_sep: ",", # comma by default
-                                             quote_char: '"', # double quote by default
+                                             col_sep: ",",
+                                             quote_char: '"'
                                              }
                               } )
     optparse = OptionParser.new do |opts|
@@ -208,10 +289,10 @@ module Rsmart::ETL
         opt[:sql_filename] = f
       end
       opts.on( '-s [separator_character]' ,'--separator [separator_character]', 'The character that separates each column of the CSV file.') do |s|
-        opt[:col_sep] = s
+        opt[:csv_options][:col_sep] = s
       end
       opts.on( '-q [quote_character]' ,'--quote [quote_character]', 'The character used to quote fields.') do |q|
-        opt[:quote_char] = q
+        opt[:csv_options][:quote_char] = q
       end
       opts.on( '-h', '--help', 'Display this screen' ) do
         puts opts

data/lib/rsmart_toolbox/etl/grm.rb

@@ -187,4 +187,23 @@ module Rsmart::ETL::GRM
     return Rsmart::ETL::parse_flag str, opt
   end
 
+  # Designed specifically for actv_ind, but could be used on *any*
+  # fields that matches /^(Y|N)$/i.
+  def self.parse_actv_ind(str, opt={})
+    #   `ACTV_IND` varchar(1) COLLATE utf8_bin DEFAULT 'Y',
+    opt[:name]         = "actv_ind" if opt[:name].nil?
+    opt[:default]      = "Y" if opt[:default].nil?
+    opt[:valid_values] = /^(Y|N)$/i if opt[:valid_values].nil?
+    return Rsmart::ETL::parse_flag str, opt
+  end
+
+  # Designed specifically for actv_ind, but could be used on *any*
+  # fields that matches /^(Y|N)$/i.
+  def self.parse_actv_ind!(row, insert_str, values_str, opt={})
+    #   `ACTV_IND` varchar(1) COLLATE utf8_bin DEFAULT 'Y',
+    opt[:name] = "actv_ind" if opt[:name].nil?
+    actv_ind = parse_actv_ind row[ Rsmart::ETL::to_symbol( opt[:name] ) ]
+    Rsmart::ETL::mutate_sql_stmt! insert_str, opt[:name], values_str, actv_ind
+  end
+
 end

data/lib/rsmart_toolbox/version.rb

@@ -15,5 +15,5 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 module Rsmart
-  VERSION = "0.5"
+  VERSION = "0.6"
 end

data/spec/rsmart_toolbox/etl_spec.rb

@@ -342,7 +342,7 @@ RSpec.describe "Rsmart::ETL" do
     it "Modifies the insert_str and values_str based on a CSV::Row match" do
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], ['Y'], true)
-      ETL.parse_actv_ind!(row, insert_str, values_str)
+      GRM.parse_actv_ind!(row, insert_str, values_str)
       expect(insert_str).to eq("ACTV_IND,")
       expect(values_str).to eq("'Y',")
     end
@@ -350,7 +350,7 @@ RSpec.describe "Rsmart::ETL" do
     it "allows for lowercase input Strings" do
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], ['n'], true)
-      ETL.parse_actv_ind!(row, insert_str, values_str)
+      GRM.parse_actv_ind!(row, insert_str, values_str)
       expect(insert_str).to eq("ACTV_IND,")
       expect(values_str).to eq("'N',")
     end
@@ -358,12 +358,12 @@ RSpec.describe "Rsmart::ETL" do
     it "Returns a default value of 'Y' and does not raise an TextParseError if nil or empty" do
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], [nil], true)
-      expect { ETL.parse_actv_ind!(row, insert_str, values_str) }.not_to raise_error
+      expect { GRM.parse_actv_ind!(row, insert_str, values_str) }.not_to raise_error
       expect(insert_str).to eq("ACTV_IND,")
       expect(values_str).to eq("'Y',")
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], [''], true)
-      expect { ETL.parse_actv_ind!(row, insert_str, values_str) }.not_to raise_error
+      expect { GRM.parse_actv_ind!(row, insert_str, values_str) }.not_to raise_error
       expect(insert_str).to eq("ACTV_IND,")
       expect(values_str).to eq("'Y',")
     end
@@ -371,13 +371,13 @@ RSpec.describe "Rsmart::ETL" do
     it "Raises an TextParseError if not a valid 'Y/N' value" do
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], ["Q"], true)
-      expect { ETL.parse_actv_ind!(row, insert_str, values_str) }.to raise_error(TextParseError)
+      expect { GRM.parse_actv_ind!(row, insert_str, values_str) }.to raise_error(TextParseError)
     end
 
     it "Raises an TextParseError if length exceeds 1 characters" do
       insert_str = ""; values_str = "";
       row = CSV::Row.new(['actv_ind'.to_sym], ["x" * 2], true)
-      expect { ETL.parse_actv_ind!(row, insert_str, values_str) }.to raise_error(TextParseError)
+      expect { GRM.parse_actv_ind!(row, insert_str, values_str) }.to raise_error(TextParseError)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsmart_toolbox
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
 platform: ruby
 authors:
 - Lance Speelmon
@@ -30,7 +30,7 @@ cert_chain:
   sKRWzEtHFamxQaIspOja5O4oQKiCbWa90fEuIoCtwyy1rQtL9VKoDTs4vZASXNuc
   F/lEyekXSjN36uTtlt4LkKLn/k7k5gRbt4+C9Q==
   -----END CERTIFICATE-----
-date: 2014-08-17 00:00:00.000000000 Z
+date: 2014-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: builder