util 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a411369612d59eb1c14f1a31b5d0a28bf8b5b4527851706e314ea096eee3aab2
-  data.tar.gz: 65f6f5e7a8bebc5418ed98ed2844010525946398841875e9769ea300ac6f12dd
+  metadata.gz: ed3de69b80836c4c8ed1ebb36a12f64a0eb9fdfe93580d37e9c92adc5fa1f592
+  data.tar.gz: 2539c7681963982bf06c4c8d9dfa5a1b462b06aac849ed60d91fdd3ae5a3e260
 SHA512:
-  metadata.gz: 417cc14f81425eae6d01052d6b0cb855e786ceb92610bc219a575413883810084fcf19492d8e2d23963aa04527ca36b0ec6fcf215f94262010fd4ef090e0575d
-  data.tar.gz: 84443a3ab823ded668be55f4768ee18209d2d9449329db2e4aeabf1fa36fd61245819d0155183951d985cb6a92c35ee805b4fb253c571367e07312d3517a5fc0
+  metadata.gz: b9ab28083a354018b031d2f9cb3aa9b113cc8bb47d1a008afe077c90d330b8b2a642fcdd484d00a875029e4df4da72f16c4b8be6ea04480d97a5cc03c7e4c9c6
+  data.tar.gz: 12f674bd048dafdb573f8fbe24a4845b5c58b1f4251885f9f0ef2a794aa29f7fde7667f8a8a2f7604164e89b5a1781dfd7557045eca962745a7613811d1b797d

data/README.md

@@ -7,20 +7,20 @@ Cette gemme regroupe un certain nombre de petits utilitaires visant à simplifie
 
 Sauf mention contraire, toutes les classes sont contenues dans le module principal `Util`. Se reporter à la documentation (en anglais) pour une explication plus détaillée du fonctionnement de chaque classe.
 
-### → `Arg` (classe indépendante)
+### → `Args` et `Opts`
 
-**Attention ! Cette classe va très certainement changer dans une version postérieure.**
-
-Cette classe sert à vérifier le type des arguments passés à une fonction et, au besoin, à remplacer un argument invalide par une valeur par défaut.
+Cette classe sert à vérifier le type des arguments passés à une fonction et, au besoin, à remplacer un argument invalide par une valeur par défaut. La variante `Opts` est utilisée pour les dictionnaires d’options.
 
 ```ruby
 def creer_dict_entier cle, valeur
-  cle = Arg.check cle, Symbol, :def # Nil ne répond pas à #to_sym
-  valeur = Arg.check valeur, Integer, nil, true
-  # Si nil est passé comme valeur, il doit rester tel quel et non
-  # être transformé en 0 par #to_i
+  cle, valeur = Util::Args.check cle, Symbol, :def, valeur, Integer, nil
   { cle => valeur }
 end
+
+def initialize opts={}
+  @encodage, @corps, @hauteur_ligne = Util::Opts.check opts, \
+    :enc, String, 'UTF-8', :corps, Integer, 12, :hauteur, Float, 1.0
+end
 ```
 
 ### → `ConsoleLogger`
@@ -40,6 +40,21 @@ rescue Exception => e
 end
 ```
 
+### → `Downloader`
+
+Une classe permettant de télécharger un fichier de manière sécurisée.
+
+```ruby
+require 'oga' # Doit être requis par l’utilisateur, `Util` ne le fera pas
+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
+```
+
 ### → `I18n`
 
 Une classe permettant de faire de l’internationalisation basique. Ce n’est *en rien* un système complet prenant en charge le sens de lecture des langues ou les différentes manières de gérer le pluriel. Un code d’identification et une langue donnent une chaîne de caractères, rien de plus. Si vous avez besoin de quelque chose de plus complexe, il vaudra mieux vous tourner vers la gemme [`i18n`](https://rubygems.org/gems/i18n) de Rails, voire vers `gettext`.
@@ -66,6 +81,42 @@ puts codes::P3.exist? :prv # true
 puts codes::P3.valid? :prv # false
 ```
 
+### → `Result`
+
+Une classe pour encapsuler un résultat et éviter les exceptions, similaire au `Result` de Rust ou OCaml.
+
+```ruby
+class Num
+  attr_reader :contenu
+  def initialize num
+    @contenu = num.to_f
+  end
+
+  def self.ajouter premier, second
+    Util::Result.ok Num.new(premier.contenu + second.contenu)
+  end
+
+  def ajouter num
+    Util::Result.ok Num.new(@contenu + num.to_f)
+  end
+
+  def diviser denom
+    return Util::Result.err :div0, self if denom == 0
+    Util::Result.ok Num.new(@contenu / denom.to_f)
+  end
+end
+
+res = Num.new(42).ajouter(79) \
+    .bindm(:ajouter, 11) \
+    .bindm(:diviser, 12) \
+    .bindcm(:ajouter, Num.new(13)).value # 24
+
+res = Num.new(42).ajouter(79) \
+    .bindm(:ajouter, 11) \
+    .bindm(:diviser, 0) \
+    .bindcm(:ajouter, Num.new(13)).error # :div0
+```
+
 ### → `Testing`
 
 Une classe pour simplifier l’écriture de tests unitaires. Là encore, on reste sur du basique. Pour quelque chose de plus complexe, on se tournera vers des environnements de test dédiés.
@@ -115,20 +166,20 @@ This gem groups together a number of small utilities that aim to make writing co
 
 Unless specified otherwise, all classes are contained inside the `Util` main module. See the documentation for a more detailed explanation of how each class works.
 
-### → `Arg` (independent class)
+### → `Args` and `Opts`
 
-**Warning! This class will most certainly change in a later version.**
-
-This class is used to typecheck the arguments provided to a function and, if needed, replace an invalid argument by a default value.
+This class is used to typecheck the arguments provided to a function and, if needed, replace an invalid argument by a default value. The `Opts` variant is used for option hashes.
 
 ```ruby
 def create_integer_hash key, value
-  key = Arg.check key, Symbol, :def # Nil does not respond to #to_sym
-  value = Arg.check value, Integer, nil, true
-  # If nil is provided as value, it shall remain as such and not
-  # be converted to 0 by #to_i
+  key, value = Util::Args.check key, Symbol, :def, value, Integer, nil
   { key => value }
 end
+
+def initialize opts={}
+  @encoding, @font_size, @line_height = Util::Opts.check opts, \
+    :enc, String, 'UTF-8', :size, Integer, 12, :height, Float, 1.0
+end
 ```
 
 ### → `ConsoleLogger`
@@ -148,6 +199,21 @@ rescue Exception => e
 end
 ```
 
+### → `Downloader`
+
+A class to safely download a file.
+
+```ruby
+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
+```
+
 ### → `I18n`
 
 A class to do some basic internationalization. It is *in no way* a full-fledged system that would take into account reading directions or different ways of pluralizing. An token and a language give a string, nothing more. If you need something more complex, you should rather use Rails [`i18n`](https://rubygems.org/gems/i18n) gem, or even `gettext`.
@@ -174,6 +240,42 @@ puts codes::P3.exist? :prv # true
 puts codes::P3.valid? :prv # false
 ```
 
+### → `Result`
+
+A class to wrap a result and avoid exceptions, similar to Rust’s or OCaml’s `Result`.
+
+```ruby
+class Num
+  attr_reader :content
+  def initialize num
+    @content = num.to_f
+  end
+
+  def self.add first, second
+    Util::Result.ok Num.new(premier.first + second.content)
+  end
+
+  def add num
+    Util::Result.ok Num.new(@content + num.to_f)
+  end
+
+  def divide denom
+    return Util::Result.err :div0, self if denom == 0
+    Util::Result.ok Num.new(@content / denom.to_f)
+  end
+end
+
+res = Num.new(42).add(79) \
+    .bindm(:add, 11) \
+    .bindm(:divide, 12) \
+    .bindcm(:add, Num.new(13)).value # 24
+
+res = Num.new(42).add(79) \
+    .bindm(:add, 11) \
+    .bindm(:divide, 0) \
+    .bindcm(:add, Num.new(13)).error # :div0
+```
+
 ### → `Testing`
 
 A class to make writing unit tests easier. There again, it remains basic. For something more complex, better go with a dedicated testing framework.
@@ -223,20 +325,20 @@ Aquesto gèmo recampo quauqui pichòtis utilita servènt à escriéure dóu code
 
 Sènso mencioun countràri, tòuti li classo soun countengudo dins lou moudule principau `Util`. Vèire la doucumentacioun pèr d’esclargimen sus coume marcho cado classo.
 
-### → `Arg` (classo independento)
+### → `Args` e `Opts`
 
-**Mèfi ! Aquesto classo va à cop segur chanja dins uno versioun venento.**
-
-Aquesto classo sèr à s’assegura dóu tipe dis argumen passa à-n-uno founcioun e, au besoun, à ramplaça un argumen invalide amé ’no valour pèr defaut.
+Aquesto classo sèr à s’assegura dóu tipe dis argumen passa à-n-uno founcioun e, au besoun, à ramplaça un argumen invalide amé ’no valour pèr defaut. La varianto `Opts` s’uso pèr li diciounàri d’oupcioun.
 
 ```ruby
 def crea_dic_entie clau, valour
-  clau = Arg.check clau, Symbol, :def # Nil respond pas à #to_sym
-  valour = Arg.check valour, Integer, nil, true
-  # Se nil es baia coume valour, dèu demoura coume acò e pas èstre
-  # vira en 0 pèr #to_i
+  clau, valour = Util::Args.check clau, Symbol, :def, valour, Integer, nil
   { clau => valour }
 end
+
+def initialize oupc={}
+  @encoudage, @cors, @aussado_ligno = Util::Opts.check oupc, \
+    :enc, String, 'UTF-8', :cors, Integer, 12, :aussado, Float, 1.0
+end
 ```
 
 ### → `ConsoleLogger`
@@ -256,6 +358,21 @@ rescue Exception => e
 end
 ```
 
+### → `Downloader`
+
+Uno classo pèr telecarga un fiquié seguramen.
+
+```ruby
+require 'oga' # Dèu èstre requist pèr l’usagié, `Util` lou fara pas
+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
+```
+
 ### → `I18n`
 
 Uno classo pèr faire de l’internaciounalisacioun elementàri. Es *pas ges* de sistèmo entié que tèn comte dóu sèns de leituro di lengo vo di biais diferènt de mena lou plurau. Un code d’identificacioun e uno lengo baion uno cadeno d’emprèsso, ges de mai. Se vous fai mestié d’agué quicon de mai coumplèisse, vaudra miés chausi la gèmo [`i18n`](https://rubygems.org/gems/i18n) de Rails, emai bessai `gettext`.
@@ -282,6 +399,42 @@ puts codes::P3.exist? :prv # true
 puts codes::P3.valid? :prv # false
 ```
 
+### → `Result`
+
+Uno classo pèr embala un resultat e s’engarda dis eicecioun, coume lou `Result` de Rust o OCaml.
+
+```ruby
+class Num
+  attr_reader :countengu
+  def initialize num
+    @countengu = num.to_f
+  end
+
+  def self.apoundre premie, segound
+    Util::Result.ok Num.new(premie.countengu + segound.countengu)
+  end
+
+  def apoundre num
+    Util::Result.ok Num.new(@countengu + num.to_f)
+  end
+
+  def parti denoum
+    return Util::Result.err :div0, self if denoum == 0
+    Util::Result.ok Num.new(@countengu / denoum.to_f)
+  end
+end
+
+res = Num.new(42).apoundre(79) \
+    .bindm(:apoundre, 11) \
+    .bindm(:parti, 12) \
+    .bindcm(:apoundre, Num.new(13)).value # 24
+
+res = Num.new(42).apoundre(79) \
+    .bindm(:apoundre, 11) \
+    .bindm(:parti, 0) \
+    .bindcm(:apoundre, Num.new(13)).error # :div0
+```
+
 ### → `Testing`
 
 Uno classo pèr assimpli l’escrituro d’assai unitàri. Aqui tambèn, demouro elementàri. Pèr quicon de mai coumplèisse, fau chausi un vertadier envirounamen d’assai.

data/lib/util.rb

@@ -1,7 +1,11 @@
+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.

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/console_logger.rb

@@ -15,7 +15,7 @@ module Util
   #         # Message written in red
   #     end
   class ConsoleLogger
-    require 'util/arg'
+    require 'util/args'
 
     # ANSI code to reset all formatting
     RESET = "\x1b[0m"
@@ -44,14 +44,14 @@ module Util
     #   :dbl_underline, :faint, :italic, :overline, :reverse,
     #   :underline, Array<idem>] :decor text decorations
     def self.escape_code opts={}
-      opts = Arg.check opts, Hash, {}
+      opts = Util::Args.check opts, Hash, {}
       return RESET if opts.empty?
       code = ''
 
       if opts.has_key? :color then
-        color = Arg.check opts[:color], Symbol, :white
+        color = Util::Args.check opts[:color], Symbol, :white
         color = :white unless COLORS.has_key? color
-        bright = Arg.check opts[:bright], 'Boolean', false
+        bright = Util::Args.check opts[:bright], 'Boolean', false
 
         cur = COLOR_TYPES[:fg] + COLORS[color]
         cur += COLOR_TYPES[:bright] if bright
@@ -59,9 +59,9 @@ module Util
       end
 
       if opts.has_key? :bgcolor then
-        color = Arg.check opts[:bgcolor], Symbol, :black
+        color = Util::Args.check opts[:bgcolor], Symbol, :black
         color = :black unless COLORS.has_key? color
-        bright = Arg.check opts[:bgbright], 'Boolean', false
+        bright = Util::Args.check opts[:bgbright], 'Boolean', false
 
         cur = COLOR_TYPES[:bg] + COLORS[color]
         cur += COLOR_TYPES[:bright] if bright
@@ -70,7 +70,7 @@ module Util
       end
 
       if opts.has_key? :decor then
-        decors = Arg.check opts[:decor], Array, [opts[:decor]]
+        decors = Util::Args.check opts[:decor], Array, [opts[:decor]]
         cur = ''
         decors.each do |d|
           cur += ';' + DECORS[d].to_s if DECORS.has_key? d
@@ -96,7 +96,7 @@ module Util
     # @option config [Hash { :stderr => Boolean, :code => String }]
     #   w configuration for warning (defaults to yellow text)
     def initialize config={}
-      config = Arg.check config, Hash, {}
+      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) },
@@ -107,7 +107,7 @@ module Util
 
       config.each_pair do |k, v|
         next unless @config.has_key? k
-        v = Arg.check v, Hash, {}
+        v = Util::Args.check v, Hash, {}
         @config[k][:io] = (v[:stderr] == true) ? $stderr : $stdout
         @config[k][:code] = CL.escape_code v
       end
@@ -167,8 +167,8 @@ module Util
     # @param payload (see #error)
     # @return nil
     def printf type, msg, payload
-      msg = Arg.check msg, String, ''
-      payload = Arg.check payload, Hash, {}
+      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