Merge pull request #1085 from Gijsreyn/add-skip-function

Add skip() function

Author: SteveL-MSFT

docs/reference/schemas/config/functions/skip.md

@@ -0,0 +1,147 @@
+---
+description: Reference for the 'skip' DSC configuration document function
+ms.date:     08/29/2025
+ms.topic:    reference
+title:       skip
+---
+
+## Synopsis
+
+Returns an array with all the elements after the specified number in the array,
+or returns a string with all the characters after the specified number in the
+string.
+
+## Syntax
+
+```Syntax
+skip(<originalValue>, <numberToSkip>)
+```
+
+## Description
+
+The `skip()` function returns the tail of an array or string by skipping a
+specified number of items from the start.
+
+- For arrays: returns a new array containing elements after the specified index
+- For strings: returns a new string containing characters after the specified index
+
+Both parameters are required. `originalValue` must be an array or a string.
+`numberToSkip` must be an integer; negative values are treated as zero. If the
+number is greater than the length of the array or string, the function returns
+an empty array or an empty string respectively.
+
+## Examples
+
+### Example 1 - Skip elements in an array
+
+The following example returns the tail of an array by skipping the first two
+elements.
+
+```yaml
+# skip.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Tail of array
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      tail: "[skip(createArray('a','b','c','d'), 2)]"
+```
+
+```bash
+dsc config get --file skip.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Tail of array
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        tail:
+        - c
+        - d
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Skip characters in a string
+
+The following example returns the substring of a string by skipping the first
+two characters.
+
+```yaml
+# skip.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Tail of string
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      tail: "[skip('hello', 2)]"
+```
+
+```bash
+dsc config get --file skip.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Tail of string
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        tail: llo
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### originalValue
+
+The value to skip items from. Can be an array or a string.
+
+```yaml
+Type:     array | string
+Required: true
+Position: 1
+```
+
+### numberToSkip
+
+The number of items to skip from the start. Must be an integer. Negative values
+are treated as zero.
+
+```yaml
+Type:     int
+Required: true
+Position: 2
+```
+
+## Output
+
+Returns the same type as `originalValue`:
+
+- If `originalValue` is an array, returns an array
+- If `originalValue` is a string, returns a string
+
+```yaml
+Type: array | string
+```
+
+## Error conditions
+
+- `originalValue` is not an array or string
+- `numberToSkip` is not an integer
+
+## Related functions
+
+- [`first()`][00] - Returns the first element or character
+- [`length()`][01] - Returns the number of elements or characters
+
+<!-- Link reference definitions -->
+[00]: ./first.md
+[01]: ./length.md

dsc/tests/dsc_functions.tests.ps1

@@ -409,6 +409,32 @@ Describe 'tests for function expressions' {
     ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
   }
 
+  It 'skip function works for: <expression>' -TestCases @(
+    @{ expression = "[skip(createArray('a','b','c','d'), 2)]"; expected = @('c','d') }
+    @{ expression = "[skip('hello', 2)]"; expected = 'llo' }
+    @{ expression = "[skip(createArray('a','b'), 0)]"; expected = @('a','b') }
+    @{ expression = "[skip('abc', 0)]"; expected = 'abc' }
+    @{ expression = "[skip(createArray('a','b'), 5)]"; expected = @() }
+    @{ expression = "[skip('', 1)]"; expected = '' }
+    # Negative counts are treated as zero
+    @{ expression = "[skip(createArray('x','y'), -3)]"; expected = @('x','y') }
+    @{ expression = "[skip('xy', -1)]"; expected = 'xy' }
+  ) {
+    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 | Out-String) | Should -BeExactly ($expected | Out-String)
+  }
+
   It 'lastIndexOf function works for: <expression>' -TestCases @(
     @{ expression = "[lastIndexOf(createArray('a', 'b', 'a', 'c'), 'a')]"; expected = 2 }
     @{ expression = "[lastIndexOf(createArray(10, 20, 30, 20), 20)]"; expected = 3 }

dsc_lib/locales/en-us.toml

@@ -410,6 +410,12 @@ secretNotFound = "Secret '%{name}' not found"
 description = "Checks if a string starts with a specific prefix"
 invoked = "startsWith function"
 
+[functions.skip]
+description = "Returns an array with all elements after the specified number, or a string with all characters after the specified number"
+invoked = "skip function"
+invalidNumberToSkip = "Second argument must be an integer"
+invalidOriginalValue = "First argument must be an array or string"
+
 [functions.string]
 description = "Converts a value to a string"
 

dsc_lib/src/functions/mod.rs

@@ -50,6 +50,7 @@ pub mod path;
 pub mod reference;
 pub mod resource_id;
 pub mod secret;
+pub mod skip;
 pub mod starts_with;
 pub mod string;
 pub mod sub;
@@ -160,6 +161,7 @@ impl FunctionDispatcher {
             Box::new(reference::Reference{}),
             Box::new(resource_id::ResourceId{}),
             Box::new(secret::Secret{}),
+            Box::new(skip::Skip{}),
             Box::new(starts_with::StartsWith{}),
             Box::new(string::StringFn{}),
             Box::new(sub::Sub{}),

dsc_lib/src/functions/skip.rs

@@ -0,0 +1,103 @@
+// 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 Skip {}
+
+impl Function for Skip {
+    fn get_metadata(&self) -> FunctionMetadata {
+        FunctionMetadata {
+            name: "skip".to_string(),
+            description: t!("functions.skip.description").to_string(),
+            category: FunctionCategory::Array,
+            min_args: 2,
+            max_args: 2,
+            accepted_arg_ordered_types: vec![
+                vec![FunctionArgKind::Array, FunctionArgKind::String],
+                vec![FunctionArgKind::Number],
+            ],
+            remaining_arg_accepted_types: None,
+            return_types: vec![FunctionArgKind::Array, FunctionArgKind::String],
+        }
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.skip.invoked"));
+
+        if let Some(count_i64) = args[1].as_i64() {
+            let count: usize = if count_i64 < 0 {
+                0
+            } else {
+                count_i64.try_into().unwrap_or(usize::MAX)
+            };
+
+            if let Some(array) = args[0].as_array() {
+                if count >= array.len() { return Ok(Value::Array(vec![])); }
+                let skipped = array.iter().skip(count).cloned().collect::<Vec<Value>>();
+                return Ok(Value::Array(skipped));
+            }
+
+            if let Some(s) = args[0].as_str() {
+                let result: String = s.chars().skip(count).collect();
+                return Ok(Value::String(result));
+            }
+
+            return Err(DscError::Parser(t!("functions.skip.invalidOriginalValue").to_string()));
+        }
+
+        Err(DscError::Parser(t!("functions.skip.invalidNumberToSkip").to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::configure::context::Context;
+    use crate::parser::Statement;
+    use serde_json::Value;
+
+    #[test]
+    fn skip_array_basic() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[skip(createArray('a','b','c','d'), 2)]", &Context::new()).unwrap();
+        assert_eq!(result, Value::Array(vec![Value::String("c".into()), Value::String("d".into())]));
+    }
+
+    #[test]
+    fn skip_string_basic() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[skip('hello', 2)]", &Context::new()).unwrap();
+        assert_eq!(result, Value::String("llo".into()));
+    }
+
+    #[test]
+    fn skip_more_than_length() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[skip(createArray('a','b'), 5)]", &Context::new()).unwrap();
+        assert_eq!(result, Value::Array(vec![]));
+    }
+
+    #[test]
+    fn skip_array_negative_is_zero() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[skip(createArray('a','b','c'), -1)]", &Context::new()).unwrap();
+        assert_eq!(result, Value::Array(vec![
+            Value::String("a".into()),
+            Value::String("b".into()),
+            Value::String("c".into()),
+        ]));
+    }
+
+    #[test]
+    fn skip_string_negative_is_zero() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[skip('ab', -2)]", &Context::new()).unwrap();
+        assert_eq!(result, Value::String("ab".into()));
+    }
+}