power_stencil 0.4.18 → 0.4.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 80af1c57689a2ba89246da59fb373577dd48a31b
-  data.tar.gz: 1c91918d21e15a9730929db9d58309b415c6098d
+  metadata.gz: 9e3d1927e39aa8060f7d38ce99b83f28ff6ef4aa
+  data.tar.gz: 9cfd4aeae7c9dbca4ebd76f51d61089df0521f68
 SHA512:
-  metadata.gz: f4ee7f37502473381418bc6184c6436f5ab05d159ed819d4bfbd4cc39554130cddd9a2d0742db82db7f7103738d7b7614df3cd1753e0d29a9713fc98608d5999
-  data.tar.gz: bd212747f02e36cc2d3d93f37246152c34ba7552af969757cada09122063ca1633e05b47a549abd9d703bb7bff3e9a8f8bc380f53b767475b0477cc4a745e5e5
+  metadata.gz: 2168d96b8d1a52ebc324b7931b59d712d364e3e352a7fd573743cb718fb835b88d92926172c9aca316e0743436c04eba1c6cb032914c8fced3a702ed4cc23cc3
+  data.tar.gz: b729958fc82e4dddc9f7180ca3198aabf32bc1475c61ad4258674db055d2df1af8b7c1432a9e34c79560419ca1137ab53c8b853e0a4e10cac8e5847766da08a1

data/README.md

@@ -119,6 +119,7 @@ PowerStencil is the Swiss-army knife templating workflow for developers and ops.
  * create: Creates entities in the repository ...
  * edit: Edit entities from repository ...
  * delete: Delete entities from repository ...
+ * describe: Detailed information about entity types ...
  * build: Builds entities ...
 ```
 

data/doc/templates.md

@@ -146,7 +146,32 @@ Here are the main methods:
 - `build_target` will return the entity that you are currently building.
 - `project_config` is a shortcut to the project entity. You could actually retrieve it using the `entity(:project_config, 'Project Config')` method.
 
-And of course you have access like in `power_stencil shell` to any class brought by `PowerStencil`, you could create entities there, destroy some, **but you should not do it**, as it would be very weird to do that during the process of detemplating !
+And of course you have access like in `power_stencil shell` to any class brought by `PowerStencil`, you could create entities there, destroy some, **but you should not do it**, as doing this during the process of detemplating could lead to strange behaviours !
+
+Nevertheless you can of course use entities data and methods within your templates. Any data can be directly accessed using [entity field] mechanism. But entities may bring as well methods you may want to use within your templates. How can we know what can be done with an entity **without reading the code** ? The answer is `power_stencil describe`... 
+
+:information_source: If you do `power_stencil describe` on any entity type, you will get a comprehensive report of what you can do with this or this entity type (by default all entity types are displayed).
+
+Here is a (not so interesting) example:
+
+```
+$ power_stencil describe simple_exec
+--------------------------------------------------------------------------------
+=> simple_exec (class: PowerStencil::SystemEntityDefinitions::SimpleExec)
+  - PARENT ENTITY TYPE: base_entity
+  - FIELDS:
+    - description
+    - post_process:
+      - has_one: process_descriptor
+      - not_null: true
+  - METHODS:
+    - delete
+    - valid?
+    - save
+```
+
+This should be self explanatory, there is another part that could be displayed in case you defined complex relation using the [reverse methods] mechanism...
+
 
 # Where do I create templates ?
 
@@ -324,7 +349,8 @@ Flawless victory !!
 [plugins]: plugins.md "Plugins in PowerStencil"
 [example use cases]: example_use_cases.md "Example uses cases using PowerStencil"
 [buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
-
+[entity field]: entities.md#field "How to access basic entity data"
+[reverse methods]: entities.md#has_one "Check reverse methods"
 <!-- Code links -->
 
 

data/etc/base_commands_definition.yml

@@ -201,7 +201,7 @@
     :options:
       property:
         :type: array
-        :summary: Specifiies a first-level property for the entity
+        :summary: Specifies a first-level property for the entity
         :short_aliases:
           - p
       edit:
@@ -230,7 +230,7 @@
 
       Usage:
 
-        edit [object_type[[/ ]object_name]] [options]
+        edit [entity_type[[/ ]entity_name]] [options]
 
       Edits repository entities. Parameters are used the same way as in 'get'.
     :options:
@@ -246,7 +246,7 @@
 
       Usage:
 
-        delete [object_type[[/ ]object_name]] [options]
+        delete [entity_type[[/ ]entity_name]] [options]
 
       Deletes repository entities. Parameters are used the same way as in 'get'.
     :options:
@@ -254,6 +254,16 @@
       delete-files:
         :type: bool
         :summary: Will also remove files related to the entity.
+  describe:
+    :banner: |
+      Detailed information about entity types.
+
+      Usage:
+
+        describe [entity_type]* [options]
+
+      Displays information about core properties of given entity types.
+      By default will describe all entity types.
   build:
     :banner: |
       Builds entities.

data/lib/power_stencil.rb

@@ -32,6 +32,7 @@ require 'power_stencil/command_processors/delete'
 require 'power_stencil/command_processors/shell'
 require 'power_stencil/command_processors/plugin'
 require 'power_stencil/command_processors/build'
+require 'power_stencil/command_processors/describe'
 
 
 module PowerStencil

data/lib/power_stencil/command_processors/describe.rb

@@ -0,0 +1,19 @@
+module PowerStencil
+  module CommandProcessors
+
+    class Describe
+
+      include Climatic::Script::UnimplementedProcessor
+      include Climatic::Proxy
+      include PowerStencil::Project::Proxy
+      include PowerStencil::CommandProcessors::EntityHelper
+
+      def execute
+        targets = extra_params_to_entity_types
+        describe_entity_types targets
+      end
+    end
+
+  end
+
+end

data/lib/power_stencil/command_processors/entity_helper.rb

@@ -9,6 +9,49 @@ module PowerStencil
         end
       end
 
+      def describe_entity_types(entity_types)
+        report = {}
+        project.engine.available_entity_types.each { |entity_type| report = build_entity_type_report entity_type, report }
+        scoped_classes = report.keys
+
+        report.select{|klass, _| entity_types.include? klass.entity_type}
+            .sort_by {|klass, _| klass.entity_type.to_s}
+            .each do |klass, info|
+          puts '-' * 80
+          puts "=> #{klass.entity_type} (class: #{klass.name})"
+          puts "  - PARENT ENTITY TYPE: #{klass.superclass.entity_type}" if scoped_classes.include? klass.superclass
+          unless info[:fields].empty?
+            puts '  - FIELDS:'
+            info[:fields].each do |field_name, constraints|
+              if constraints.empty?
+                puts "    - #{field_name}"
+              else
+                puts "    - #{field_name}:"
+                constraints.each do |name, value|
+                  puts "      - #{name}: #{value}"
+                end
+              end
+            end
+          end
+          unless info[:methods].empty?
+            puts '  - METHODS:'
+            info[:methods].each do |method_name, _|
+              puts "    - #{method_name}"
+            end
+          end
+          unless info[:special_methods].empty?
+            puts '  - SPECIAL METHODS:'
+            info[:special_methods].each do |method_name, method_info|
+              puts "    - #{method_name} (reverse method defined from relation '#{method_info[:source_field]}' in entity type '#{method_info[:source_entity]}')"
+            end
+          end
+
+        end
+
+      end
+
+
+
       def display_entity(entity)
         puts_and_logs "# Entity '#{entity.name}' (#{entity.type})"
         if config[:'names-only']
@@ -66,6 +109,20 @@ module PowerStencil
         end
       end
 
+      def extra_params_to_entity_types(params = config.command_line_layer.extra_parameters)
+        known_entity_types = project.engine.available_entity_types
+        return known_entity_types if params.empty?
+
+        params.map do |possible_entity_type|
+          possible_entity_type = possible_entity_type.to_sym
+          raise PowerStencil::Error, "Invalid entity type '#{possible_entity_type}' !" unless known_entity_types.include? possible_entity_type
+          possible_entity_type
+        end
+      end
+
+
+
+
       def extra_params_to_entity_search_criteria(params)
         criteria = []
         next_entity_reference = EntitySearchReference.new
@@ -101,6 +158,34 @@ module PowerStencil
       private
 
 
+      def build_entity_type_report(entity_type, report = {})
+        klass = project.engine.available_entities_hash[entity_type]
+        report[klass] ||= {fields: {}, methods: {}, special_methods: {}}
+        entity_type_info = report[klass]
+
+        # Fields
+        klass.fields_constraints.each  do |field_name, constraints|
+          next if constraints[:reverse_method]
+          entity_type_info[:fields][field_name] = {}
+          constraints.each do |constraint_name, constraints_value|
+            entity_type_info[:fields][field_name][constraint_name] = constraints_value
+          end
+        end
+        # Methods
+        klass.public_instance_methods(false).select do |method_name|
+          klass.method_defined? method_name
+        end .each do |method_name|
+          entity_type_info[:methods][method_name] = klass
+        end
+        # Special methods
+        klass.fields_constraints.each  do |method_name, constraints|
+          next unless constraints[:reverse_method]
+          entity_type_info[:special_methods][method_name] = constraints[:reverse_method]
+        end
+
+        report
+      end
+
       def analyse_extra_params(extra_params = config.command_line_layer.extra_parameters, default: [''])
         params_to_check = if extra_params.empty? then
                             config[:regexp] = true

data/lib/power_stencil/initializer.rb

@@ -48,7 +48,8 @@ module PowerStencil
           delete: PowerStencil::CommandProcessors::Delete,
           shell: PowerStencil::CommandProcessors::Shell,
           plugin: PowerStencil::CommandProcessors::Plugin,
-          build: PowerStencil::CommandProcessors::Build
+          build: PowerStencil::CommandProcessors::Build,
+          describe: PowerStencil::CommandProcessors::Describe
       }.each do |command_name, processor|
         command_line_manager.register_processor command_line_manager.command_by_alias(command_name),
                                                 processor.new

data/lib/power_stencil/project/versioning.rb

@@ -5,7 +5,11 @@ module PowerStencil
 
       def check_project_version
         return if project_version_valid?
-        raise PowerStencil::Error, msg
+        msg = <<~EOM
+            This PowerStencil project requires a version of PowerStencil >= #{config[:min_power_stencil_version]} (You are using version #{PowerStencil::VERSION}) !
+            You should consider upgrading by doing 'gem install power_stencil'...
+        EOM
+        raise PowerStencil::Error, msg.chomp
       end
 
       private

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.4.18'.freeze
+  VERSION = '0.4.19'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.4.18
+  version: 0.4.19
 platform: ruby
 authors:
 - Laurent Briais
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-04 00:00:00.000000000 Z
+date: 2019-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -191,6 +191,7 @@ files:
 - lib/power_stencil/command_processors/check.rb
 - lib/power_stencil/command_processors/create.rb
 - lib/power_stencil/command_processors/delete.rb
+- lib/power_stencil/command_processors/describe.rb
 - lib/power_stencil/command_processors/edit.rb
 - lib/power_stencil/command_processors/entity_helper.rb
 - lib/power_stencil/command_processors/get.rb
@@ -260,7 +261,7 @@ metadata:
   documentation_uri: https://gitlab.com/tools4devops/power_stencil/blob/master/README.md
   source_code_uri: https://gitlab.com/tools4devops/power_stencil
   homepage_uri: https://powerstencil.brizone.org/
-post_install_message: "\nThank you for installing PowerStencil 0.4.18 !\nFrom the
+post_install_message: "\nThank you for installing PowerStencil 0.4.19 !\nFrom the
   command line you can run `power_stencil --help`\nIf your shell is not completing
   the command:\n  If you use rbenv: `rbenv rehash`\n  If you use zsh  : `rehash`\n\nOfficial
   Website          : https://powerstencil.brizone.org/\nFull documentation here   :