1FcPatternFormat(3)                                          FcPatternFormat(3)
2
3
4

NAME

6       FcPatternFormat  - Format a pattern into a string according to a format
7       specifier
8

SYNOPSIS

10       #include <fontconfig/fontconfig.h>
11
12       FcChar8 * FcPatternFormat (FcPattern *pat, const FcChar8 *format);
13

DESCRIPTION

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
19       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
23       variety of ways (explained below).  Special characters can  be  escaped
24       using  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
29       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
37       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
44       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
48       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
54       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
59       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
65       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
70       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
79       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
81       enclosed in curly braces. The sub-expression will be expanded but  with
82       a  pattern  that has the listed elements removed from it.  For example,
83       the format "%{-size,pixelsize{sub-expr}}" will expand  "sub-expr"  with
84       pattern sans the size and pixelsize elements.
85
86       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
88       enclosed  in curly braces. The sub-expression will be expanded but with
89       a pattern that only has the listed elements from the  surrounding  pat‐
90       tern.   For  example, the format "%{+family,familylang{sub-expr}}" will
91       expand "sub-expr" with a sub-pattern consisting  only  the  family  and
92       family lang elements of pattern.
93
94       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
106       An  enumerate  tag  is  one starting with the string "[]" followed by a
107       comma-separated list of element names,  followed  by  a  sub-expression
108       enclosed 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
118       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
122       A  builtin  tag  is  one  starting with the character "=" followed by a
123       builtin name. The following builtins are defined:
124
125       unparse
126              Expands to the result of calling FcNameUnparse() on the pattern.
127
128       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
132       fclist Expands  to  the  output of the default output format of the fc-
133              list command on the pattern, without the final newline.
134
135       fccat  Expands to the output of the default output format of the fc-cat
136              command on the pattern, without the final newline.
137
138       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
144       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
148       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
152       basename
153              Replaces text with the results of calling FcStrBasename() on it.
154
155       dirname
156              Replaces text with the results of calling FcStrDirname() on it.
157
158       downcase
159              Replaces text with the results of calling FcStrDowncase() on it.
160
161       shescape
162              Escapes text for one level of shell expansion.  (Escapes single-
163              quotes, also encloses text in single-quotes.)
164
165       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
169       xmlescape
170              Escapes text such that it can be used in XML and HTML.  (Escapes
171              less-than, greater-than, and ampersand.)
172
173       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
177       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
182       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
189       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

SINCE

194       version 2.9.0
195
196
197
198Fontconfig 2.13.1                 30 8月 2018               FcPatternFormat(3)
Impressum