THE ISSUE
The incorrect use of quotations can result in errors, this happens when a special character is used or the OS terminal does not accept the used quotations.
The use of quotations differs from environment to environment, and it also depends on the application and tool that you are using.
For example, single quotes are accepted on the command line where the terminal processor handles the single quotes but not when running actions in a run script.
If you use single quotes in a terminal environment, the variables in double quotes are converted to their value, if you use single quotes, the variables are not converted to their value.
SOLUTION
Follow the examples in the Quotations-Usage table, to ensure that you use the correct quotations for the environment.
When required, adopt the special character parameter.
Quotation Usage Table
ENVIRONMENTS AND SPECIFIC CASES | EXAMPLE |
|---|---|
Windows Command Terminal | Use embedded double quotes within a double-quoted string. “-a addComment --comment ““This is an example of a double quoted string inside a double quote”” “ |
LINUX and MAC/OS terminals | LINUX quotes are used. -common “ -a addComment --comment \ ”This is an example of a double quoted string \ ” ” |
RUN CLI Actions | Use the same syntax as on the Windows terminal “-a addComment --comment ““This is an example of a double quoted string inside a double quote”” “ |
Comma Separated Parameters | For parameters that allow entry of a comma separated list of values, the values that contain a comma must be enclosed in single quotes. Embedded single quotes within a quoted string must be doubled. --custom “ 'first:a,b,c' second: x” |
Run Scripts | Action in run scripts do not accept single quotes, hence use the same syntax as on the Windows terminal run: “-a addComment --comment ““This is an example of a double quoted string inside a double quote”” “ |
Text Fields | Text fields may support the automatic conversion of " \n " (blanks are significant) to be replaced with a new line character. --description "A multi-line text field: \n # line 1 \n # line 2" |
THE SPECIAL CHARACTERS PARAMETER
Special characters can pose problems due to the special meaning they may have in:
the OS command terminal
the tool command line parsing
the tool use of separators such as comma or colon separated lists
The special parameter allows for converting a special character in the user’s data to an alternative character within the parameter values.
For example, if you have a parameter that accepts comma separated values and one of the values contains the # symbol instead of a comma, the # symbol needs to be converted so that the values can be treated as separate.
Give the special parameter a specific substitute character.
The substitute character is replaced with the real character after all other parsing occurs.
--parameter abc, def#ghi
To treat def and ghi as separate values, # must be replaced with a comma.
The choice of what special characters to use depends on the content so that you do not have conflicts with intended content.
The table provides a list of the most frequent special characters and suggestions on which replacement character to use.
Position | Character | Character name | Suggested alternative | Usage |
|---|---|---|---|---|
1 | , | comma |
| Some parameters use comma separated lists. |
2 | : | colon | # | Some parameters use colon separated values. |
3 | @ | at sign |
| Replacement variables syntax: @...@. |
4 | ' | single quote |
| Used in separated lists to cover cases where content contains separator. |
5 | " | double quote | ~ | Parameters containing blanks. |
6 | ^ | caret |
| Substitution double quote indicator: ^^...^^. See ACLI-673 for details. |
A blank in any position is ignored (no alternative provided).
Example: –special " # ~" provides alternates for colon and double quote.
--common "--findReplace ~something to find containing a : (colon)#replacement~"