Add tryGet() function

Author: SteveL-MSFT

dsc/tests/dsc_functions.tests.ps1

@@ -901,4 +901,33 @@ Describe 'tests for function expressions' {
     $out = $config_yaml | dsc config get -f - | ConvertFrom-Json
     $out.results[0].result.actualState.output | Should -Be $expected
   }
+
+  It 'tryGet() function works for: <expression>' -TestCases @(
+    @{ expression = "[tryGet(createObject('a', 1, 'b', 2), 'a')]"; expected = 1 }
+    @{ expression = "[tryGet(createObject('a', 1, 'b', 2), 'c')]"; expected = $null }
+    @{ expression = "[tryGet(createObject('key', 'value'), 'key')]"; expected = 'value' }
+    @{ expression = "[tryGet(createObject('nested', createObject('x', 10)), 'nested')]"; expected = [pscustomobject]@{ x = 10 } }
+    @{ expression = "[tryGet(createObject('nested', createObject('x', 10)), 'missing')]"; expected = $null }
+    @{ expression = "[tryGet(createArray(1,2,3), 0)]"; expected = 1 }
+    @{ expression = "[tryGet(createArray(1,2,3), 3)]"; expected = $null }
+    @{ expression = "[tryGet(createArray(1,2,3), -3)]"; expected = $null }
+  ) {
+    param($expression, $expected)
+
+    $escapedExpression = $expression -replace "'", "''"
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: '$escapedExpression'
+"@
+    $out = $config_yaml | dsc config get -f - | ConvertFrom-Json
+    if ($expected -is [pscustomobject]) {
+      ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
+    } else {
+      $out.results[0].result.actualState.output | Should -BeExactly $expected
+    }
+  }
 }

lib/dsc-lib/locales/en-us.toml

@@ -523,6 +523,12 @@ description = "Removes all leading and trailing white-space characters from the
 description = "Returns the boolean value true"
 invoked = "true function"
 
+[functions.tryGet]
+description = "Attempts to retrieve a value from an array (by index) or object (by key).  Null is returned if the key or index does not exist."
+invoked = "tryGet function"
+invalidKeyType = "Invalid key type, must be a string"
+invalidIndexType = "Invalid index type, must be an integer"
+
 [functions.union]
 description = "Returns a single array or object with all elements from the parameters"
 invoked = "union function"

lib/dsc-lib/src/functions/mod.rs

@@ -68,6 +68,7 @@ pub mod to_lower;
 pub mod to_upper;
 pub mod trim;
 pub mod r#true;
+pub mod try_get;
 pub mod union;
 pub mod unique_string;
 pub mod user_function;
@@ -191,6 +192,7 @@ impl FunctionDispatcher {
             Box::new(to_upper::ToUpper{}),
             Box::new(trim::Trim{}),
             Box::new(r#true::True{}),
+            Box::new(try_get::TryGet{}),
             Box::new(utc_now::UtcNow{}),
             Box::new(union::Union{}),
             Box::new(unique_string::UniqueString{}),

lib/dsc-lib/src/functions/try_get.rs

@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use crate::DscError;
+use crate::configure::context::Context;
+use crate::functions::{FunctionArgKind, Function, FunctionCategory, FunctionMetadata};
+use rust_i18n::t;
+use serde_json::Value;
+use tracing::debug;
+
+#[derive(Debug, Default)]
+pub struct TryGet {}
+
+impl Function for TryGet {
+    fn get_metadata(&self) -> FunctionMetadata {
+        FunctionMetadata {
+            name: "tryGet".to_string(),
+            description: t!("functions.tryGet.description").to_string(),
+            category: vec![FunctionCategory::Logical],
+            min_args: 2,
+            max_args: 2,
+            accepted_arg_ordered_types: vec![
+                vec![FunctionArgKind::Array, FunctionArgKind::Object],
+                vec![FunctionArgKind::Number, FunctionArgKind::String],
+            ],
+            remaining_arg_accepted_types: None,
+            return_types: vec![FunctionArgKind::Array, FunctionArgKind::Boolean, FunctionArgKind::Null, FunctionArgKind::Number, FunctionArgKind::Object, FunctionArgKind::String],
+        }
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.tryGet.invoked"));
+
+        if let Some(object) = args[0].as_object() {
+            if let Some(key) = args[1].as_str() {
+                if let Some(value) = object.get(key) {
+                    return Ok(value.clone());
+                }
+                return Ok(Value::Null);
+            }
+            return Err(DscError::Parser(t!("functions.tryGet.invalidKeyType").to_string()));
+        }
+
+        if let Some(array) = args[0].as_array() {
+            if let Some(index) = args[1].as_i64() {
+                let Ok(index) = usize::try_from(index) else {
+                    // handle negative index
+                    return Ok(Value::Null);
+                };
+                let index = if index >= array.len() {
+                    return Ok(Value::Null);
+                } else {
+                    index
+                };
+                return Ok(array[index].clone());
+            }
+            return Err(DscError::Parser(t!("functions.tryGet.invalidIndexType").to_string()));
+        }
+
+        Err(DscError::Parser(t!("functions.invalidArgType").to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::configure::context::Context;
+    use crate::parser::Statement;
+
+    #[test]
+    fn try_get_object() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createObject('key1', 'value1'), 'key1')]", &Context::new()).unwrap();
+        assert_eq!(result, serde_json::json!(["value1"]));
+    }
+
+    #[test]
+    fn try_get_object_not_found() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createObject('key1', 'value1'), 'key2')]", &Context::new()).unwrap();
+        assert_eq!(result, serde_json::json!([null]));
+    }
+
+    #[test]
+    fn try_get_array() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createArray('value1', 'value2'), 1)]", &Context::new()).unwrap();
+        assert_eq!(result, serde_json::json!(["value2"]));
+    }
+
+    #[test]
+    fn try_get_array_negative_index() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createArray('value1', 'value2'), -1)]", &Context::new()).unwrap();
+        assert_eq!(result, serde_json::json!(["value2"]));
+    }
+
+    #[test]
+    fn try_get_array_index_not_found() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createArray('value1', 'value2'), 2)]", &Context::new()).unwrap();
+        assert_eq!(result, serde_json::json!([null]));
+    }
+
+    #[test]
+    fn try_get_object_invalid_key_type() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createObject('key1', 'value1'), 1)]", &Context::new());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn try_get_array_invalid_index_type() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[tryGet(createArray('value1', 'value2'), '1')]", &Context::new());
+        assert!(result.is_err());
+    }
+}