en-US/about_PSDocs_Selectors.help.txt
|
TOPIC
about_psdocs_selectors SHORT DESCRIPTION Describes PSDocs Selectors including how to use and author them. LONG DESCRIPTION PSDocs executes document to validate an object from input. When evaluating an object from input, PSDocs can use selectors to perform complex matches of an object. - A selector is a YAML-based expression that evaluates an object. - Each selector is comprised of nested conditions, operators, and comparison properties. - Selectors must use one or more available conditions with a comparison property to evaluate the object. - Optionally a condition can be nested in an operator. - Operators can be nested within other operators. The following conditions are available: - Contains - Equals - EndsWith - Exists - Greater - GreaterOrEquals - HasValue - In - IsLower - IsString - IsUpper - Less - LessOrEquals - Match - NotEquals - NotIn - NotMatch - StartsWith The following operators are available: - AllOf - AnyOf - Not The following comparison properties are available: - Field Currently the following limitations apply: - Selectors can only evaluate a field of the target object. The following examples can not be evaluated by selectors: - State variables such as `$PSDocs`. USING SELECTORS AS PRE-CONDITIONS Selectors can be referenced by name as a document pre-condition by using the `-With` parameter. For example: Document 'SampleWithSelector' -With 'BasicSelector' { # Additional content } Selector pre-conditions can be used together with script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before script block pre-conditions. DEFINING SELECTORS Selectors are defined in YAML and can be included within a module or standalone `.Doc.yaml` file. In either case, define a selector within a file ending with the `.Doc.yaml` extension. Use the following template to define a selector: ```yaml SYNOPSIS: {{ SYNOPSIS }} apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: '{{ Name }}' spec: if: { } Within the `if` object, one or more conditions or logical operators can be used. ### AllOf The `allOf` operator is used to require all nested expressions to match. When any nested expression does not match, `allOf` does not match. This is similar to a logical _and_ operation. Syntax: yaml allOf: <expression[]> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleAllOf' spec: if: allOf: # Both Name and Description must exist. - field: 'Name' exists: true - field: 'Description' exists: true ### AnyOf The `anyOf` operator is used to require one or more nested expressions to match. When any nested expression matches, `allOf` matches. This is similar to a logical _or_ operation. Syntax: yaml anyOf: <expression[]> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleAnyOf' spec: if: anyOf: # Name and/ or AlternativeName must exist. - field: 'Name' exists: true - field: 'AlternativeName' exists: true ### Contains The `contains` condition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified. Syntax: yaml contains: <string | array> - If the operand is a field, and the field does not exist, _contains_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleContains' spec: if: anyOf: - field: 'url' contains: '/azure/' - field: 'url' contains: - 'github.io' - 'github.com' ### Equals The `equals` condition can be used to compare if a field is equal to a supplied value. Syntax: yaml equals: <string | int | bool> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleEquals' spec: if: field: 'Name' equals: 'TargetObject1' ### EndsWith The `endsWith` condition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified. Syntax: yaml endsWith: <string | array> - If the operand is a field, and the field does not exist, _endsWith_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleEndsWith' spec: if: anyOf: - field: 'hostname' endsWith: '.com' - field: 'hostname' endsWith: - '.com.au' - '.com' ### Exists The `exists` condition determines if the specified field exists. Syntax: yaml exists: <bool> - When `exists: true`, exists will return `true` if the field exists. - When `exists: false`, exists will return `true` if the field does not exist. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleExists' spec: if: field: 'Name' exists: true ### Field The comparison property `field` is used with a condition to determine field of the object to evaluate. A field can be: - A property name. - A key within a hashtable or dictionary. - An index in an array or collection. - A nested path through an object. Syntax: yaml field: <string> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleField' spec: if: field: 'Properties.securityRules[0].name' exists: true ### Greater Syntax: yaml greater: <int> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleGreater' spec: if: field: 'Name' greater: 3 ### GreaterOrEquals Syntax: yaml greaterOrEquals: <int> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleGreaterOrEquals' spec: if: field: 'Name' greaterOrEquals: 3 ### HasValue The `hasValue` condition determines if the field exists and has a non-empty value. Syntax: yaml hasValue: <bool> - When `hasValue: true`, hasValue will return `true` if the field is not empty. - When `hasValue: false`, hasValue will return `true` if the field is empty. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleHasValue' spec: if: field: 'Name' hasValue: true ### In The `in` condition can be used to compare if a field contains one of the specified values. Syntax: yaml in: <array> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleIn' spec: if: field: 'Name' in: - 'Value1' - 'Value2' ### IsLower The `isLower` condition determines if the operand is a lowercase string. Syntax: yaml isLower: <bool> - When `isLower: true`, _isLower_ will return `true` if the operand is a lowercase string. Non-letter characters are ignored. - When `isLower: false`, _isLower_ will return `true` if the operand is not a lowercase string. - If the operand is a field, and the field does not exist _isLower_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleIsLower' spec: if: field: 'Name' isLower: true ### IsString The `isString` condition determines if the operand is a string or other type. Syntax: yaml isString: <bool> - When `isString: true`, _isString_ will return `true` if the operand is a string. - When `isString: false`, _isString_ will return `true` if the operand is not a string or is null. - If the operand is a field, and the field does not exist _isString_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleIsString' spec: if: field: 'Name' isString: true ### IsUpper The `isUpper` condition determines if the operand is an uppercase string. Syntax: yaml isUpper: <bool> - When `isUpper: true`, _isUpper_ will return `true` if the operand is an uppercase string. Non-letter characters are ignored. - When `isUpper: false`, _isUpper_ will return `true` if the operand is not an uppercase string. - If the operand is a field, and the field does not exist _isUpper_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleIsUpper' spec: if: field: 'Name' isUpper: true ### Less Syntax: yaml less: <int> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleLess' spec: if: field: 'Name' less: 3 ### LessOrEquals Syntax: yaml lessOrEquals: <int> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleLessOrEquals' spec: if: field: 'Name' lessOrEquals: 3 ### Match The `match` condition can be used to compare if a field matches a supplied regular expression. Syntax: yaml match: <string> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleMatch' spec: if: field: 'Name' match: '$(abc|efg)$' ### Not The `any` operator is used to invert the result of the nested expression. When a nested expression matches, `not` does not match. When a nested expression does not match, `not` matches. Syntax: yaml not: <expression> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleNot' spec: if: not: # The AlternativeName field must not exist. field: 'AlternativeName' exists: true ### NotEquals The `notEquals` condition can be used to compare if a field is equal to a supplied value. Syntax: yaml notEquals: <string | int | bool> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleNotEquals' spec: if: field: 'Name' notEquals: 'TargetObject1' ### NotIn The `notIn` condition can be used to compare if a field does not contains one of the specified values. Syntax: yaml notIn: <array> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleNotIn' spec: if: field: 'Name' notIn: - 'Value1' - 'Value2' ### NotMatch The `notMatch` condition can be used to compare if a field does not matches a supplied regular expression. Syntax: yaml notMatch: <string> For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleNotMatch' spec: if: field: 'Name' notMatch: '$(abc|efg)$' ### StartsWith The `startsWith` condition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified. Syntax: yaml startsWith: <string | array> - If the operand is a field, and the field does not exist, _startsWith_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: 'ExampleStartsWith' spec: if: anyOf: - field: 'url' startsWith: 'http' - field: 'url' startsWith: - 'http://' - 'https://' ## EXAMPLES ### Example Selectors.Doc.yaml yaml EXAMPLE SELECTORS.DOC.YAML --- SYNOPSIS: REQUIRE THE CUSTOMVALUE FIELD. apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: RequireCustomValue spec: if: field: 'CustomValue' exists: true --- SYNOPSIS: REQUIRE A NAME OR ALTERNATIVENAME. apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: RequireName spec: if: anyOf: - field: 'AlternateName' exists: true - field: 'Name' exists: true --- SYNOPSIS: REQUIRE A SPECIFIC CUSTOMVALUE apiVersion: github.com/microsoft/PSDocs/v1 kind: Selector metadata: name: RequireSpecificCustomValue spec: if: field: 'CustomValue' in: - 'Value1' - 'Value2' ``` NOTE An online version of this document is available at https://microsoft.github.io/PSDocs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md. SEE ALSO - Invoke-PSDocs KEYWORDS - Selectors - PSDocs |