1FcPatternFormat(3) FcPatternFormat(3)
2
6 FcPatternFormat - Format a pattern into a string according to a format
7 specifier
8
10 #include <fontconfig.h>
11 FcChar8 * FcPatternFormat(FcPattern *pat);
13 (const FcChar8 *format);
14 .fi
15
17 Converts given pattern pat into text described by the format specifier
18 format. The return value refers to newly allocated memory which should
19 be freed by the caller using free(), or NULL if format is invalid.
20 The format is loosely modelled after printf-style format string. The
22 format string is composed of zero or more directives: ordinary charac‐
23 ters (not "%"), which are copied unchanged to the output stream; and
24 tags which are interpreted to construct text from the pattern in a
25 variety of ways (explained below). Special characters can be escaped
26 using backslash. C-string style special characters like \n and \r are
27 also supported (this is useful when the format string is not a C string
28 literal). It is advisable to always escape curly braces that are meant
29 to be copied to the output as ordinary characters.
30 Each tags is introduced by the character "%", followed by an optional
32 minimum field width, followed by tag contents in curly braces ({}). If
33 the minimum field width value is provided the tag will be expanded and
34 the result padded to achieve the minimum width. If the minimum field
35 width is positive, the padding will right-align the text. Negative
36 field width will left-align. The rest of this section describes vari‐
37 ous supported tag contents and their expansion.
38 A simple tag is one where the content is an identifier. When simple
40 tags are expanded, the named identifier will be looked up in pattern
41 and the resulting list of values returned, joined together using comma.
42 For example, to print the family name and style the pattern, use the
43 format "%{family} %{style}\n". To extend the family column to forty
44 characters use "%-40{family}%{style}\n".
45 Simple tags expand to list of all values for an element. To only choose
47 one of the values, one can index using the syntax "%{elt[idx]}". For
48 example, to get the first family name only, use "%{family[0]}".
49 If a simple tag ends with "=" and the element is found in the pattern,
51 the name of the element followed by "=" will be output before the list
52 of values. For example, "%{weight=}" may expand to the string
53 "weight=80". Or to the empty string if pattern does not have weight
54 set.
55 If a simple tag starts with ":" and the element is found in the pat‐
57 tern, ":" will be printed first. For example, combining this with the
58 =, the format "%{:weight=}" may expand to ":weight=80" or to the empty
59 string if pattern does not have weight set.
60 If a simple tag contains the string ":-", the rest of the the tag con‐
62 tents will be used as a default string. The default string is output if
63 the element is not found in the pattern. For example, the format
64 "%{:weight=:-123}" may expand to ":weight=80" or to the string
65 ":weight=123" if pattern does not have weight set.
66 A count tag is one that starts with the character "#" followed by an
68 element name, and expands to the number of values for the element in
69 the pattern. For example, "%{#family}" expands to the number of family
70 names pattern has set, which may be zero.
71 A sub-expression tag is one that expands a sub-expression. The tag con‐
73 tents are the sub-expression to expand placed inside another set of
74 curly braces. Sub-expression tags are useful for aligning an entire
75 sub-expression, or to apply converters (explained later) on an entire
76 sub-expression. For example, the format "%40{{%{family} %{style}}}"
77 expands the sub-expression to construct the family name followed by the
78 style, then takes the entire string and pads it on the left to be at
79 least forty characters.
80 A filter-out tag is one starting with the character "-" followed by a
82 comma-separated list of element names, followed by a sub-expression
83 enclosed in curly braces. The sub-expression will be expanded but with
84 a pattern that has the listed elements removed from it. For example,
85 the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr" with
86 pattern sans the size and pixelsize elements.
87 A filter-in tag is one starting with the character "+" followed by a
89 comma-separated list of element names, followed by a sub-expression
90 enclosed in curly braces. The sub-expression will be expanded but with
91 a pattern that only has the listed elements from the surrounding pat‐
92 tern. For example, the format "%{+family,familylang{sub-expr}}" will
93 expand "sub-expr" with a sub-pattern consisting only the family and
94 family lang elements of pattern.
95 A conditional tag is one starting with the character "?" followed by a
97 comma-separated list of element conditions, followed by two sub-expres‐
98 sion enclosed in curly braces. An element condition can be an element
99 name, in which case it tests whether the element is defined in pattern,
100 or the character "!" followed by an element name, in which case the
101 test is negated. The conditional passes if all the element conditions
102 pass. The tag expands the first sub-expression if the conditional
103 passes, and expands the second sub-expression otherwise. For example,
104 the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand to "pass"
105 if pattern has size and dpi elements but no pixelsize element, and to
106 "fail" otherwise.
107 An enumerate tag is one starting with the string "[]" followed by a
109 comma-separated list of element names, followed by a sub-expression
110 enclosed in curly braces. The list of values for the named elements are
111 walked in parallel and the sub-expression expanded each time with a
112 pattern just having a single value for those elements, starting from
113 the first value and continuing as long as any of those elements has a
114 value. For example, the format "%{[]family,familylang{%{family}
115 (%{familylang})\n}}" will expand the pattern "%{family} (%{family‐
116 lang})\n" with a pattern having only the first value of the family and
117 familylang elemtns, then expands it with the second values, then the
118 third, etc.
119 As a special case, if an enumerate tag has only one element, and that
121 element has only one value in the pattern, and that value is of type
122 FcLangSet, the individual languages in the language set are enumerated.
123 A builtin tag is one starting with the character "=" followed by a
125 builtin name. The following builtins are defined:
126 unparse
128 Expands to the result of calling FcNameUnparse() on the pattern.
129 fcmatch
131 Expands to the output of the default output format of the fc-
132 match command on the pattern, without the final newline.
133 fclist Expands to the output of the default output format of the fc-
135 list command on the pattern, without the final newline.
136 pkgkit Expands to the list of PackageKit font() tags for the pattern.
138 Currently this includes tags for each family name, and each lan‐
139 guage from the pattern, enumerated and sanitized into a set of
140 tags terminated by newline. Package management systems can use
141 these tags to tag their packages accordingly.
142 For example, the format "%{+family,style{%{=unparse}}}\n" will expand
144 to an unparsed name containing only the family and style element values
145 from pattern.
146 The contents of any tag can be followed by a set of zero or more con‐
148 verters. A converter is specified by the character "|" followed by the
149 converter name and arguments. The following converters are defined:
150 basename
152 Replaces text with the results of calling FcStrBasename() on it.
153 dirname
155 Replaces text with the results of calling FcStrDirname() on it.
156 downcase
158 Replaces text with the results of calling FcStrDowncase() on it.
159 shescape
161 Escapes text for one level of shell expansion. (Escapes single-
162 quotes, also encloses text in single-quotes.)
163 cescape
165 Escapes text such that it can be used as part of a C string lit‐
166 eral. (Escapes backslash and double-quotes.)
167 xmlescape
169 Escapes text such that it can be used in XML and HTML. (Escapes
170 less-than, greater-than, and ampersand.)
171 delete(chars)
173 Deletes all occurrences of each of the characters in chars from
174 the text. FIXME: This converter is not UTF-8 aware yet.
175 escape(chars)
177 Escapes all occurrences of each of the characters in chars by
178 prepending it by the first character in chars. FIXME: This con‐
179 verter is not UTF-8 aware yet.
180 translate(from,to)
182 Translates all occurrences of each of the characters in from by
183 replacing them with their corresponding character in to. If to
184 has fewer characters than from, it will be extended by repeating
185 its last character. FIXME: This converter is not UTF-8 aware
186 yet.
187 For example, the format "%{family|downcase|delete( )}\n" will expand to
189 the values of the family element in pattern, lower-cased and with spa‐
190 ces removed.
191
193 Fontconfig version 2.8.0
194 18 November 2009 FcPatternFormat(3)