Commit a6b01dea authored by Laurent Briais's avatar Laurent Briais

Integration works

The framework kept its promises, adding a new templating engine was **really simple**.
parent f44b0c55
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
require 'fileutils'
require 'erb'
require 'haml'
module PowerStencil
module Engine
......
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
......@@ -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'
......
%xml
%wow
%msg= Time.now
%content= build_target.as_path
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment