util 0.2.0 → 0.4.0

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

data/lib/util/i18n.rb

@@ -53,10 +53,10 @@ module Util
         return ''
       end
 
-      require 'util/arg'
-      id, opts = Arg.check_a [[id, String, ''], [opts, Hash, {}]]
-      o_lang, o_mod = Arg.check_h opts, [[:lang, Symbol, @default_lang],
-        [:mod, String, @last_used_mod]]
+      require 'util/args'
+      id = Util::Args.check id, String, ''
+      o_lang, o_mod = Util::Opts.check opts, :lang, Symbol, @default_lang, \
+        :mod, String, @last_used_mod
 
       mod = o_mod.empty? ? @last_used_mod : o_mod
       mod = @messages.keys[0] if mod.empty?
@@ -194,12 +194,11 @@ module Util
     # @return [String, String, Boolean, Boolean] success
     # @return [false] failure
     def self.register_check_args o_name, path, relative, recursive
-      require 'util/arg'
+      require 'util/args'
       init unless initialized?
-      name, path, relative, recursive = Arg.check_a [
-        [o_name, String, ''], [path, String, ''],
-        [relative, FalseClass, true], [recursive, TrueClass, false]
-      ]
+      name, path, relative, recursive = Util::Args.check \
+        o_name, String, '', path, String, '', \
+        relative, FalseClass, true, recursive, TrueClass, false
       return false if check_t name.empty?, :reg_no_name, o_name
 
       path = relative ? './temp.rb' : '.' if path.empty?

data/lib/util/lists/iso639.rb

@@ -79,8 +79,8 @@ module Util
         # @return [:dep, :priv, :val, nil]
         def self.category code
           init if @complete.nil?
-          require 'util/arg'
-          code = Arg.check code, Symbol, false, true
+          require 'util/args'
+          code = Util::Args.check code, Symbol, false
           return nil unless code
 
           info = @complete[code]
@@ -129,8 +129,8 @@ module Util
         # @return [Symbol]
         def self.from1 code
           init if @complete.nil?
-          require 'util/arg'
-          code = Arg.check code, Symbol, false, true
+          require 'util/args'
+          code = Util::Args.check code, Symbol, false
           @from1[code]
         end
 
@@ -139,8 +139,8 @@ module Util
         # @return [Symbol]
         def self.from2 code
           init if @complete.nil?
-          require 'util/arg'
-          code = Arg.check code, Symbol, false, true
+          require 'util/args'
+          code = Util::Args.check code, Symbol, false
           @from2[code]
         end
       end

data/lib/util/result.rb

@@ -0,0 +1,175 @@
+module Util
+  # An object representing the result of a computation, whether if be a success
+  # or a failure. Similar to +Result+ in Rust and OCaml and +Maybe+ in
+  # Haskell.
+  # @example
+  #   def divide num, denom
+  #     return Util::Result.err 'Division by zero.', self if denom == 0
+  #     Util::Result.ok num / denom
+  #   end
+  # No exception is ever raised, except when the value is retrieved
+  class Result
+    private_class_method :new
+    # The function in which the error happened, if defined.
+    # @return [String, nil]
+    attr_reader :where
+
+    # Create an error +Result+.
+    # @param [Object] content return value
+    # @param [Object] caller must be set to +self+ so that the +Result+
+    #   can store the function in which the error happened.
+    # @return [Result]
+    def self.err content=nil, caller=nil
+      self.send :new, :err, content, caller
+    end
+
+    # Create a success +Result+.
+    # @param [Object] content return value
+    # @return [Result]
+    def self.ok content=nil
+      self.send :new, :ok, content
+    end
+
+    # Create a +Result+.
+    # @param [:err, :ok] type type of +Result+
+    # @param [Object] content return value
+    # @param [Object] caller must be set to +self+ so that the +Result+
+    #   can store the function in which the error happened.
+    # @return [Result]
+    def initialize type, content, caller=nil
+      @type, @content = type, content
+      return if caller.nil?
+
+      fn = caller_locations(3).first.base_label
+      @where = (fn == '<main>') ? fn : (caller.is_a?(Class) \
+        ? "#{caller}.#{fn}" : "#{caller.class}##{fn}")
+    end
+
+    # Compare two +Result+s. Will return true if both are of the same
+    # type, and if their contents are equal.
+    # @param [Result] other other +Result+
+    # @return [Boolean]
+    def == other
+      return false if other.instance_variable_get('@type') != @type
+      other_content = other.instance_variable_get('@content')
+      return false if @content.class != other_content.class
+      return true unless @content.respond_to? '=='
+      @content == other_content
+    end
+
+    # Call a method from the toplevel namespace on the value of
+    # the result, if it is a success. Otherwise, does nothing.
+    #
+    # If the method being called does not return a +Result+, the return
+    # value will be wrapped in a success +Result+. Any raised exception
+    # will be wrapped in an error +Result+.
+    # @param name [Symbol, String] Name of the method to call. If a String
+    #   is provided, will convert it to a symbol.
+    # @return [Result]
+    def bind name, *args
+      bind_common Object, name, *args
+    end
+
+    # Call a class method on the value of the result if it is a success.
+    # Otherwise, does nothing.
+    #
+    # If the method being called does not return a +Result+, the return
+    # value will be wrapped in a success +Result+. Any raised exception
+    # will be wrapped in an error +Result+.
+    # @param (see #bind)
+    # @return [Result]
+    def bindcm name, *args
+      bind_common @content.class, name, *args
+    end
+
+    # Call an instance method on the value of the result if it is a success.
+    # Otherwise, does nothing.
+    #
+    # If the method being called does not return a +Result+, the return
+    # value will be wrapped in a success +Result+. Any raised exception
+    # will be wrapped in an error +Result+.
+    # @param (see #bind)
+    # @return [Result]
+    def bindm name, *args
+      bind_common @content, name, *args
+    end
+
+    # Indicate whether the result is an error.
+    # @return [Boolean]
+    def err?
+      @type == :err
+    end
+
+    # Retrieve the error value.
+    # @return [Object]
+    # @raise [ArgumentError] if the result is not an error.
+    def error
+      return @content if @type == :err
+      raise ArgumentError
+    end
+
+    # Retrieve the error value or a placeholder.
+    # @param [Object] alt placeholder
+    # @return [Object]
+    def error_or alt
+      @type == :err ? @content : alt
+    end
+
+    # Indicate whether the result is a success.
+    # @return [Boolean]
+    def ok?
+      @type == :ok
+    end
+
+    # Respresent the value as a string.
+    # @return [String]
+    # @note This functions “prettyfies” the +Result+. To actually
+    #   see its state, use +inspect+.
+    def to_s
+      return '[+] ' + @content.to_s if @type == :ok
+      (@where.nil? ? '[-] ' : "[- #{@where}] ") + @content.to_s
+    end
+
+    # Retrieve the success value.
+    # @return [Object]
+    # @raise [ArgumentError] if the result is not a success.
+    def value
+      return @content if @type == :ok
+      raise ArgumentError
+    end
+
+    # Retrieve the success value or a placeholder.
+    # @param [Object] alt placeholder
+    # @return [Object]
+    def value_or alt
+      @type == :ok ? @content : alt
+    end
+
+    private
+
+    # Call a method of a given base on the value of the result,
+    # if it is a success. Otherwise, does nothing.
+    #
+    # If the method being called does not return a +Result+, the return
+    # value will be wrapped in a success +Result+. Any raised exception
+    # will be wrapped in an error +Result+.
+    # @param base [Object] The base from which to call the method. Can be
+    #   a class, an instance or the main object.
+    # @param name [Symbol, String] Name of the method to call. If a String
+    #   is provided, will convert it to a symbol.
+    # @return [Result]
+    def bind_common base, name, *args
+      return self if @type == :err
+      name = name.to_s.to_sym unless name.is_a? Symbol
+      begin
+        method = base.method name
+        res = base.is_a?(Class) \
+          ? method.call(@content, *args)
+          : method.call(*args)
+        return res.is_a?(Result) ? res : Result.ok(res)
+      rescue Exception => e
+        Result.err e, self
+      end
+    end
+  end
+end

data/test/unit/args.rb

@@ -0,0 +1,22 @@
+results = [nil, '', true, 42, 42.0, :nil, true, true, Util, NilClass, 'tata']
+$test.register 'args-check', results do ||
+  require 'util/args'
+  [ Util::Args.check,
+    Util::Args.check(nil, String, '', nil, FalseClass),
+    Util::Args.check(42, Integer, 0, 42, Float, 0.0, 42, Symbol, :nil),
+    Util::Args.check(true, 'Boolean', false, 42, 'Boolean'),
+    Util::Args.check(Util, Module, Kernel, Util, Class, NilClass),
+    Util::Args.check('toto', 'NotAClass', 'tata')
+  ].flatten
+end
+
+results = [nil, 'toto', 'tata', 42.0, NilClass]
+$test.register 'opts-check', results do ||
+  require 'util/args'
+  opts = { :toto => 'tata', :titi => 42, 'tutu' => TrueClass }
+  [ Util::Opts.check(nil),
+    Util::Opts.check(nil, :toto, String),
+    Util::Opts.check(opts, :toto, String, '', :titi, Float, 0.0, \
+      :tutu, Class, NilClass),
+  ].flatten
+end

data/test/unit/downloader.rb

@@ -0,0 +1,145 @@
+require 'open-uri'
+require 'yaml'
+
+results = [nil, __dir__, false, 'fake.html', 'http://www.qwant.com']
+results += ['http://www.fake.info', nil, __dir__, false, 'fake.html']
+results += ['http://www.qwant.com', 'http://www.fake.info', nil, nil, __dir__]
+results += ['.', true, 'drop.htm', '42']
+$test.register 'downloader-setters-getters', results do ||
+  require 'util/downloader'
+  dl = Util::Downloader.new 'http://www.fake.info', dest: __dir__, \
+    name: 'fake.html', ref: 'http://www.qwant.com', force: 'true'
+  res = [dl.data, dl.dest, dl.force, dl.name, dl.ref, dl.url,
+    dl[:data], dl[:dest], dl[:force], dl[:name], dl[:ref], dl[:url],
+    dl[42], dl[:io], dl['dest']
+  ]
+  dl.set_force.set_ref(42).unset_force.set_dest.set_name('drop.htm').set_force
+  res += [dl.dest, dl.force, dl.name, dl.ref]
+  res
+end
+
+results = [:no_url, :no_dir, :no_dir, :file_exists]
+$test.register 'downloader-normal-errors', results do ||
+  require 'util/downloader'
+  path = File.join __dir__, 'downloader'
+  fake_path = File.join path, 'fake'
+  true_path = File.join path, 'orig'
+  not_a_dir = File.join path, 'orig', 'simple.html'
+  url = 'https://gitlab.com/uploads/-/system/user/avatar/5582173/avatar.png'
+  [ Util::Downloader.new('').download.error,
+    Util::Downloader.new(url).set_dest(fake_path).download.error,
+    Util::Downloader.new(url).set_dest(not_a_dir).download.error,
+    Util::Downloader.new(url).set_dest(true_path).set_name('simple.html')\
+      .download.error
+  ]
+end
+
+$test.register 'downloader-404', OpenURI::HTTPError, '404' do ||
+  require 'util/downloader'
+  path = File.join __dir__, 'downloader'
+  url = 'https://www.perdu.com/404'
+  Util::Downloader.new(url).set_dest(path).download.error
+end
+
+$test.register 'downloader-success' do ||
+  require 'util/downloader'
+  path = File.join __dir__, 'downloader'
+  url = 'https://www.perdu.com/'
+  Util::Downloader.new(url).set_dest(path).download.value.nil?
+end
+
+$test.register 'downloader-second-download', :file_exists do ||
+  require 'util/downloader'
+  path = File.join __dir__, 'downloader'
+  url = 'https://www.perdu.com/'
+  Util::Downloader.new(url).set_dest(path).download.error
+end
+
+$test.register 'downloader-third-download' do ||
+  require 'util/downloader'
+  path = File.join __dir__, 'downloader'
+  url = 'https://www.perdu.com/'
+  dl = Util::Downloader.new(url).set_dest(path).set_force.download.value.nil?
+end
+
+results = [204, '<html>', 'Perdu sur l\'Internet ?']
+$test.register 'downloader-right-download', results do ||
+  path = File.join __dir__, 'downloader', 'index.html'
+  content = File.read path
+  File.delete path
+  [content.length, content[0..5], content[61..82]]
+end
+
+begin
+  require 'rmagick'
+
+  results = [nil, 5798, 'PNG', 200, 200, '#D4D400001C1C']
+  $test.register 'downloader-rmagick', results do ||
+    require 'util/downloader'
+    url = 'https://gitlab.com/uploads/-/system/user/avatar/5582173/avatar.png'
+    dl = Util::Downloader.new(url).set_dest(Magick)
+    [ dl.download.value,
+      dl.data[0].filesize,
+      dl.data[0].format,
+      dl.data[0].rows,
+      dl.data[0].columns,
+      dl.data[0].pixel_color(79, 142).to_color,
+    ]
+  end
+rescue LoadError
+  $test.register 'downloader-RMAGICK-NOT-INSTALLED' do || true end
+end
+
+begin
+  require 'nokogiri'
+
+  results = [nil, 'Vous Etes Perdu ?', 'Perdu sur l\'Internet ?']
+  $test.register 'downloader-nokogiri', results do ||
+    require 'util/downloader'
+    url = 'https://www.perdu.com/'
+    dl = Util::Downloader.new(url).set_dest(Nokogiri::HTML)
+    [ dl.download.value,
+      dl.data.title,
+      dl.data.at_css('h1').text
+    ]
+  end
+rescue LoadError
+  $test.register 'downloader-NOKOGIRI-NOT-INSTALLED' do || true end
+end
+
+begin
+  require 'oga'
+
+  results = [nil, :html, 'Perdu sur l\'Internet ?']
+  $test.register 'downloader-oga', results do ||
+    require 'util/downloader'
+    url = 'https://www.perdu.com/'
+    dl = Util::Downloader.new(url).set_dest(Oga::HTML)
+    [ dl.download.value,
+      dl.data.type,
+      dl.data.at_css('h1').text
+    ]
+  end
+rescue LoadError
+  $test.register 'downloader-OGA-NOT-INSTALLED', nil do || end
+end
+
+results = [nil, 'Browse the first website']
+results += ['http://info.cern.ch/hypertext/WWW/TheProject.html']
+$test.register 'downloader-rexml', results do ||
+  require 'util/downloader'
+  require 'rexml/document'
+  url = 'http://info.cern.ch'
+  dl = Util::Downloader.new(url).set_dest(REXML)
+  [ dl.download.value,
+    dl.data.root.get_elements('//ul/li/a')[0].text,
+    dl.data.root.get_elements('//ul/li/a')[0]['href'],
+  ]
+end
+
+$test.register 'dowloader-yaml', YAML::SyntaxError, 'mapping values' do ||
+  require 'util/downloader'
+  url = 'https://gitlab.com/guillel/util-gem/-/blob/master' \
+    '/share/lists/iso639-3.yml'
+  Util::Downloader.new(url).set_dest(YAML).download.error
+end