Added initial function support microsoft#1227 (microsoft#1228)

.vscode/settings.json

@@ -58,6 +58,18 @@
         ],
         "files.insertFinalNewline": true
     },
+    "[jsonc]": {
+        "editor.tabSize": 4,
+        "editor.tabCompletion": "on",
+        "editor.quickSuggestions": {
+            "strings": true
+        },
+        "editor.suggest.insertMode": "replace",
+        "gitlens.codeLens.scopes": [
+            "document"
+        ],
+        "files.insertFinalNewline": true
+    },
     "files.associations": {
         "**/.azure-pipelines/*.yaml": "azure-pipelines",
         "**/.azure-pipelines/jobs/*.yaml": "azure-pipelines",
@@ -67,6 +79,7 @@
         "APPSERVICEMININSTANCECOUNT",
         "cmdlet",
         "cmdlets",
+        "concat",
         "datetime",
         "deserialize",
         "deserialized",

docs/CHANGELOG-v2.md

@@ -11,8 +11,21 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
   [2]: https://microsoft.github.io/PSRule/latest/deprecations/#deprecations-for-v3
 
+**Experimental features**:
+
+- Functions within YAML expressions can be used to perform manipulation prior to testing a condition.
+
 ## Unreleased
 
+What's changed since pre-release v2.4.0-B0022:
+
+- New features:
+  - **Experimental**: Added support for functions within YAML and JSON expressions.
+    [#1227](https://github.com/microsoft/PSRule/issues/1227)
+    - Added conversion functions `boolean`, `string`, and `integer`.
+    - Added lookup functions `configuration`, and `path`.
+    - Added string functions `concat`, `substring`.
+
 ## v2.4.0-B0022 (pre-release)
 
 What's changed since pre-release v2.4.0-B0009:

docs/expressions/functions.md

@@ -0,0 +1,127 @@
+# Expression functions
+
+!!! Abstract
+    Functions are an advanced lanaguage feature specific to YAML and JSON resources.
+    That extend the language to allow for more complex use cases with expressions.
+
+!!! Experimental
+    Functions are a work in progress and subject to change.
+    We hope to add more functions, broader support, and more detailed documentation in the future.
+    [Join or start a disucssion][1] to let us know how we can improve this feature going forward.
+
+  [1]: https://github.com/microsoft/PSRule/discussions
+
+## Using functions
+
+It may be necessary to perform minor transformation before evaluating a condition.
+
+- `boolean` - Convert a value to a boolean.
+- `string` - Convert a value to a string.
+- `integer` - Convert a value to an integer.
+- `concat` - Concatenate multiple values.
+- `substring` - Extract a substring from a string.
+- `configuration` - Get a configuration value.
+- `path` - Get a value from an object path.
+
+## Supported conditions
+
+Currently functions are only supported on a subset of conditions.
+The conditions that are supported are:
+
+- `equals`
+- `notEquals`
+- `count`
+- `less`
+- `lessOrEquals`
+- `greater`
+- `greaterOrEquals`
+
+## Examples
+
+```yaml
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example1
+spec:
+  if:
+    value:
+      $:
+        substring:
+          path: name
+        length: 7
+    equals: TestObj
+
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example2
+spec:
+  if:
+    value:
+      $:
+        configuration: 'ConfigArray'
+    count: 5
+
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example3
+spec:
+  if:
+    value:
+      $:
+        boolean: true
+    equals: true
+
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example4
+spec:
+  if:
+    value:
+      $:
+        concat:
+        - path: name
+        - string: '-'
+        - path: name
+    equals: TestObject1-TestObject1
+
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example5
+spec:
+  if:
+    value:
+      $:
+        integer: 6
+    greater: 5
+
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example6
+spec:
+  if:
+    value: TestObject1-TestObject1
+    equals:
+      $:
+        concat:
+        - path: name
+        - string: '-'
+        - path: name
+```

docs/specs/function-spec.md

@@ -0,0 +1,34 @@
+# PSRule function expressions spec (draft)
+
+This is a spec for implementing function expressions in PSRule v2.
+
+## Synopsis
+
+Functions are available to handle complex conditions within YAML and JSON expressions.
+
+## Schema driven
+
+While functions allow handing for complex use cases, they should still remain schema driven.
+A schema driven design allows auto-completion and validation during authoring in a broad set of tools.
+
+## Syntax
+
+Functions can be used within YAML and JSON expressions by using the `$` object property.
+For example:
+
+```yaml
+---
+# Synopsis: An expression function example.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: Yaml.Fn.Example1
+spec:
+  if:
+    value:
+      $:
+        substring:
+          path: name
+        length: 3
+    equals: abc
+```

mkdocs.yml

@@ -55,6 +55,8 @@ nav:
       - Azure resource tagging example: scenarios/azure-tags/azure-tags.md
       - Kubernetes resource validation example: scenarios/kubernetes-resources/kubernetes-resources.md
     - Concepts:
+      - Expressions:
+        - Functions: expressions/functions.md
       - Using within continuous integration: scenarios/validation-pipeline/validation-pipeline.md
     # - Troubleshooting: troubleshooting.md
     - License and contributing: license-contributing.md