doc: Improve doc of flags --filter and --format

Signed-off-by: Arthur Amstutz <arthur.amstutz@corp.ovh.com>

Author: amstuta

doc/ovhcloud_account.md

@@ -12,7 +12,14 @@ Manage your account
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api.md

@@ -12,7 +12,14 @@ Manage your API credentials
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2.md

@@ -12,7 +12,14 @@ Manage your OAuth2 clients
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client.md

@@ -12,7 +12,14 @@ Manage your OAuth2 clients
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client_create.md

@@ -24,7 +24,14 @@ ovhcloud account api oauth2 client create [flags]
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client_delete.md

@@ -16,7 +16,14 @@ ovhcloud account api oauth2 client delete <client_id> [flags]
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client_edit.md

@@ -20,7 +20,14 @@ ovhcloud account api oauth2 client edit <client_id> [flags]
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client_get.md

@@ -16,7 +16,14 @@ ovhcloud account api oauth2 client get <client_id> [flags]
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_api_oauth2_client_list.md

@@ -9,15 +9,28 @@ ovhcloud account api oauth2 client list [flags]
 ### Options
 
 ```
-      --filter stringArray   Filter results by any property using https://github.com/PaesslerAG/gval syntax'
+      --filter stringArray   Filter results by any property using https://github.com/PaesslerAG/gval syntax
+                             Examples:
+                               --filter 'state="running"'
+                               --filter 'name=~"^my.*"'
+                               --filter 'nested.property.subproperty>10'
+                               --filter 'startDate>="2023-12-01"'
+                               --filter 'name=~"something" && nbField>10'
   -h, --help                 help for list
 ```
 
 ### Options inherited from parent commands
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON

doc/ovhcloud_account_ssh-key.md

@@ -12,7 +12,14 @@ Manage your SSH keys
 
 ```
   -d, --debug           Activate debug mode (will log all HTTP requests details)
-  -f, --format string   Output value according to given format (expression using gval format)
+  -f, --format string   Output value according to given format (expression using https://github.com/PaesslerAG/gval syntax)
+                        Examples:
+                          --format 'id' (to extract a single field)
+                          --format 'nested.field.subfield' (to extract a nested field)
+                          --format '[id, 'name']' (to extract multiple fields as an array)
+                          --format '{"newKey": oldKey, "otherKey": nested.field}' (to extract and rename fields in an object)
+                          --format 'name+","+type' (to extract and concatenate fields in a string)
+                          --format '(nbFieldA + nbFieldB) * 10' (to compute values from numeric fields)
   -e, --ignore-errors   Ignore errors in API calls when it is not fatal to the execution
   -i, --interactive     Interactive output
   -j, --json            Output in JSON