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