Naming and formatting

The output for most commands is arranged into aligned columns by default. The format string is distributed into columns using the default separator character, which is a space.

For example, a format string of "%name Release=%release" is distributed into these columns:

• The first column contains one element, the %name keyword.
• The second column contains two elements:

  * The string literal "Release="

  * The keyword %release

A command that reports on three objects might show the following output:

ClientSessionContext.java Release=client/1.0
DisplayNameResourceBundle.java Release=client/2.0
DataNotFoundException.java Release=client/1.0

In the example output, the first column contains spaces to vertically align the second column. The alignment is calculated assuming that the terminal display device uses a monospaced font. If you see incorrectly aligned columns, check that your display device uses a fixed space font rather than a proportional font. You might must set ccm.cli.format.font to the fixed space font for your display device to correct alignment.

A newline character causes a format string to end at the current column. The text following the newline character becomes part of the first column in the next line.

With the -sep|-separator separator option, you can specify a different separator character. For example, consider the format string "%name|Release %release". With the default separator character, the format string consists of two columns as follows:

• The first column contains two elements:

  * The keyword %name

  * The string literal "|Release"

• The second column contains the keyword %release

A command that reports on three objects might show the following output:

ClientSessionContext.java|Release client/1.0
 DisplayNameResourceBundle.java|Release client/2.0
 DataNotFoundException.java|Release client/1.0

Now consider the same format string but with the option -sep "|" specified. The format string is distributed in columns using the pipe separator character:

• The first column contains the keyword %name
• The second column contains two elements:

  * The string literal "Release "

  * The keyword %release

With the same data, the following output is the result:

ClientSessionContext.java Release client/1.0
DisplayNameResourceBundle.java Release client/2.0
DataNotFoundException.java Release client/1.0

The -nf|-noformat option specifies not to use column alignment. When specified, the format string is interpreted as a single column containing all of the elements. Use this option to produce a delimiter-separated output (such as comma-separated).

In the examples described so far, the format strings have consisted of either string literals or simple keywords, such as %release. This might be sufficient to achieve the format you want. However, the Synergy CLI client supports more advanced forms that provide greater control and flexibility.

As described earlier, a format string is first distributed into columns unless you specify the -nf|-noformat option. Each column can consist of a collection of any of these elements:

• A string literal

  This is displayed as is in the output. If you want a single percent sign % to appear in the output, specify a pair, for example %%.

• A keyword

  This is replaced with a string representation of the value of a specified property on the object being reported.

• A column property format element

  This controls some overall formatting of the contents of that column. See Column format elements for more information.

In the previous examples, the simplest form of a keyword was a percent sign followed by the name of a property. For example, %release is replaced with a string representation of the value of a property named release. When the objects being reported are objects in a Synergy database, the property name is either the name of an attribute, or Built-in keywords.

In some cases, the objects being reported might not be database entities. For example, a project membership conflict consists of data, such as the object in conflict, the parent project, the type of conflict, the associated tasks, and so on. To specify what data is reported, you can use an objectkey keyword:

%[objectkey]propertyname

The objectkey specifies the part of the object that the named property refers to. For example, for a project membership conflict, the object object key refers to the file or directory in conflict and the project object key refers to the parent project associated with the conflict. A format string of %[project]displayname %[object]release shows the built-in displayname property of the project associated with each membership conflict, and the release property of the file or directory in conflict.

The details of which object keys are supported are described in each command.

The Synergy CLI supports advanced keywords with any of these forms:

%{keywordspec}
%{keywordspec:-substitutionstring}
%{keywordspec:+substitutionstring}

where a keywordspec can be any of these forms:

propertyname
+propertyname
-propertyname
[objectkey]propertyname
+[objectkey]propertyname
-[objectkey]propertyname
propertyname[propertyformat]
+propertyname[propertyformat]
-propertyname[propertyformat]
[objectkey]propertyname[propertyformat]
+[objectkey]propertyname[propertyformat]
-[objectkey]propertyname[propertyformat]

In each form, the objectkey specifies which object to reference, and the propertyname is the name of a property, such as an attribute or Built-in keywords.

The propertyformat specifies how to convert the property value to a string and then format it. See Property formatting for more information.

The forms using the substitutionstring use an alternate string literal for the expanded keyword whether the specified property or attribute exists.

• The -substitutionstring form means that the specified substitution string is used if the property does not exist. If the property exists, its value is used.
• The +substitutionstring form means that the specified substitution string is used if the property exists, otherwise a string representation of a null value is used.

The optional leading + or - specifies a default sorting order. See Sorting and grouping for more information.

Examples:

The keyword "%{release:-No release}" references the release property of the object. If the property exists, its value is displayed. If the property does not exist, the string "No release" is displayed.

The keyword "%{[project]release[truncate='20']}" references the release property of the project associated with the object. If the property exists, its value is displayed, truncated with ellipsis if it exceeds a width of 20.

When a keyword references a property of an object, its value is converted into a string and formatted using property formatting options. For example, a boolean attribute is converted into a string that represents the boolean true or false value. If a property format is not specified, the property value is converted to a string as follows:

In keywords or Column format elements, you can specify additional controls to format each property value. This is done by specifying a propertyformat that consists of zero, one, or more of these items separated by white space characters:

propertyFormatName=propertyFormatValue
propertyFormatName='singleQuotedPropertyFormatValue'
propertyFormatName="doubleQuotedPropertyFormatValue"

where:

propertyFormatName is a name of a supported property format option.

propertyFormatValue is a value that does not contain white space characters. This value must consist of "word" characters as defined by Java™ regular expression rules.

singleQuotedPropertyFormatValue is a string that can contain any character except a single quote (apostrophe).

doubleQuotedPropertyFormatValue is a string that can contain any character except a double quotation mark.

Example

wrap=20 truncate=100

This specifies that the value is truncated to a maximum of 100 characters, and the characters wrapped to fit in a column width of 20.

Rational Synergy supports these property format names:

null

Specifies a string to represent a null value when the property does not exist.

false

Specifies a string to represent a boolean false value.

true

Specifies a string to represent a boolean true value.

format

Specifies a format string to be used to format the property value. If the string contains "{0", the formatting uses MessageFormat, a standard Java formatting and localization feature. If the string does not contain "{0", the formatting uses printf, a standard Java string formatting feature.

dateformat

Specifies a date format string to be used to format a date property value. The date format must be a valid string for SimpleDateFormat, a standard Java date formatter.

list_begin

Specifies the starting string to be used when the property value is a collection.

list_end

Specifies the ending string to be used when the property value is a collection.

separator

Specifies the item separator to be used when the property value is a collection.

truncate

Specifies the maximum length for the displayed string. If the string is truncated, the string ends with the truncate indicator and be the specified maximum length. By default, the truncate indicator is ellipsis (...).

truncate_each

Specifies the maximum length for each element in a value that is a collection. If the string is truncated, the string ends with the truncate indicator and be the specified maximum length. By default, the truncate indicator is ellipsis (...).

truncate_indicator

Specifies the string to be used to show the truncated display value. By default, the value is ellipsis (...).

wordwrap

Specifies the maximum column width. Also specifies to wrap characters wider than the specified width.

wrap

Specifies the maximum column width. Also specifies to wrap characters wider than the specified width.

keep_trailing_newlines

A value of true preserves the value's trailing newlines in the output.

nocolumn

A value of true specifies to ignore the column for alignment.

indent

Specifies the line indentation width for the property value. The value must be an integer between 1 - 1000, inclusive.

In a format string, you can specify a column format element to control how to format data in that column. When you specify a column format element, the entire column is formatted using the specified options in it. A column format element takes the form:

%[propertyformat]

where propertyformat is a property format described in Property formatting.

For example, consider the format string "%name|%[wrap=20]%version %{release[truncate=30]}" with a separator character of pipe |. The format string consists of two columns:

The first column contains the %name keyword.

The second column contains four elements:

• A column format element "%[wrap=20]" that will result in the column being character wrapped at a width of 20.
• The keyword %version
• The string literal " "
• The keyword %{release[truncate=30]} that will show the release value truncated to a width of 30.

When the second column is processed, the displayed string is determined as follows:

The release property value is converted into a string as required.

1. The string literal " " is appended.
2. The release property value is converted into a string, as required.
3. If necessary, the release string is truncated to a maximum width of 30.
4. The potentially truncated string is appended to the column.
5. The whole column value is character wrapped at a width of 20.

The -f|-format format option specifies a format string to be used. It can use any of the global formatting options. When omitted, commands will use a default format string specific to the subcommand.

With most commands, if sorting is to be performed without sorting or grouping options specified, a default sort algorithm sorts the objects that are reported. If the Selection set is updated, it reflects the order in which the objects were reported in the sorted output.

The default sort algorithm uses the format string and the real property values referenced by the keywords in that format string. For example, if you use the format string "%create_time %release %displayname" for objects in a Synergy database, you'll see this sorting:

1. The create_time attribute as an ascending primary key and using the real date value (not the date string that is displayed)
2. The release attribute as an ascending secondary key
3. The displayname built-in keyword as an ascending tertiary key

   By default, each sort key performs an ascending sort of its property value. You can change it by using one of the advanced keyword forms. See Keywords for further details. For example, the format string "%{-create_time} %{-release} %displayname" sorts using:

4. The create_time attribute as a descending primary key and the real date value (not the date string that is displayed)
5. The release attribute as a descending secondary key
6. The displayname built-in keyword as an ascending tertiary key

   Commands that process arguments in the order they are specified generally do not perform sorting and do not support any of the sorting or grouping related options. An example of such a command is ccm properties.

The -ns|-nosort option disables all sorting and grouping. Use this option to preserve the order of objects as found.

The -sby|-sortby sort_spec option specifies explicit sorting for the output that overrides the default sort algorithm based on the format string. The sort_spec is a list of one or more items of these forms with optional comma separator characters:

propertyname
+propertyname
-propertyname
[objectkey]propertyname

+[objectkey]propertyname
-[objectkey]propertyname

An item with a leading + is used as an ascending sort key. An item with a leading - is used as a descending sort key. An item without either is used as an ascending sort key.

Examples

• create_time,release

  Sort with ascending create_time as the primary key and ascending release as the secondary key.

• -create_time,release

  Sort with descending create_time as the primary key and ascending release as the secondary key.

• +release-create_time

  Sort with ascending release as the primary key and descending create_time as the secondary key.

Note that the properties listed in the sort_spec do not need to appear in the format string. If you specify -sby|-sortby, sorting does not depend on the properties referenced in the format string.

Grouping is another form of sorting. When you specify the -gby|-groupby groupformat option, the values specified in the groupformat format string perform the initial levels of sorting. Objects having an identical set of grouped data values are kept together and preceded by a group header in the output. The group header is formed by expanding the specified groupformat format string. See Format strings for further information.

For example, if you specify -groupby "Release %release:", all objects are sorted using the release property value as the primary key. This takes precedence over any other sort keys. For example if the command reports five objects, two with a release value of 1.0 and three with a release value of 2.0, the objects are grouped as follows:

Release 1.0:
first object with release 1.0
second object with release 1.0

Release 2.0:
first object with release 2.0
second object with release 2.0
third object with release 2.0

If you use both grouping and sorting, the sort keys specified by the groupformat are used first, followed by the sort keys from any sort_spec, or if not specified, the format string. For example, if you specify -groupby "Release %release:" -sortby create_time, sorting uses release as an ascending primary key and create_time as an ascending secondary key.

See the second example in Formatting usage examples for a detailed example of grouping, sorting, and column headers.

Column headers are title strings that are derived from the format string. They appear as headings above each column in the output. For example, if you specify a format string of "%name %release %create_time", the corresponding column headings are Name, Release, and Create_time for columns one, two, and three, respectively.

See the second example in Formatting usage examples for a detailed example of grouping, sorting, and column headers.

Specifies to use column headers for the output. This option cannot be used with the
-nf|-noformat option.

The default is for no column headers to be used.

Specifies not to use column headers for the output. This is the default for most commands.

Commands whose output represents objects in a Synergy database and that set the selection set use numbered output by default. The numbering reflects the selection set reference number used to refer to that object using a Query selection set reference forms.

This specifies that the output will not be numbered. This option has no effect on the ordering of the output or the resulting selection set.

Restricted object names

An object name can contain any combination of alpha numerics and symbols except for those characters that are restricted.

These are some of the Rational Synergy object naming restrictions.

• 8-bit and double-byte characters (with the top bit set) are not permitted in object names.
• Project names must not contain tabs. Makefile names must not contain tabs or spaces.

Other restricted characters, and the reasons they are restricted, are shown in the table.

You cannot use these characters as the first character in an object name:

• , (comma)
• + (plus sign)
• - (dash)
• ~ (tilde)