Merge branches 'gh-57/main/add-base64string-function' and 'main' of https://github.com/Gijsreyn/operation-methods into gh-57/main/add-base64string-function

Author: Gijsreyn

docs/concepts/resources/capabilities.md

@@ -76,7 +76,7 @@ resource. DSC performs the synthetic test by:
 1. Invoking the **Get** operation on the resource to retrieve the actual state of the instance.
 1. Synthetically testing each property for the desired state of an instance against the actual
    state returned. The synthetic test:
-   
+
    - Uses strict, case-sensitive equivalence for strings.
    - Uses simple equivalence for numerical, boolean, and null values.
    - For arrays, item order doesn't matter. Arrays are considered equivalent if both the desired
@@ -134,32 +134,59 @@ manifest.
 A resource with the `export` capability supports enumerating every instance of the resource with
 the **Export** operation.
 
-You can use resources with this capability with the following commands:
+You can use resources with the `export` capability with the following commands:
 
-- [dsc config export][15] to return a configuration document
-  representing the actual state for every instance of each resource defined in the input document.
-- [dsc resource export][16] to return a configuration document
-  representing the actual state for every instance of the input resource.
-- `dsc resource get` with the [--all][17] option to return
-  the actual state of every instance of the input resource.
+- [dsc config export][15] to return a configuration document representing the actual state for
+  every instance of each resource defined in the input document.
+- [dsc resource export][16] to return a configuration document representing the actual state for
+  every instance of the input resource.
+- `dsc resource get` with the [--all][17] option to return the actual state of every instance of
+  the input resource.
 
 A command resource has this capability when it defines the [export][18] property in its resource
 manifest.
 
+### Synthetic export
+
+When a resource doesn't have the `export` capability, DSC uses a synthetic export for instances of
+the resource. DSC performs the synthetic export by:
+
+1. Invoking the **Get** operation on the resource to retrieve the actual state of the instance.
+
+   Unlike non-synthetic export operations, users _must_ provide a filter for the resource if the
+   resource instance JSON schema defines any [required properties][19].
+1. Exporting an instance of the resource with:
+
+   - The `properties` field populated by the actual state returned by the **Get** operation.
+   - The `name` field populated by a string with the format `<short-type-name>-0`. The
+     `<short-type-name>` is the last segment of the resource type name, like `Registry` for
+     `Microsoft.Windows/Registry`.
+
+Synthetic export only ever returns a single instance and always requires a filtering instance. You
+can use resources that rely on synthetic exporting with the following commands:
+
+- [dsc config export][15] to return a configuration document representing the actual state for
+  every instance of each resource defined in the input document. For resources that rely on
+  synthetic export, you _must_ define a filtering instance in the input document. The resource
+  can only export a single instance per filtering instance.
+- [dsc resource export][16] to return a configuration document representing the actual state for
+  the required filtering instance. If you invoke this command without providing a filtering
+  instance, the operation fails.
+
 ## resolve
 
 A resource with the `resolve` capability supports resolving nested resource instances from an
-external source. This capability is primarily used by [importer resources][19] to enable users to
+external source. This capability is primarily used by [importer resources][20] to enable users to
 compose configuration documents.
 
-A command resource has this capability when it defines the [resolve][20] property in its resource
+A command resource has this capability when it defines the [resolve][21] property in its resource
 manifest.
 
 ## See also
 
-- [DSC resource operations][21]
-- [DSC resource kinds][22]
-- [DSC resource properties][23]
+- [DSC resource operations][22]
+- [DSC resource kinds][23]
+- [DSC resource properties][24]
 
 <!-- Link reference definitions -->
 [01]: operations.md#get-operation
@@ -180,8 +207,9 @@ manifest.
 [16]: ../../reference/cli/resource/export.md
 [17]: ../../reference/cli/resource/get.md#--all
 [18]: ../../reference/schemas/resource/manifest/export.md
-[19]: ../resources/kinds.md#importer-resources
-[20]: ../../reference/schemas/resource/manifest/resolve.md
-[21]: operations.md
-[22]: kinds.md
-[23]: ../../concepts/resources/properties.md
+[19]: ./properties.md#required-resource-properties
+[20]: ../resources/kinds.md#importer-resources
+[21]: ../../reference/schemas/resource/manifest/resolve.md
+[22]: operations.md
+[23]: kinds.md
+[24]: ../../concepts/resources/properties.md

docs/concepts/resources/operations.md

@@ -67,7 +67,8 @@ DSC invokes the **Delete** operation when you use the following commands:
 The **Export** operation retrieves the actual state for every instance of the resource on a system.
 The result is a configuration document that includes the exported instances.
 
-This operation is only available for resources with the [export capability][05].
+If a resource doesn't have the [`export` capability][05], DSC synthetically exports the resource.
+For more information, see [Synthetic export][06].
 
 DSC invokes the **Export** operation when you use the following commands:
 
@@ -83,7 +84,7 @@ DSC invokes the **Export** operation when you use the following commands:
 The **List** operation retrieves the available adapted resources for a specific DSC adapter
 resource.
 
-This operation is only available for [adapter resources][06].
+This operation is only available for [adapter resources][07].
 
 ## Validate operation
 
@@ -101,26 +102,27 @@ invoke an adapted resource.
 The **Resolve** operation processes an importer resource instance to return a configuration
 document.
 
-This operation is only available for resources with the [resolve capability][07]. This operation
-is primarily useful for [importer resources][08].
+This operation is only available for resources with the [resolve capability][08]. This operation
+is primarily useful for [importer resources][09].
 
 ## See also
 
-- [DSC resource capabilities][09]
-- [DSC resource kinds][10]
-- [DSC resource properties][11]
-- [DSC command reference][12]
+- [DSC resource capabilities][10]
+- [DSC resource kinds][11]
+- [DSC resource properties][12]
+- [DSC command reference][13]
 
 <!-- Link reference definitions -->
 [01]: ./capabilities.md#get
 [02]: ./capabilities.md#test
 [03]: ./capabilities.md#set
 [04]: ./capabilities.md#delete
 [05]: ./capabilities.md#export
-[06]: ./kinds.md#adapter-resources
-[07]: ./capabilities.md#resolve
-[08]: ./kinds.md#importer-resources
-[09]: ./capabilities.md
-[10]: ./kinds.md
-[11]: ./properties.md
-[12]: ../../reference/cli/index.md
+[06]: ./capabilities.md#synthetic-export
+[07]: ./kinds.md#adapter-resources
+[08]: ./capabilities.md#resolve
+[09]: ./kinds.md#importer-resources
+[10]: ./capabilities.md
+[11]: ./kinds.md
+[12]: ./properties.md
+[13]: ../../reference/cli/index.md

docs/concepts/resources/overview.md

@@ -264,6 +264,12 @@ Use the `dsc resource export` command to invoke the operation. When you invoke t
 operation, DSC returns an array of resources instance definitions you can copy into a configuration
 document.
 
+You can specify an input instance for the **Export** operation to filter the exported instances. If
+a resource doesn't implement **Export**, you can still invoke the `dsc resource export` command.
+When you invoke the **Export** operation for a resource that doesn't implement **Export**, DSC
+provides a _synthetic export_. When using DSC's synthetic export feature, you must provide a
+filtering instance of the resource. For more information, see [Synthetic export][04].
+
 ## Declaring resource instances
 
 DSC configuration documents enable managing more than one resource or resource instance at a time.
@@ -298,14 +304,15 @@ resources:
 
 ## See also
 
-- [Anatomy of a DSC command resource][04] to learn about authoring resources in your language
+- [Anatomy of a DSC command resource][05] to learn about authoring resources in your language
   of choice.
-- [DSC configuration documents][05] to learn about using resources in a configuration document.
-- [Command line reference for the 'dsc resource' command][06]
+- [DSC configuration documents][06] to learn about using resources in a configuration document.
+- [Command line reference for the 'dsc resource' command][07]
 
 [01]: ../../reference/schemas/definitions/resourceType.md
 [02]: ../../reference/schemas/resource/properties/overview.md
 [03]: ../../reference/cli/resource/list.md
-[04]: ./anatomy.md
-[05]: ../configuration-documents/overview.md
-[06]: ../../reference/cli/resource/index.md
+[04]: capabilities.md#synthetic-export
+[05]: ./anatomy.md
+[06]: ../configuration-documents/overview.md
+[07]: ../../reference/cli/resource/index.md

dsc/tests/dsc_functions.tests.ps1

@@ -120,7 +120,7 @@ Describe 'tests for function expressions' {
     @{ expression = "[intersection(parameters('firstObject'), parameters('firstArray'))]"; isError = $true }
     @{ expression = "[intersection(parameters('firstArray'), parameters('secondArray'), parameters('fifthArray'))]"; expected = @('cd') }
     @{ expression = "[intersection(parameters('firstObject'), parameters('secondObject'), parameters('sixthObject'))]"; expected = [pscustomobject]@{ two = 'b' } }
-    @{ expression = "[intersection(parameters('nestedObject1'), parameters('nestedObject2'))]"; expected = [pscustomobject]@{ 
+    @{ expression = "[intersection(parameters('nestedObject1'), parameters('nestedObject2'))]"; expected = [pscustomobject]@{
       shared = [pscustomobject]@{ value = 42; flag = $true }
       level = 1
     } }
@@ -711,13 +711,34 @@ Describe 'tests for function expressions' {
               properties:
                 output: `"$expression`"
 "@
-    $out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log
+    $null = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log
     $LASTEXITCODE | Should -Not -Be 0
     $errorContent = Get-Content $TestDrive/error.log -Raw
     $errorContent | Should -Match ([regex]::Escape($expectedError))
   }
 
-  It 'base64ToString function works for: <expression>' -TestCases @(
+  It 'mixed booleans with functions works' -TestCases @(
+    @{ expression = "[and(true(), false, not(false))]"; expected = $false }
+    @{ expression = "[or(false, false(), not(false()))]"; expected = $true }
+    @{ expression = "[and(true(), true, not(false))]"; expected = $true }
+    @{ expression = "[or(false, false(), not(true()))]"; expected = $false }
+  ) {
+    param($expression, $expected)
+
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: "$expression"
+"@
+    $out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log | ConvertFrom-Json
+    $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+    $out.results[0].result.actualState.output | Should -BeExactly $expected
+  }
+
+    It 'base64ToString function works for: <expression>' -TestCases @(
     @{ expression = "[base64ToString('aGVsbG8gd29ybGQ=')]"; expected = 'hello world' }
     @{ expression = "[base64ToString('')]"; expected = '' }
     @{ expression = "[base64ToString('aMOpbGxv')]"; expected = 'héllo' }

dsc_lib/src/functions/concat.rs

@@ -16,7 +16,7 @@ impl Function for Concat {
         FunctionMetadata {
             name: "concat".to_string(),
             description: t!("functions.concat.description").to_string(),
-            category: vec![FunctionCategory::String, FunctionCategory::Array],
+            category: vec![FunctionCategory::Array, FunctionCategory::String],
             min_args: 2,
             max_args: usize::MAX,
             accepted_arg_ordered_types: vec![

dsc_lib/src/functions/contains.rs

@@ -16,7 +16,7 @@ impl Function for Contains {
         FunctionMetadata {
             name: "contains".to_string(),
             description: t!("functions.contains.description").to_string(),
-            category: vec![FunctionCategory::String, FunctionCategory::Array],
+            category: vec![FunctionCategory::Array, FunctionCategory::String],
             min_args: 2,
             max_args: 2,
             accepted_arg_ordered_types: vec![

tree-sitter-dscexpression/grammar.js

@@ -1,6 +1,8 @@
 const PREC = {
   ESCAPEDSTRING: 2,
   EXPRESSIONSTRING: 1,
+  FUNCTION: 1,
+  BOOLEAN: 0,
   STRINGLITERAL: -11,
 }
 
@@ -20,16 +22,20 @@ module.exports = grammar({
     expression: $ => seq(field('function', $.function), optional(field('accessor',$.accessor))),
     stringLiteral: $ => token(prec(PREC.STRINGLITERAL, /[^\[](.|\n)*?/)),
 
-    function: $ => seq(field('name', $.functionName), '(', field('args', optional($.arguments)), ')'),
-    functionName: $ => /[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)?/,
+    function: $ => prec(PREC.FUNCTION, seq(field('name', $.functionName), '(', field('args', optional($.arguments)), ')')),
+    functionName: $ => choice(
+      /[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)?/,
+      $._booleanLiteral
+    ),
     arguments: $ => seq($._argument, repeat(seq(',', $._argument))),
     _argument: $ => choice($.expression, $._quotedString, $.number, $.boolean),
 
     _quotedString: $ => seq('\'', $.string, '\''),
     // ARM strings are not allowed to contain single-quote characters unless escaped
     string: $ => /([^']|''|\n)*/,
     number: $ => /-?\d+/,
-    boolean: $ => choice('true', 'false'),
+    boolean: $ => prec(PREC.BOOLEAN, $._booleanLiteral),
+    _booleanLiteral: $ => choice('true', 'false'),
 
     accessor: $ => repeat1(choice($.memberAccess, $.index)),
 

tree-sitter-dscexpression/test/corpus/invalid_expressions.txt

@@ -18,7 +18,6 @@ String parameter not in quotes
         (function
           (functionName)
           (ERROR
-            (functionName)
             (functionName)))))
 
 =====
@@ -79,8 +78,6 @@ String starting with bracket
 ---
 
     (ERROR
-      (ERROR
-        (functionName))
       (functionName))
 
 =====
@@ -179,8 +176,7 @@ Expression with member accessor outside
           (functionName)
           (arguments
             (number))))
-      (ERROR
-        (functionName)))
+      (ERROR))
 
 =====
 Expression with index accessor outside
@@ -209,6 +205,4 @@ String with un-escaped single-quote
           (functionName)
           (arguments
             (string))
-          (ERROR
-            (functionName)
-            (functionName)))))
+          (ERROR))))

tree-sitter-dscexpression/test/corpus/valid_expressions.txt

@@ -34,7 +34,7 @@ Simple expression
 =====
 Multiple arguments
 =====
-[myFunction('argString', 1, -1, true)]
+[myFunction('argString', 1, -1, true, false)]
 ---
 
 (statement
@@ -45,6 +45,7 @@ Multiple arguments
         (string)
         (number)
         (number)
+        (boolean)
         (boolean)))))
 
 =====
@@ -335,3 +336,19 @@ User Function
       (arguments
         (number)
         (number)))))
+
+=====
+User Function with nested function
+=====
+[Environment.getEnvironmentConfig(true(), false)]
+---
+
+(statement
+      (expression
+        (function
+          (functionName)
+          (arguments
+            (expression
+              (function
+                (functionName)))
+            (boolean)))))