2 fontconfig/doc/func.sgml
4 Copyright © 2003 Keith Packard
6 Permission to use, copy, modify, distribute, and sell this software and its
7 documentation for any purpose is hereby granted without fee, provided that
8 the above copyright notice appear in all copies and that both that
9 copyright notice and this permission notice appear in supporting
10 documentation, and that the name of the author(s) not be used in
11 advertising or publicity pertaining to distribution of the software without
12 specific, written prior permission. The authors make no
13 representations about the suitability of this software for any purpose. It
14 is provided "as is" without express or implied warranty.
16 THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
19 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22 PERFORMANCE OF THIS SOFTWARE.
24 <refentry id="FcPatternFormat">
26 <refentrytitle>FcPatternFormat</refentrytitle>
27 <manvolnum>3</manvolnum>
28 <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
31 <refname>FcPatternFormat</refname>
32 <refpurpose>Format a pattern into a string according to a format specifier</refpurpose>
37 #include <fontconfig/fontconfig.h>
40 <funcdef>FcChar8 * <function>FcPatternFormat</function></funcdef>
41 <paramdef>FcPattern *<parameter>pat</parameter></paramdef>
42 <paramdef>const FcChar8 *<parameter>format</parameter></paramdef>
46 <refsect1><title>Description</title>
48 Converts given pattern <parameter>pat</parameter> into text described by
49 the format specifier <parameter>format</parameter>.
50 The return value refers to newly allocated memory which should be freed by the
51 caller using free(), or NULL if <parameter>format</parameter> is invalid.
55 The format is loosely modeled after printf-style format string.
56 The format string is composed of zero or more directives: ordinary
57 characters (not "%"), which are copied unchanged to the output stream;
58 and tags which are interpreted to construct text from the pattern in a
59 variety of ways (explained below).
60 Special characters can be escaped
61 using backslash. C-string style special characters like \n and \r are
62 also supported (this is useful when the format string is not a C string
64 It is advisable to always escape curly braces that
65 are meant to be copied to the output as ordinary characters.
69 Each tag is introduced by the character "%",
70 followed by an optional minimum field width,
71 followed by tag contents in curly braces ({}).
72 If the minimum field width value is provided the tag
73 will be expanded and the result padded to achieve the minimum width.
74 If the minimum field width is positive, the padding will right-align
75 the text. Negative field width will left-align.
76 The rest of this section describes various supported tag contents
81 A <firstterm>simple</firstterm> tag
82 is one where the content is an identifier. When simple
83 tags are expanded, the named identifier will be looked up in
84 <parameter>pattern</parameter> and the resulting list of values returned,
85 joined together using comma. For example, to print the family name and style of the
86 pattern, use the format "%{family} %{style}\n". To extend the family column
87 to forty characters use "%-40{family}%{style}\n".
91 Simple tags expand to list of all values for an element. To only choose
92 one of the values, one can index using the syntax "%{elt[idx]}". For example,
93 to get the first family name only, use "%{family[0]}".
97 If a simple tag ends with "=" and the element is found in the pattern, the
98 name of the element followed by "=" will be output before the list of values.
99 For example, "%{weight=}" may expand to the string "weight=80". Or to the empty
100 string if <parameter>pattern</parameter> does not have weight set.
104 If a simple tag starts with ":" and the element is found in the pattern, ":"
105 will be printed first. For example, combining this with the =, the format
106 "%{:weight=}" may expand to ":weight=80" or to the empty string
107 if <parameter>pattern</parameter> does not have weight set.
111 If a simple tag contains the string ":-", the rest of the the tag contents
112 will be used as a default string. The default string is output if the element
113 is not found in the pattern. For example, the format
114 "%{:weight=:-123}" may expand to ":weight=80" or to the string
115 ":weight=123" if <parameter>pattern</parameter> does not have weight set.
119 A <firstterm>count</firstterm> tag
120 is one that starts with the character "#" followed by an element
121 name, and expands to the number of values for the element in the pattern.
122 For example, "%{#family}" expands to the number of family names
123 <parameter>pattern</parameter> has set, which may be zero.
127 A <firstterm>sub-expression</firstterm> tag
128 is one that expands a sub-expression. The tag contents
129 are the sub-expression to expand placed inside another set of curly braces.
130 Sub-expression tags are useful for aligning an entire sub-expression, or to
131 apply converters (explained later) to the entire sub-expression output.
132 For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
133 to construct the family name followed by the style, then takes the entire
134 string and pads it on the left to be at least forty characters.
138 A <firstterm>filter-out</firstterm> tag
139 is one starting with the character "-" followed by a
140 comma-separated list of element names, followed by a sub-expression enclosed
141 in curly braces. The sub-expression will be expanded but with a pattern that
142 has the listed elements removed from it.
143 For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
144 with <parameter>pattern</parameter> sans the size and pixelsize elements.
148 A <firstterm>filter-in</firstterm> tag
149 is one starting with the character "+" followed by a
150 comma-separated list of element names, followed by a sub-expression enclosed
151 in curly braces. The sub-expression will be expanded but with a pattern that
152 only has the listed elements from the surrounding pattern.
153 For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
154 with a sub-pattern consisting only the family and family lang elements of
155 <parameter>pattern</parameter>.
159 A <firstterm>conditional</firstterm> tag
160 is one starting with the character "?" followed by a
161 comma-separated list of element conditions, followed by two sub-expression
162 enclosed in curly braces. An element condition can be an element name,
163 in which case it tests whether the element is defined in pattern, or
164 the character "!" followed by an element name, in which case the test
165 is negated. The conditional passes if all the element conditions pass.
166 The tag expands the first sub-expression if the conditional passes, and
167 expands the second sub-expression otherwise.
168 For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
169 to "pass" if <parameter>pattern</parameter> has size and dpi elements but
170 no pixelsize element, and to "fail" otherwise.
174 An <firstterm>enumerate</firstterm> tag
175 is one starting with the string "[]" followed by a
176 comma-separated list of element names, followed by a sub-expression enclosed
177 in curly braces. The list of values for the named elements are walked in
178 parallel and the sub-expression expanded each time with a pattern just having
179 a single value for those elements, starting from the first value and
180 continuing as long as any of those elements has a value.
181 For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}"
182 will expand the pattern "%{family} (%{familylang})\n" with a pattern
183 having only the first value of the family and familylang elements, then expands
184 it with the second values, then the third, etc.
188 As a special case, if an enumerate tag has only one element, and that element
189 has only one value in the pattern, and that value is of type FcLangSet, the
190 individual languages in the language set are enumerated.
194 A <firstterm>builtin</firstterm> tag
195 is one starting with the character "=" followed by a builtin
196 name. The following builtins are defined:
202 </term><listitem><para>
203 Expands to the result of calling FcNameUnparse() on the pattern.
204 </para></listitem></varlistentry>
208 </term><listitem><para>
209 Expands to the output of the default output format of the fc-match
210 command on the pattern, without the final newline.
211 </para></listitem></varlistentry>
215 </term><listitem><para>
216 Expands to the output of the default output format of the fc-list
217 command on the pattern, without the final newline.
218 </para></listitem></varlistentry>
222 </term><listitem><para>
223 Expands to the output of the default output format of the fc-cat
224 command on the pattern, without the final newline.
225 </para></listitem></varlistentry>
229 </term><listitem><para>
230 Expands to the list of PackageKit font() tags for the pattern.
231 Currently this includes tags for each family name, and each language
232 from the pattern, enumerated and sanitized into a set of tags terminated
233 by newline. Package management systems can use these tags to tag their
234 packages accordingly.
235 </para></listitem></varlistentry>
239 For example, the format "%{+family,style{%{=unparse}}}\n" will expand
240 to an unparsed name containing only the family and style element values
241 from <parameter>pattern</parameter>.
245 The contents of any tag can be followed by a set of zero or more
246 <firstterm>converter</firstterm>s. A converter is specified by the
247 character "|" followed by the converter name and arguments. The
248 following converters are defined:
254 </term><listitem><para>
255 Replaces text with the results of calling FcStrBasename() on it.
256 </para></listitem></varlistentry>
260 </term><listitem><para>
261 Replaces text with the results of calling FcStrDirname() on it.
262 </para></listitem></varlistentry>
266 </term><listitem><para>
267 Replaces text with the results of calling FcStrDowncase() on it.
268 </para></listitem></varlistentry>
272 </term><listitem><para>
273 Escapes text for one level of shell expansion.
274 (Escapes single-quotes, also encloses text in single-quotes.)
275 </para></listitem></varlistentry>
279 </term><listitem><para>
280 Escapes text such that it can be used as part of a C string literal.
281 (Escapes backslash and double-quotes.)
282 </para></listitem></varlistentry>
286 </term><listitem><para>
287 Escapes text such that it can be used in XML and HTML.
288 (Escapes less-than, greater-than, and ampersand.)
289 </para></listitem></varlistentry>
292 delete(<parameter>chars</parameter>)
293 </term><listitem><para>
294 Deletes all occurrences of each of the characters in <parameter>chars</parameter>
296 FIXME: This converter is not UTF-8 aware yet.
297 </para></listitem></varlistentry>
300 escape(<parameter>chars</parameter>)
301 </term><listitem><para>
302 Escapes all occurrences of each of the characters in <parameter>chars</parameter>
303 by prepending it by the first character in <parameter>chars</parameter>.
304 FIXME: This converter is not UTF-8 aware yet.
305 </para></listitem></varlistentry>
308 translate(<parameter>from</parameter>,<parameter>to</parameter>)
309 </term><listitem><para>
310 Translates all occurrences of each of the characters in <parameter>from</parameter>
311 by replacing them with their corresponding character in <parameter>to</parameter>.
312 If <parameter>to</parameter> has fewer characters than
313 <parameter>from</parameter>, it will be extended by repeating its last
315 FIXME: This converter is not UTF-8 aware yet.
316 </para></listitem></varlistentry>
320 For example, the format "%{family|downcase|delete( )}\n" will expand
321 to the values of the family element in <parameter>pattern</parameter>,
322 lower-cased and with spaces removed.
325 <refsect1><title>Since</title>
326 <para>version 2.9.0</para>