en-US/about_Jagabata.psm_Filter_parameter.help.txt
|
TOPIC About `-Filter` parameter SHORT DESCRIPTION About `-Filter` parameter on Jagabata.psm's cmdlets. LONG DESCRIPTION Many command, especially those with "File-" have `-Filter` parameter. This allows you to filter the reults using a various set of contiditions. See [Filtering — Automation Controller API Guide](https://docs.ansible.com/automation-controller/latest/html/controllerapi/filtering.html) for specification on what kind of fitering is available. ## Parameter values `-Filter` parameter accepts one or more values separated by commas (`,`). For example: ```powershell Find-xyz -Filter field1=value1, "field2=value2&field3=value3", @{ name="field4"; value="value4" } ``` A parameter value can be accepted following types: ### Type "string" A `key=value` format string, or multiple the formated values combined with `&`. It's means that `string` parameter value is same as HTTP URL query. However, `&` has a special meaning in PowerShell, so if you use `&`, you should quote `"` or `'`. All `key` values are coverted to lowwercase. #### For example: - `field=xyz`. - `"field=xyz&created__gt=2024-01-01"` or `field=xyz, created_gt=2024-01-1`; example with multiple parameter values. - `FIELD=xyz`; same as `field=xyz`; field name is converted to lowercase. ### Type "NameValueCollection" Especially, `NameValueCollection` created by `System.Web.HttpUtility.ParseQueryString(...)`. The specification is almost same as "Type string". #### For example: - `([Web.HttpUtility]::ParseQueryString("field=xyz"))`. - `([Web.HttpUtility]::ParseQueryString("field=xyz&created__gt=2024-01-01"))`. ### Type "IDictionary" Accepts `IDictionary` type like `Hashtable` or `OrderedDictionary` for easy conversion from PowerShell to the following `Jagabata.Cmdlets.Filter` type. #### For example: - `@{ name = "field"; value = "xyz" }` => `field=xyz`. - `@{ NAME = "FIELD"; VALUE = "XYZ" }` => `field=XYZ`; Dictionary Keys are case-insensitive, and `Name` property value is converted to lowercase. - `@{ name = "Field"; value = "xyz"; type = "Contains" }` => `field__contains=xyz`. - `@{ name = "field__contains"; value = "xyz" }` => `field__contains=xyz`; same as above. - `@{ name = "field"; value = "xyz"; or = $true }` => `or__field__contains=xyz`. - `@{ name = "or__field"; value = "xyz" }` => `or__field__contains=xyz`; same as above. - `@{ name = "field"; value = "xyz"; not = $true }` => `not__field__contains=xyz`. - `@{ name = "not__field"; value = "xyz"; not = $true }` => `not__field__contains=xyz`; same as above. - `@{ name = "created"; value = Get-Date 2024-01-01; type = "gt" }` => `creeated__gt=2024-01-01T00:00:00.0000000{TimeZone}`; `DateTime` object is converted to ISO Date string. - `@{ name = "id__in"; value = 1,2,3 }` => `id__in=1,2,3`; `IList` object is converted to commas separeted string. ### Type "Jagabata.Cmdlets.Filter" This is the most primitive object of this filtering mechanism. All of the above types, `string`, `NameValueCollection` and `IDictionary`, are converted once into this `Jagabata.Cmdlets.Filter` type. This type has following properties: - `Name`: (string) The field name to be filtered - `Value`: (string) The field value to be filtered - `Type`: (Enum) Lookup Type - `Excat` : Exact match (default lookup if not specified) - `IExact` : Case-insensitive version of `Exact`. - `Contains` : Field contains value. - `IContains` : Case-insensitive version of `Contains`. - `StartsWith` : Field starts with value. - `IStartsWith` : Case-insensitive version of `StartsWith`. - `EndsWith` : Field ends with value. - `IEndsWith` : Case-insensitive version of `EndsWith`. - `Regex` : Field matches the given regular expression. - `IRegex` : Case-insensitive version of `Regex`. - `GreaterThan`, `GT` : Greater than comparision. - `GreaterThanOrEqual`, `GTE` : Greater than or equal comparision. - `LessThan`, `LT `: Less than comparision. - `LessThanOrEqual`, `LTE` : Less than or equal comparision. - `IsNull` : Check whether the given field or selected object is null; expectes a boolean value. - `In` : Check whether the given field's value is present in the list provided; expects a list of items. - `Or`: (bool) Whether "or__" prefix is appended or not - `Not`: (bool) Whether "not__" prefix is appended or not #### For example: - `[Jagabata.Cmdlets.Filter]::new("field", "xyz")` => `field=xyz`. - `[Jagabata.Cmdlets.Filter]::new("field", "xyz", "icontains")` => `field_icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("field", "xyz", "icontains", $true)` => `or__field__icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("field", "xyz", "icontains", $true, $true)` => `or__not__field__icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("field", "xyz", "icontains", $false, $true)` => `not__field__icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("field__icontains", "xyz")` => `field__icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("or__field__icontains", "xyz")` => `or__field__icontains=xyz`. - `[Jagabata.Cmdlets.Filter]::new("or__not__field__icontains", "xyz")` => `or__not__field__icontains=xyz`. |