power_stencil 0.8.14 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 953c643a9a919791eeb8dc12c8e725c2a8ab80c6
-  data.tar.gz: 8231bae8f9f3d2fe16987b758ffcc8e22be3f295
+  metadata.gz: a7a7ba04e35989e29c761da1e15018121ada88a4
+  data.tar.gz: be2c3cfe6550a722e126d0587a5aa76273573edb
 SHA512:
-  metadata.gz: dfede811fa8dc0efc67e158abf08e93aac47fb327c6642fff344d6caa0bb7b908443ad31bc229c9b165ab3868c1f311adb63c7d24d168e5fbef98b09495634a4
-  data.tar.gz: 1b962bde64576cc9cb8a20f272a048289e42caf212d4fa63814c778fb672e1b0e137ff3dcedb3ecfab6a30488942f1db37e26eceb8b2e687a39156ec13419268
+  metadata.gz: 1f29b2f27112124935ec5b9c63222206d9ec34570154c05d02d38ad2954a74a12590ba3ab017f978ef1f9f5d71fb56d4dc75e5b2e3f48ab6d95418935d770bee
+  data.tar.gz: bad80333308df6484785785077046e16161188297a15eb95302024e48c882e1ceca0d3ac48c45b19c616f0b61973aab6795d99549ae9dc781eb7bd1614e0acfe

data/README.md

@@ -15,10 +15,10 @@ See [official website][PowerStencil site].
 - [Installation](#installation)
 - [Usage](#usage)
     - [Help](#help)
-    - [Command line auto-completion](#command-line-auto-completion)
-    - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
-    - [`PowerStencil` project structure](#powerstencil-project-structure)
     - [Getting started](#getting-started)
+        - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
+        - [`PowerStencil` project structure overview](#powerstencil-project-structure-overview)
+        - [Command line auto-completion](#command-line-auto-completion)
         - [Entities](#entities)
         - [Templates](#templates)
         - [Builds](#builds)
@@ -62,11 +62,12 @@ The `PowerStencil` gem provides the `power_stencil` executable which is a plugga
 
 **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] (as `PowerStencil` already comes with a mechanism to select a templating engine regarding some criteria like file extension, path etc...). 
+`PowerStenil` currently embeds two templating engines:
 
-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].
+* **[ERB] is the default**. This is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. This is a generic templating engine which can handle any use-case. Each template will be processed by default using the [ERB] engine.
+* When it comes to generate mark-up documents like XML or HTML, many people prefer to use [Haml], as it designed towards generating these kinds of documents and tends to end-up with much clearer templates. Any template whose names ends by `.haml` will be processed by the [Haml] engine by default instead of [ERB].
 
-So `PowerStencil` is definitely not a templating it is actually much more than that.
+So `PowerStencil` is definitely not a templating engine, it is actually much more than that. It is a framework to manage your templates, design the relational data you can use in your templates, manage the versioning, define the way you build things etc... Read this documentation (and especially the [getting started](#getting-started) section which is a tutorial in itself).
 
 
 # Installation
@@ -134,17 +135,16 @@ The program uses the standard paradigm of sub-commands (à-la-git), and each can
 
 [Plugins] may bring extra subcommands and/or options, so depending on the project you are working in, the output of `--help` may differ...
 
-## Command line auto-completion
 
-`PowerStencil` comes with a command-line auto-completion feature for `zsh`. It is not yet available for `bash`.
 
-You can install it by running:
 
-    $ power_stencil adm --zsh-completion
 
-It provides a very useful auto-completion for sub-commands, options as well as parameters...
+## Getting started
+
+See the 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.
 
-## Creating a `PowerStencil` project
+
+### Creating a `PowerStencil` project
 
 To create a new project, use the `init` sub-command. It works as you would expect. If you run it in an existing directory it will create the project here but you can specify the directory where you want the project to be created (the path will be created provided you have enough rights on the filesystem):
 
@@ -156,7 +156,7 @@ Once the project created, if you are anywhere within the project tree, you don't
 
 **:information_source: If you have `git` installed on your system, **the repository of the newly created project has been automatically turned into a git repository. And any action done through the `power_stencil` command-line will be automatically tracked by `git`**. Only things you will do outside of the `power_stencil` command-line (adding or modifying templates, creating or modifying entity types... any manual action) will require a user action to make `git` take it in account. You can completely de-activate this behaviour if you want to fully manage things by yourself by adding `:no-git: true` in the `.ps_project/versioned-config.yaml`, yet there is no good reason for that... Unless you know what you are doing, you should keep the default settings. See [Git integration] for further information.
 
-## `PowerStencil` project structure
+### `PowerStencil` project structure overview
 
 The structure of a brand new `PowerStencil` project is the following:
 
@@ -191,9 +191,21 @@ There is the same mechanism between `.ps_project/entities` (where the project da
 
 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
+### Command line auto-completion
+
+`PowerStencil` comes with a powerful command-line auto-completion feature for `zsh`. (It is not yet available for `bash`).
+
+You can install it by running:
+
+    $ power_stencil adm --zsh-completion
+
+It provides a very useful auto-completion for sub-commands, options as well as options parameters...
+
+`PowerStencil` uses a _two-stages_ auto-completion mechanism:
+
+* Project independent completion is generated in `~/.zsh/completion/_power_stencil`, whereas completion related to new commands or options, coming from plugins used in a project, is generated (and versioned) within the project itself, in `.ps_project/.zsh_project_completion`.
 
-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.
+* Meaning that if you want to benefit from the "_full_" completion from within a project you may have to re-run `power_stencil add --zsh-completion` from within any project where you use extra plugins, in order to generate that `.ps_project/.zsh_project_completion` file. If you don't, it is not a big deal, but then you will only have access to the "_generic_" completion, ie completion not taking in account any of the extra commands or options you are using in this project brought by plugins you may use...
 
 ### Entities
 

data/doc/faq.md

@@ -72,12 +72,13 @@ I had the opportunity to have access to a Windows VM and tested `PowerStencil`.
 
 # What is the status of `PowerStencil` ?
 
-`PowerStencil` is still under development, yet **it can already be safely used**.
+`PowerStencil` is still considered under development until version `1.0.0` is released, yet **it can already be safely used**, event for production.
+
+**Since it entered the `0.9.x` version, no new feature should be added**. That branch will be used for statibilisation and anything released there should only be related to bugfixes, and plugin developement. As a bunch of official plugins should be released along with the version `1.0.0`.
 
 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.
+- The plugin related features may still evole a bit along with first official plugins development, but since both local and gems plugins are supported no big change may arise in the architecture.
 - The functional documentation is evolving.
 - There is almost no technical/architectural documentation yet. Read the code...
 
@@ -85,10 +86,6 @@ Anyway `PowerStencil` follows the semantic versioning pattern and if incompatibl
 
 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...
-
-
-
 
 [:back:][Documentation root]
 <!-- End of Document -->

data/doc/git_integration.md

@@ -13,6 +13,7 @@ Git integration
     - [Deleting an entity](#deleting-an-entity)
     - [`PowerStencil` shell session](#powerstencil-shell-session)
     - [Plugin creation](#plugin-creation)
+    - [(Re)Generating `zsh` command line completion for the project](#regenerating-zsh-command-line-completion-for-the-project)
 - [Manual actions](#manual-actions)
 
 <!-- /TOC -->
@@ -36,18 +37,19 @@ Here is a summary:
 
 | `PowerStencil` sub-command | Status |
 |----------------------------|:------:|
-|init        | creates a project
-|info        | read-only
-|plugin      | creates a plugin
-|get         | read-only
-|shell       | do anything  
-|adm         | read-only
-|check       | read-only  
-|create      | creates entities
-|edit        | modifies entities
-|delete      | deletes entities
-|describe    | read-only
-|build       | read-only  
+|`init`                      | creates a project
+|`info`                      | read-only
+|`plugin`                    | creates a plugin
+|`get`                       | read-only
+|`shell`                     | do anything  
+|`adm --zsh-completion`      | generates zsh command-line completion
+|`check`                     | read-only  
+|`create`                    | creates entities
+|`edit`                      | modifies entities
+|`delete`                    | deletes entities
+|`describe`                  | read-only
+|`build`                     | read-only  
+
 
 On top this we could add some other actions, you can obviously perform manually within the repository, like:
 
@@ -306,6 +308,30 @@ Date:   Sun Nov 3 19:42:11 2019 +0100
 Cool ! Nevertheless, plugins may be one of the things you may want to track a bit differently. For example as git sub-modules, to keep a separated git history, and ease future re-useability of the plugin you are developing.
 So it's up to you and `PowerStencil` provides an easy way to keep your plugin out of your project repo. Same as for `power_stencil init`, `power_stencil plugin --create` supports the `--no-git` option...
 
+## (Re)Generating `zsh` command line completion for the project
+
+If you generate the zsh command line completion file for the project by doing, from within the project:
+
+    $ power_stencil adm --zsh-completion
+
+You will then generate a file that contains project-specific zsh completion directives: `.ps_project/.zsh_project_completion`.
+
+That file is versioned too, because its content depends on the plugins (local or as gems) that you actually use in this project. **If you add a new plugin or modify the way local ones handle the command-line, you should then regenerate it**, by re-running that command if you want the completion to fully take in account your changes.
+
+It is tracked like that:
+```
+$ git log -1 --summary
+commit 0c7bedb7249654873882c56bb15172c528511cff
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 10 11:21:10 2019 +0100
+
+    Adding project specific zsh completion file: '.ps_project/.zsh_project_completion'.
+
+ create mode 100644 .ps_project/.zsh_project_completion
+```
+
+
+
 # Manual actions
 
 Ok, so far we have a pretty nice git history:

data/etc/power_stencil.yaml

@@ -72,7 +72,9 @@
 # Map to define which kind of template engine for which type of file. Be careful if you
 # overlap two definitions. Warning, it is ruby Regex not shell pattern !
 :templating_engines_map:
-  # Currently all files are rendered using ERB engine
+  # Haml for .haml files
+  :haml: '\.haml$'
+  # All the rest with ERB
   :erb: '.*'
 
 # Files matching particular patterns can be changed on the fly
@@ -82,6 +84,8 @@
   ^(.+)\.zzzgitignore\.erb$: '\1.gitignore'
   # Erb files
   ^(.+)\.erb$: '\1'
+  # Haml files
+  ^(.+)\.haml$: '\1'
 
 
 # PLUGINS

data/lib/power_stencil/engine/base.rb

@@ -2,6 +2,7 @@ require 'power_stencil/engine/entities_definitions'
 require 'power_stencil/engine/directory_processor'
 
 require 'power_stencil/engine/renderers/erb'
+require 'power_stencil/engine/renderers/haml'
 require 'power_stencil/dsl/base'
 require 'power_stencil/dsl/plugin_generation'
 require 'power_stencil/dsl/completion'
@@ -18,6 +19,7 @@ module PowerStencil
       include PowerStencil::Engine::DirectoryProcessor
 
       include PowerStencil::Engine::Renderers::Erb
+      include PowerStencil::Engine::Renderers::Haml
 
       attr_accessor :dsl
       attr_reader :root_universe

data/lib/power_stencil/engine/directory_processor.rb

@@ -1,5 +1,7 @@
 require 'fileutils'
 require 'erb'
+require 'haml'
+
 
 module PowerStencil
   module Engine

data/lib/power_stencil/engine/renderers/haml.rb

@@ -0,0 +1,21 @@
+module PowerStencil
+  module Engine
+    module Renderers
+
+      module Haml
+
+        private
+
+        def render_haml_template(source, context)
+          logger.debug "Using HAML to render file '#{source}'"
+          ::Haml::Engine.new(File.read source).render(context)
+        rescue => e
+          logger.debug PowerStencil::Error.report_error(e)
+          raise PowerStencil::Error, "Error rendering '#{source}': '#{e.message}'"
+        end
+
+      end
+
+    end
+  end
+end

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.8.14'.freeze
+  VERSION = '0.9.0'.freeze
 end

data/power_stencil.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'universe_compiler', '~> 0.5.5'
   spec.add_dependency 'pry'
   spec.add_dependency 'git' , '~> 1.5.0'
+  spec.add_dependency 'haml', '~> 5.1.2'
 
   source_code_uri = 'https://gitlab.com/tools4devops/power_stencil'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.8.14
+  version: 0.9.0
 platform: ruby
 authors:
 - Laurent Briais
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-09 00:00:00.000000000 Z
+date: 2019-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.2
 description: PowerStencil is the Swiss-army knife templating workflow for developers
   and ops.
 email:
@@ -245,6 +259,7 @@ files:
 - lib/power_stencil/engine/init_engine.rb
 - lib/power_stencil/engine/project_engine.rb
 - lib/power_stencil/engine/renderers/erb.rb
+- lib/power_stencil/engine/renderers/haml.rb
 - lib/power_stencil/error.rb
 - lib/power_stencil/initializer.rb
 - lib/power_stencil/plugins/base.rb
@@ -306,13 +321,12 @@ 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.8.14 !\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   :
-  https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel free to
-  report issues: https://gitlab.com/tools4devops/power_stencil/issues\n\nType 'power_stencil
-  adm --zsh-completion' to install auto-completion for zsh.\n\n  "
+post_install_message: "\nThank you for installing PowerStencil 0.9.0 !\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   : https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel
+  free to report issues: https://gitlab.com/tools4devops/power_stencil/issues\n\nType
+  'power_stencil adm --zsh-completion' to install auto-completion for zsh.\n\n  "
 rdoc_options: []
 require_paths:
 - lib