util 0.2.0

data/LICENSES.md

@@ -0,0 +1,21 @@
+Code principal / Main code / Code principau
+===========================================
+
+Distribué sous license [CeCIll-C](https://cecill.info/licences.fr.html) (plus ou moins équivalent à une LGPL, mais conforme au droit français). Texte complet dans `CECILL-C.FR`.
+
+Distributed under [CeCIll-C](https://cecill.info/licences.fr.html) license (more or less a compliant with French law version of LGPL). See full text in `CECILL-C.EN`.
+
+Espargi amé la licènci [CeCIll-C](https://cecill.info/licences.fr.html) (mai o mens coume uno LGPL, mai counforme au dre francés). Tèste entié dins `CECILL-C.FR`.
+
+ISO 639-3 Code Tables
+=====================
+
+The ISO 639-3 code set may be downloaded and incorporated into software products, web-based systems, digital devices, etc., either commercial or non-commercial, provided that:
+
+- attribution is given [www.iso639-3.sil.org](https://iso639-3.sil.org) as the source of the codes;
+- the identifiers of the code set are not modified or extended except as may be privately agreed using the Private Use Area (range qaa to qtz), and then such extensions shall not be distributed publicly;
+- the product, system, or device does not provide a means to redistribute the code set.
+
+Expansions to the information provided by the standard (e.g., population data, names in other languages, geographic coordinates, etc.) may be made and distributed as long as such added information is clearly identified as not being part of the standard itself. The ISO 639-3 website is the only authorized distribution site for the ISO 639-3 code tables.
+
+For any questions about whether a particular use is covered by these guidelines, contact the Registration Authority at [ISO639-3@sil.org](mailto:iso639-3@sil.org).

data/README.md

@@ -0,0 +1,325 @@
+Gemme `Util`
+============
+
+**English explanations [below](#util-gem). ⇓ Esplicacioun en prouvènçau [dessouto](#gèmo-util).**
+
+Cette gemme regroupe un certain nombre de petits utilitaires visant à simplifier l’écriture de code en Ruby. Il n'y a pas de logique particulière dans ce qui y est réuni, si ce n’est que chaque classe correspond à une fonctionnalité répétitive à écrire, mais utile dans de nombreux codes plus spécialisés. Pour l’heure, les classes sont les suivantes (par ordre alphabétique).
+
+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)
+
+**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.
+
+```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 }
+end
+```
+
+### → `ConsoleLogger`
+
+Cette classe offre une interface simple pour écrire différents types de messages sur le terminal, mis en forme et avec des couleurs. Fortement configurable.
+
+```ruby
+cl = ConsoleLogger.new e: { :stderr => true }
+cl.warning 'Les erreurs seront affichées sur STDERR.'
+  # Message écrit en jaune
+begin
+  texte = File.read 'secret.msg'
+rescue Exception => e
+  msg = 'Impossible d’aller plus loin à cause de %E%, abandon.'
+  cl.error msg, 'E': e.message
+    # Message écrit en rouge
+end
+```
+
+### → `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`.
+
+```ruby
+Util::I18n << __FILE__
+Util::I18n.set_default_language :prv
+Util::I18n.message 'bonjour' # 'Adiéu'
+Util::I18n.message 'bonjour', lang: :fra # 'Bonjour'
+```
+
+### → `Lists`
+
+Un module qui regroupe des sous-modules représentant des listes utiles.
+
+#### ⇒ `Lists::ISO639`
+
+Un module contenant les codes [ISO 639](https://fr.wikipedia.org/wiki/ISO_639). Pour l’instant, seule la classe `P3` contenant les codes ISO 639-3 est disponible.
+
+```ruby
+codes = Util::Lists::ISO639
+puts codes::P3.from1 'fr' # :fre
+puts codes::P3.exist? :prv # true
+puts codes::P3.valid? :prv # false
+```
+
+### → `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.
+
+```ruby
+class MaClasse
+  def self.fonction arg
+    raise ArgumentError, 'Ce n’est pas un entier non signé.' unless arg.to_i >= 0
+    -arg.to_i
+  end
+end
+
+test = Util::Testing.new
+
+test.register 'succes', [-12, -42] do ||
+  [MaClasse.fonction('12'), MaClasse.fonction(42.0)]
+end
+
+test.register 'succes-avec-resultat-implicite' do ||
+  MaClasse.fonction '12'
+  true
+end
+
+test.register 'echec-attendu', ArgumentError, 'signé' do ||
+  MaClasse.fonction -1
+end
+
+test.register 'mauvaise-raison', ArgumentError, 'signé' do ||
+  MaClasse.fonction
+end
+
+test.register 'mauvaise-exception', ArgumentError, 'signé' do ||
+  MonAutreClasse.fonction
+end
+
+test.run
+```
+
+### → `YAML` (module indépendant)
+
+Une extension du module `YAML` de la bibliothèque standard, qui se contente d’ajouter une fonction `from_file` permettant de lire un fichier YAML tout en vérifiant qu’aucune erreur ne s’est produite.
+
+`Util` gem
+==========
+
+This gem groups together a number of small utilities that aim to make writing code in Ruby easier. There is no specific logic behind the collection, except that each class corresponds to a functionality that is repetitive to write, but useful in many more specialized codes. For now, the following classes are extant (in alphabetical order).
+
+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)
+
+**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.
+
+```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 }
+end
+```
+
+### → `ConsoleLogger`
+
+This class offers a simple interface to write different kinds of messages on the console, formatted and colored. Highly configurable.
+
+```ruby
+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
+```
+
+### → `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`.
+
+```ruby
+Util::I18n << __FILE__
+Util::I18n.set_default_language :prv
+Util::I18n.message 'bonjour' # 'Adiéu'
+Util::I18n.message 'bonjour', lang: :fra # 'Bonjour'
+```
+
+### → `Lists`
+
+A collection of submodules respresenting useful lists.
+
+#### ⇒ `Lists::ISO639`
+
+A module containing [ISO 639](https://en.wikipedia.org/wiki/ISO_639) codes. For now, the class `P3` containing ISO 639-3 codes is the only one available.
+
+```ruby
+codes = Util::Lists::ISO639
+puts codes::P3.from1 'fr' # :fre
+puts codes::P3.exist? :prv # true
+puts codes::P3.valid? :prv # false
+```
+
+### → `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.
+
+```ruby
+class MyClass
+  def self.function arg
+    raise ArgumentError, 'Not an unsigned int.' unless arg.to_i >= 0
+    -arg.to_i
+  end
+end
+
+test = Util::Testing.new
+
+test.register 'success', [-12, -42] do ||
+  [MyClass.function('12'), MyClass.function(42.0)]
+end
+
+test.register 'success-with-implicit-result' do ||
+  MyClass.function '12'
+  true
+end
+
+test.register 'expected-fail', ArgumentError, 'unsigned' do ||
+  MyClass.function -1
+end
+
+test.register 'wrong-reason', ArgumentError, 'unsigned' do ||
+  MyClass.function
+end
+
+test.register 'wrong-exception', ArgumentError, 'unsigned' do ||
+  MyOtherClass.function
+end
+
+test.run
+```
+
+### → `YAML` (module indépendant)
+
+An extension to the standard library module `YAML`, that just adds a `from_file` function allowing to read a YAML file while checking that no error happened.
+
+Gèmo `Util`
+===========
+
+Aquesto gèmo recampo quauqui pichòtis utilita servènt à escriéure dóu code Ruby mai simplamen. I a pas gaire de lougico dins ço qu’i es reüni, à despart de que cado classo courrespond à quicon de repetitéu à escriéure, mai utile dins un mouloun de code mai especialisa. Aro, li classo soun li seguènto (alfabeticamen).
+
+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)
+
+**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.
+
+```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 }
+end
+```
+
+### → `ConsoleLogger`
+
+Aquesto classo óufris uno interfàci simplo pèr escriéure divèrsi message sus lou terminau, mes en fourmo e acoulouri. Se pòu mai counfigura.
+
+```ruby
+cl = ConsoleLogger.new e: { :stderr => true }
+cl.warning 'Lis errour saran escricho sus STDERR.'
+  # Message escri en jaune
+begin
+  text = File.read 'secret.msg'
+rescue Exception => e
+  msg = 'Impoussible d’ana mai liuen à cause de %E%, abandoun.'
+  cl.error msg, 'E': e.message
+    # Message escri en rouge
+end
+```
+
+### → `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`.
+
+```ruby
+Util::I18n << __FILE__
+Util::I18n.set_default_language :prv
+Util::I18n.message 'bonjour' # 'Adiéu'
+Util::I18n.message 'bonjour', lang: :fra # 'Bonjour'
+```
+
+### → `Lists`
+
+Uno couleicioun de souto-moudule que represènton de tiero utile.
+
+#### ⇒ `Lists::ISO639`
+
+Un moudule countenènt li code [ISO 639](https://fr.wikipedia.org/wiki/ISO_639). Aro, i a que la classo `P3`, que countèn li code ISO 639-3.
+
+```ruby
+codes = Util::Lists::ISO639
+puts codes::P3.from1 'fr' # :fre
+puts codes::P3.exist? :prv # true
+puts codes::P3.valid? :prv # false
+```
+
+### → `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.
+
+```ruby
+class MaClasso
+  def self.founcioun arg
+    raise ArgumentError, 'Pas ges d’entié noun signa.' unless arg.to_i >= 0
+    -arg.to_i
+  end
+end
+
+assai = Util::Testing.new
+
+assai.register 'reussido', [-12, -42] do ||
+  [MaClasso.founcioun('12'), MaClasso.founcioun(42.0)]
+end
+
+assai.register 'reussido-senso-resultat-espres' do ||
+  MaClasso.founcioun '12'
+  true
+end
+
+assai.register 'revirado-esperado', ArgumentError, 'signa' do ||
+  MaClasso.founcioun -1
+end
+
+assai.register 'marrido-encauso', ArgumentError, 'signa' do ||
+  MaClasso.founcioun
+end
+
+assai.register 'marrido-eicecioun', ArgumentError, 'signa' do ||
+  MounAutroClasso.founcioun
+end
+
+assai.run
+```
+
+### → `YAML` (moudule independènt)
+
+Vèn espandi lou moudule `YAML` de la biblioutèco ourdinàrio, e fai ren de mai qu’apoundre uno founcioun `from_file`, que permet de legi un fiquié YAML en s’assegurant que i a pas agu d’errour.

data/lib/util.rb

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

data/lib/util/arg.rb

@@ -0,0 +1,90 @@
+# Functions to typecheck the arguments of a function.
+# @note WARNING!! The API of the module will most probably change
+#   in future versions of the gem. For now consider it for internal
+#   use only.
+class Arg
+  private_class_method :new
+
+  # Verify whether a given argument belongs to a class or can be converted
+  # into that class.
+  # @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
+  # @param [Object] alt value to use if the argument does not belong to the
+  #   wanted class
+  # @param [Boolean] disallow_nil if true and +value+ is +nil+, then +alt+
+  #   will be returned instead of trying to convert +nil+ to the right type
+  # @return [Object]
+  # @example
+  #     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 }
+  #     end
+  #
+  #     hash1 = create_integer_hash 'hello', 13.4 # { :hello => 13 }
+  #     hash2 = create_integer_hash nil, nil # { :def => nil }
+  def self.check value, klass, alt, disallow_nil = false
+    return alt if disallow_nil and value.nil?
+    case klass.to_s
+    when 'Array' then return value.respond_to?(:to_a) ? value.to_a : alt
+    when 'Boolean' then return value === true ? true : alt
+    when 'Complex' then return value.respond_to?(:to_c) ? value.to_c : alt
+    when 'FalseClass' then return value === false ? false : alt
+    when 'Float' then return value.respond_to?(:to_f) ? value.to_f : alt
+    when 'Hash' then return value.respond_to?(:to_h) ? value.to_h : alt
+    when 'Integer' then return value.respond_to?(:to_i) ? value.to_i : alt
+    when 'Rational' then return value.respond_to?(:to_r) ? value.to_r : alt
+    when 'String' then return value.respond_to?(:to_s) ? value.to_s : alt
+    when 'Symbol' then return value.respond_to?(:to_sym) ? value.to_sym : alt
+    when 'TrueClass' then return value === true ? true : alt
+    else return value.is_a?(klass) ? value : alt
+    end
+  end
+
+  # Easier way to typecheck a whole list of argument than individually
+  # calling Arg.check on each of them. Takes an array of arrays containing
+  # the three or four argument of Arg.check, performs said method on each
+  # of them, and returns an array of the results.
+  # @param [Array<Array<Object, Class, Object, Boolean>>] array arguments to check
+  # @return [Array<Object>]
+  # @example
+  #     def create_integer_hash key, value
+  #       key, value = Arg.check_a [ [key, Symbol, :def],
+  #                                  [value, Integer, nil, true] ]
+  #       { key => value }
+  #     end
+  def self.check_a array
+    result = []
+    array.each do |elem|
+      value, klass, alt, dis = elem
+      result << check(value, klass, alt, (dis.nil? ? false : dis))
+    end
+    result
+  end
+
+  # Typecheck the content of an options hash, while ignoring undefined
+  # options. Calls Arg.check on the values associated with a given key,
+  # according to the rest of the informations given.
+  # @param [Hash] hash hash whose content to check
+  # @param [Array<Array<Object, Class, Object, Boolean>>] array options to check
+  # @return [Array<Object>]
+  # @example
+  #     def initialize opts={}
+  #       opts = Arg.check opts, Hash, {}
+  #       @encoding, @font_size, @line_height = Arg.check_h opts,
+  #         [ [:enc, String, 'UTF-8', true], [:size, Integer, 12, true ],
+  #           [:height, Float, 1.0, true] ]
+  #     end
+  def self.check_h hash, array
+    result = []
+    array.each do |elem|
+      idx, klass, alt, dis = elem
+      result << check(hash[idx], klass, alt, (dis.nil? ? false : dis))
+    end
+    result
+  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