Add contains() and union() Array functions

Steve Lee (POWERSHELL HE/HIM) (from Dev Box) · Steve Lee (POWERSHELL HE/HIM) (from Dev Box) · commit bc5e1ae675b6 · 2025-07-24T14:43:52.000-07:00
diff --git a/dsc/tests/dsc_functions.tests.ps1 b/dsc/tests/dsc_functions.tests.ps1
@@ -62,4 +62,101 @@ Describe 'tests for function expressions' {
         $LASTEXITCODE | Should -Be 0
         $out.results[0].result.actualState.output | Should -BeExactly $expected
     }
+
+    It 'union function works for: <expression>' -TestCases @(
+        @{ expression = "[union(parameters('firstArray'), parameters('secondArray'))]"; expected = @('ab', 'cd', 'ef') }
+        @{ expression = "[union(parameters('firstObject'), parameters('secondObject'))]"; expected = [pscustomobject]@{ one = 'a'; two = 'c'; three = 'd' } }
+        @{ expression = "[union(parameters('secondArray'), parameters('secondArray'))]"; expected = @('cd', 'ef') }
+        @{ expression = "[union(parameters('secondObject'), parameters('secondObject'))]"; expected = [pscustomobject]@{ two = 'c'; three = 'd' } }
+        @{ expression = "[union(parameters('firstObject'), parameters('firstArray'))]"; isError = $true }
+    ) {
+        param($expression, $expected, $isError)
+
+        $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            parameters:
+              firstObject:
+                type: object
+                defaultValue:
+                  one: a
+                  two: b
+              secondObject:
+                type: object
+                defaultValue:
+                  two: c
+                  three: d
+              firstArray:
+                type: array
+                defaultValue:
+                - ab
+                - cd
+              secondArray:
+                type: array
+                defaultValue:
+                - cd
+                - ef
+            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
+        if ($isError) {
+            $LASTEXITCODE | Should -Be 2 -Because (Get-Content $TestDrive/error.log -Raw)
+            (Get-Content $TestDrive/error.log -Raw) | Should -Match 'All arguments must either be arrays or objects'
+        } else {
+            $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+            ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
+        }
+    }
+
+    It 'contain function works for: <expression>' -TestCases @(
+        @{ expression = "[contains(parameters('array'), 'a')]" ; expected = $true }
+        @{ expression = "[contains(parameters('array'), 2)]" ; expected = $false }
+        @{ expression = "[contains(parameters('array'), 1)]" ; expected = $true }
+        @{ expression = "[contains(parameters('object'), 'a')]" ; expected = $true }
+        @{ expression = "[contains(parameters('object'), 'c')]" ; expected = $false }
+        @{ expression = "[contains(parameters('object'), 3)]" ; expected = $true }
+        @{ expression = "[contains(parameters('object'), parameters('object'))]" ; isError = $true }
+        @{ expression = "[contains(parameters('array'), parameters('array'))]" ; isError = $true }
+        @{ expression = "[contains(parameters('string'), 'not found')]" ; expected = $false }
+        @{ expression = "[contains(parameters('string'), 'hello')]" ; expected = $true }
+        @{ expression = "[contains(parameters('string'), 12)]" ; expected = $true }
+    ) {
+        param($expression, $expected, $isError)
+
+        $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            parameters:
+              array:
+                type: array
+                defaultValue:
+                - a
+                - b
+                - 1
+              object:
+                type: object
+                defaultValue:
+                  a: 1
+                  b: 2
+                  3: c
+              string:
+                type: string
+                defaultValue: 'hello 123 world!'
+            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
+        if ($isError) {
+            $LASTEXITCODE | Should -Be 2 -Because (Get-Content $TestDrive/error.log -Raw)
+            (Get-Content $TestDrive/error.log -Raw) | Should -Match 'Invalid item to find, must be a string or number'
+        } else {
+            $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+            ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
+        }
+    }
 }
diff --git a/dsc_lib/locales/en-us.toml b/dsc_lib/locales/en-us.toml
@@ -229,6 +229,11 @@ argsMustBeStrings = "Arguments must all be strings"
 argsMustBeArrays = "Arguments must all be arrays"
 onlyArraysOfStrings = "Arguments must all be arrays of strings"
 
+[functions.contains]
+description = "Checks if an array contains a specific item"
+invoked = "contains function"
+invalidItemToFind = "Invalid item to find, must be a string or number"
+
 [functions.createArray]
 description = "Creates an array from the given elements"
 invoked = "createArray function"
@@ -361,6 +366,11 @@ invoked = "systemRoot function"
 description = "Returns the boolean value true"
 invoked = "true function"
 
+[functions.union]
+description = "Returns a single array or object with all elements from the parameters"
+invoked = "union function"
+invalidArgType = "All arguments must either be arrays or objects"
+
 [functions.variables]
 description = "Retrieves the value of a variable"
 invoked = "variables function"
diff --git a/dsc_lib/src/functions/contains.rs b/dsc_lib/src/functions/contains.rs
@@ -0,0 +1,115 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use crate::DscError;
+use crate::configure::context::Context;
+use crate::functions::{AcceptedArgKind, Function, FunctionCategory};
+use rust_i18n::t;
+use serde_json::Value;
+use tracing::debug;
+
+#[derive(Debug, Default)]
+pub struct Contains {}
+
+impl Function for Contains {
+    fn description(&self) -> String {
+        t!("functions.contains.description").to_string()
+    }
+
+    fn category(&self) -> FunctionCategory {
+        FunctionCategory::Array
+    }
+
+    fn min_args(&self) -> usize {
+        2
+    }
+
+    fn max_args(&self) -> usize {
+        usize::MAX
+    }
+
+    fn accepted_arg_types(&self) -> Vec<AcceptedArgKind> {
+        vec![AcceptedArgKind::Array, AcceptedArgKind::Object, AcceptedArgKind::String, AcceptedArgKind::Number]
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.contains.invoked"));
+        let mut found = false;
+
+        let (string_to_find, number_to_find) = if let Some(string) = args[1].as_str() {
+            (string.to_string(), 0)
+        } else if let Some(number) = args[1].as_i64() {
+            (number.to_string(), number)
+        } else {
+            return Err(DscError::Parser(t!("functions.contains.invalidItemToFind").to_string()));
+        };
+
+        // for array, we check if the string or number exists
+        if let Some(array) = args[0].as_array() {
+            for item in array {
+                if let Some(item_str) = item.as_str() {
+                    if item_str == string_to_find {
+                        found = true;
+                        break;
+                    }
+                } else if let Some(item_num) = item.as_i64() {
+                    if item_num == number_to_find {
+                        found = true;
+                        break;
+                    }
+                }
+            }
+            return Ok(Value::Bool(found));
+        }
+
+        // for object, we check if the key exists
+        if let Some(object) = args[0].as_object() {
+            // see if key exists
+            for key in object.keys() {
+                if key == &string_to_find {
+                    found = true;
+                    break;
+                }
+            }
+            return Ok(Value::Bool(found));
+        }
+
+        // for string, we check if the string contains the substring or number
+        if let Some(str) = args[0].as_str() {
+            if str.contains(&string_to_find) {
+                found = true;
+            }
+            return Ok(Value::Bool(found));
+        }
+
+        Err(DscError::Parser(t!("functions.contains.invalidArgType").to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::configure::context::Context;
+    use crate::parser::Statement;
+
+    #[test]
+    fn string_contains_string() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[contains('hello', 'lo')]", &Context::new()).unwrap();
+        assert_eq!(result, true);
+    }
+
+    #[test]
+    fn string_does_not_contain_string() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[contains('hello', 'world')]", &Context::new()).unwrap();
+        assert_eq!(result, false);
+    }
+
+    #[test]
+    fn string_contains_number() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[contains('hello123', 123)]", &Context::new()).unwrap();
+        assert_eq!(result, true);
+    }
+}
+
diff --git a/dsc_lib/src/functions/mod.rs b/dsc_lib/src/functions/mod.rs
@@ -16,6 +16,7 @@ pub mod and;
 pub mod base64;
 pub mod bool;
 pub mod concat;
+pub mod contains;
 pub mod create_array;
 pub mod div;
 pub mod envvar;
@@ -42,6 +43,7 @@ pub mod secret;
 pub mod sub;
 pub mod system_root;
 pub mod r#true;
+pub mod union;
 pub mod variables;
 
 /// The kind of argument that a function accepts.
@@ -91,6 +93,7 @@ impl FunctionDispatcher {
         functions.insert("base64".to_string(), Box::new(base64::Base64{}));
         functions.insert("bool".to_string(), Box::new(bool::Bool{}));
         functions.insert("concat".to_string(), Box::new(concat::Concat{}));
+        functions.insert("contains".to_string(), Box::new(contains::Contains{}));
         functions.insert("createArray".to_string(), Box::new(create_array::CreateArray{}));
         functions.insert("div".to_string(), Box::new(div::Div{}));
         functions.insert("envvar".to_string(), Box::new(envvar::Envvar{}));
@@ -117,6 +120,7 @@ impl FunctionDispatcher {
         functions.insert("sub".to_string(), Box::new(sub::Sub{}));
         functions.insert("systemRoot".to_string(), Box::new(system_root::SystemRoot{}));
         functions.insert("true".to_string(), Box::new(r#true::True{}));
+        functions.insert("union".to_string(), Box::new(union::Union{}));
         functions.insert("variables".to_string(), Box::new(variables::Variables{}));
         Self {
             functions,
diff --git a/dsc_lib/src/functions/union.rs b/dsc_lib/src/functions/union.rs
@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use crate::DscError;
+use crate::configure::context::Context;
+use crate::functions::{AcceptedArgKind, Function, FunctionCategory};
+use rust_i18n::t;
+use serde_json::{Map, Value};
+use tracing::debug;
+
+#[derive(Debug, Default)]
+pub struct Union {}
+
+impl Function for Union {
+    fn description(&self) -> String {
+        t!("functions.union.description").to_string()
+    }
+
+    fn category(&self) -> FunctionCategory {
+        FunctionCategory::Array
+    }
+
+    fn min_args(&self) -> usize {
+        2
+    }
+
+    fn max_args(&self) -> usize {
+        usize::MAX
+    }
+
+    fn accepted_arg_types(&self) -> Vec<AcceptedArgKind> {
+        vec![AcceptedArgKind::Array, AcceptedArgKind::Object]
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.union.invoked"));
+        if args[0].is_array() {
+            let mut result = Vec::new();
+            // iterate through array and skip elements that are already in result
+            for arg in args {
+                if let Some(array) = arg.as_array() {
+                    for item in array {
+                        if !result.contains(item) {
+                            result.push(item.clone());
+                        }
+                    }
+                } else {
+                    return Err(DscError::Parser(t!("functions.union.invalidArgType").to_string()));
+                }
+            }
+            return Ok(Value::Array(result));
+        }
+
+        if args[0].is_object() {
+            let mut result = Map::new();
+            // iterate through objects, duplicate keys are overwritten
+            for arg in args {
+                if let Some(object) = arg.as_object() {
+                    for (key, value) in object {
+                        result.insert(key.clone(), value.clone());
+                    }
+                } else {
+                    return Err(DscError::Parser(t!("functions.union.invalidArgType").to_string()));
+                }
+            }
+            return Ok(Value::Object(result));
+        }
+
+        Err(DscError::Parser(t!("functions.union.invalidArgType").to_string()))
+    }
+}
