Synergy Advance help: format strings

Basics

Synergy Advance makes use of user-definable format strings in a number of places to allow a high degree of customization of text. A "string" is merely a string of textual characters. A "format string" is a special kind of string that describes the format that a string should take. Format strings are commonly used in programming because they are a compact way of representing textual patterns. Traditionally the percent symbol (%) has been used to introduce a format marker; the character that immediately follows the percent symbol indicates what kind of information should be inserted in the string.

The following is an example of a simple format string. The "%t" is a format marker because it is introduced by a percent symbol; it indicates that the current track title should be inserted in the string at that point, replacing the format marker. The "%a" is also a format marker and it indicates that the artist of the current track should be substituted at that point:

Track title: %t by %a

If the current track title is "Se esfuma tu amor" and the artist is "Marc Anthony", then the format string will be translated into the following at runtime:

Track title: Se esfuma tu amor by Marc Anthony

Format strings are case sensitive. If you change "%t" to "%T", or "%a" to "%A" in the example above then no substitution will occur and Synergy Advance will print a warning to the console indicating that "%T" and "%A" are not valid format markers (unless you've turned the logging level down to zero in the Advanced preferences).

As of version 0.5, Synergy Advance provides you with instant feedback during editing to let you know whether the current format string is valid. It does this by showing a small triangular warning icon next to any invalid format string in the user interface. Clicking on the warning icon brings you to this help page in your web browser.

Literal percent symbols

So if the percent symbol is used to introduce a format marker, how do you include a literal percent symbol in your format string? The answer is to immediately follow the percent symbol by a second percent symbol; Synergy Advance will interpret that to mean "literal percent symbol" and will print a single percent symbol in the output. Thus, this format string:

100%% Gold!

Will be printed as follows in the final output:

100% Gold!

Where are format strings used in Synergy Advance?

Synergy Advance uses format strings in places where it must output textual (non-graphical) information. For example, if you use Synergy Advance to send Growl notifications or you use it to update your iChat status line automatically. In both cases the target which receives that information (Growl or iChat respectively) expects to receive a textual string. If you look at the Instant Messaging or Growl preference panes you will see spaces in which you can enter custom format strings. The user interface displays a list of available format markers so that you don't have to constantly refer to the documentation to remind yourself what the different markers are.

Format string reference

%t	track title
%a	artist
%c	composer
%b	album
%e	genre
%p	player state ("Playing", "Paused", "Stopped")
%z	year
%r	rating (displayed as stars)
%n	track number
%k	track count
%d	disc number
%u	disc count
%g	grouping
%i	total time
%x	date added
%m	BPM
%y	play count
%%	literal %