Merge pull request #981 from Gijsreyn/logical-functions-ref-docs

Add reference docs for logical functions

Author: michaeltlombardi

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(<arg1>, <arg2>, ...)
+```
+
+## 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
+```
+
+<!-- Link reference definitions -->

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

@@ -0,0 +1,135 @@
+---
+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(<value>)
+```
+
+## 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`.
+
+> [!NOTE]
+> Any string argument other than `true` or `false` (case-insensitive) will raise a DSC error.
+
+## 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
+```

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
+```
+
+<!-- Link reference definitions -->