Merge pull request #6 from wild-devops/develop

Implemented kind of DSL via templates composition

.github/workflows/tests.yml

@@ -11,5 +11,5 @@ jobs:
     steps:
     - uses: actions/checkout@master
     - name: Run tests
-      run: ./tests/pwshake.Tests.ps1
+      run: ./pwshake.ps1
       shell: pwsh

README.md

@@ -30,6 +30,15 @@ Average time to live for most of them is during from 30 minutes (for auto-testin
 
 So, we do not need to manage a big **snowflake** infrastructure and to care about managed **state** of it (say hello to **Chef** and **DSC**). Rather we need to organize a simple and robust way to make the full initial configuration of our hosts (quite complex in some cases) and to perform it only once per each host instantiation.
 
+# Where is your own DSL?
+
+All respectable makers or config managers have their own **DSL**, all those `knife`-s, `cookbook`-s, `recipe`-s and other `cucumber`-s.
+
+The **PWSHAKE** is not an exception, but its **DSL** is based on simple concept of `templates:` and implemented via basic functionality of **PWSHAKE** engine: to read `yaml` configs, to compose `[hashtable]`-s from them and to execute `powershell:` commands.
+
+[See about our **DSL**](/pwshake/templates)
+
+
 # How to prepare **PWSHAKE** usage on Windows or Linux
 
 * Create a new working directory
@@ -95,16 +104,19 @@ tasks:
   hello:
   - powershell: Write-Host "Hello PWSHAKE!"
 includes: []
+templates: {}
 attributes_overrides: []
-scripts_directories: .
+scripts_directories:
+- .
+resources: []
 invoke_tasks: hello
 attributes:
   pwshake_module_path: /path/to/pwshake/module/source
   pwshake_path: /absolute/path/to/your/working/directory
-  pwshake_version: <current.pwshake.version>
+  pwshake_version: 1.4.0
   work_dir: /absolute/path/to/process/working/directory
-  hello: Hello PWSHAKE!
   pwshake_log_path: /absolute/path/to/your/working/directory/my_pwshake.log
+  some_attribute: this is an attribute value
 
 Arranged tasks:
 - when: $true
@@ -116,16 +128,15 @@ Arranged tasks:
 
 Invoke task: hello
 Execute step: step_66875131
-powershell: {Write-Host "Hello PWSHAKE!"}
 Hello PWSHAKE!
 ```
 ## Test **PWSHAKE** by itself
 
 Clone this repo, change current directory to the repo root folder.
 
-Start the `./tests/pwshake.Tests.ps1` script without any arguments passed:
+Start the bootstrapper `./pwshake.ps1` script without any arguments passed:
 ```
-PS>./tests/pwshake.Tests.ps1
+PS>./pwshake.ps1
 ```
 And it runs various tests and examples included in this repo.
 

doc/config.md

@@ -135,18 +135,21 @@
     [See more about `attributes_overrides:`](/doc/attributes_overrides.md)
 
 * ### **`resources:` element**
-    Optional
 
-    ```
-    resources:
-    - git:
-        repo: https://github.com/wild-devops/pwshake.git
-        ref: v1.0.0
-        sparses:
-        - examples
-        - doc
-        target: .old_repo
-    ```
-    Tells to **PWSHAKE** engine about the source(-s) of outer resources that should be loaded before the current execution starts.
-    
-    [See more about `resources:`](/doc/resources.md)
+  Alias: **`repositories:`**
+
+  Optional
+
+  ```
+  resources:
+  - git:
+      repo: https://github.com/wild-devops/pwshake.git
+      ref: v1.0.0
+      sparses:
+      - examples
+      - doc
+      target: .old_repo
+  ```
+  Tells to **PWSHAKE** engine about the source(-s) of outer resources that should be loaded before the current execution starts.
+  
+  [See more about `resources:`](/doc/resources.md)

doc/resources.md

@@ -2,6 +2,8 @@
 
 **Optional**
 
+Alias: **`repositories:`**
+
 Contains list of executable steps that all invoked before the current `yaml` config processing starts by the **PWSHAKE** engine.
 
 The results of these invokations can be used in the current `yaml` config file processing.

doc/templates.md

@@ -84,18 +84,36 @@ This tells to **PWSHAKE** engine how to substitute any structured `yaml` input i
     ...
     tasks:
       - cmd: 'dir /b'
+      - directory: .test_results
+      - each:
+          items:
+            - Hello
+            - PWSHAKE
+          action: echo $_
       - echo: 'Hello PWSHAKE!'
       - file:
           path: 'test.json'
           content: '{"I":"m","a":"test"}'
           encoding: Ascii # default is UTF8
       - git:
-          repo: https://github.com/wild-devops/pwshake.git
+          source: https://github.com/wild-devops/pwshake.git
           ref: v1.0.0
-          sparses:
-          - examples
-          - doc
+          directories:
+            - examples
+            - doc
           target: .old_repo
+      - if:
+          condition: true
+          then:
+            - echo: true
+          else:
+            - echo: false
+            - pwsh: throw 'Good bye!'
+      - invoke_steps:
+          - echo: List
+          - cmd: echo of
+          - pwsh: echo other
+          - shell: echo steps
       - invoke_tasks:
           - list_of
           - tasks_to_execute

examples/5.templates/v1.2/python_pwshake.yaml

@@ -3,14 +3,20 @@ includes:
 
 tasks:
   test_python_template:
-  - python:
+  - 'All defaults':
+      python:
   - 'Give me a version please':
       python: --version
+  - 'Inline python':
+      python:
+        inline: print('Hello pwshake!');
+  - 'Explicit file':
+      python:
+        options: '{{pwshake_path}}/hello.py again'
+  - 'Implicit file':
+      python: '{{pwshake_path}}/hello.py twice'
   - python:
       inline: print('Hello pwshake!');
-  - python:
-      file: '{{pwshake_path}}/hello.py again'
-  - python: '{{pwshake_path}}/hello.py twice'
 
 invoke_tasks:
 - test_python_template

examples/5.templates/v1.2/templates/python.yaml

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

examples/5.templates/v1.4/built_in_templates_override_pwshake.yaml

@@ -0,0 +1,19 @@
+templates:
+  echo:
+    text: '...'
+    color: DarkGreen # this is default
+    powershell: |
+      Write-Host (Coalesce $step.echo, $step.text) -ForegroundColor $step.color
+
+tasks:
+  print_me_in_green:
+  - echo: I'm not green
+  print_me_in_cyan:
+  - echo:
+  - echo:
+      text:  I'm not cyan
+      color: Cyan
+
+invoke_tasks:
+- print_me_in_green
+- print_me_in_cyan

examples/5.templates/v1.4/composed_templates.yaml

@@ -0,0 +1,35 @@
+includes:
+- templates/composed.yaml
+
+tasks:
+  test_composed_templates:
+  - 'dotnet versions':
+      steps:
+      - 'implicit version':
+          dotnet:
+      - 'inline command':
+          dotnet: --version
+      - 'explicit command':
+          dotnet:
+            command: --version
+      - 'explicit options':
+          dotnet:
+            options: --version
+      - 'explicit command and options':
+          dotnet:
+            command: msbuild
+            options: /version
+      - 'nested version':
+          dotnet_version:
+      - 'deep nested version':
+          msbuild_version:
+      - 'circular reference error':
+        on_error: continue
+        circular1:
+
+  test_all:
+    depends_on:
+    - test_composed_templates
+
+invoke_tasks:
+- test_all

examples/5.templates/v1.4/nested_and_composed_templates_pwshake.yaml

@@ -0,0 +1,31 @@
+includes:
+- nested_templates.yaml
+- composed_templates.yaml
+- templates/sparse-checkout.yaml
+
+tasks:
+  test_nested_composed_templates:
+  - 'Test each':
+      each:
+        items:
+        - one
+        - two
+        - three
+        action: echo $_
+  - 'Prepare sparse-checkout file':
+      sparse-checkout:
+      - examples
+      - doc
+      - tools
+  - 'Prepare other sparse-checkout file':
+      sparse-checkout:
+        directories:
+        - tests
+        - scripts
+
+  test_all:
+    depends_on:
+    - test_nested_composed_templates
+
+invoke_tasks:
+- test_all

examples/5.templates/v1.4/nested_templates.yaml

@@ -0,0 +1,33 @@
+includes:
+- templates/nested.yaml
+
+tasks:
+  test_nested_templates:
+  - 'implicit version':
+      dotnet:
+  - 'inline command':
+      dotnet: --version
+  - 'explicit command':
+      dotnet:
+        command: --version
+  - 'explicit options':
+      dotnet:
+        options: --version
+  - 'explicit command and options':
+      dotnet:
+        command: msbuild
+        options: /version
+  - 'nested version':
+      dotnet_version:
+  - 'deep nested version':
+      msbuild_version:
+  - 'circular reference error':
+    on_error: continue
+    circular1:
+
+  test_all:
+    depends_on:
+    - test_nested_templates
+
+invoke_tasks:
+- test_all

examples/5.templates/v1.4/templates/composed.yaml

@@ -0,0 +1,11 @@
+includes:
+- nested.yaml
+
+templates:
+  each:
+    powershell: |
+      (@() + $step.items) | ForEach-Object { Invoke-Expression $step.action }
+  steps:
+    each:
+      items: $[[$step.steps]]
+      action: Invoke-Step $config $_

examples/5.templates/v1.4/templates/nested.yaml

@@ -0,0 +1,20 @@
+templates:
+  dotnet:
+    command:
+    options:
+    powershell: |
+      & dotnet $(Coalesce $step.command, $step.dotnet, '') $(Coalesce $step.options, $step.dotnet, '--version')
+  dotnet_version:
+    dotnet: --version
+  msbuild_version:
+    dotnet_version:
+      command: msbuild
+      options: /version
+  circular1:
+    circular2:
+  circular2:
+    circular3:
+  circular3:
+    circular4:
+  circular4:
+    circular2:

examples/5.templates/v1.4/templates/sparse-checkout.yaml

@@ -0,0 +1,6 @@
+templates:
+  sparse-checkout:
+    powershell: |
+      foreach ($directory in (Coalesce $step.directories, $step['sparse-checkout'])) {
+        Invoke-Step $config @{echo=$directory}
+      }

examples/7.resources/v1.3/resources.yaml

@@ -0,0 +1,41 @@
+
+resources:
+- git:
+    repo: https://github.com/wild-devops/pwshake.git
+    ref: v1.0.0
+    sparses:
+    - examples
+    - doc
+    target: .old_repo
+
+templates:
+  git:
+    repo:
+    ref:
+    sparses:
+    target:
+    powershell: |
+      $target = Join-Path -Path $config.attributes.pwshake_path -ChildPath $step.target
+      if (Test-Path $target) {
+          Remove-Item -Path $target -Recurse -Force
+      }
+      New-Item -Path $target -ItemType Directory | Out-Null
+      try {
+        Push-Location $target
+        git init --quiet
+        & git remote add origin $($step.repo)
+        git fetch --quiet --tags --prune --no-progress --no-recurse-submodules origin +refs/heads/*:refs/remotes/origin/*
+        if ($step.sparses) {
+          git config core.sparsecheckout true
+          New-Item -Path .git/info/sparse-checkout -ItemType File | Out-Null
+          foreach ($folder in $step.sparses) {
+            Add-Content -path .git/info/sparse-checkout -value "/$folder" -Encoding Ascii -Force
+          }
+        }
+        & git checkout --quiet $($step.ref)
+      } finally {
+        Pop-Location
+      }
+
+includes:
+- .old_repo/examples/hello_pwshake.yaml