From e0d63909e484b4190b1baa8ab3a62c1b6473f1f3 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sat, 19 Jul 2025 08:01:07 +0200 Subject: [PATCH 1/4] Add reference docs for logical functions --- .../reference/schemas/config/functions/and.md | 148 ++++++++++++++++++ .../schemas/config/functions/bool.md | 132 ++++++++++++++++ .../schemas/config/functions/false.md | 76 +++++++++ .../reference/schemas/config/functions/not.md | 83 ++++++++++ docs/reference/schemas/config/functions/or.md | 148 ++++++++++++++++++ .../schemas/config/functions/true.md | 76 +++++++++ 6 files changed, 663 insertions(+) create mode 100644 docs/reference/schemas/config/functions/and.md create mode 100644 docs/reference/schemas/config/functions/bool.md create mode 100644 docs/reference/schemas/config/functions/false.md create mode 100644 docs/reference/schemas/config/functions/not.md create mode 100644 docs/reference/schemas/config/functions/or.md create mode 100644 docs/reference/schemas/config/functions/true.md diff --git a/docs/reference/schemas/config/functions/and.md b/docs/reference/schemas/config/functions/and.md new file mode 100644 index 00000000..aca1267d --- /dev/null +++ b/docs/reference/schemas/config/functions/and.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'and' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: and +--- + +# and + +## Synopsis + +Returns true if all arguments are true. + +## Syntax + +```Syntax +and(, , ...) +``` + +## Description + +The `and()` function evaluates if all arguments are true. It takes two or more boolean arguments +and returns `true` only if every argument is `true`. If any argument is `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `false` as soon as it encounters +the first `false` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic and operation + +This configuration demonstrates basic usage of the `and()` function. + +```yaml +# and.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, true)]" +``` + +```bash +dsc config get --file and.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.1291763S + name: Echo and result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - And operation with false value + +This example shows the `and()` function returning false when one argument is false. + +```yaml +# and.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, false, true)]" +``` + +```bash +dsc config get --file and.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329292S + name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - And operation with multiple conditions + +This configuration uses the `and()` function with multiple boolean expressions. + +```yaml +# and.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(equals(5, 5), equals('hello', 'hello'), true)]" +``` + +```bash +dsc config get --file and.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0514415S + name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `and()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `and()` function returns `true` if all arguments are `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/bool.md b/docs/reference/schemas/config/functions/bool.md new file mode 100644 index 00000000..73643a8c --- /dev/null +++ b/docs/reference/schemas/config/functions/bool.md @@ -0,0 +1,132 @@ +--- +description: Reference for the 'bool' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: bool +--- + +# bool + +## Synopsis + +Converts a string or number to a boolean value. + +## Syntax + +```Syntax +bool() +``` + +## Description + +The `bool()` function converts a string or number to a boolean value. For string arguments, +it accepts "true" (case-insensitive) which converts to `true`, and "false" (case-insensitive) +which converts to `false`. For numeric arguments, zero converts to `false` and any non-zero +value converts to `true`. + +## Examples + +### Example 1 - Convert string to boolean + +This configuration demonstrates converting string values to boolean. + +```yaml +# bool.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + properties: + output: + trueValue: "[bool('true')]" + falseValue: "[bool('FALSE')]" +``` + +```bash +dsc config get --file bool.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0334711S + name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + trueValue: true + falseValue: false +messages: [] +hadErrors: false +``` + +### Example 2 - Convert number to boolean + +This example shows the `bool()` function converting numeric values to boolean. + +```yaml +# bool.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + zeroIsFalse: "[bool(0)]" + oneIsTrue: "[bool(1)]" + negativeIsTrue: "[bool(-5)]" + positiveIsTrue: "[bool(42)]" +``` + +```bash +dsc config get --file bool.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0323199S + name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + zeroIsFalse: false + oneIsTrue: true + negativeIsTrue: true + positiveIsTrue: true +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The `bool()` function requires a single argument that is either a string or number. + +For strings, valid values are: +- "true" (case-insensitive) - converts to `true` +- "false" (case-insensitive) - converts to `false` + +For numbers: +- 0 - converts to `false` +- Any non-zero value - converts to `true` + +```yaml +Type: [string, integer] +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `bool()` function returns a boolean value based on the input argument. + +```yaml +Type: boolean +``` diff --git a/docs/reference/schemas/config/functions/false.md b/docs/reference/schemas/config/functions/false.md new file mode 100644 index 00000000..c5be372b --- /dev/null +++ b/docs/reference/schemas/config/functions/false.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'false' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: false +--- + +# false + +## Synopsis + +Returns the boolean value false. + +## Syntax + +```Syntax +false() +``` + +## Description + +The `false()` function returns the boolean value `false`. This function takes no arguments and +always returns `false`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic false value + +This configuration demonstrates basic usage of the `false()` function. + +```yaml +# false.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo false value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[false()]" +``` + +```bash +dsc config get --file false.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo false value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +## Parameters + +The `false()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `false()` function always returns the boolean value `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/not.md b/docs/reference/schemas/config/functions/not.md new file mode 100644 index 00000000..2338751a --- /dev/null +++ b/docs/reference/schemas/config/functions/not.md @@ -0,0 +1,83 @@ +--- +description: Reference for the 'not' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: not +--- + +# not + +## Synopsis + +Negates a boolean value. + +## Syntax + +```Syntax +not() +``` + +## Description + +The `not()` function negates a boolean value, returning the logical opposite. If the input is +`true`, it returns `false`. If the input is `false`, it returns `true`. This function accepts +a single boolean argument. + +## Examples + +### Example 1 - Basic not operation + +This configuration demonstrates basic usage of the `not()` function. + +```yaml +# not.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo not operations + type: Microsoft.DSC.Debug/Echo + properties: + output: + notTrue: "[not(true)]" + notFalse: "[not(false)]" +``` + +```bash +dsc config get --file not.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0328813S + name: Echo not operations + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + notTrue: false + notFalse: true +``` + +## Parameters + +### value + +The `not()` function requires a single boolean argument. + +```yaml +Type: boolean +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `not()` function returns the logical opposite of the input boolean value. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/or.md b/docs/reference/schemas/config/functions/or.md new file mode 100644 index 00000000..a61e0399 --- /dev/null +++ b/docs/reference/schemas/config/functions/or.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'or' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: or +--- + +# or + +## Synopsis + +Returns true if any arguments are true. + +## Syntax + +```Syntax +or(, , ...) +``` + +## Description + +The `or()` function evaluates if any arguments are true. It takes two or more boolean arguments +and returns `true` if at least one argument is `true`. If all arguments are `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `true` as soon as it encounters +the first `true` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic or operation + +This configuration demonstrates basic usage of the `or()` function. + +```yaml +# or.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, true)]" +``` + +```bash +dsc config get --file or.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329859S + name: Echo or result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - Or operation with all false values + +This example shows the `or()` function returning false when all arguments are false. + +```yaml +# or.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, false, false)]" +``` + +```bash +dsc config get --file or.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0320911S + name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - Or operation with multiple conditions + +This configuration uses the `or()` function with multiple boolean expressions. + +```yaml +# or.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(equals(5, 10), equals('hello', 'world'), true)]" +``` + +```bash +dsc config get --file or.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0324607S + name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `or()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `or()` function returns `true` if any argument is `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/true.md b/docs/reference/schemas/config/functions/true.md new file mode 100644 index 00000000..dd1a37aa --- /dev/null +++ b/docs/reference/schemas/config/functions/true.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'true' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: true +--- + +# true + +## Synopsis + +Returns the boolean value true. + +## Syntax + +```Syntax +true() +``` + +## Description + +The `true()` function returns the boolean value `true`. This function takes no arguments and +always returns `true`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic true value + +This configuration demonstrates basic usage of the `true()` function. + +```yaml +# true.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo true value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[true()]" +``` + +```bash +dsc config get --file true.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo true value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +The `true()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `true()` function always returns the boolean value `true`. + +```yaml +Type: boolean +``` + + From 07c24d85f03b7b00bd7fec061742bf7100b65303 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sat, 19 Jul 2025 08:01:07 +0200 Subject: [PATCH 2/4] Add reference docs for logical functions --- .../reference/schemas/config/functions/and.md | 148 ++++++++++++++++++ .../schemas/config/functions/bool.md | 132 ++++++++++++++++ .../schemas/config/functions/false.md | 76 +++++++++ .../reference/schemas/config/functions/not.md | 83 ++++++++++ docs/reference/schemas/config/functions/or.md | 148 ++++++++++++++++++ .../schemas/config/functions/true.md | 76 +++++++++ 6 files changed, 663 insertions(+) create mode 100644 docs/reference/schemas/config/functions/and.md create mode 100644 docs/reference/schemas/config/functions/bool.md create mode 100644 docs/reference/schemas/config/functions/false.md create mode 100644 docs/reference/schemas/config/functions/not.md create mode 100644 docs/reference/schemas/config/functions/or.md create mode 100644 docs/reference/schemas/config/functions/true.md diff --git a/docs/reference/schemas/config/functions/and.md b/docs/reference/schemas/config/functions/and.md new file mode 100644 index 00000000..aca1267d --- /dev/null +++ b/docs/reference/schemas/config/functions/and.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'and' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: and +--- + +# and + +## Synopsis + +Returns true if all arguments are true. + +## Syntax + +```Syntax +and(, , ...) +``` + +## Description + +The `and()` function evaluates if all arguments are true. It takes two or more boolean arguments +and returns `true` only if every argument is `true`. If any argument is `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `false` as soon as it encounters +the first `false` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic and operation + +This configuration demonstrates basic usage of the `and()` function. + +```yaml +# and.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, true)]" +``` + +```bash +dsc config get --file and.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.1291763S + name: Echo and result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - And operation with false value + +This example shows the `and()` function returning false when one argument is false. + +```yaml +# and.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, false, true)]" +``` + +```bash +dsc config get --file and.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329292S + name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - And operation with multiple conditions + +This configuration uses the `and()` function with multiple boolean expressions. + +```yaml +# and.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(equals(5, 5), equals('hello', 'hello'), true)]" +``` + +```bash +dsc config get --file and.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0514415S + name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `and()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `and()` function returns `true` if all arguments are `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/bool.md b/docs/reference/schemas/config/functions/bool.md new file mode 100644 index 00000000..73643a8c --- /dev/null +++ b/docs/reference/schemas/config/functions/bool.md @@ -0,0 +1,132 @@ +--- +description: Reference for the 'bool' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: bool +--- + +# bool + +## Synopsis + +Converts a string or number to a boolean value. + +## Syntax + +```Syntax +bool() +``` + +## Description + +The `bool()` function converts a string or number to a boolean value. For string arguments, +it accepts "true" (case-insensitive) which converts to `true`, and "false" (case-insensitive) +which converts to `false`. For numeric arguments, zero converts to `false` and any non-zero +value converts to `true`. + +## Examples + +### Example 1 - Convert string to boolean + +This configuration demonstrates converting string values to boolean. + +```yaml +# bool.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + properties: + output: + trueValue: "[bool('true')]" + falseValue: "[bool('FALSE')]" +``` + +```bash +dsc config get --file bool.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0334711S + name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + trueValue: true + falseValue: false +messages: [] +hadErrors: false +``` + +### Example 2 - Convert number to boolean + +This example shows the `bool()` function converting numeric values to boolean. + +```yaml +# bool.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + zeroIsFalse: "[bool(0)]" + oneIsTrue: "[bool(1)]" + negativeIsTrue: "[bool(-5)]" + positiveIsTrue: "[bool(42)]" +``` + +```bash +dsc config get --file bool.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0323199S + name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + zeroIsFalse: false + oneIsTrue: true + negativeIsTrue: true + positiveIsTrue: true +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The `bool()` function requires a single argument that is either a string or number. + +For strings, valid values are: +- "true" (case-insensitive) - converts to `true` +- "false" (case-insensitive) - converts to `false` + +For numbers: +- 0 - converts to `false` +- Any non-zero value - converts to `true` + +```yaml +Type: [string, integer] +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `bool()` function returns a boolean value based on the input argument. + +```yaml +Type: boolean +``` diff --git a/docs/reference/schemas/config/functions/false.md b/docs/reference/schemas/config/functions/false.md new file mode 100644 index 00000000..c5be372b --- /dev/null +++ b/docs/reference/schemas/config/functions/false.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'false' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: false +--- + +# false + +## Synopsis + +Returns the boolean value false. + +## Syntax + +```Syntax +false() +``` + +## Description + +The `false()` function returns the boolean value `false`. This function takes no arguments and +always returns `false`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic false value + +This configuration demonstrates basic usage of the `false()` function. + +```yaml +# false.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo false value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[false()]" +``` + +```bash +dsc config get --file false.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo false value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +## Parameters + +The `false()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `false()` function always returns the boolean value `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/not.md b/docs/reference/schemas/config/functions/not.md new file mode 100644 index 00000000..2338751a --- /dev/null +++ b/docs/reference/schemas/config/functions/not.md @@ -0,0 +1,83 @@ +--- +description: Reference for the 'not' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: not +--- + +# not + +## Synopsis + +Negates a boolean value. + +## Syntax + +```Syntax +not() +``` + +## Description + +The `not()` function negates a boolean value, returning the logical opposite. If the input is +`true`, it returns `false`. If the input is `false`, it returns `true`. This function accepts +a single boolean argument. + +## Examples + +### Example 1 - Basic not operation + +This configuration demonstrates basic usage of the `not()` function. + +```yaml +# not.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo not operations + type: Microsoft.DSC.Debug/Echo + properties: + output: + notTrue: "[not(true)]" + notFalse: "[not(false)]" +``` + +```bash +dsc config get --file not.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0328813S + name: Echo not operations + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + notTrue: false + notFalse: true +``` + +## Parameters + +### value + +The `not()` function requires a single boolean argument. + +```yaml +Type: boolean +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `not()` function returns the logical opposite of the input boolean value. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/or.md b/docs/reference/schemas/config/functions/or.md new file mode 100644 index 00000000..a61e0399 --- /dev/null +++ b/docs/reference/schemas/config/functions/or.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'or' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: or +--- + +# or + +## Synopsis + +Returns true if any arguments are true. + +## Syntax + +```Syntax +or(, , ...) +``` + +## Description + +The `or()` function evaluates if any arguments are true. It takes two or more boolean arguments +and returns `true` if at least one argument is `true`. If all arguments are `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `true` as soon as it encounters +the first `true` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic or operation + +This configuration demonstrates basic usage of the `or()` function. + +```yaml +# or.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, true)]" +``` + +```bash +dsc config get --file or.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329859S + name: Echo or result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - Or operation with all false values + +This example shows the `or()` function returning false when all arguments are false. + +```yaml +# or.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, false, false)]" +``` + +```bash +dsc config get --file or.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0320911S + name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - Or operation with multiple conditions + +This configuration uses the `or()` function with multiple boolean expressions. + +```yaml +# or.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(equals(5, 10), equals('hello', 'world'), true)]" +``` + +```bash +dsc config get --file or.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0324607S + name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `or()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `or()` function returns `true` if any argument is `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/docs/reference/schemas/config/functions/true.md b/docs/reference/schemas/config/functions/true.md new file mode 100644 index 00000000..dd1a37aa --- /dev/null +++ b/docs/reference/schemas/config/functions/true.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'true' DSC configuration document function +ms.date: 01/19/2025 +ms.topic: reference +title: true +--- + +# true + +## Synopsis + +Returns the boolean value true. + +## Syntax + +```Syntax +true() +``` + +## Description + +The `true()` function returns the boolean value `true`. This function takes no arguments and +always returns `true`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic true value + +This configuration demonstrates basic usage of the `true()` function. + +```yaml +# true.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo true value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[true()]" +``` + +```bash +dsc config get --file true.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo true value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +The `true()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `true()` function always returns the boolean value `true`. + +```yaml +Type: boolean +``` + + From d7280ebb58434616109a42129fbec0001e559ce2 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 29 Jul 2025 02:27:02 +0200 Subject: [PATCH 3/4] Small note added --- docs/reference/schemas/config/functions/bool.md | 3 +++ docs/reference/schemas/config/functions/coalesce.md | 0 docs/reference/schemas/config/functions/createObject.md | 0 docs/reference/schemas/config/functions/null.md | 0 4 files changed, 3 insertions(+) create mode 100644 docs/reference/schemas/config/functions/coalesce.md create mode 100644 docs/reference/schemas/config/functions/createObject.md create mode 100644 docs/reference/schemas/config/functions/null.md diff --git a/docs/reference/schemas/config/functions/bool.md b/docs/reference/schemas/config/functions/bool.md index 73643a8c..b1ac488c 100644 --- a/docs/reference/schemas/config/functions/bool.md +++ b/docs/reference/schemas/config/functions/bool.md @@ -24,6 +24,9 @@ it accepts "true" (case-insensitive) which converts to `true`, and "false" (case which converts to `false`. For numeric arguments, zero converts to `false` and any non-zero value converts to `true`. +> [!NOTE] +> Any string argument other than `true` or `false` (case-insensitive) will raise a DSC error. + ## Examples ### Example 1 - Convert string to boolean diff --git a/docs/reference/schemas/config/functions/coalesce.md b/docs/reference/schemas/config/functions/coalesce.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/schemas/config/functions/createObject.md b/docs/reference/schemas/config/functions/createObject.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/schemas/config/functions/null.md b/docs/reference/schemas/config/functions/null.md new file mode 100644 index 00000000..e69de29b From 11f78c98a11215d12e13f9a3ee12f5031a10ffc8 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 29 Jul 2025 02:28:09 +0200 Subject: [PATCH 4/4] Wrong files commit --- docs/reference/schemas/config/functions/coalesce.md | 0 docs/reference/schemas/config/functions/createObject.md | 0 docs/reference/schemas/config/functions/null.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/reference/schemas/config/functions/coalesce.md delete mode 100644 docs/reference/schemas/config/functions/createObject.md delete mode 100644 docs/reference/schemas/config/functions/null.md diff --git a/docs/reference/schemas/config/functions/coalesce.md b/docs/reference/schemas/config/functions/coalesce.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/reference/schemas/config/functions/createObject.md b/docs/reference/schemas/config/functions/createObject.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/reference/schemas/config/functions/null.md b/docs/reference/schemas/config/functions/null.md deleted file mode 100644 index e69de29b..00000000