]>
Commit | Line | Data |
---|---|---|
1 | /* | |
2 | * fontconfig/doc/fcformat.fncs | |
3 | * | |
4 | * Copyright © 2008 Behdad Esfahbod | |
5 | * | |
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 Keith Packard not be used in | |
11 | * advertising or publicity pertaining to distribution of the software without | |
12 | * specific, written prior permission. Keith Packard makes no | |
13 | * representations about the suitability of this software for any purpose. It | |
14 | * is provided "as is" without express or implied warranty. | |
15 | * | |
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. | |
23 | */ | |
24 | ||
25 | @RET@ FcChar8 * | |
26 | @FUNC@ FcPatternFormat | |
27 | @TYPE1@ FcPattern * @ARG1@ pat | |
28 | @TYPE2@ const FcChar8 * @ARG2@ format | |
29 | @PURPOSE@ Format a pattern into a string according to a format specifier | |
30 | @DESC@ | |
31 | ||
32 | Converts given pattern <parameter>pat</parameter> into text described by | |
33 | the format specifier <parameter>format</parameter>. | |
34 | The return value refers to newly allocated memory which should be freed by the | |
35 | caller using free(), or NULL if <parameter>format</parameter> is invalid. | |
36 | ||
37 | </para><para> | |
38 | ||
39 | The format is loosely modelled after printf-style format string. | |
40 | The format string is composed of zero or more directives: ordinary | |
41 | characters (not "%"), which are copied unchanged to the output stream; | |
42 | and tags which are interpreted to construct text from the pattern in a | |
43 | variety of ways (explained below). | |
44 | Special characters can be escaped | |
45 | using backslash. C-string style special characters like \n and \r are | |
46 | also supported (this is useful when the format string is not a C string | |
47 | literal). | |
48 | It is advisable to always escape curly braces that | |
49 | are meant to be copied to the output as ordinary characters. | |
50 | ||
51 | </para><para> | |
52 | ||
53 | Each tags is introduced by the character "%", | |
54 | followed by an optional minimum field width, | |
55 | followed by tag contents in curly braces ({}). | |
56 | If the minimum field width value is provided the tag | |
57 | will be expanded and the result padded to achieve the minimum width. | |
58 | If the minimum field width is positive, the padding will right-align | |
59 | the text. Negative field width will left-align. | |
60 | The rest of this section describes various supported tag contents | |
61 | and their expansion. | |
62 | ||
63 | </para><para> | |
64 | ||
65 | A <firstterm>simple</firstterm> tag | |
66 | is one where the content is an identifier. When simple | |
67 | tags are expanded, the named identifier will be looked up in | |
68 | <parameter>pattern</parameter> and the resulting list of values returned, | |
69 | joined together using comma. For example, to print the family name and style the | |
70 | pattern, use the format "%{family} %{style}\n". To extend the family column | |
71 | to forty characters use "%-40{family}%{style}\n". | |
72 | ||
73 | </para><para> | |
74 | ||
75 | Simple tags expand to list of all values for an element. To only choose | |
76 | one of the values, one can index using the syntax "%{elt[idx]}". For example, | |
77 | to get the first family name only, use "%{family[0]}". | |
78 | ||
79 | </para><para> | |
80 | ||
81 | If a simple tag ends with "=" and the element is found in the pattern, the | |
82 | name of the element followed by "=" will be output before the list of values. | |
83 | For example, "%{weight=}" may expand to the string "weight=80". Or to the empty | |
84 | string if <parameter>pattern</parameter> does not have weight set. | |
85 | ||
86 | </para><para> | |
87 | ||
88 | If a simple tag starts with ":" and the element is found in the pattern, ":" | |
89 | will be printed first. For example, combining this with the =, the format | |
90 | "%{:weight=}" may expand to ":weight=80" or to the empty string | |
91 | if <parameter>pattern</parameter> does not have weight set. | |
92 | ||
93 | </para><para> | |
94 | ||
95 | If a simple tag contains the string ":-", the rest of the the tag contents | |
96 | will be used as a default string. The default string is output if the element | |
97 | is not found in the pattern. For example, the format | |
98 | "%{:weight=:-123}" may expand to ":weight=80" or to the string | |
99 | ":weight=123" if <parameter>pattern</parameter> does not have weight set. | |
100 | ||
101 | </para><para> | |
102 | ||
103 | A <firstterm>count</firstterm> tag | |
104 | is one that starts with the character "#" followed by an element | |
105 | name, and expands to the number of values for the element in the pattern. | |
106 | For example, "%{#family}" expands to the number of family names | |
107 | <parameter>pattern</parameter> has set, which may be zero. | |
108 | ||
109 | </para><para> | |
110 | ||
111 | A <firstterm>sub-expression</firstterm> tag | |
112 | is one that expands a sub-expression. The tag contents | |
113 | are the sub-expression to expand placed inside another set of curly braces. | |
114 | Sub-expression tags are useful for aligning an entire sub-expression, or to | |
115 | apply converters (explained later) on an entire sub-expression. | |
116 | For example, the format "%40{{%{family} %{style}}}" expands the sub-expression | |
117 | to construct the family name followed by the style, then takes the entire | |
118 | string and pads it on the left to be at least forty characters. | |
119 | ||
120 | </para><para> | |
121 | ||
122 | A <firstterm>filter-out</firstterm> tag | |
123 | is one starting with the character "-" followed by a | |
124 | comma-separated list of element names, followed by a sub-expression enclosed | |
125 | in curly braces. The sub-expression will be expanded but with a pattern that | |
126 | has the listed elements removed from it. | |
127 | For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr" | |
128 | with <parameter>pattern</parameter> sans the size and pixelsize elements. | |
129 | ||
130 | </para><para> | |
131 | ||
132 | A <firstterm>filter-in</firstterm> tag | |
133 | is one starting with the character "+" followed by a | |
134 | comma-separated list of element names, followed by a sub-expression enclosed | |
135 | in curly braces. The sub-expression will be expanded but with a pattern that | |
136 | only has the listed elements from the surrounding pattern. | |
137 | For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr" | |
138 | with a sub-pattern consisting only the family and family lang elements of | |
139 | <parameter>pattern</parameter>. | |
140 | ||
141 | </para><para> | |
142 | ||
143 | A <firstterm>conditional</firstterm> tag | |
144 | is one starting with the character "?" followed by a | |
145 | comma-separated list of element conditions, followed by two sub-expression | |
146 | enclosed in curly braces. An element condition can be an element name, | |
147 | in which case it tests whether the element is defined in pattern, or | |
148 | the character "!" followed by an element name, in which case the test | |
149 | is negated. The conditional passes if all the element conditions pass. | |
150 | The tag expands the first sub-expression if the conditional passes, and | |
151 | expands the second sub-expression otherwise. | |
152 | For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand | |
153 | to "pass" if <parameter>pattern</parameter> has size and dpi elements but | |
154 | no pixelsize element, and to "fail" otherwise. | |
155 | ||
156 | </para><para> | |
157 | ||
158 | An <firstterm>enumerate</firstterm> tag | |
159 | is one starting with the string "[]" followed by a | |
160 | comma-separated list of element names, followed by a sub-expression enclosed | |
161 | in curly braces. The list of values for the named elements are walked in | |
162 | parallel and the sub-expression expanded each time with a pattern just having | |
163 | a single value for those elements, starting from the first value and | |
164 | continuing as long as any of those elements has a value. | |
165 | For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}" | |
166 | will expand the pattern "%{family} (%{familylang})\n" with a pattern | |
167 | having only the first value of the family and familylang elemtns, then expands | |
168 | it with the second values, then the third, etc. | |
169 | ||
170 | </para><para> | |
171 | ||
172 | As a special case, if an enumerate tag has only one element, and that element | |
173 | has only one value in the pattern, and that value is of type FcLangSet, the | |
174 | individual languages in the language set are enumerated. | |
175 | ||
176 | </para><para> | |
177 | ||
178 | A <firstterm>builtin</firstterm> tag | |
179 | is one starting with the character "=" followed by a builtin | |
180 | name. The following builtins are defined: | |
181 | ||
182 | <variablelist> | |
183 | ||
184 | <varlistentry><term> | |
185 | unparse | |
186 | </term><listitem><para> | |
187 | Expands to the result of calling FcNameUnparse() on the pattern. | |
188 | </para></listitem></varlistentry> | |
189 | ||
190 | <varlistentry><term> | |
191 | fcmatch | |
192 | </term><listitem><para> | |
193 | Expands to the output of the default output format of the fc-match | |
194 | command on the pattern, without the final newline. | |
195 | </para></listitem></varlistentry> | |
196 | ||
197 | <varlistentry><term> | |
198 | fclist | |
199 | </term><listitem><para> | |
200 | Expands to the output of the default output format of the fc-list | |
201 | command on the pattern, without the final newline. | |
202 | </para></listitem></varlistentry> | |
203 | ||
204 | <varlistentry><term> | |
205 | pkgkit | |
206 | </term><listitem><para> | |
207 | Expands to the list of PackageKit font() tags for the pattern. | |
208 | Currently this includes tags for each family name, and each language | |
209 | from the pattern, enumerated and sanitized into a set of tags terminated | |
210 | by newline. Package management systems can use these tags to tag their | |
211 | packages accordingly. | |
212 | </para></listitem></varlistentry> | |
213 | ||
214 | </variablelist> | |
215 | ||
216 | For example, the format "%{+family,style{%{=unparse}}}\n" will expand | |
217 | to an unparsed name containing only the family and style element values | |
218 | from <parameter>pattern</parameter>. | |
219 | ||
220 | </para><para> | |
221 | ||
222 | The contents of any tag can be followed by a set of zero or more | |
223 | <firstterm>converter</firstterm>s. A converter is specified by the | |
224 | character "|" followed by the converter name and arguments. The | |
225 | following converters are defined: | |
226 | ||
227 | <variablelist> | |
228 | ||
229 | <varlistentry><term> | |
230 | basename | |
231 | </term><listitem><para> | |
232 | Replaces text with the results of calling FcStrBasename() on it. | |
233 | </para></listitem></varlistentry> | |
234 | ||
235 | <varlistentry><term> | |
236 | dirname | |
237 | </term><listitem><para> | |
238 | Replaces text with the results of calling FcStrDirname() on it. | |
239 | </para></listitem></varlistentry> | |
240 | ||
241 | <varlistentry><term> | |
242 | downcase | |
243 | </term><listitem><para> | |
244 | Replaces text with the results of calling FcStrDowncase() on it. | |
245 | </para></listitem></varlistentry> | |
246 | ||
247 | <varlistentry><term> | |
248 | shescape | |
249 | </term><listitem><para> | |
250 | Escapes text for one level of shell expansion. | |
251 | (Escapes single-quotes, also encloses text in single-quotes.) | |
252 | </para></listitem></varlistentry> | |
253 | ||
254 | <varlistentry><term> | |
255 | cescape | |
256 | </term><listitem><para> | |
257 | Escapes text such that it can be used as part of a C string literal. | |
258 | (Escapes backslash and double-quotes.) | |
259 | </para></listitem></varlistentry> | |
260 | ||
261 | <varlistentry><term> | |
262 | xmlescape | |
263 | </term><listitem><para> | |
264 | Escapes text such that it can be used in XML and HTML. | |
265 | (Escapes less-than, greater-than, and ampersand.) | |
266 | </para></listitem></varlistentry> | |
267 | ||
268 | <varlistentry><term> | |
269 | delete(<parameter>chars</parameter>) | |
270 | </term><listitem><para> | |
271 | Deletes all occurrences of each of the characters in <parameter>chars</parameter> | |
272 | from the text. | |
273 | FIXME: This converter is not UTF-8 aware yet. | |
274 | </para></listitem></varlistentry> | |
275 | ||
276 | <varlistentry><term> | |
277 | escape(<parameter>chars</parameter>) | |
278 | </term><listitem><para> | |
279 | Escapes all occurrences of each of the characters in <parameter>chars</parameter> | |
280 | by prepending it by the first character in <parameter>chars</parameter>. | |
281 | FIXME: This converter is not UTF-8 aware yet. | |
282 | </para></listitem></varlistentry> | |
283 | ||
284 | <varlistentry><term> | |
285 | translate(<parameter>from</parameter>,<parameter>to</parameter>) | |
286 | </term><listitem><para> | |
287 | Translates all occurrences of each of the characters in <parameter>from</parameter> | |
288 | by replacing them with their corresponding character in <parameter>to</parameter>. | |
289 | If <parameter>to</parameter> has fewer characters than | |
290 | <parameter>from</parameter>, it will be extended by repeating its last | |
291 | character. | |
292 | FIXME: This converter is not UTF-8 aware yet. | |
293 | </para></listitem></varlistentry> | |
294 | ||
295 | </variablelist> | |
296 | ||
297 | For example, the format "%{family|downcase|delete( )}\n" will expand | |
298 | to the values of the family element in <parameter>pattern</parameter>, | |
299 | lower-cased and with spaces removed. | |
300 | ||
301 | @@ |