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