clir-data_manager 0.3.1

data/README.md

@@ -0,0 +1,279 @@
+# Clir::DataManager
+
+1. You define (deeply) the instance properties,
+2. you "attach" the DataManager to your class,
+3. you can then create, edit, remove and save your instances in command line.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clir/data_manager'
+```
+
+En attendant que le gem soit complet, mettre le code suivant dans le programme devant l'utiliser (pas besoin de faire `bundle install` etc.) :
+
+~~~
+
+$LOAD_PATH.unshift File.join(Dir.home,'Programmes','Gems','clir-data_manager','lib')
+
+~~~
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install clir-data_manager
+
+## Usage
+
+Pour qu'une classe quelconque puisse utiliser le gem, lui mettre :
+
+~~~ruby
+module MonModule
+  class MaClasse
+    include ClirDataManagerConstants # <==== usefull
+
+    DATA_PROPERTIES = [...]             # <== see below
+    @@save_system   = :card             # <== see below
+    @@save_format   = :yaml             # <== see below
+    @@save_location = '/path/to/folder' # <== see below
+  end
+end
+
+Clir::DataManager.new(MonModule::MaClasse)
+
+~~~
+
+### Définition du système de sauvegarde
+
+Il y a 6 façons de sauvegarder les données avec `Clir::DataManager` :
+
+* dans un unique fichier, au format CSV ou YAML,
+* dans des fiches individuelles, au format CSV ou YAML,
+* par un fichier de configuration, au format CSV ou YAML [Ce système n'est pas encore implémenté, il fonctionnera sur la base d'un fichier de configuration qui définira la façon de sauvegarder les données, toujours en CSV ou YAML]
+
+
+
+### Définition des propriétés de l'instance
+
+Le module `ClirDataManagerConstants` permet de charger les constants comme `REQUIRED`, `EDITABLE`, etc.
+
+Il faut ensuite définir les propriétés des instances de cette classe, à l'aide la constante `DATA_PROPERTIES` :
+
+~~~ruby
+module MonModule
+  class MaClasse
+
+    DATA_PROPERTIES = [
+      {prop: :id,   type: :id, name: "ID", specs: REQUIRED, default: :new_id},
+      {prop: :name, type: :string,  name:"Votre nom", specs:REQUIRED|EDITABLE|DISPLAYABLE},
+      {prop: :name, type: :string,  name:"Votre genre", specs:ALL, default: 'F'}
+      # ...
+    ]
+
+  end
+end
+~~~
+
+On pourrait aussi envoyer les données lors de l'installation du manager de propriétés :
+
+~~~ruby
+
+pdata = [
+  {prop: :id, ...}
+]
+
+Clir::DataManager.new(MonModule::MaClasse, pdata)
+
+~~~
+
+Pour créer la première instance, il suffit ensuite de faire :
+
+~~~ruby
+
+MonModule::MaClasse.new.create
+
+~~~
+
+Pour éditer ou afficher une instance de la classe :
+
+~~~ruby
+i = MonModule::MaClasse.new()
+
+i.edit
+
+i.show
+
+~~~
+
+Les données sont toujours placées dans la propriété `@data` de l'instance, qui peut être définie à l'instanciation, une fois qu'on a les données :
+
+~~~ruby
+
+module MonModule
+  class MaClasse
+
+    def initialize(data)
+      @data = data
+    end
+  end
+end
+~~~
+
+Noter qu'il n'est pas nécessaire de faire `attribute_reader: :data` puisque data est automatiquement défini en accesseur.
+
+Noter qu'il n'est pas non plus nécessaire de créer toutes les méthodes-propriété qui sont nécessaires habituellement pour récupérer et définir les valeurs.
+
+À partir du moment où `DATA_PROPERTIES` définit : 
+
+~~~ruby
+DATA_PROPERTIES = [
+  # ...
+  {prop: :maprop, ...}
+  # ...
+]
+~~~
+
+… alors le manager de propriétés définit les méthodes : 
+
+~~~ruby
+module MonModule
+  class MaClasse
+
+    def maprop
+      return @data[:maprop]
+    end
+
+    def maprop=(value)
+      @data.merge!(maprop: value)
+    end
+
+  end
+end
+~~~
+
+Donc, on récupère et définit les valeurs de cette manière :
+
+~~~ruby
+
+i = MonModule::MaClasse.new({maprop: "Valeur courante"})
+
+i.maprop
+# => "Valeur courante"
+
+i.maprop = "Nouvelle valeur"
+
+i.maprop
+# => "Nouvelle valeur"
+
+~~~
+
+### Définition des propriétés
+
+C'est donc la grosse partie pour utiliser profitablement de `DataManager`. Une bonne définition des propriétés conduit à une utilisation tout à fait efficace.
+
+#### Identifiant de la propriété 
+
+Cet identifiant se définit à l'aide de l'attribut `:prop`.
+
+~~~ruby
+DATA_PROPERTIES = [
+  { prop: :maprop }
+]
+~~~
+
+C'est par ce nom que l'instance connaitra la valeur consignée. Pour définir quelqu'un, par exemple, on aura :
+
+~~~ruby
+DATA_PROPERTIES = [
+  { prop: :prenom },
+  { prop: :nom    },
+]
+~~~
+
+Et une instance pourra utiliser :
+
+~~~ruby
+simone = MaClasse.new
+simone.prenom
+# => "Simone"
+simone.nom
+# => "De Beauvoir"
+~~~
+
+#### Question personnalisée
+
+Par défaut, la question « Nouvelle valeur pour “`<propriété>`” » est posée pour modifier une propriété.
+
+On peut néanmoins définir une autre question avec l'attribut `:quest` qui peut contenir des valeurs de template <b>qui ne doivent utiliser que les valeurs dans les `data` de l'instance</b>.
+
+TODO: Plus tard on pourra aussi imaginer évaluer la question ou fournir d'autres valeurs au template (par exemple un attribut `:quest_values` qui pourrait être définie en dur ou par une procédure qui utiliserait l'instance en premier argument).
+
+#### Valeur par défaut dans les propriétés
+
+Une donnée propriété peut définir la valeur par défaut de cette propriété pour une instance donnée. 
+
+~~~ruby
+DATA_PROPERTIES = [
+  {prop: :maprop ... default: <...> }
+]
+~~~
+
+Cette valeur peut être de diférent type :
+
+* une valeur explicite :
+
+~~~ruby
+  default: "Ma valeur par défafut"
+  default: 12
+  default: true
+~~~
+
+* une procédure :
+
+~~~ruby
+  default: Proc.new() { |instance| instance.name.length }
+~~~
+
+> Noter que l'instance est toujours transmise en premier argument.
+
+* une méthode d'instance :
+
+~~~ruby
+class MaClasse
+  def valeur_default_pour_prop
+    return "oui"
+  end
+end
+
+default: :valeur_default_pour_prop
+~~~
+
+* une méthode de classe :
+
+~~~ruby
+class MaClasse
+  def self.valeur_default_pour_prop
+    @@valeur_prop += 1
+  end
+end
+
+default: :valeur_default_pour_prop
+~~~
+
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/clir-data_manager.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "clir/data_manager"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/clir-data_manager.gemspec

@@ -0,0 +1,34 @@
+require_relative 'lib/clir/data_manager/version'
+
+Gem::Specification.new do |s|
+  s.name          = "clir-data_manager"
+  s.version       = Clir::DataManager::VERSION
+  s.authors       = ["PhilippePerret"]
+  s.email         = ["philippe.perret@yahoo.fr"]
+  s.licenses      = ['Nonstandard']
+
+  s.summary       = %q{Properties Manager for classes and instances}
+  s.description   = %q{This gem provides useful Classes and methods to deal with instances properties edition and display}
+  s.homepage      = "https://github.com/PhilippePerret/clir-data_manager"
+  s.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  # s.metadata["allowed_push_host"] = "https://github.com/PhilippePerret/clir-data_manager"
+  s.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  s.add_dependency 'clir', '~> 0.4'
+  s.add_development_dependency 'minitest', '~> 5.10'
+  s.add_development_dependency 'minitest-color', '>= 5'
+
+  s.metadata["homepage_uri"] = s.homepage
+  s.metadata["source_code_uri"] = s.homepage
+  s.metadata["changelog_uri"] = "https://github.com/PhilippePerret/clir-data_manager/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  s.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|features)/}) }
+  end
+  s.bindir        = "exe"
+  s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/clir/data_manager/Displayer.rb

@@ -0,0 +1,30 @@
+=begin
+  Clir::DataManager::Manager::Displayer
+  -------------------------------------
+  To display a instance values
+=end
+module Clir
+module DataManager
+class Manager
+class Displayer
+
+  attr_reader :manager
+  
+  def initialize(manager)
+    @manager = manager    
+  end
+
+  def show(instance, options)
+    liste = []
+    manager.each_property do |property|
+      next if not(property.displayable?(instance))
+      # puts "Je dois afficher la propriété @#{property.prop} de specs #{property.specs}"
+      liste << [property.name, property.formated_value_in(instance)]
+    end
+    puts labelize(liste)
+  end
+
+end #/class Displayer
+end #/class Manager
+end #/module DataManager
+end #/module Clir

data/lib/clir/data_manager/Editor.rb

@@ -0,0 +1,208 @@
+=begin
+  Clir::DataManager::Manager::Editor
+  -------------------------------------
+  To edit a instance values (i.e. a proprerty)
+
+  2 editing system:
+
+    1.  Property after property
+    2.  [default] All properties are displayed and user chose which
+        one to edit. When all required properties are defined, the
+        user can save the values.
+
+
+=end
+module Clir
+module DataManager
+class Manager
+class Editor
+
+  attr_reader :manager
+  
+  def initialize(manager)
+    @manager = manager    
+  end
+
+  def edit(instance, options)
+    data_modified = false
+    data_saved    = false
+    error         = nil
+    while true
+      # 
+      # Pour choisir la propriété à définir (et l'index par défaut)
+      # 
+      choices, index_default = set_choices_with(instance)
+      clear unless debug?
+      # 
+      # Si une erreur a été rencontrée
+      # 
+      puts error.rouge unless error.nil?
+      # 
+      # L'user peut choisir la propriété à définir ou le choix
+      # "Enregistrer" pour enregistrer l'instance
+      # 
+      case prop = Q.select((options[:question]||(MSG[:define_thing] % instance.class.class_name)).jaune, choices, { per_page:choices.count, default: (index_default unless choices.empty?), filter:true, show_help:false, echo:false} )
+      when NilClass 
+        break
+      when :save
+        if not(all_required?(instance))
+          error = MSG[:all_required_data_must_be_defined]
+        elsif data_modified && confirmed?(instance)
+          instance.save 
+          data_saved = true
+          break
+        end
+      else
+        modified = prop.edit(instance, options)
+        data_modified = true if modified
+      end
+    end
+    # / while
+    if data_modified && not(data_saved)
+      unless Q.yes?(MSG[:data_not_saved_cancel].orange)
+        instance.save # on sauve les données, finalement
+      end
+    end
+  end
+
+  # Confirmation (ou non) des données de l'instance
+  def confirmed?(instance)
+    clear unless debug?
+    instance.show
+    puts "\n\n"
+    return Q.yes?(MSG[:q_confirm_data].jaune)
+  end
+
+  # @return TRUE si toutes les propriétés requises sont définies
+  # pour l'instance donnée
+  def all_required?(instance)
+    manager.properties.each do |property|
+      if property.required?(instance) && instance.send(property.prop).nil?
+        return false
+      end
+    end
+    return true
+  end
+
+  # Tty-prompt choices panel
+  # Should be update after each user input
+  # 
+  # @return [choices, index_default]
+  # At creation, index_default is the first required property which
+  # is undefined (1-start)
+  # 
+  def set_choices_with(instance)
+    requirement_missing = false
+    max_label_width = 0
+    cs = manager.properties.map do |property|
+      next if not(property.editable?(instance))
+      pvalue = property.formated_value_in(instance)
+      pname  = property.name(instance)
+      pname || raise(ERRORS[:no_name_for_property] % property.prop.inspect)
+      max_label_width = pname.length if pname.length > max_label_width
+      [pname, pvalue]
+    end.compact
+
+    # Ajout de la gouttière entre label et valeur
+    max_label_width += 4
+
+    #
+    # Le menu qui devra être sélectionné
+    # 
+    index_default = nil
+    #
+    # Index courant réel
+    #
+    # Avant qu'il existe des propriétés conditionnelles (:if) on
+    # pouvait prendre l'index de la propriété pour savoir quel menu
+    # sélectionner. Maintenant, on doit utiliser cette variable
+    # +real_current_index+ pour connaitre l'index réel du menu  à
+    # sélectionner ensuite.
+    # 
+    # On commence à 1 pour avoir le premier choix à 2 car le 
+    # premier item est toujours l'item "Enregistrer"
+    # 
+    real_current_index = 1
+
+    # 
+    # Boucle pour récupérer tous les menus à afficher
+    # 
+    cs = manager.properties.map do |property|
+      # 
+      # Si ce n'est pas une propriété éditable (pas ses :specs), on
+      # la passe.
+      # 
+      next if not(property.editable?(instance))
+      # 
+      # Est-ce une propriété requise ? (en fonction ou non de l'instance)
+      # 
+      is_required = property.required?(instance)
+
+      real_current_index += 1 if index_default.nil?
+      curval = instance.send(property.prop)
+      isdef  = curval != nil
+      #
+      # Si c'est une création d'instance, on se placera automati-
+      # quement sur le premier champ (property) qui n'est pas défini
+      # 
+      if index_default.nil? && instance.new? && not(isdef)
+        index_default = real_current_index
+      end
+      # 
+      # Si c'est une propriété requise et qu'elle n'est pas définie,
+      # on indique qu'il manque des définitions avant d'avoir la
+      # possibilité d'enregistrer. On en profite aussi, si c'est la
+      # première, pour définir l'index par défaut
+      # 
+      if is_required && not(isdef)
+        requirement_missing = true
+        index_default = real_current_index if index_default.nil?
+      end
+      # choix = cs.shift
+      # choix = "#{property.name(instance).ljust(max_label_width)}#{curval}"
+      # 
+      # Faut-il utiliser une méthode de formatage d'affichage
+      # 
+      fvalue  = property.formated_value_in(instance)
+      choix   = "#{property.name(instance).ljust(max_label_width)}#{fvalue}"
+      # 
+      # Couleur en fonction de propriété requise ou non
+      # 
+      choix = choix.send(isdef ? :bleu : :orange) if is_required
+      #
+      # Marque de propriété requise
+      # 
+      choix = (is_required ? '* '.rouge : '  ') + choix        
+      # 
+      # Le choice à utiliser
+      # 
+      {name: choix, value: property}
+    end.compact
+
+    # 
+    # Si toutes les valeurs requises sont définies, on peut ajouter
+    # un menu pour enregistrer
+    # 
+    savable = not(requirement_missing)
+    choix_save = {name: MSG[:save].send(savable ? :bleu : :gris), value: :save}
+    choix_save.merge!(disabled: "(#{MESSAGES[:still_required_values]})".gris) if not(savable)
+    cs.unshift(choix_save)
+    # 
+    # On a toujours la possibilité d'annuler l'édition
+    # 
+    cs << CHOIX_RENONCER
+    #
+    # Si l'index par défaut n'a pas pu être déterminé, on prend le
+    # milieu de la liste de propriétés
+    # 
+    index_default = cs.count / 2 if index_default.nil?
+    # 
+    # On retourne la liste des choix et l'item sélectionné
+    # 
+    return [cs, index_default]
+  end
+
+end #/class Editor
+end #/class Manager
+end #/module DataManager
+end #/module Clir