libis-tools 0.9.20 → 0.9.21

data/lib/libis/tools/config_file.rb

@@ -2,7 +2,6 @@
 require 'singleton'
 require 'yaml'
 require 'erb'
-require 'logger'
 
 require 'libis/tools/deep_struct'
 

data/lib/libis/tools/deep_struct.rb

@@ -4,10 +4,18 @@ require 'recursive-open-struct'
 module Libis
   module Tools
 
-    # A class that derives from OpenStruct through the RecursiveOpenStruct. A RecursiveOpenStruct is derived from
-    # stdlib's OpenStruct, but can be made recursive. DeepStruct enforces this behaviour and adds a clear! method.
+    # A class that derives from OpenStruct through the RecursiveOpenStruct.
+    # By wrapping a Hash recursively, it allows for easy access to the content by method names.
+    # A RecursiveOpenStruct is derived from stdlib's OpenStruct, but can be made recursive.
+    # DeepStruct enforces this behaviour and adds a clear! method.
     class DeepStruct < RecursiveOpenStruct
 
+      # Create a new DeepStruct from a Hash and configure the behaviour.
+      #
+      # @param [Hash] hash the initial data structure.
+      # @param [Hash] opts optional configuration options:
+      #           * recurse_over_arrays: also wrap the Hashes that are enbedded in Arrays. Default: true.
+      #           * preserver_original_keys: creating a Hash from the wrapper preserves symbols and strings as keys. Default: true.
       def initialize(hash = {}, opts = {})
         hash = {} unless hash
         opts = {} unless opts

data/lib/libis/tools/extend/empty.rb

@@ -1,6 +1,6 @@
-# encoding: utf-8
-
+# Extension for NilClass
 class NilClass
+  # Allows nil.empty?
   def empty?
     true
   end

data/lib/libis/tools/extend/hash.rb

@@ -1,11 +1,14 @@
 require 'backports/rails/hash'
 
+# Extension class for Hash
 class Hash
 
+  # Removes all hash entries for which value.empty? is true
   def cleanup
     self.delete_if { |_,v| v.nil? || (v.respond_to?(:empty?) ? v.empty? : false) }
   end unless method_defined? :cleanup
 
+  # Removes all hash entries for which value.empty? is true. Performed recursively.
   def recursive_cleanup
     delete_proc = Proc.new do |_, v|
       v.delete_if(&delete_proc) if v.kind_of?(Hash)
@@ -14,6 +17,7 @@ class Hash
     self.delete_if &delete_proc
   end unless method_defined? :recursive_cleanup
 
+  # Merges two hashes, but does so recursively.
   def recursive_merge(other_hash)
     self.merge(other_hash) do |_, old_val, new_val|
       if old_val.is_a? Hash
@@ -24,6 +28,7 @@ class Hash
     end
   end unless method_defined? :recursive_merge
 
+  # Merges two hashes in-place, but does so recursively.
   def recursive_merge!(other_hash)
     self.merge!(other_hash) do |_, old_val, new_val|
       if old_val.is_a? Hash
@@ -34,30 +39,38 @@ class Hash
     end
   end unless method_defined? :recursive_merge!
 
-  def key_strings_to_symbols!(opts = {})
-    self.replace self.key_strings_to_symbols opts
+  # Convert all keys to symbols. In-place operation.
+  # @param (see #key_strings_to_symbols)
+  def key_strings_to_symbols!(options = {})
+    self.replace self.key_strings_to_symbols options
   end unless method_defined? :key_strings_to_symbols!
 
-  def key_strings_to_symbols(opts = {})
-    opts = {resursive: false, upcase: false, downcase: false}.merge opts
+  # Return new Hash with all keys converted to symbols.
+  # @param [Hash] opts valid options are:
+  #   * recursive : perform operation recursively
+  #   * upcase : convert all keys to upper case
+  #   * downcase : convert all keys to lower case
+  #   all options are false by default
+  def key_strings_to_symbols(options = {})
+    options = {resursive: false, upcase: false, downcase: false}.merge options
 
     r = Hash.new
     self.each_pair do |k,v|
 
       k = k.to_s if k.kind_of? Symbol
       if k.kind_of? String
-        k = k.downcase if opts[:downcase]
-        k = k.upcase if opts[:upcase]
+        k = k.downcase if options[:downcase]
+        k = k.upcase if options[:upcase]
         k = k.to_sym
       end
 
-      if opts[:recursive]
+      if options[:recursive]
         case v
           when Hash
-            v = v.key_strings_to_symbols opts
+            v = v.key_strings_to_symbols options
           when Array
             # noinspection RubyResolve
-            v = v.collect { |a| (a.kind_of? Hash) ? a.key_strings_to_symbols(opts) :  Marshal.load(Marshal.dump(a)) }
+            v = v.collect { |a| (a.kind_of? Hash) ? a.key_strings_to_symbols(options) :  Marshal.load(Marshal.dump(a)) }
           else
             # noinspection RubyResolve
             v = Marshal.load(Marshal.dump(v))
@@ -71,12 +84,18 @@ class Hash
     r
   end unless method_defined? :key_strings_to_symbols
 
-  def key_symbols_to_strings!(opts = {})
-    self.replace self.key_symbols_to_strings opts
+  # Convert all keys to strings. In-place operation.
+  # (@see #key_symbols_to_strings)
+  # @param (see #key_symbols_to_strings)
+  def key_symbols_to_strings!(options = {})
+    self.replace self.key_symbols_to_strings options
   end unless method_defined? :key_symbols_to_strings!
 
-  def key_symbols_to_strings(opts = {})
-    opts = {resursive: false, upcase: false, downcase: false}.merge opts
+  # Return new Hash with all keys converted to strings.
+  # (see #key_strings_to_symbols)
+  # @param (see #key_strings_to_symbols)
+  def key_symbols_to_strings(options = {})
+  options = {resursive: false, upcase: false, downcase: false}.merge options
 
     r = Hash.new
     self.each_pair do |k,v|
@@ -84,17 +103,17 @@ class Hash
       k = k.to_sym if k.kind_of? String
       if k.kind_of? Symbol
         k = k.to_s
-        k = k.downcase if opts[:downcase]
-        k = k.upcase if opts[:upcase]
+        k = k.downcase if options[:downcase]
+        k = k.upcase if options[:upcase]
       end
 
-      if opts[:recursive]
+      if options[:recursive]
         case v
           when Hash
-            v = v.key_symbols_to_strings(opts)
+            v = v.key_symbols_to_strings(options)
           when Array
             # noinspection RubyResolve
-            v = v.collect { |a| (a.kind_of? Hash) ? a.key_symbols_to_strings(opts) : Marshal.load(Marshal.dump(a)) }
+            v = v.collect { |a| (a.kind_of? Hash) ? a.key_symbols_to_strings(options) : Marshal.load(Marshal.dump(a)) }
           else
             # noinspection RubyResolve
             v = Marshal.load(Marshal.dump(v))

data/lib/libis/tools/extend/kernel.rb

@@ -1,5 +1,7 @@
+# Extension class
 module Kernel
 
+  # Debugging aid: extract the name of the argument of the last caller
   def extract_argstring_from(name, call_stack)
     file, line_number = call_stack.first.match(/^(.+):(\d+)/).captures
     line = File.readlines(file)[line_number.to_i - 1].strip
@@ -8,6 +10,13 @@ module Kernel
     argstring
   end
 
+  # Debugging aid: print "<name> : <value>"
+  #
+  # Example:
+  #     x = 'abc'
+  #     dputs x
+  #     # => x : 'abc'
+  #
   def dputs(value)
     name = extract_argstring_from :dputs, caller
     puts "#{name} : '#{value}'"

data/lib/libis/tools/extend/string.rb

@@ -1,9 +1,14 @@
+require 'backports/rails/string'
+
+# Extension class
 class String
 
+  # Check if string is empty
   def blank?
     self == ''
   end unless method_defined? :blank?
 
+  # Create sortable object from string. Supports better natural sorting.
   def sort_form
     result = []
     matcher = /^(\D*)(\d*)(.*)$/
@@ -19,30 +24,27 @@ class String
     result
   end unless method_defined? :sort_form
 
-  def underscore
-    self.gsub(/::/, '/').
-        gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
-        gsub(/([a-z\d])([A-Z])/, '\1_\2').
-        tr('-', '_').
-        downcase
-  end unless method_defined? :underscore
-
+  # Quote string for command-line use.
   def quote
     '\"' + self.gsub(/"/) { |s| '\\' + s[0] } + '\"'
   end unless method_defined? :quote
 
+  # Escape string for use in Regular Expressions
   def escape_for_regexp
     self.gsub(/[\.\+\*\(\)\{\}\|\/\\\^\$"']/) { |s| '\\' + s[0].to_s }
   end
 
+  # Escape double quotes for usage in code strings.
   def escape_for_string
     self.gsub(/"/) { |s| '\\' + s[0].to_s }
   end
 
+  # Escape double quotes for usage in passing through scripts
   def escape_for_cmd
     self.gsub(/"/) { |s| '\\\\\\' + s[0].to_s }
   end
 
+  # Escape single quotes for usage in SQL statements
   def escape_for_sql
     self.gsub(/'/) { |s| ($` == '' || $' == '' ? '' : '\'') + s[0].to_s }
   end
@@ -51,19 +53,23 @@ class String
     self.gsub /^(\d+|error|float|string);\\?#/, ''
   end
 
+  # Convert whitespace into underscores
   def remove_whitespace
     self.gsub(/\s/, '_')
   end
 
+  # Escape all not-printabe characters in hex format
   def encode_visual(regex = nil)
     regex ||= /\W/
     self.gsub(regex) { |c| '_x' + '%04x' % c.unpack('U')[0] + '_'}
   end unless method_defined? :encode_visual
 
+  # Convert all not-printable characters encoded in hex format back to original
   def decode_visual
     self.gsub(/_x([0-9a-f]{4})_/i) { [$1.to_i(16)].pack('U') }
   end unless method_defined? :decode_visual
 
+  # Align a multi-line string to the left by removing as much spaces from the left as possible.
   def align_left
     string = dup
     relevant_lines = string.split(/\r\n|\r|\n/).select { |line| line.size > 0 }
@@ -78,7 +84,10 @@ class String
 
 end
 
+# Extension class
 class NilClass
+
+  # Allow nil.blank? so that blank? can be applied without errors.
   def blank?
     true
   end

data/lib/libis/tools/logger.rb

@@ -7,64 +7,115 @@ require 'libis/tools/extend/string'
 module Libis
   module Tools
 
-    # The Logger module adds logging functionality to any class.
+    # This module adds logging functionality to any class.
     #
     # Just include the ::Libis::Tools::Logger module and the methods debug, info, warn, error and fatal will be
     # available to the class instance. Each method takes a message argument and optional extra parameters.
     #
-    # The methods all call the {#message} method with the logging level as first argument and the supplied arguments
-    # appended.
+    # It is possible to overwrite the {#logger} method with your own implementation to use
+    # a different logger for your class.
+    #
+    # The methods all call the {#message} method with the logging level as first argument
+    # and the supplied arguments appended.
+    #
+    # Example:
+    #
+    #     require 'libis/tools/logger'
+    #     class TestLogger
+    #       include ::Libis::Tools::Logger
+    #       attr_accessor :options, name
+    #     end
+    #     tl = TestLogger.new
+    #     tl.debug 'message'
+    #     tl.warn 'message'
+    #     tl.error 'huge error: [%d] %s', 1000, 'Exit'
+    #     tl.info 'Running application: %s', t.class.name
+    #
+    # produces:
+    #     D, [...] DEBUG : message
+    #     W, [...]  WARN : message
+    #     E, [...] ERROR : huge error: [1000] Exit
+    #     I, [...]  INFO : Running application TestLogger
+    #
     module Logger
 
-      def self.included(klass)
-        klass.class_eval do
-
-          def debug(msg, *args)
-            return if (self.options[:quiet] rescue false)
-            message ::Logger::DEBUG, msg, *args
-          end
+      # Get the logger instance
+      #
+      # Default implementation is to get the root logger from the Config, but can be overwritten for sub-loggers.
+      # @!method(logger)
+      def logger
+        Config.logger
+      end
 
-          def info(msg, *args)
-            return if (self.options[:quiet] rescue false)
-            message ::Logger::INFO, msg, *args
-          end
+      # Send a debug message to the logger.
+      #
+      # If the optional extra parameters are supplied, the first parameter will be interpreted as a format
+      # specification. It's up to the caller to make sure the format specification complies with the number and
+      # types of the extra arguments. If the format substitution fails, the message will be printed as:
+      # '<msg> - [<args>]'.
+      #
+      # @param [String] msg the message.
+      # @param [Array] args optional extra arguments.
+      # @!method(debug(msg, *args))
+      def debug(msg, *args)
+        message :DEBUG, msg, *args
+      end
 
-          def warn(msg, *args)
-            return if (self.options[:quiet] rescue false)
-            message ::Logger::WARN, msg, *args
-          end
+      # Send an info message to the logger.
+      #
+      # (see #debug)
+      # @param (see #debug)
+      # @!method(info(msg, *args))
+      def info(msg, *args)
+        message :INFO, msg, *args
+      end
 
-          def error(msg, *args)
-            message ::Logger::ERROR, msg, *args
-          end
+      # Send a warning message to the logger.
+      #
+      # (see #debug)
+      # @param (see #debug)
+      # @!method(warn(msg, *args))
+      def warn(msg, *args)
+        message :WARN, msg, *args
+      end
 
-          def fatal(msg, *args)
-            message ::Logger::FATAL, msg, *args
-          end
+      # Send an error message to the logger.
+      #
+      # (see #debug)
+      # @param (see #debug)
+      # @!method(error(msg, *args))
+      def error(msg, *args)
+        message :ERROR, msg, *args
+      end
 
-          # The method that performs the code logging action.
-          #
-          # If extra arguments are supplied, the message string is expected to be a format specification string and the
-          # extra arguments will be applied to it.
-          #
-          # This default message method implementation uses the logger of ::Libis::Tools::Config. If an 'appname'
-          # parameter is defined in the Config object, it will be used as program name by the logger, otherwise the
-          # class name is taken.
-          #
-          # @param [{::Logger::Severity}] severity
-          # @param [String] msg message string
-          # @param [Object] args optional list of extra arguments
-          def message(severity, msg, *args)
-            message_text = (msg % args rescue ((msg + ' - %s') % args.to_s))
-            appname = Config.appname
-            appname = self.name if self.respond_to? :name
-            appname = self.class.name if appname.blank?
-            Config.logger.add(severity, message_text, appname)
-          end
+      # Send a fatal message to the logger.
+      #
+      # (see #debug)
+      # @param (see #debug)
+      # @!method(fatal(msg, *args))
+      def fatal(msg, *args)
+        message :FATAL, msg, *args
+      end
 
-        end
+      # The method that performs the code logging action.
+      #
+      # If extra arguments are supplied, the message string is expected to be a format specification string and the
+      # extra arguments will be applied to it.
+      #
+      # This default message method implementation uses the logger of ::Libis::Tools::Config. If an 'appname'
+      # parameter is defined in the Config object, it will be used as program name by the logger, otherwise the
+      # class name is taken.
+      #
+      # @param [{::Logger::Severity}] severity
+      # @param [String] msg message string
+      # @param [Object] args optional list of extra arguments
+      # @!method(message(severity, msg, *args))
+      def message(severity, msg, *args)
+        message_text = (msg % args rescue ((msg + ' - %s') % args.to_s))
+        self.logger.add(::Logging.level_num(severity), message_text)
       end
 
+
     end
 
   end

data/lib/libis/tools/metadata.rb

@@ -1,11 +1,15 @@
 module Libis
   module Tools
+
+    # This module groups several metadata formats. Note that all metadata related classes will move into a Gem of their
+    # own in the future.
     module Metadata
 
       autoload :MarcRecord, 'libis/tools/metadata/marc_record'
       autoload :Marc21Record, 'libis/tools/metadata/marc21_record'
       autoload :DublinCoreRecord, 'libis/tools/metadata/dublin_core_record'
 
+      # Mappers implementations for converting MARC records to Dublin Core.
       module Mappers
 
         autoload :Kuleuven, 'libis/tools/metadata/mappers/kuleuven'
@@ -17,4 +21,4 @@ module Libis
   end
 end
 
-require_relative 'metadata/parsers'
+require_relative 'metadata/parsers'