Skip to content

Commit b18e589

Browse files
committed
Add documentation for 'tryGet' DSC configuration function
1 parent 4affdc2 commit b18e589

File tree

2 files changed

+467
-20
lines changed

2 files changed

+467
-20
lines changed

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

Lines changed: 155 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -567,24 +567,65 @@ resources:
567567

568568
The following sections include the available DSC configuration functions by purpose and input type.
569569

570-
### Array functions
570+
### Array and collection functions
571571

572-
The following list of functions operate on arrays:
572+
The following list of functions operate on arrays and collections:
573573

574+
- [array()][array] - Convert a value into an array containing that value.
574575
- [concat()][concat] - Combine multiple arrays of strings into a single array of strings.
576+
- [contains()][contains] - Check if an array contains a value or an object contains a key.
575577
- [createArray()][createArray] - Create an array of a given type from zero or more values of the
576578
same type.
577-
- [min()][min] - Return the smallest integer value from an array of integers.
579+
- [empty()][empty] - Check if a value (string, array, or object) is empty.
580+
- [first()][first] - Return the first element of an array or the first character of a string.
581+
- [indexOf()][indexOf] - Return the zero-based index of the first occurrence of a value in an array.
582+
- [intersection()][intersection] - Return a single array or object with the common elements from the parameters.
583+
- [items()][items] - Convert an object into an array of key-value pair objects.
584+
- [join()][join] - Combine array elements into a single string with a specified delimiter.
585+
- [last()][last] - Return the last element of an array or the last character of a string.
586+
- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an array.
587+
- [length()][length] - Return the number of elements in an array, characters in a string, or top-level properties in an object.
578588
- [max()][max] - Return the largest integer value from an array of integers.
589+
- [min()][min] - Return the smallest integer value from an array of integers.
590+
- [range()][range] - Create an array of integers within a specified range.
591+
- [skip()][skip] - Return an array or string with elements skipped from the beginning.
592+
- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without throwing an error.
593+
- [tryIndexFromEnd()][tryIndexFromEnd] - Safely retrieve a value from an array by counting backward from the end.
594+
- [union()][union] - Return a single array or object with all unique elements from the parameters.
595+
596+
### Comparison functions
597+
598+
The following list of functions compare values:
599+
600+
- [equals()][equals] - Check if two values are equal.
601+
- [greater()][greater] - Check if the first value is greater than the second value.
602+
- [greaterOrEquals()][greaterOrEquals] - Check if the first value is greater than or equal to the second value.
603+
- [less()][less] - Check if the first value is less than the second value.
604+
- [lessOrEquals()][lessOrEquals] - Check if the first value is less than or equal to the second value.
579605

580606
### Data functions
581607

582608
The following list of functions operate on data outside of a resource instance:
583609

610+
- [context()][context] - Return contextual information about the system and execution environment.
584611
- [envvar()][envvar] - Return the value of a specified environment variable.
585612
- [parameters()][parameters] - Return the value of a specified configuration parameter.
613+
- [secret()][secret] - Retrieve a secret value from a secure store.
586614
- [variables()][variables] - Return the value of a specified configuration variable.
587615

616+
### Logical functions
617+
618+
The following list of functions perform logical operations:
619+
620+
- [and()][and] - Return true if all boolean values are true.
621+
- [bool()][bool] - Convert a value to a boolean.
622+
- [false()][false] - Return the boolean value false.
623+
- [if()][if] - Return one of two values based on a boolean condition.
624+
- [not()][not] - Return the logical negation of a boolean value.
625+
- [null()][null] - Return a null value.
626+
- [or()][or] - Return true if any boolean value is true.
627+
- [true()][true] - Return the boolean value true.
628+
588629
### Mathematics functions
589630

590631
The following list of functions operate on integer values or arrays of integer values:
@@ -599,6 +640,18 @@ The following list of functions operate on integer values or arrays of integer v
599640
- [mul()][mul] - Return the product from multiplying two integers.
600641
- [sub()][sub] - Return the difference from subtracting one integer from another.
601642

643+
### Object functions
644+
645+
The following list of functions operate on objects:
646+
647+
- [coalesce()][coalesce] - Return the first non-null value from the provided arguments.
648+
- [contains()][contains] - Check if an array contains a value or an object contains a key.
649+
- [createObject()][createObject] - Create an object from key-value pairs.
650+
- [empty()][empty] - Check if a value (string, array, or object) is empty.
651+
- [items()][items] - Convert an object into an array of key-value pair objects.
652+
- [json()][json] - Parse a JSON string and return the resulting value.
653+
- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without throwing an error.
654+
602655
### Resource functions
603656

604657
The following list of functions operate on resource instances:
@@ -613,36 +666,118 @@ The following list of functions operate on resource instances:
613666
The following list of functions are for manipulating strings:
614667

615668
- [base64()][base64] - Return the base64 representation of a string.
669+
- [base64ToString()][base64ToString] - Decode a base64-encoded string and return the original string.
616670
- [concat()][concat] - Return a combined string where the input strings are concatenated in the
617671
order they're specified.
672+
- [contains()][contains] - Check if an array contains a value or an object contains a key.
673+
- [empty()][empty] - Check if a value (string, array, or object) is empty.
674+
- [endsWith()][endsWith] - Check if a string ends with a specified suffix.
675+
- [first()][first] - Return the first element of an array or the first character of a string.
676+
- [format()][format] - Create a formatted string from input values.
677+
- [join()][join] - Combine array elements into a single string with a specified delimiter.
678+
- [last()][last] - Return the last element of an array or the last character of a string.
679+
- [length()][length] - Return the number of elements in an array, characters in a string, or top-level properties in an object.
680+
- [skip()][skip] - Return an array or string with elements skipped from the beginning.
681+
- [startsWith()][startsWith] - Check if a string starts with a specified prefix.
682+
- [string()][string] - Convert a value to its string representation.
683+
- [substring()][substring] - Extract a portion of a string starting at a specified position.
684+
- [toLower()][toLower] - Convert a string to lowercase.
685+
- [toUpper()][toUpper] - Convert a string to uppercase.
686+
- [trim()][trim] - Remove leading and trailing whitespace from a string.
687+
- [uniqueString()][uniqueString] - Create a deterministic hash string based on provided values.
688+
- [uri()][uri] - Create an absolute URI by combining a base URI with a relative URI string.
689+
- [uriComponent()][uriComponent] - Encode a string for use as a URI component.
690+
- [uriComponentToString()][uriComponentToString] - Decode a URI-encoded string.
691+
692+
### System functions
693+
694+
The following list of functions provide system-level information:
695+
696+
- [path()][path] - Construct a file system path from one or more path segments.
697+
- [systemRoot()][systemRoot] - Return the system root directory path.
698+
- [utcNow()][utcNow] - Return the current UTC datetime in a specified format.
618699

619700
### Type functions
620701

621702
The following list of functions create or convert values of a given type:
622703

704+
- [array()][array] - Convert a value into an array containing that value.
705+
- [bool()][bool] - Convert a value to a boolean.
623706
- [createArray()][createArray] - Create an array of a given type from zero or more values of the
624707
same type.
708+
- [createObject()][createObject] - Create an object from key-value pairs.
625709
- [int()][int] - Convert a string or number with a fractional part into an integer.
710+
- [string()][string] - Convert a value to its string representation.
626711

627712
<!-- Link references -->
628713
[01]: https://yaml.org/spec/1.2.2/#folded-style
629714
[02]: https://yaml.org/spec/1.2.2/#literal-style
630715
[03]: https://yaml.org/spec/1.2.2/#block-chomping-indicator
631716
<!-- Function link references -->
632-
[add]: ./add.md
633-
[base64]: ./base64.md
634-
[concat]: ./concat.md
635-
[copyIndex]: ./copyIndex.md
636-
[createArray]: ./createArray.md
637-
[div]: ./div.md
638-
[envvar]: ./envvar.md
639-
[int]: ./int.md
640-
[max]: ./max.md
641-
[min]: ./min.md
642-
[mod]: ./mod.md
643-
[mul]: ./mul.md
644-
[parameters]: ./parameters.md
645-
[reference]: ./reference.md
646-
[resourceId]: ./resourceId.md
647-
[sub]: ./sub.md
648-
[variables]: ./variables.md
717+
[add]: ./add.md
718+
[and]: ./and.md
719+
[array]: ./array.md
720+
[base64]: ./base64.md
721+
[base64ToString]: ./base64ToString.md
722+
[bool]: ./bool.md
723+
[coalesce]: ./coalesce.md
724+
[concat]: ./concat.md
725+
[contains]: ./contains.md
726+
[context]: ./context.md
727+
[copyIndex]: ./copyIndex.md
728+
[createArray]: ./createArray.md
729+
[createObject]: ./createObject.md
730+
[div]: ./div.md
731+
[empty]: ./empty.md
732+
[endsWith]: ./endsWith.md
733+
[envvar]: ./envvar.md
734+
[equals]: ./equals.md
735+
[false]: ./false.md
736+
[first]: ./first.md
737+
[format]: ./format.md
738+
[greater]: ./greater.md
739+
[greaterOrEquals]: ./greaterOrEquals.md
740+
[if]: ./if.md
741+
[indexOf]: ./indexOf.md
742+
[int]: ./int.md
743+
[intersection]: ./intersection.md
744+
[items]: ./items.md
745+
[join]: ./join.md
746+
[json]: ./json.md
747+
[last]: ./last.md
748+
[lastIndexOf]: ./lastIndexOf.md
749+
[length]: ./length.md
750+
[less]: ./less.md
751+
[lessOrEquals]: ./lessOrEquals.md
752+
[max]: ./max.md
753+
[min]: ./min.md
754+
[mod]: ./mod.md
755+
[mul]: ./mul.md
756+
[not]: ./not.md
757+
[null]: ./null.md
758+
[or]: ./or.md
759+
[parameters]: ./parameters.md
760+
[path]: ./path.md
761+
[range]: ./range.md
762+
[reference]: ./reference.md
763+
[resourceId]: ./resourceId.md
764+
[secret]: ./secret.md
765+
[skip]: ./skip.md
766+
[startsWith]: ./startsWith.md
767+
[string]: ./string.md
768+
[sub]: ./sub.md
769+
[substring]: ./substring.md
770+
[systemRoot]: ./systemRoot.md
771+
[toLower]: ./toLower.md
772+
[toUpper]: ./toUpper.md
773+
[trim]: ./trim.md
774+
[true]: ./true.md
775+
[tryGet]: ./tryGet.md
776+
[tryIndexFromEnd]: ./tryIndexFromEnd.md
777+
[union]: ./union.md
778+
[uniqueString]: ./uniqueString.md
779+
[uri]: ./uri.md
780+
[uriComponent]: ./uriComponent.md
781+
[uriComponentToString]: ./uriComponentToString.md
782+
[utcNow]: ./utcNow.md
783+
[variables]: ./variables.md

0 commit comments

Comments
 (0)