doc/FcPatternFormat.3

   1 .\" auto-generated by docbook2man-spec from docbook-utils package
   2 .TH "FcPatternFormat" "3" "09 3月 2015" "Fontconfig 2.11.93" ""
   3 .SH NAME
   4 FcPatternFormat \- Format a pattern into a string according to a format specifier
   5 .SH SYNOPSIS
   6 .nf
   7 \fB#include <fontconfig/fontconfig.h>
   8 .sp
   9 FcChar8 * FcPatternFormat (FcPattern *\fIpat\fB, const FcChar8 *\fIformat\fB);
  10 .fi\fR
  11 .SH "DESCRIPTION"
  12 .PP
  13 Converts given pattern \fIpat\fR into text described by
  14 the format specifier \fIformat\fR\&.
  15 The return value refers to newly allocated memory which should be freed by the
  16 caller using free(), or NULL if \fIformat\fR is invalid.
  17 .PP
  18 The format is loosely modeled after printf-style format string.
  19 The format string is composed of zero or more directives: ordinary
  20 characters (not "%"), which are copied unchanged to the output stream;
  21 and tags which are interpreted to construct text from the pattern in a
  22 variety of ways (explained below).
  23 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).
  27 It is advisable to always escape curly braces that
  28 are meant to be copied to the output as ordinary characters.
  29 .PP
  30 Each tag is introduced by the character "%",
  31 followed by an optional minimum field width,
  32 followed by tag contents in curly braces ({}).
  33 If the minimum field width value is provided the tag
  34 will be expanded and the result padded to achieve the minimum width.
  35 If the minimum field width is positive, the padding will right-align
  36 the text. Negative field width will left-align.
  37 The rest of this section describes various supported tag contents
  38 and their expansion.
  39 .PP
  40 A \fIsimple\fR tag
  41 is one where the content is an identifier. When simple
  42 tags are expanded, the named identifier will be looked up in
  43 \fIpattern\fR and the resulting list of values returned,
  44 joined together using comma. For example, to print the family name and style of the
  45 pattern, use the format "%{family} %{style}\\n". To extend the family column
  46 to forty characters use "%-40{family}%{style}\\n".
  47 .PP
  48 Simple tags expand to list of all values for an element. To only choose
  49 one of the values, one can index using the syntax "%{elt[idx]}". For example,
  50 to get the first family name only, use "%{family[0]}".
  51 .PP
  52 If a simple tag ends with "=" and the element is found in the pattern, the
  53 name of the element followed by "=" will be output before the list of values.
  54 For example, "%{weight=}" may expand to the string "weight=80". Or to the empty
  55 string if \fIpattern\fR does not have weight set.
  56 .PP
  57 If a simple tag starts with ":" and the element is found in the pattern, ":"
  58 will be printed first. For example, combining this with the =, the format
  59 "%{:weight=}" may expand to ":weight=80" or to the empty string
  60 if \fIpattern\fR does not have weight set.
  61 .PP
  62 If a simple tag contains the string ":-", the rest of the the tag contents
  63 will be used as a default string. The default string is output if the element
  64 is not found in the pattern. For example, the format
  65 "%{:weight=:-123}" may expand to ":weight=80" or to the string
  66 ":weight=123" if \fIpattern\fR does not have weight set.
  67 .PP
  68 A \fIcount\fR tag
  69 is one that starts with the character "#" followed by an element
  70 name, and expands to the number of values for the element in the pattern.
  71 For example, "%{#family}" expands to the number of family names
  72 \fIpattern\fR has set, which may be zero.
  73 .PP
  74 A \fIsub-expression\fR tag
  75 is one that expands a sub-expression. The tag contents
  76 are the sub-expression to expand placed inside another set of curly braces.
  77 Sub-expression tags are useful for aligning an entire sub-expression, or to
  78 apply converters (explained later) to the entire sub-expression output.
  79 For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
  80 to construct the family name followed by the style, then takes the entire
  81 string and pads it on the left to be at least forty characters.
  82 .PP
  83 A \fIfilter-out\fR tag
  84 is one starting with the character "-" followed by a
  85 comma-separated list of element names, followed by a sub-expression enclosed
  86 in curly braces. The sub-expression will be expanded but with a pattern that
  87 has the listed elements removed from it.
  88 For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
  89 with \fIpattern\fR sans the size and pixelsize elements.
  90 .PP
  91 A \fIfilter-in\fR tag
  92 is one starting with the character "+" followed by a
  93 comma-separated list of element names, followed by a sub-expression enclosed
  94 in curly braces. The sub-expression will be expanded but with a pattern that
  95 only has the listed elements from the surrounding pattern.
  96 For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
  97 with a sub-pattern consisting only the family and family lang elements of
  98 \fIpattern\fR\&.
  99 .PP
 100 A \fIconditional\fR tag
 101 is one starting with the character "?" followed by a
 102 comma-separated list of element conditions, followed by two sub-expression
 103 enclosed in curly braces. An element condition can be an element name,
 104 in which case it tests whether the element is defined in pattern, or
 105 the character "!" followed by an element name, in which case the test
 106 is negated. The conditional passes if all the element conditions pass.
 107 The tag expands the first sub-expression if the conditional passes, and
 108 expands the second sub-expression otherwise.
 109 For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
 110 to "pass" if \fIpattern\fR has size and dpi elements but
 111 no pixelsize element, and to "fail" otherwise.
 112 .PP
 113 An \fIenumerate\fR tag
 114 is one starting with the string "[]" followed by a
 115 comma-separated list of element names, followed by a sub-expression enclosed
 116 in curly braces. The list of values for the named elements are walked in
 117 parallel and the sub-expression expanded each time with a pattern just having
 118 a single value for those elements, starting from the first value and
 119 continuing as long as any of those elements has a value.
 120 For example, the format "%{[]family,familylang{%{family} (%{familylang})\\n}}"
 121 will expand the pattern "%{family} (%{familylang})\\n" with a pattern
 122 having only the first value of the family and familylang elements, then expands
 123 it with the second values, then the third, etc.
 124 .PP
 125 As a special case, if an enumerate tag has only one element, and that element
 126 has only one value in the pattern, and that value is of type FcLangSet, the
 127 individual languages in the language set are enumerated.
 128 .PP
 129 A \fIbuiltin\fR tag
 130 is one starting with the character "=" followed by a builtin
 131 name. The following builtins are defined:
 132 .TP
 133 \fBunparse\fR
 134 Expands to the result of calling FcNameUnparse() on the pattern.
 135 .TP
 136 \fBfcmatch\fR
 137 Expands to the output of the default output format of the fc-match
 138 command on the pattern, without the final newline.
 139 .TP
 140 \fBfclist\fR
 141 Expands to the output of the default output format of the fc-list
 142 command on the pattern, without the final newline.
 143 .TP
 144 \fBfccat\fR
 145 Expands to the output of the default output format of the fc-cat
 146 command on the pattern, without the final newline.
 147 .TP
 148 \fBpkgkit\fR
 149 Expands to the list of PackageKit font() tags for the pattern.
 150 Currently this includes tags for each family name, and each language
 151 from the pattern, enumerated and sanitized into a set of tags terminated
 152 by newline. Package management systems can use these tags to tag their
 153 packages accordingly.
 154 .PP
 155 For example, the format "%{+family,style{%{=unparse}}}\\n" will expand
 156 to an unparsed name containing only the family and style element values
 157 from \fIpattern\fR\&.
 158 .PP
 159 The contents of any tag can be followed by a set of zero or more
 160 \fIconverter\fRs. A converter is specified by the
 161 character "|" followed by the converter name and arguments. The
 162 following converters are defined:
 163 .TP
 164 \fBbasename\fR
 165 Replaces text with the results of calling FcStrBasename() on it.
 166 .TP
 167 \fBdirname\fR
 168 Replaces text with the results of calling FcStrDirname() on it.
 169 .TP
 170 \fBdowncase\fR
 171 Replaces text with the results of calling FcStrDowncase() on it.
 172 .TP
 173 \fBshescape\fR
 174 Escapes text for one level of shell expansion.
 175 (Escapes single-quotes, also encloses text in single-quotes.)
 176 .TP
 177 \fBcescape\fR
 178 Escapes text such that it can be used as part of a C string literal.
 179 (Escapes backslash and double-quotes.)
 180 .TP
 181 \fBxmlescape\fR
 182 Escapes text such that it can be used in XML and HTML.
 183 (Escapes less-than, greater-than, and ampersand.)
 184 .TP
 185 \fBdelete(\fIchars\fB)\fR
 186 Deletes all occurrences of each of the characters in \fIchars\fR
 187 from the text.
 188 FIXME: This converter is not UTF-8 aware yet.
 189 .TP
 190 \fBescape(\fIchars\fB)\fR
 191 Escapes all occurrences of each of the characters in \fIchars\fR
 192 by prepending it by the first character in \fIchars\fR\&.
 193 FIXME: This converter is not UTF-8 aware yet.
 194 .TP
 195 \fBtranslate(\fIfrom\fB,\fIto\fB)\fR
 196 Translates all occurrences of each of the characters in \fIfrom\fR
 197 by replacing them with their corresponding character in \fIto\fR\&.
 198 If \fIto\fR has fewer characters than
 199 \fIfrom\fR, it will be extended by repeating its last
 200 character.
 201 FIXME: This converter is not UTF-8 aware yet.
 202 .PP
 203 For example, the format "%{family|downcase|delete( )}\\n" will expand
 204 to the values of the family element in \fIpattern\fR,
 205 lower-cased and with spaces removed.
 206 .SH "SINCE"
 207 .PP
 208 version 2.9.0