Added string selector conditions #178 (#179)

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+What's changed since pre-release v0.9.0-B2107015:
+
+- General improvements:
+  - Added string selector conditions. [#178](https://github.com/microsoft/PSDocs/issues/178)
+    - Use `startWith`, `contains`, and `endsWith` to check for a sub-string.
+    - Use `isString`, `isLower`, and `isUpper` to check for string type and casing.
+    - See [about_PSDocs_Selectors] and [about_PSDocs_Options] for more details.
+
 ## v0.9.0-B2107015 (pre-release)
 
 What's changed since pre-release v0.9.0-B2107010:
@@ -22,7 +30,7 @@ What's changed since pre-release v0.9.0-B2107002:
     - Script block based conditions are PowerShell code that can be added to `Document` blocks with `-If`.
     - Selector block based conditions are YAML filters that can be added to `Document` blocks with `-With`.
     - Added options for configuring processing of input.
-    - See [about_PSDocs_Options] for more details.
+    - See [about_PSDocs_Selectors] and [about_PSDocs_Options] for more details.
 - General improvements:
   - Added schema for PSDocs configuration options within `ps-docs.yaml`. [#113](https://github.com/Microsoft/PSDocs/issues/113)
 
@@ -326,3 +334,4 @@ What's changed since v0.1.0:
 [about_PSDocs_Conventions]: docs/concepts/PSDocs/en-US/about_PSDocs_Conventions.md
 [about_PSDocs_Keywords]: docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md
 [about_PSDocs_Options]: docs/concepts/PSDocs/en-US/about_PSDocs_Options.md
+[about_PSDocs_Selectors]: docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md

README.md

@@ -135,20 +135,26 @@ The following conceptual topics exist in the `PSDocs` module:
 - [Selectors](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md)
   - [AllOf](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#allof)
   - [AnyOf](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#anyof)
-  - [Exists](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#exists)
+  - [Contains](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#contains)
   - [Equals](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#equals)
+  - [EndsWith](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#endswith)
+  - [Exists](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#exists)
   - [Field](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#field)
   - [Greater](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#greater)
   - [GreaterOrEquals](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#greaterorequals)
   - [HasValue](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#hasvalue)
   - [In](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#in)
+  - [IsLower](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#islower)
+  - [IsString](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#isstring)
+  - [IsUpper](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#isupper)
   - [Less](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#less)
   - [LessOrEquals](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#lessorequals)
   - [Match](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#match)
   - [Not](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#not)
   - [NotEquals](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#notequals)
   - [NotIn](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#notin)
   - [NotMatch](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#notmatch)
+  - [StartsWith](docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md#startswith)
 - [Variables](docs/concepts/PSDocs/en-US/about_PSDocs_Variables.md)
   - [$Culture](docs/concepts/PSDocs/en-US/about_PSDocs_Variables.md#culture)
   - [$Document](docs/concepts/PSDocs/en-US/about_PSDocs_Variables.md#document)

docs/concepts/PSDocs/en-US/about_PSDocs_Selectors.md

@@ -19,18 +19,24 @@ When evaluating an object from input, PSDocs can use selectors to perform comple
 
 The following conditions are available:
 
-- [Exists](#exists)
+- [Contains](#contains)
 - [Equals](#equals)
+- [EndsWith](#endswith)
+- [Exists](#exists)
 - [Greater](#greater)
 - [GreaterOrEquals](#greaterorequals)
 - [HasValue](#hasvalue)
 - [In](#in)
+- [IsLower](#islower)
+- [IsString](#isstring)
+- [IsUpper](#isupper)
 - [Less](#less)
 - [LessOrEquals](#lessorequals)
 - [Match](#match)
 - [NotEquals](#notequals)
 - [NotIn](#notin)
 - [NotMatch](#notmatch)
+- [StartsWith](#startswith)
 
 The following operators are available:
 
@@ -59,8 +65,8 @@ Document 'SampleWithSelector' -With 'BasicSelector' {
 }
 ```
 
-Selector pre-conditions can be used together with type and script block pre-conditions.
-If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.
+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
 
@@ -140,30 +146,35 @@ spec:
       exists: true
 ```
 
-### Exists
+### Contains
 
-The `exists` condition determines if the specified field exists.
+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
-exists: <bool>
+contains: <string | array>
 ```
 
-- When `exists: true`, exists will return `true` if the field exists.
-- When `exists: false`, exists will return `true` if the field does not exist.
+- 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: 'ExampleExists'
+  name: 'ExampleContains'
 spec:
   if:
-    field: 'Name'
-    exists: true
+    anyOf:
+    - field: 'url'
+      contains: '/azure/'
+    - field: 'url'
+      contains:
+      - 'github.io'
+      - 'github.com'
 ```
 
 ### Equals
@@ -189,6 +200,63 @@ spec:
     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.
@@ -311,6 +379,89 @@ spec:
     - '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:
@@ -474,6 +625,37 @@ spec:
     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