Merge pull request #4 from wild-devops/develop

Adjust template concept to initial state

README.md

@@ -79,7 +79,7 @@ The result looks like the followed output including information about:
 *  `PWSHAKE config:` - loaded config file content (may be rearranged due to overriding, interpolation, and merging metadata)
 *  `Arranged tasks:` - tasks to be executed in actual order
 *  `Invoke task:` - invoked tasks name
-*  `Execute <step|powershell|cmd>:` - invoked steps caption
+*  `Execute step:` - invoked steps caption
 *  Everything else - invoked scripts output
 
 ```
@@ -128,6 +128,7 @@ And it runs various tests and examples included in this repo.
   * [`includes:` element](/doc/includes.md)
   * [`invoke_tasks:` element](/doc/invoke_tasks.md)
   * [`tasks:` element](/doc/tasks.md)
+  * [`templates:` element](/doc/templates.md)
   * [implicit `[step]:` element](/doc/step.md)
   * [`scripts_directories:` element](/doc/scripts_directories.md)
 

doc/step.md

@@ -9,12 +9,7 @@ The internal representation of a single **step** looks like a following **Powers
   when = "`$true";
   work_dir = $null;
   on_error = "throw";
-  script = $null;
   powershell = $null;
-  cmd = $null;
-  invoke_tasks = $null;
-  template = $null;
-  parameters = @{};
 }
 ```
 
@@ -29,6 +24,10 @@ will be transformed into the following structure:
 ```
 @{
   name = "step name";
+  when = "`$true";
+  work_dir = $null;
+  on_error = "throw";
+  powershell = $null;
   script = "script_name";
 }
 ```
@@ -40,19 +39,7 @@ Pay attention that the `step1` identifier itself does not bring any actual value
 ```
 In this case the `-` sign means that subsequent items in `yaml` hierarchy are keys of the same **Powershell** `[hashtable]`.
 
-So, the full allowed form of the `- [step]:` element could be the following:
-```
-- name: step name
-  script: script_name
-  powershell: "some inline powershell code"
-  cmd: "other inline cmd.exe commands"
-  template: my_template
-  when: $true
-...
-```
-But **PWSHAKE** engine take pecedence over the given structure items and executes only the first non empty item, in this case `script:` item with '`script_name`' value, all others (`powershell:`, `cmd:`, `template:`) are ignored.
-
-* ### - `[step]:` element implicit shortenings
+* ## - `[step]:` element implicit shortenings
   Since the actual payload in the executed structure have only the two elements:
   * `name:`
   * first non empty of `[script: | powershell: | cmd:]`
@@ -105,10 +92,28 @@ But **PWSHAKE** engine take pecedence over the given structure items and execute
   ```
   This is the same as:
   ```
-  - name: pwshake_2122574676
+  - name: step_2122574676
     powershell: rm ./ -recurse -force
   ```
 
+* ### - `[msbuild]:` element implicit shortenings
+  All things described above are eligible for the `msbuild:` element.
+
+
+  Since the actual payload of this element is the **MSBuild** project file name, so the shortening syntax use this value as a `project:` element value.
+
+  Example:
+  ```
+  - name: Build
+    msbuild: some_project_file_name
+  ```
+  This is actually the same as:
+  ```
+  - name: Build
+    msbuild:
+      project: some_project_file_name
+  ```
+
 * ### - `[when|only|except|skip_on]:` element implicit shortenings
   Since the `[when|only|except|skip_on]:` elements contain inline code that evaluated by **PWSHAKE** engine to make a decision whether or not to execute a particular **step** they can be omitted in general because of the default value is always set to `$true` (`-not ($true) ` for negation aliases `except:`, `skip_on:`).
 
@@ -157,7 +162,7 @@ But **PWSHAKE** engine take pecedence over the given structure items and execute
   - step:
       name: Do all stuff if solution file is present
       scripts:
-      - powershell: $skip_it_all = -not (Test-Path MySolution.sln)
+      - powershell: $script:skip_it_all = -not (Test-Path MySolution.sln)
       - skip: $skip_it_all
         invoke_tasks:
         - clean

doc/tasks.md

@@ -121,6 +121,20 @@ Every named element of the `tasks:` can contain some definitions to provide more
           -list -of -fake -parameters
     ```
 
+  * `- msbuild:` - element to run **MSBuild** with particular settings
+
+    Example:
+    ```
+    tasks:
+      build:
+      - msbuild: .\MySolution.sln
+      - msbuild:
+          project: .\MyProject.csproj
+          targets: TransformConfigs
+          properties: Configuration=Debug
+    ```
+    The above are 2 calls to **MSBuild**: the first is in shortened form and just uses default target (`Build`) and default options, the second uses given parameters `targets:` and `properties:` passed from `pwshake.yaml` config.
+
   * `- [step]:` - an implicit element to fulfill the particular step settings in explicit way
 
     Example:
@@ -134,8 +148,7 @@ Every named element of the `tasks:` can contain some definitions to provide more
         cmd: echo 'step2'
       - step3:
           name: Do msbuild task
-          template: msbuild
-          parameters:
+          msbuild:
             project: .\MyProject.csproj
             targets: TransformConfigs
             properties: Configuration=Debug

doc/templates.md

@@ -0,0 +1,87 @@
+## `templates:` **element**
+Contains definitions of `step:` elements structure for reusing and syntax shortenings in the whole `pwshake.yaml` config.
+
+This tells to **PWSHAKE** engine how to substitute any structured `yaml` input in step definitions into an executable **Powershell** command.
+
+* ## `templates:` example
+    ```
+    PS>cat python.yaml
+    templates:
+      python:
+        file:
+        inline:
+        powershell: |
+          if ($step.python) {
+            "python $($step.python)" | Cmd-Shell
+          } elseif ($step.file) {
+            "python $($step.file)" | Cmd-Shell
+          } elseif ($step.inline) {
+            python -c $step.inline
+          } else {
+            python --version
+          }
+    ```
+    The given example can be used with regular `pwshake.yaml` config by including the template file `python.yaml` and using a new `python:` element as a regular step in tasks definition.
+    ```
+    PS>cat hello.py
+    import sys
+    print("Hello " + sys.argv[1] + "!", file=sys.stdout, flush=True)
+
+    PS>cat python_pwshake.yaml
+    includes:
+    - python.yaml
+
+    tasks:
+      test_python_template:
+      - python:
+      - python: --version
+      - python:
+          inline: print('Hello pwshake!');
+      - python:
+          file: |
+            {{pwshake_path}}/hello.py again
+      - python: '{{pwshake_path}}/hello.py twice'
+
+    invoke_tasks:
+    - test_python_template
+    ```
+    Output should look like the following:
+    ```
+    PS>Invoke-pwshake ./python_pwshake.yaml
+    ...
+    Invoke task: test_python_template
+    Execute step: step_25540982
+    Python 3.6.8
+    Execute step: step_8493528
+    bash: python --version
+    Python 3.6.8
+    Execute step: step_46664441
+    Hello pwshake!
+    Execute step: step_6213368
+    bash: python /workdir/examples/templates/hello.py again
+
+    Hello again!
+    Execute step: step_32712664
+    bash: python /workdir/examples/templates/hello.py twice
+    Hello twice!
+    ```
+
+* ## Implicit built-in `templates:`
+    
+    Some built-in `[step:]` template definitions are already included into the **PWSHAKE** module and loaded during the **PWSHAKE** engine initialization.
+
+    So, they can be used in regular `pwshake.yaml` config without including either as external files or `templates:` element items.
+
+    Examples:
+    ```
+    PS>cat some_pwshake.yaml
+    ...
+    tasks:
+      - cmd:
+      - shell:
+      - msbuild:
+      - script:
+      - invoke_tasks:
+    ```
+    All these steps above are actually substituted templates which are loaded from [this location](/pwshake/templates).
+

examples/hello_pwshake.yaml

@@ -7,13 +7,20 @@ attributes:
 # List of directories relative to this file location where executable scripts are looking for (can be omitted)
 scripts_directories:
   - .
+  - pwshake_scripts
 
 # Declaration of run lists that compose and determine order of executing for scripts
 tasks:
   hello:
   - pwsh: |
       Write-Host "{{pwsh1}}"
       Write-Host "{{pwsh2}}"
+  - cmd: |
+      ls .
+  - create_windows
+  - script: create_linux
+  - shell: |
+      ls .
 
 # Run lists to current execute
 invoke_tasks:

examples/msbuild_pwshake.yaml

@@ -6,16 +6,19 @@ attributes:
 
 tasks:
   msbuild:
-  - template: msbuild
-    parameters:
-      project: '{{pwshake_path}}/example.msbuild.proj'
-  - template: msbuild
-    on_error: continue
-    parameters:
+  - msbuild:
+  - msbuild: '{{pwshake_path}}/example.msbuild.proj'
+  - msbuild:
+      name: Build all
+      on_error: continue
       project: '{{pwshake_path}}/example.msbuild.proj'
       targets: Build
       properties: Configuration={{configuration}}
-  - template: dotnet
+  - dotnet:
+  - dotnet:
+      name: Build again
+      command: msbuild
+      options: '{{pwshake_path}}/example.msbuild.proj'
 
 invoke_tasks:
 - msbuild

examples/templates/hello.py

@@ -0,0 +1,2 @@
+import sys
+print("Hello " + sys.argv[1] + "!", file=sys.stdout, flush=True)

examples/templates/python.yaml

@@ -0,0 +1,14 @@
+templates:
+  python:
+    file:
+    inline:
+    powershell: |
+      if ($step.python) {
+        "python $($step.python)" | Cmd-Shell
+      } elseif ($step.file) {
+        "python $($step.file)" | Cmd-Shell
+      } elseif ($step.inline) {
+        python -c $step.inline
+      } else {
+        python --version
+      }

examples/templates/python_pwshake.yaml

@@ -0,0 +1,16 @@
+includes:
+- python.yaml
+
+tasks:
+  test_python_template:
+  - python:
+  - python: --version
+  - python:
+      inline: print('Hello pwshake!');
+  - python:
+      file: |
+        {{pwshake_path}}/hello.py again
+  - python: '{{pwshake_path}}/hello.py twice'
+
+invoke_tasks:
+- test_python_template

examples/templates/templates.yaml

@@ -1,57 +1,22 @@
 templates:
-  python:
-    parameters:
-      file:
-      options:
-    cmd: |
-      python [[file]] [[options]]
   dotnet:
-    parameters:
-      command:
-      options: --version
-    cmd: |
-      dotnet [[command]] [[options]]
-  msbuild:
-    parameters:
-      project: /version
-      targets:
-      properties:
-      options:
-    pwsh: |
-      $cmd = if (${is-Linux}) {'dotnet msbuild'} else {'msbuild'}
-      if ($step.parameters.project) {
-        $cmd += " $($step.parameters.project)"
-      }
-      if ($step.parameters.targets) {
-        foreach ($target in $step.parameters.targets) {
-          $cmd += " /t:$target"
-        }
-      }
-      if ($step.parameters.properties) {
-        foreach ($property in $step.parameters.properties) {
-          $cmd += " /p:$property"
-        }
-      }
-      if ($step.parameters.options) {
-        foreach ($option in $step.parameters.options) {
-          $cmd += " $option"
-        }
-      }
-      $cmd | Cmd-Shell
+    command:
+    options: --version
+    powershell: |
+      "dotnet $($step.command) $($step.options)" | Cmd-Shell
 
   transform_xml_file:
-    parameters:
-      path:
-      appends:
-      updates:
-      removes:
-    pwsh: |
-      $path = $step.parameters.path
-      $appends = $step.parameters.appends
-      $updates = $step.parameters.updates
-      $removes = $step.parameters.removes
-      Write-Host "Transforming file '$(Resolve-Path $path)'"
-      $xml = [xml](Get-Content (Resolve-Path $path) -Raw)
+    path:
+    appends:
+    updates:
+    removes:
+    powershell: |
+      $path = Normalize-Path (Coalesce $step.transform_xml_file, $step.path) $config
+      $appends = $step.appends
+      $updates = $step.updates
+      $removes = $step.removes
+      Write-Host "Transforming file '$path'"
+      $xml = [xml](Get-Content $path -Raw)
       if ($appends) {
         foreach ($key in $appends.Keys) {
           foreach ($node in $xml.SelectNodes($key)) {
@@ -80,4 +45,4 @@ templates:
           }
         }
       }
-      $xml.Save((Resolve-Path $path))
+      $xml.Save($path)