doc/fcformat.fncs

   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
  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 modeled 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 tag 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 of 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) to the entire sub-expression output.
 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 elements, 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 fccat
 206 </term><listitem><para>
 207 Expands to the output of the default output format of the fc-cat
 208 command on the pattern, without the final newline.
 209 </para></listitem></varlistentry>
 210
 211 <varlistentry><term>
 212 pkgkit
 213 </term><listitem><para>
 214 Expands to the list of PackageKit font() tags for the pattern.
 215 Currently this includes tags for each family name, and each language
 216 from the pattern, enumerated and sanitized into a set of tags terminated
 217 by newline.  Package management systems can use these tags to tag their
 218 packages accordingly.
 219 </para></listitem></varlistentry>
 220
 221 </variablelist>
 222
 223 For example, the format "%{+family,style{%{=unparse}}}\n" will expand
 224 to an unparsed name containing only the family and style element values
 225 from <parameter>pattern</parameter>.
 226
 227 </para><para>
 228
 229 The 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
 231 character "|" followed by the converter name and arguments.  The
 232 following converters are defined:
 233
 234 <variablelist>
 235
 236 <varlistentry><term>
 237 basename
 238 </term><listitem><para>
 239 Replaces text with the results of calling FcStrBasename() on it.
 240 </para></listitem></varlistentry>
 241
 242 <varlistentry><term>
 243 dirname
 244 </term><listitem><para>
 245 Replaces text with the results of calling FcStrDirname() on it.
 246 </para></listitem></varlistentry>
 247
 248 <varlistentry><term>
 249 downcase
 250 </term><listitem><para>
 251 Replaces text with the results of calling FcStrDowncase() on it.
 252 </para></listitem></varlistentry>
 253
 254 <varlistentry><term>
 255 shescape
 256 </term><listitem><para>
 257 Escapes 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>
 262 cescape
 263 </term><listitem><para>
 264 Escapes 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>
 269 xmlescape
 270 </term><listitem><para>
 271 Escapes 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>
 276 delete(<parameter>chars</parameter>)
 277 </term><listitem><para>
 278 Deletes all occurrences of each of the characters in <parameter>chars</parameter>
 279 from the text.
 280 FIXME: This converter is not UTF-8 aware yet.
 281 </para></listitem></varlistentry>
 282
 283 <varlistentry><term>
 284 escape(<parameter>chars</parameter>)
 285 </term><listitem><para>
 286 Escapes all occurrences of each of the characters in <parameter>chars</parameter>
 287 by prepending it by the first character in <parameter>chars</parameter>.
 288 FIXME: This converter is not UTF-8 aware yet.
 289 </para></listitem></varlistentry>
 290
 291 <varlistentry><term>
 292 translate(<parameter>from</parameter>,<parameter>to</parameter>)
 293 </term><listitem><para>
 294 Translates all occurrences of each of the characters in <parameter>from</parameter>
 295 by replacing them with their corresponding character in <parameter>to</parameter>.
 296 If <parameter>to</parameter> has fewer characters than
 297 <parameter>from</parameter>, it will be extended by repeating its last
 298 character.
 299 FIXME: This converter is not UTF-8 aware yet.
 300 </para></listitem></varlistentry>
 301
 302 </variablelist>
 303
 304 For example, the format "%{family|downcase|delete( )}\n" will expand
 305 to the values of the family element in <parameter>pattern</parameter>,
 306 lower-cased and with spaces removed.
 307
 308 @@