Skip to content

Commit 997c35f

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #1175 from Gijsreyn/gh-57/main/add-trim-function
Add `trim()` function
2 parents e5868f3 + b8b186f commit 997c35f

File tree

5 files changed

+414
-0
lines changed

5 files changed

+414
-0
lines changed

‎docs/reference/schemas/config/functions/trim.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
description: Reference for the 'trim' DSC configuration document function
3+
ms.date: 01/10/2025
4+
ms.topic: reference
5+
title: trim
6+
---
7+
8+
# trim
9+
10+
## Synopsis
11+
12+
Removes all leading and trailing white-space characters from the specified string.
13+
14+
## Syntax
15+
16+
```Syntax
17+
trim(<stringToTrim>)
18+
```
19+
20+
## Description
21+
22+
The `trim()` function removes all leading and trailing white-space characters from
23+
the input string. White-space characters include spaces, tabs, newlines, carriage
24+
returns, and other Unicode whitespace characters. The function preserves internal
25+
whitespace within the string. Use it for cleaning user input, normalizing
26+
configuration values, or preparing strings for comparison.
27+
28+
## Examples
29+
30+
### Example 1 - Clean user input
31+
32+
The following example removes leading and trailing spaces from a parameter value.
33+
34+
```yaml
35+
# trim.example.1.dsc.config.yaml
36+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
37+
parameters:
38+
userName:
39+
type: string
40+
defaultValue: ' admin '
41+
resources:
42+
- name: Clean user input
43+
type: Microsoft.DSC.Debug/Echo
44+
properties:
45+
output:
46+
rawInput: "[parameters('userName')]"
47+
cleanedInput: "[trim(parameters('userName'))]"
48+
```
49+
50+
```bash
51+
dsc config get --file trim.example.1.dsc.config.yaml
52+
```
53+
54+
```yaml
55+
results:
56+
- name: Clean user input
57+
type: Microsoft.DSC.Debug/Echo
58+
result:
59+
actualState:
60+
output:
61+
rawInput: ' admin '
62+
cleanedInput: admin
63+
messages: []
64+
hadErrors: false
65+
```
66+
67+
### Example 2 - Normalize file paths
68+
69+
The following example demonstrates using `trim()` with [`concat()`][01] to clean
70+
path components before building a complete file path.
71+
72+
```yaml
73+
# trim.example.2.dsc.config.yaml
74+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
75+
parameters:
76+
baseDir:
77+
type: string
78+
defaultValue: ' /var/log '
79+
fileName:
80+
type: string
81+
defaultValue: ' app.log '
82+
resources:
83+
- name: Build clean file path
84+
type: Microsoft.DSC.Debug/Echo
85+
properties:
86+
output:
87+
filePath: "[concat(trim(parameters('baseDir')), '/', trim(parameters('fileName')))]"
88+
```
89+
90+
```bash
91+
dsc config get --file trim.example.2.dsc.config.yaml
92+
```
93+
94+
```yaml
95+
results:
96+
- name: Build clean file path
97+
type: Microsoft.DSC.Debug/Echo
98+
result:
99+
actualState:
100+
output:
101+
filePath: /var/log/app.log
102+
messages: []
103+
hadErrors: false
104+
```
105+
106+
### Example 3 - Clean configuration values for comparison
107+
108+
The following example uses `trim()` to normalize strings before comparing them with
109+
the [`equals()`][02] function.
110+
111+
```yaml
112+
# trim.example.3.dsc.config.yaml
113+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
114+
parameters:
115+
expectedEnv:
116+
type: string
117+
defaultValue: production
118+
actualEnv:
119+
type: string
120+
defaultValue: ' production '
121+
resources:
122+
- name: Environment comparison
123+
type: Microsoft.DSC.Debug/Echo
124+
properties:
125+
output:
126+
matches: "[equals(trim(parameters('actualEnv')), parameters('expectedEnv'))]"
127+
```
128+
129+
```bash
130+
dsc config get --file trim.example.3.dsc.config.yaml
131+
```
132+
133+
```yaml
134+
results:
135+
- name: Environment comparison
136+
type: Microsoft.DSC.Debug/Echo
137+
result:
138+
actualState:
139+
output:
140+
matches: true
141+
messages: []
142+
hadErrors: false
143+
```
144+
145+
### Example 4 - Process multi-line configuration
146+
147+
The following example shows how `trim()` handles tabs, newlines, and various
148+
whitespace characters.
149+
150+
```yaml
151+
# trim.example.4.dsc.config.yaml
152+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
153+
resources:
154+
- name: Whitespace handling
155+
type: Microsoft.DSC.Debug/Echo
156+
properties:
157+
output:
158+
spaces: "[trim(' content ')]"
159+
mixed: "[trim(' \t\n content \n\t ')]"
160+
internal: "[trim(' multiple spaces inside ')]"
161+
```
162+
163+
```bash
164+
dsc config get --file trim.example.4.dsc.config.yaml
165+
```
166+
167+
```yaml
168+
results:
169+
- name: Whitespace handling
170+
type: Microsoft.DSC.Debug/Echo
171+
result:
172+
actualState:
173+
output:
174+
spaces: content
175+
mixed: content
176+
internal: multiple spaces inside
177+
messages: []
178+
hadErrors: false
179+
```
180+
181+
### Example 5 - Combine with case conversion
182+
183+
The following example demonstrates using `trim()` with [`toLower()`][00] to both
184+
clean and normalize a string value.
185+
186+
```yaml
187+
# trim.example.5.dsc.config.yaml
188+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
189+
parameters:
190+
serviceName:
191+
type: string
192+
defaultValue: ' WEB-SERVER '
193+
resources:
194+
- name: Clean and normalize service name
195+
type: Microsoft.DSC.Debug/Echo
196+
properties:
197+
output:
198+
original: "[parameters('serviceName')]"
199+
normalized: "[toLower(trim(parameters('serviceName')))]"
200+
```
201+
202+
```bash
203+
dsc config get --file trim.example.5.dsc.config.yaml
204+
```
205+
206+
```yaml
207+
results:
208+
- name: Clean and normalize service name
209+
type: Microsoft.DSC.Debug/Echo
210+
result:
211+
actualState:
212+
output:
213+
original: ' WEB-SERVER '
214+
normalized: web-server
215+
messages: []
216+
hadErrors: false
217+
```
218+
219+
## Parameters
220+
221+
### stringToTrim
222+
223+
The string value to remove leading and trailing whitespace from.
224+
225+
```yaml
226+
Type: string
227+
Required: true
228+
Position: 1
229+
```
230+
231+
## Output
232+
233+
The `trim()` function returns the input string with all leading and trailing
234+
white-space characters removed. Internal whitespace is preserved.
235+
236+
```yaml
237+
Type: string
238+
```
239+
240+
## Related functions
241+
242+
- [`toLower()`][00] - Converts a string to lower case
243+
- [`concat()`][01] - Concatenates strings together
244+
- [`equals()`][02] - Compares two values for equality
245+
- [`startsWith()`][03] - Checks if a string starts with a value
246+
- [`endsWith()`][04] - Checks if a string ends with a value
247+
- [`substring()`][05] - Extracts a portion of a string
248+
- [`replace()`][06] - Replaces text in a string
249+
- [`parameters()`][07] - Retrieves parameter values
250+
251+
<!-- Link reference definitions -->
252+
[00]: ./toLower.md
253+
[01]: ./concat.md
254+
[02]: ./equals.md
255+
[03]: ./startsWith.md
256+
[04]: ./endsWith.md
257+
[05]: ./substring.md
258+
[06]: ./replace.md
259+
[07]: ./parameters.md

‎dsc/tests/dsc_functions.tests.ps1‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -831,4 +831,31 @@ Describe 'tests for function expressions' {
831831
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
832832
$out.results[0].result.actualState.output | Should -Be $expected
833833
}
834+
835+
It 'trim function works for: <expression>' -TestCases @(
836+
@{ expression = "[trim(' hello')]"; expected = 'hello' }
837+
@{ expression = "[trim('hello ')]"; expected = 'hello' }
838+
@{ expression = "[trim(' hello world ')]"; expected = 'hello world' }
839+
@{ expression = "[trim('hello')]"; expected = 'hello' }
840+
@{ expression = "[trim('')]"; expected = '' }
841+
@{ expression = "[trim(' ')]"; expected = '' }
842+
@{ expression = "[trim(' hello world ')]"; expected = 'hello world' }
843+
@{ expression = "[trim(' café ')]"; expected = 'café' }
844+
@{ expression = "[trim(' a ')]"; expected = 'a' }
845+
@{ expression = "[trim(concat(' hello', ' '))]"; expected = 'hello' }
846+
) {
847+
param($expression, $expected)
848+
849+
$escapedExpression = $expression -replace "'", "''"
850+
$config_yaml = @"
851+
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
852+
resources:
853+
- name: Echo
854+
type: Microsoft.DSC.Debug/Echo
855+
properties:
856+
output: '$escapedExpression'
857+
"@
858+
$out = $config_yaml | dsc config get -f - | ConvertFrom-Json
859+
$out.results[0].result.actualState.output | Should -Be $expected
860+
}
834861
}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -512,6 +512,9 @@ description = "Converts the specified string to lower case"
512512
[functions.toUpper]
513513
description = "Converts the specified string to upper case"
514514

515+
[functions.trim]
516+
description = "Removes all leading and trailing white-space characters from the specified string"
517+
515518
[functions.true]
516519
description = "Returns the boolean value true"
517520
invoked = "true function"

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ pub mod substring;
6565
pub mod system_root;
6666
pub mod to_lower;
6767
pub mod to_upper;
68+
pub mod trim;
6869
pub mod r#true;
6970
pub mod union;
7071
pub mod unique_string;
@@ -186,6 +187,7 @@ impl FunctionDispatcher {
186187
Box::new(system_root::SystemRoot{}),
187188
Box::new(to_lower::ToLower{}),
188189
Box::new(to_upper::ToUpper{}),
190+
Box::new(trim::Trim{}),
189191
Box::new(r#true::True{}),
190192
Box::new(utc_now::UtcNow{}),
191193
Box::new(union::Union{}),

0 commit comments

Comments
 (0)