power_stencil 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cf42bb3aa3fce0dcef410238959e9394cc65f0ff
-  data.tar.gz: 7de48ededf8571e15521a0b24e4b38ea2371e56e
+  metadata.gz: 0422be311b723e5ba9d9f58e0884b73964359b96
+  data.tar.gz: 594d2a82611aef291f2dfcf9237282d1dcd4a0d0
 SHA512:
-  metadata.gz: 2740f61ea898b2996ad83818de653ad63ac5a737afa0a41bc18351a5b745d0ce3d27d46813572f283e290b576babecf64df6be36ec8159abfa178054260c872d
-  data.tar.gz: 710d575d1ca588505ca2c4cd58d60f55c7b530a6466634f26751906a0ab86735343e9f483b3e07c757033d3d85a97d88e0b75463648ba27eeab82c9872d85877
+  metadata.gz: cba7ef3b6731db7b4e5957536c5a8bfe182c6c533f8750d6a65baf4ba408aed245d32c62421ac652cbe7266a5c21cf6739a1ea3bb2d2f44fd7e3067e9e314c4f
+  data.tar.gz: 100ec840751ddfdba4e47bcb99769c666d7256f9882667f0da94c12987c1d6245947992c44772fc1511d98d402d3d8b9268b249eda5c7abcad08730d3f98260e

data/README.md

@@ -13,6 +13,10 @@ PowerStencil
     - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
     - [`PowerStencil` project structure](#powerstencil-project-structure)
     - [Getting started](#getting-started)
+        - [Entities](#entities)
+        - [Templates](#templates)
+        - [Builds](#builds)
+        - [Plugins](#plugins)
 - [Project status](#project-status)
 - [Contributing](#contributing)
     - [License](#license)
@@ -36,30 +40,37 @@ It is a common pattern to introduce a database to manage shared configuration fo
 
 A `PowerStencil` project is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization and **with `PowerStencil` everything is maintained in a git repository**: data, templates, specific code **without sacrificing on data integrity and relational features**. No more config loss, no more change applied without a full lineage.
 
-**:information_source: With `PowerStencil` data can either be managed as documents to edit (Yaml) or code !!**. Use the best method depending on what you are doing.
+**:information_source: With `PowerStencil` data can either be managed as documents to edit (Yaml) or fully as code within a powerful shell !!**. Choose the method that fits the most to what you are doing.
 
 The `PowerStencil` gem provides the `power_stencil` executable which is a pluggable CLI to:
 
-- Manage the project data
-- Manage templates
-- Manage builds
-- Create and manipulate plugins
+- Manage your project **relational-integrity-checked data** in a versioned, git diff friendly yet flexible format.
+- Visualize your **data relations with graphviz**. Customize generated graphs easily.
+- Easily **manage templates** to generate whatever your project/organization requires.
+- Define builds that you can easily **embed in your CI/CD process** or use them standalone.
+- Ensure **re-usability** with a versatile extension mechanism including plugins.
 
 # Pfff, yet another templating engine...
 
-**Actually `PowerStencil` is _not_ a templating engine** per se. Instead it uses already existing and proven templating engines.
-Currently it uses [ERB], which is pretty standard in [Ruby] world, but this is not hardcoded and any templating engine could be used (in parallel, meaning different templating engines can be used automatically depending on what you actually want to generate), even if only [ERB] is implemented for the time-being, `PowerStencil` is modular from ground-up and at least a second implementation for [Haml] templating engine is planned to ease generation of XML-like files, still currently you can do it with [ERB]. See the [templates] section for more information about templates in `PowerStencil`.
+**Actually `PowerStencil` is _not_ a templating engine**. It uses already existing and proven templating engines.
+
+Currently it uses [ERB], which is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. Virtually any templating engine existing in the Ruby ecosystem could be integrated in the `PowerStencil` framework next to [ERB]. This will probably be the case in a future release, at least to integrate the [Haml] templating engine in order to ease the generation of XML-like files, still you obviously already can do it with [ERB].
+
+No, the real value of `PowerStencil` is in the development flow it proposes around this templating mechanism, for both development and/or operations teams, and most specifically in **the way you organize and trace the data which is the real asset**, and in the way you can easily extend it to fit the particular needs of a project or organization.
 
-No, the real value of `PowerStencil` is not really in its templating capabilities even if very powerful, but in the development flow it proposes around this templating mechanism for both development and/or operations teams, in the way you organize and trace the data which is the real asset, and in the way you can easily extend it to fit the particular needs of a project or organization.
 
 # Installation
 
-You need a working install of the [Ruby] language (>= 2.2).
+You need a working install of the [Ruby] language (>= 2.3).
 
 You can install the `PowerStencil` gem by issuing the usual:
 
     $ gem install power_stencil
 
+If you want to create graphviz graphs, you probably may want to install it for your system. If you are using an _apt-based_ system like Ubuntu or Debian it may probably be as simple as:
+
+    $ sudo apt install graphviz
+
 # Usage
 
 ## Help
@@ -144,38 +155,47 @@ The structure of a brand new `PowerStencil` project is the following:
     │   └── README.md
     └── versioned-config.yaml
 ```
-New directories will appear once you start some [builds] or when you will define [templates], but this is the initial state.
 
-Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project. It is prefilled so that unless you want to specifically avoid a file to be versioned, you don't need any action regarding `PowerStencil` project files.
+Other directories will appear once you start working with the project, perform some [builds] or when you will define [templates], but this is the initial state.
 
-The project has two distinct config files. Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest will be versioned. But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml` which is not be versioned. The content defined in the latter overrides the content of the official one. This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.
+Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project. It is prefilled so that unless you want to specifically avoid a file to be versioned, you don't need to worry regarding `PowerStencil` project files. **By default everything that must be versioned actually is and everything that shouldn't isn't**.
 
-There is the same mechanism between `.ps_project/entities` and `.ps_project/user_entities`, but as opposed to the two aforementioned config files you should not edit anything directly there, but instead interact using the CLI. More information on how to manage entities [here][entities].
+The project has two distinct config files.
 
-The `plugins` directory can optionally contain project specific plugins. Plugins are a great way to extend `PowerStencil` for the needs of a project or organization. See the [plugins] documentation.
+- Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest, will be versioned. 
+- But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml`, which is not be versioned. The content defined in the latter overrides the content of the official one. 
+
+**This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.**
+
+There is the same mechanism between `.ps_project/entities` (where the project data is stored and which is versioned) and `.ps_project/user_entities` (where local data is stored and not versioned), but as opposed to the two aforementioned config files, you should not edit anything directly there but instead use the CLI or the shell. More information on how to manage entities [here][entities].
+
+The `plugins` directory can optionally contain project specific plugins. Plugins are a great way to extend `PowerStencil` for the needs of a project or organization.
 
 ## Getting started
 
-The core of the system is the `entity`, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
+See the four following topics as a kind of tutorial on `PowerStencil`. You should read them in order, as each of them assumes you already read the previous one.
+
+### Entities
 
-> :arrow_forward: [Entities]
+The **core of the system** is the **[entity][entities]**, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
 
-Then it is important to understand how to use entities within `templates`. Templates are the way to generate something (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
+### Templates
 
-> :arrow_forward: [Templates]
+Then it is important to understand how to use entities within **[templates]**. Templates are the way to **generate whatever you need** (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
 
-The mechanism that combines entities and templates is called a `build`. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
+### Builds
 
-> :arrow_forward: [Builds]
+The mechanism that **combines entities and templates** is called a **[build][builds]**. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
 
-`PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. `Plugins` provide a way to completely extend `PowerStencil`, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
+### Plugins
 
-> :arrow_forward: [Plugins]
+`PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. **[Plugins]** provide a way to completely **extend `PowerStencil` and ease cross-projects share and re-usability**, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. 
+Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
 
-And course, you may:
+<br>
+<br>
 
-- Read the [F.A.Q.]
-- See some real world [example use cases].
+And course, you may want to **read the [F.A.Q.]**
 
 # Project status
 
@@ -216,3 +236,4 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [ERB]: https://ruby-doc.org/stdlib-2.6.3/libdoc/erb/rdoc/ERB.html "Quick ERB description"
 [Haml]: http://haml.info/ "The templating engine for XML-like documents"
 [Ruby]: https://www.ruby-lang.org "The powerful Ruby language"
+[Rails]: https://rubyonrails.org/ "The Ruby on Rails framework"

data/doc/entities.md

@@ -25,14 +25,16 @@ Entities
         - [entity_type](#entity_type)
         - [auto_named_entity_type](#auto_named_entity_type)
         - [field](#field)
-        - [has_one](#has_one)
-        - [has_many](#has_many)
-        - [is_array](#is_array)
-        - [is_hash](#is_hash)
-        - [not_null](#not_null)
-        - [not_empty](#not_empty)
-        - [should_match](#should_match)
-        - [class_name](#class_name)
+        - [Integrity constraints](#integrity-constraints)
+            - [is_array](#is_array)
+            - [is_hash](#is_hash)
+            - [not_null](#not_null)
+            - [not_empty](#not_empty)
+            - [should_match](#should_match)
+            - [class_name](#class_name)
+        - [Relational constraints](#relational-constraints)
+            - [has_one](#has_one)
+            - [has_many](#has_many)
         - [buildable and buildable_by](#buildable-and-buildable_by)
     - [Module you could include in your entity types](#module-you-could-include-in-your-entity-types)
     - [Adding functional code](#adding-functional-code)
@@ -612,116 +614,11 @@ PowerStencil DSL> e.fields['another_field']
 - The `name` field that we already saw and which is mandatory.
 - The `description` field which is optional, and which is pretty self-explanatory.
 
-### has_one
 
-This property may look familiar to users of [ActiveRecord], it introduces the concept of relationship between entities.
-
-```ruby
-class MyCustomEntity < PowerStencil::SystemEntityDefinitions::ProjectEntity
-  entity_type :custom_entity
-
-  has_one :custom_entity, name: :parent
-end
-```
+### Integrity constraints
 
-```ruby
-PowerStencil DSL> e = new_custom_entity name: :test_entity
-=> #<MyCustomEntity:47215552142260 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566478203.584915)'>
-PowerStencil DSL> p = new_custom_entity name: :foo
-=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
-PowerStencil DSL> e.parent = p 
-=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
-PowerStencil DSL> e.fields
-=> {:name=>"test_entity", :parent=>#<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>}
-PowerStencil DSL> p.save=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
-PowerStencil DSL> e.save
-=> #<MyCustomEntity:47215552142260 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566478203.584915)'>
-PowerStencil DSL> exit
-```
-
-Which translates at persistence level as:
-
-```shell
-$ power_stencil get custom_entity/test_entity --raw
---- !ruby/object:MyCustomEntity
-:name: test_entity
-:parent: !psref
-  type: :custom_entity
-  name: foo
-```
-Here we are referencing an entity of the same type, but of course you can reference any type of entity. Using `has_one` will enforce the type of data you reference. Let's try to mess-up:
-
-```ruby
-PowerStencil DSL> e.parent = :bar
-=> :bar
-PowerStencil DSL> e.fields
-=> {:name=>"test_entity", :parent=>:bar}
-PowerStencil DSL> e.valid?
-=> false
-PowerStencil DSL> e.valid? raise_error: true
-UniverseCompiler::Error: Invalid entity '[:custom_entity, "test_entity"]' for fields parent !
-from /opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/universe_compiler-0.2.7/lib/universe_compiler/utils/error_propagation.rb:10:in `false_or_raise'
-PowerStencil DSL> e.save
-UniverseCompiler::Error: Invalid entity '[:custom_entity, "test_entity"]' for fields parent !
-from /opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/universe_compiler-0.2.7/lib/universe_compiler/utils/error_propagation.rb:10:in `false_or_raise'
-```
-So you see that if we try to set parent with something wrong, the accessor seems to accept, you can even see the `#fields` Hash updated. But as soon as you try to save to entity, or if you use the `#valid?` method, it complains about the type... Cool.
-
-:information_source: The `name` property of the `has_one` directive is optional. If not present the field will be named from the entity_type referenced instead...
 
-**:warning: See more advanced features, like reverse methods in the [universe_compiler advanced relations documentation].**
-
-### has_many
-
-Once you know the `has_one` directive, you should not be surprised by the `has_many` directive...
-
-```ruby
-class MyCustomEntity < PowerStencil::SystemEntityDefinitions::ProjectEntity
-  entity_type :custom_entity
-  
-  has_many :base_entity, name: :sub_properties
-end
-```
-
-```ruby
-PowerStencil DSL> e = new_custom_entity name: :test_entity
-=> #<MyCustomEntity:47312117001560 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> sub_prop1 = new_base_entity name: :prop1
-=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> e.sub_properties << sub_prop1
-=> [#<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>]
-PowerStencil DSL> sub_prop2 = new_base_entity name: :prop2
-=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> e.sub_properties << sub_prop2
-=> [#<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>,
- #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>]
-PowerStencil DSL> sub_prop1.save
-=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> sub_prop2.save
-=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> e.save
-=> #<MyCustomEntity:47312117001560 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566482056.789871)'>
-PowerStencil DSL> exit
-```
-
-Which translates at persistence level as:
-
-```shell
---- !ruby/object:MyCustomEntity
-:sub_properties:
-- !psref
-  type: :base_entity
-  name: prop1
-- !psref
-  type: :base_entity
-  name: prop2
-:name: test_entity
-```
-Nice !
-
-**:warning: See more advanced features, like reverse methods in the [universe_compiler advanced relations documentation].**
-
-### is_array
+#### is_array
 
 You can define a field as being an array:
 
@@ -745,7 +642,7 @@ PowerStencil DSL> e.fields
 
 :information_source: Please note the two syntaxes are equivalent.
 
-### is_hash
+#### is_hash
 
 You can define a field as being an array:
 
@@ -769,7 +666,7 @@ PowerStencil DSL> e.fields
 
 :information_source: Please note the two syntaxes are equivalent.
 
-### not_null
+#### not_null
 
 I guess you start getting used to what happens:
 
@@ -804,7 +701,7 @@ PowerStencil DSL> e.valid?
 ```
 Nothing very surprising there. Please note an empty string is not a null value...
 
-### not_empty
+#### not_empty
 
 This directive will adapt depending on the field type
 
@@ -847,7 +744,7 @@ Pretty simple nope ?
 
 :information_source: `has_one` does not support `not_empty` but support `not_null`, and the opposite for `has_many`...
 
-### should_match
+#### should_match
 
 `should_match` will perform a validation of the content regarding a regular expression or a string. It should work on strings or symbols:
 
@@ -888,7 +785,7 @@ PowerStencil DSL> e.valid? raise_error: true
 
 :warning: As you can see there, unless specified as `not_null` or `not_empty`, the `should_match` validation will not be performed ! Pretty normal if you think about it...
 
-### class_name
+#### class_name
 
 ```ruby
 class MyCustomEntity < PowerStencil::SystemEntityDefinitions::ProjectEntity
@@ -917,6 +814,119 @@ PowerStencil DSL> e.valid? raise_error: true
 
 :warning: Use this one with caution, as it does not test anything regarding inheritance...
 
+
+### Relational constraints
+
+#### has_one
+
+This property may look familiar to users of [ActiveRecord], it introduces the concept of relationship between entities.
+
+```ruby
+class MyCustomEntity < PowerStencil::SystemEntityDefinitions::ProjectEntity
+  entity_type :custom_entity
+
+  has_one :custom_entity, name: :parent
+end
+```
+
+```ruby
+PowerStencil DSL> e = new_custom_entity name: :test_entity
+=> #<MyCustomEntity:47215552142260 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566478203.584915)'>
+PowerStencil DSL> p = new_custom_entity name: :foo
+=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
+PowerStencil DSL> e.parent = p 
+=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
+PowerStencil DSL> e.fields
+=> {:name=>"test_entity", :parent=>#<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>}
+PowerStencil DSL> p.save=> #<MyCustomEntity:47215551934000 composite_key=[:custom_entity, "foo"], @universe='Project entities (1566478203.584915)'>
+PowerStencil DSL> e.save
+=> #<MyCustomEntity:47215552142260 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566478203.584915)'>
+PowerStencil DSL> exit
+```
+
+Which translates at persistence level as:
+
+```shell
+$ power_stencil get custom_entity/test_entity --raw
+--- !ruby/object:MyCustomEntity
+:name: test_entity
+:parent: !psref
+  type: :custom_entity
+  name: foo
+```
+Here we are referencing an entity of the same type, but of course you can reference any type of entity. Using `has_one` will enforce the type of data you reference. Let's try to mess-up:
+
+```ruby
+PowerStencil DSL> e.parent = :bar
+=> :bar
+PowerStencil DSL> e.fields
+=> {:name=>"test_entity", :parent=>:bar}
+PowerStencil DSL> e.valid?
+=> false
+PowerStencil DSL> e.valid? raise_error: true
+UniverseCompiler::Error: Invalid entity '[:custom_entity, "test_entity"]' for fields parent !
+from /opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/universe_compiler-0.2.7/lib/universe_compiler/utils/error_propagation.rb:10:in `false_or_raise'
+PowerStencil DSL> e.save
+UniverseCompiler::Error: Invalid entity '[:custom_entity, "test_entity"]' for fields parent !
+from /opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/universe_compiler-0.2.7/lib/universe_compiler/utils/error_propagation.rb:10:in `false_or_raise'
+```
+So you see that if we try to set parent with something wrong, the accessor seems to accept, you can even see the `#fields` Hash updated. But as soon as you try to save to entity, or if you use the `#valid?` method, it complains about the type... Cool.
+
+:information_source: The `name` property of the `has_one` directive is optional. If not present the field will be named from the entity_type referenced instead...
+
+**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].**
+
+#### has_many
+
+Once you know the `has_one` directive, you should not be surprised by the `has_many` directive...
+
+```ruby
+class MyCustomEntity < PowerStencil::SystemEntityDefinitions::ProjectEntity
+  entity_type :custom_entity
+  
+  has_many :base_entity, name: :sub_properties
+end
+```
+
+```ruby
+PowerStencil DSL> e = new_custom_entity name: :test_entity
+=> #<MyCustomEntity:47312117001560 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> sub_prop1 = new_base_entity name: :prop1
+=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> e.sub_properties << sub_prop1
+=> [#<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>]
+PowerStencil DSL> sub_prop2 = new_base_entity name: :prop2
+=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> e.sub_properties << sub_prop2
+=> [#<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>,
+ #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>]
+PowerStencil DSL> sub_prop1.save
+=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116793880 composite_key=[:base_entity, "prop1"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> sub_prop2.save
+=> #<PowerStencil::SystemEntityDefinitions::ProjectEntity:47312116175620 composite_key=[:base_entity, "prop2"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> e.save
+=> #<MyCustomEntity:47312117001560 composite_key=[:custom_entity, "test_entity"], @universe='Project entities (1566482056.789871)'>
+PowerStencil DSL> exit
+```
+
+Which translates at persistence level as:
+
+```shell
+--- !ruby/object:MyCustomEntity
+:sub_properties:
+- !psref
+  type: :base_entity
+  name: prop1
+- !psref
+  type: :base_entity
+  name: prop2
+:name: test_entity
+```
+Nice !
+
+**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].**
+
+
 ### buildable and buildable_by
 
 One of the most important directives !
@@ -973,5 +983,5 @@ Now you know an entity type is just a regular Ruby class. As such you could add
 [ActiveRecord]: https://guides.rubyonrails.org/active_record_basics.html "The ultimate ORM"
 [Ruby On Rails]: https://rubyonrails.org/ "One of the best Web framework"
 [universe_compiler]: https://gitlab.com/tools4devops/universe_compiler "The underlying engine to manage entities and compilation !"
-[universe_compiler advanced relations documentation]: https://gitlab.com/tools4devops/universe_compiler#advanced-relations "Advanced relational features"
+[`universe_compiler` advanced relations documentation]: https://gitlab.com/tools4devops/universe_compiler#advanced-relations "Advanced relational features"
 [Graphviz]: (https://www.graphviz.org/) "Graph Visualization Software"

data/doc/example_use_cases.md

@@ -17,6 +17,7 @@ Example use cases
 Considering the genericity of the `PowerStencil` framework, it is a bit difficult to define a strict scope for its usage. It's a bit like wondering what you could do with a programming language.
 
 Neverthless, I will give two short ideas that should open you mind to things you could do with it.
+Plugins are currently in development around these topics, and may come pretty soon.
 
 
 # Managing machines, routers, firewalls...
@@ -29,6 +30,8 @@ You could define machines, interfaces, networks as [entities] and having [templa
 
 And of course, changes are tracked using Git, providing easy fallback for something as critical as your network config.
 
+An official plugin is under development for this.
+
 # Deploying Snaps, Docker containers, VMs
 
 If you manage a containerized infrastructure, you probably noticed how often you need to have the same information duplicated from your application builds, Snaps, Docker containers or VM definitions (names, ports, entry-points...)

data/doc/faq.md

@@ -70,16 +70,17 @@ Regarding Windows, I stopped using spywareOS years ago so I can't really tell yo
 
 # What is the status of `PowerStencil` ?
 
-Although `PowerStencil` is still under development, **it can already be safely used**.
+`PowerStencil` is still under development, yet **it can already be safely used**.
 
 Regarding `PowerStencil` core:
 
 - The part that may evolve the most is the plugin part (including documentation which is not really in par with the rest...), but it should not break anything developed now.
-- New system entity types may appear. 
+- New system entity types may appear.
+- The documentation is evolving
 
 Anyway `PowerStencil` follows the semantic versioning pattern and if incompatible changes arise it may be reflected in the version.
 
-There are already some plugins in the pipe, especially around contenerization topics.
+There are already some plugins in the pipe. See [example use cases], to get an idea of the first official plugins to come.
 
 :information_source: Of course, `PowerStencil` is new software and it is expected to evolve with the needs of its users...
 
@@ -94,6 +95,7 @@ There are already some plugins in the pipe, especially around contenerization to
 [entities]: entities.md "Entities in PowerStencil"
 [plugins]: plugins.md "Plugins in PowerStencil"
 [overrides]: builds.md#overriding-entities-and-build-scenarii "Overriding data locally"
+[example use cases]: example_use_cases.md "Example uses cases using PowerStencil"
 
 
 <!-- Code links -->

data/doc/templates.md

@@ -19,15 +19,19 @@ Templates
 
 # Templates overview
 
-Templates are the key feature of `PowerStencil` (hence the name). Templates are what will use the [entities] you carefully crafted in order to produce something during the [build][builds] process.
+Template is a key feature of `PowerStencil` (hence the name). In templates you define how you will use the [entities] you carefully crafted in order to produce something during a [build][builds] process.
 
-Currently the underlying engine is [ERB].
+The default templating engine being [ERB], your templates should be written using the [ERB] syntax, like most templates are written in the [Ruby On Rails] framework. This is basically some [Ruby] inside some ERB tags.
 
-When an entity type has some templates associated and you create an entity, it will create a directory `<entity_type>/<entity_name>` where you will fond those templates.
+Templates are always associated to some [buildable entities][buildable].
+
+When a [buildable entity][buildable] has some templates associated, they will be located in a directory `<entity_type>/<entity_name>/`. For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph). This is what is called `templates-templates`.
+
+In this document, you will learn how to create your own templates, as well as your own templates-templates.
 
 # Templates discovery with `simple_exec` entity type
 
-In the basic entity types, the only one having templates is the `simple_exec` entity type. So let's try with it:
+In the basic entity types, the only one providing default templates is the `simple_exec` entity type. So let's try with it:
 
 ```shell
 $ power_stencil create simple_exec/demo_templates 
@@ -41,9 +45,9 @@ RAW ENTITIES
   - Status         : Valid 
   - Buildable      : true
 ```
-As you can see the output of `power_stencil check` shows more information than entities we already created. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information.
+As you can see the output of `power_stencil check` shows more information than entities we created so far. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information.
 
-And it's true if we have a look in the `simple_exec/demo_templates` from the root of the project, a file appeared there:
+And it's true if we have a look in the `simple_exec/demo_templates/` directory from the root of the project, a file appeared there:
 
 ```shell
 $ ls -l simple_exec/demo_templates
@@ -138,7 +142,7 @@ Here are the main methods:
 - `entity(type, name)` will return any entity from the repository. The method is self-explanatory, this is the most generic way to access any entity of the repository.
 - `entities(criterion: nil, value: nil, &filter_block)` which is a more generic entities query method where `criterion` can be `:by_name` or `:by_type` and that will return an array (that you can potentially filter using the `filter_block`).
 - `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(type, name)` method. 
+- `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 !
 

data/lib/power_stencil/command_processors/entity_helper.rb

@@ -21,10 +21,18 @@ module PowerStencil
             h = entity.to_hash
             entity.class.fields_constraints.each do |field_name, constraints|
               next unless constraints[:reverse_method]
+
               reverse_method_conf = constraints[:reverse_method]
               val = entity.send(reverse_method_conf[:actual_method])
               node = h[entity.class.name][:dynamic_data] ||= {}
-              node[reverse_method_conf[:actual_method]] = val.as_path unless val.nil?
+              next if val.nil?
+              next if val.is_a? Array and val.empty?
+
+              node[reverse_method_conf[:actual_method]] = if val.is_a? Array
+                                                            val.map &:as_path
+                                                          else
+                                                            val.as_path
+                                                          end
             end
             puts h.to_yaml
           end

data/lib/power_stencil/dsl/base.rb

@@ -14,10 +14,6 @@ module PowerStencil
         @universe = universe
       end
 
-      def project_config
-        project.config
-      end
-
     end
 
   end

data/lib/power_stencil/dsl/entities.rb

@@ -13,6 +13,10 @@ module PowerStencil
         e.nil? ? entity(type.to_sym, name) : e
       end
 
+      def project_config
+        entity :project_config, 'Project Config'
+      end
+
       def entity(type_or_path, name = nil)
         type, name = if name.nil?
                        md = type_or_path.match /^(?<type>[^\/]+)\/(?<name>.*)$/

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.4.6'.freeze
+  VERSION = '0.4.7'.freeze
 end

data/power_stencil.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'climatic', '~> 0.2.29'
   spec.add_dependency 'dir_glob_ignore', '~> 0.3'
-  spec.add_dependency 'universe_compiler', '~> 0.4.2'
+  spec.add_dependency 'universe_compiler', '~> 0.4.3'
   spec.add_dependency 'pry'
 
   spec.post_install_message = %Q{

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-17 00:00:00.000000000 Z
+date: 2019-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.2
+        version: 0.4.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.2
+        version: 0.4.3
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -253,7 +253,7 @@ homepage: https://gitlab.com/tools4devops/power_stencil
 licenses:
 - MIT
 metadata: {}
-post_install_message: "\nThank you for installing PowerStencil 0.4.6 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.4.7 !\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\nFull documentation
   here   : https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel