util 0.4.0

data/lib/util.rb

@@ -0,0 +1,12 @@
+require 'util/args'
+require 'util/communia'
+require 'util/console_logger'
+require 'util/downloader'
+require 'util/i18n'
+require 'util/lists'
+require 'util/result'
+require 'util/test'
+require 'util/yaml'
+
+# A collection of simple utilities to reduce boilerplate.
+module Util; end

data/lib/util/args.rb

@@ -0,0 +1,138 @@
+module Util
+  # Functions to typecheck the arguments of a function.
+  class Args
+    private_class_method :new
+
+    # If no alternative value is provided to {check}, these will be used.
+    DEFAULT_VALUES = {
+      Array => [],
+      'Boolean' => false,
+      Class => NilClass,
+      Complex => 0.to_c,
+      Encoding => Encoding::UTF_8,
+      FalseClass => true,
+      Float => 0.0,
+      Hash => {},
+      Integer => 0,
+      Module => Kernel,
+      NilClass => nil,
+      Object => Object.new,
+      Queue => Queue.new,
+      Random => Random::DEFAULT,
+      Range => (0..),
+      Rational => 0.to_r,
+      Regexp => /.*/,
+      SizedQueue => SizedQueue.new(1),
+      String => '',
+      Symbol => :nil,
+      Time => Time.now,
+      TrueClass => false,
+    }
+
+    # @no_doc
+    FUNCTIONS = {
+      Array => :to_a,
+      Complex => :to_c,
+      Enumerator => :to_enum,
+      Float => :to_f,
+      Hash => :to_h,
+      Integer => :to_i,
+      Rational => :to_r,
+      String => :to_s,
+      Symbol => :to_sym,
+    }
+
+    # Verify whether a given argument or arguments belong to a class or can
+    # be converted into that class. Any number of sequences of the three
+    # arguments below can be passed.
+    # @param [Object] value argument to check
+    # @param [Class, String] klass class to which it must belong; Boolean is
+    #   a synonym for TrueClass; all standard classes who have #to_X will try
+    #   to convert the value if it responds to the given conversion method
+    #   (if not provided, +NilClass+ is used)
+    # @param [Object] alt value to use if the argument does not belong to the
+    #   wanted class (if not provided, will default to +DEFAULT_VALUES[klass]+)
+    # @return [Object, Array<Object>] an array of the checked and converted
+    #   values, or just the value if the array has only one element
+    # @example
+    #     def create_integer_hash key, value
+    #       key, value = Util::Args.check key, Symbol, :def, value, Integer, nil
+    #       { key => value }
+    #     end
+    #
+    #     hash1 = create_integer_hash 'hello', 13.4 # { :hello => 13 }
+    #     hash2 = create_integer_hash nil, nil # { :def => nil }
+    def self.check *args
+      check_internal nil, *args
+    end
+
+    # Typecheck the content of an options hash, while ignoring undefined
+    # options. Calls Args.check on the values associated with a given key,
+    # according to the rest of the informations given.
+    # @param [Hash] opts hash whose content to check
+    # @param [Array] args see {check} for the rest of the arguments
+    # @return (see check)
+    # @note It is not necessary to check whether +opts+ is a +Hash+, the
+    #   method will do it.
+    # @example
+    #     def initialize opts={}
+    #       @encoding, @font_size, @line_height = Util::Args.check_opts opts, \
+    #         :enc, String, 'UTF-8', :size, Integer, 12, :height, Float, 1.0
+    #     end
+    def self.check_opts opts, *args
+      check_internal opts, *args
+    end
+
+    private
+
+    # Common parts to both {check} and {check_opts}.
+    def self.check_internal opts, *args
+      return nil if args.length == 0
+      opts = check opts, Hash, {} unless opts.nil?
+      count, modulo = args.length.divmod 3
+
+      if modulo == 1 then
+        args << NilClass
+      end
+
+      if modulo > 0 then
+        count += 1
+        args << DEFAULT_VALUES[args.last]
+      end
+
+      res = []
+      (0...count).each do |i|
+        value, klass, alt = args[i*3], args[i*3+1], args[i*3+2]
+        value = opts[value] unless opts.nil?
+        res << alt and next if value.nil?
+
+        if FUNCTIONS.has_key? klass then
+          f = FUNCTIONS[klass]
+          res << (value.respond_to?(f) ? value.send(f) : alt)
+          next
+        end
+
+        case klass.to_s
+        when 'Boolean' then res << (value ? true : alt) and next
+        when 'FalseClass' then res << (value ? alt : false) and next
+        when 'TrueClass' then res << (value ? true : alt) and next
+        end
+
+        res << alt and next unless klass.is_a?(Class) and value.is_a?(klass)
+        res << value
+      end
+
+      (res.length < 2) ? res.first : res
+    end
+  end
+
+  # Alias for {Args.check_opts}
+  class Opts
+    private_class_method :new
+
+    # Alias for {Args.check_opts}
+    def self.check opts, *args
+      Args.check_opts opts, *args
+    end
+  end
+end

data/lib/util/communia.rb

@@ -0,0 +1,8 @@
+module Util
+  # @no_doc
+  # Path to source code of the Ruby part of the gem.
+  LIB_PATH = File.dirname(File.dirname(File.expand_path(__FILE__)))
+  # @no_doc
+  # Path to the data files of the gem.
+  SHARE_PATH = File.join File.dirname(LIB_PATH), 'share'
+end

data/lib/util/console_logger.rb

@@ -0,0 +1,178 @@
+module Util
+  # Help write formatted messages to the console, for friendlier
+  # command-line interface. Uses generally available ANSI codes, so
+  # it should work on all UNIXes and on recent Windows.
+  #
+  # @example
+  #     cl = ConsoleLogger.new e: { :stderr => true }
+  #     cl.warning 'Errors will be logged on STDERR.'
+  #       # Message written in yellow
+  #     begin
+  #       text = File.read 'secret.msg'
+  #     rescue Exception => e
+  #       msg = 'Cannot go any further because of %E%, aborting.'
+  #       cl.error msg, 'E': e.message
+  #         # Message written in red
+  #     end
+  class ConsoleLogger
+    require 'util/args'
+
+    # ANSI code to reset all formatting
+    RESET = "\x1b[0m"
+    # @no_doc
+    BASE = "\x1b[%CODE%m"
+    # @no_doc
+    COLORS = { :black => 0, :red => 1, :green => 2, :yellow => 3,
+               :blue => 4, :magenta => 5, :cyan => 6, :white => 7 }
+    # @no_doc
+    COLOR_TYPES = { :fg => 30, :bg => 40, :bright => 60 }
+    # @no_doc
+    DECORS = { :bold => 1, :faint => 2, :italic => 3, :underline => 4,
+               :blink => 5, :reverse => 7, :conceal => 8, :crossed => 9,
+               :dbl_underline => 21, :overline => 53 }
+    # @no_doc
+    CL = ConsoleLogger
+
+    # Generate the ANSI code to obtain a given formatting.
+    # @param opts [Hash] the wanted formatting
+    # @option opts [:black, :blue, :cyan, :green, :magenta,
+    #   :red, :white, :yellow] :color font color
+    # @option opts [idem] :bgcolor background color
+    # @option opts [Boolean] :bright use bright font color
+    # @option opts [Boolean] :bgbright use bright background color
+    # @option opts [:blink, :bold, :conceal, :crossed,
+    #   :dbl_underline, :faint, :italic, :overline, :reverse,
+    #   :underline, Array<idem>] :decor text decorations
+    def self.escape_code opts={}
+      opts = Util::Args.check opts, Hash, {}
+      return RESET if opts.empty?
+      code = ''
+
+      if opts.has_key? :color then
+        color = Util::Args.check opts[:color], Symbol, :white
+        color = :white unless COLORS.has_key? color
+        bright = Util::Args.check opts[:bright], 'Boolean', false
+
+        cur = COLOR_TYPES[:fg] + COLORS[color]
+        cur += COLOR_TYPES[:bright] if bright
+        code += cur.to_s
+      end
+
+      if opts.has_key? :bgcolor then
+        color = Util::Args.check opts[:bgcolor], Symbol, :black
+        color = :black unless COLORS.has_key? color
+        bright = Util::Args.check opts[:bgbright], 'Boolean', false
+
+        cur = COLOR_TYPES[:bg] + COLORS[color]
+        cur += COLOR_TYPES[:bright] if bright
+        code += ';' unless code.empty?
+        code += cur.to_s
+      end
+
+      if opts.has_key? :decor then
+        decors = Util::Args.check opts[:decor], Array, [opts[:decor]]
+        cur = ''
+        decors.each do |d|
+          cur += ';' + DECORS[d].to_s if DECORS.has_key? d
+        end
+        cur = cur.sub ';', '' if code.empty?
+        code += cur
+      end
+
+      code.empty? ? RESET : BASE.sub('%CODE%', code)
+    end
+
+    # Create a new ConsoleLogger.
+    # @param config [Hash] initial configuration: for each kind of
+    #   message, whether to use STDERR or STDOUT, and which formatting
+    # @option config [Hash { :stderr => Boolean, :code => String }]
+    #   e configuration for error (defaults to red text)
+    # @option config [Hash { :stderr => Boolean, :code => String }]
+    #   i configuration for information (defaults to cyan text)
+    # @option config [Hash { :stderr => Boolean, :code => String }]
+    #   n configuration for normal (defaults to no formatting)
+    # @option config [Hash { :stderr => Boolean, :code => String }]
+    #   o configuration for ok (defaults to green text)
+    # @option config [Hash { :stderr => Boolean, :code => String }]
+    #   w configuration for warning (defaults to yellow text)
+    def initialize config={}
+      config = Util::Args.check config, Hash, {}
+      @config = {
+        :e => { :io => $stdout, :code => CL.escape_code(color: :red) },
+        :i => { :io => $stdout, :code => CL.escape_code(color: :cyan) },
+        :n => { :io => $stdout, :code => '' },
+        :o => { :io => $stdout, :code => CL.escape_code(color: :green) },
+        :w => { :io => $stdout, :code => CL.escape_code(color: :yellow) },
+      }
+
+      config.each_pair do |k, v|
+        next unless @config.has_key? k
+        v = Util::Args.check v, Hash, {}
+        @config[k][:io] = (v[:stderr] == true) ? $stderr : $stdout
+        @config[k][:code] = CL.escape_code v
+      end
+    end
+
+    # Print an error to the console.
+    # @param msg [String] message to print
+    # @param payload [Hash<#to_s, #to_s>] parts to replace in the base
+    #   message: '%KEY%' will be replaced by 'VALUE'.
+    # @example
+    #     msg = 'The array contains only %I% objects of type %T%.'
+    #     cl.error msg, 'T': Float, 'I': arr.how_many?(Float)
+    #
+    #     # Results in `The array contains only 42 objects of type Float.`
+    # @return nil
+    def error msg, payload={}
+      self.printf :e, msg, payload
+    end
+
+    # Print an important message to the console.
+    # @param (see #error)
+    # @example (see #error)
+    # @return (see #error)
+    def important msg, payload={}
+      self.printf :i, msg, payload
+    end
+
+    # Print a normal message to the console.
+    # @param (see #error)
+    # @example (see #error)
+    # @return (see #error)
+    def normal msg, payload={}
+      self.printf :n, msg, payload
+    end
+
+    # Print an approval to the console.
+    # @param (see #error)
+    # @example (see #error)
+    # @return (see #error)
+    def ok msg, payload={}
+      self.printf :o, msg, payload
+    end
+
+    # Print a warning to the console.
+    # @param (see #error)
+    # @example (see #error)
+    # @return (see #error)
+    def warning msg, payload={}
+      self.printf :w, msg, payload
+    end
+
+    private
+
+    # Common parts to all messaging methods.
+    # @param type [:e, :i, :n, :o, :w] kind of message
+    # @param msg (see #error)
+    # @param payload (see #error)
+    # @return nil
+    def printf type, msg, payload
+      msg = Util::Args.check msg, String, ''
+      payload = Util::Args.check payload, Hash, {}
+      payload.each_pair do |k, v|
+        msg = msg.gsub "%#{k}%", v.to_s
+      end
+      @config[type][:io].puts @config[type][:code] + msg + RESET
+    end
+  end
+end

data/lib/util/downloader.rb

@@ -0,0 +1,157 @@
+module Util
+  # A helper to safely dowload a file. Can be dowloaded to an actual file,
+  # or directly parsed by another gem (e. g. +Nokogiri+).
+  # @example
+  #     require 'oga' # Must be required by the user, `Util` will not do it
+  #     url = 'https://www.perdu.com/'
+  #     html = Util::Downloader.new(url).set_dest(Oga)
+  #     html.download # => Util::Result.ok
+  #     html.data.at_css('h1').text # 'Perdu sur l\'Internet ?'
+  #
+  #     url = 'https://gitlab.com/uploads/-/system/user/avatar/5582173/avatar.png'
+  #     Util::Downloader.new(url).set_name('guillel.png').set_force.download
+  class Downloader
+    attr_reader :data
+    attr_reader :dest
+    attr_reader :force
+    attr_reader :name
+    attr_reader :ref
+    attr_reader :url
+
+    # @no_doc
+    ALLOWED = [:data, :force, :url]
+    # @no_doc
+    DEFAULT_OPTIONS = {
+      :dest => '.',
+      :name => '',
+      :ref => '',
+    }
+
+    # Create a new helper to safely download a file.
+    # @param url [String] URL of the page to download
+    # @param opts [#to_h] download options
+    # @option opts [String, Class] :dest the directory in which to download,
+    #   or the class with which to parse it
+    # @option opts [Boolean] :force whether to replace an existing file
+    # @option opts [String] :name name under which to save the file
+    # @option opts [String] :ref referer to use while downloading
+    # @return [self]
+    def initialize url, opts={}
+      require 'util/args'
+      @url, opts = Util::Args.check url, String, '', opts, Hash, {}
+      opts[:force] === true ? set_force : unset_force
+
+      DEFAULT_OPTIONS.each_pair do |k, v|
+        self.method('set_' + k.to_s).call (opts[k].nil? ? v : opts[k])
+      end
+    end
+
+    # Actually download the file, according to the given options.
+    # @return [Util::Result]
+    def download
+      require 'open-uri'
+      require 'util/result'
+
+      return Util::Result.err :no_url, self if @url.empty?
+      @name = File.basename URI(@url).path if @name.empty?
+      @name = 'index.html' if @name.empty? or @name == '/'
+
+      if @dest.is_a?(String) then
+        return Util::Result.err :no_dir, self unless File.directory? @dest
+        return Util::Result.err :file_exists, self if not @force \
+          and File.exists?(File.join @dest, @name)
+      end
+
+      begin
+        io = @ref.empty? ? URI.open(@url) : URI.open(@url, 'Referer' => @ref)
+        case @dest.to_s
+        when 'Magick' then @data = Magick::Image.from_blob io.read
+        when 'Nokogiri' then @data = Nokogiri::HTML io
+        when 'Nokogiri::HTML' then @data = Nokogiri::HTML io
+        when 'Nokogiri::XML' then @data = Nokogiri::XML io
+        when 'Oga' then @data = Oga.parse_html io
+        when 'Oga::HTML' then @data = Oga.parse_html io
+        when 'Oga::XML' then @data = Oga.parse_xml io
+        when 'REXML' then @data = REXML::Document.new io
+        else
+          if @dest.respond_to? :parse then
+            @data = @dest.parse io
+          elsif @dest.respond_to? :read then
+            @data = @dest.read io
+          else
+            IO.copy_stream(io, File.join(@dest, @name))
+          end
+        end
+      rescue Exception => e
+        return Util::Result.err e, self
+      end
+
+      Util::Result.ok
+    end
+
+    # Return the value of one of the options, the URL, or the parsed web page.
+    # @param key [#to_sym] the attribute to read
+    # @return [Object] if succesfull
+    # @return [nil] if +key+ cannot be converted to a symbol, or is not part
+    #   of the allowed attributes to read
+    def [] key
+      require 'util/args'
+      key = Util::Args.check key, Symbol, nil
+      return nil if key.nil?
+      return nil unless (DEFAULT_OPTIONS.keys + ALLOWED).include? key
+      instance_variable_get('@' + key.to_s)
+    end
+
+    # Set the directory in which to download the file, or the class with
+    # which to parse it. Currently accepted class are the following.
+    # - +Magick+ (will try to parse a +Magick::Image+).
+    # - +Nokogiri::HTML+ or its alias +Nokogiri+.
+    # - +Nokogiri::XML+.
+    # - +Oga::HTML+ or its alias +Oga+.
+    # - +Oga::XML+.
+    # - +REXML+.
+    # - Any class that responds to +parse+.
+    # - Any class that responds to +read+.
+    # Please note that with the last two, the methods are tried in this
+    # order, and the result might not be what would be expected, especially
+    # if the given method does not accept an +IO+ object.
+    # @param dir [Module] path to the directory, or if the file shall not
+    #   be saved, the class that shall parse it
+    # @return [self]
+    def set_dest dir=DEFAULT_OPTIONS[:dest]
+      @dest = dir.is_a?(Module) ? dir : dir.to_s
+      self
+    end
+
+    # Set {download} to replace the destination file if it already exists.
+    # @return [self]
+    def set_force
+      @force = true
+      self
+    end
+
+    # Set {download} to not replace the destination file if it already exists.
+    # @return [self]
+    def unset_force
+      @force = false
+      self
+    end
+
+    # Set the name under which to save the file. If the given name is
+    # empty, defaults to the same name as in the remote location.
+    # @param n [String] the file name
+    # @return [self]
+    def set_name n=DEFAULT_OPTIONS[:name]
+      @name = n.to_s
+      self
+    end
+
+    # Set the referer to use while downloading.
+    # @param r [String] the referer
+    # @return [self]
+    def set_ref r=DEFAULT_OPTIONS[:ref]
+      @ref = r.to_s
+      self
+    end
+  end
+end