doc/fontconfig-devel/fcpatternformat.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >FcPatternFormat</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="HOME"
  10 HREF="t1.html"><LINK
  11 REL="UP"
  12 TITLE="FcPattern"
  13 HREF="x103.html#AEN242"><LINK
  14 REL="PREVIOUS"
  15 TITLE="FcNameUnparse"
  16 HREF="fcnameunparse.html"></HEAD
  17 ><BODY
  18 CLASS="REFENTRY"
  19 BGCOLOR="#FFFFFF"
  20 TEXT="#000000"
  21 LINK="#0000FF"
  22 VLINK="#840084"
  23 ALINK="#0000FF"
  24 ><DIV
  25 CLASS="NAVHEADER"
  26 ><TABLE
  27 SUMMARY="Header navigation table"
  28 WIDTH="100%"
  29 BORDER="0"
  30 CELLPADDING="0"
  31 CELLSPACING="0"
  32 ><TR
  33 ><TH
  34 COLSPAN="3"
  35 ALIGN="center"
  36 ></TH
  37 ></TR
  38 ><TR
  39 ><TD
  40 WIDTH="10%"
  41 ALIGN="left"
  42 VALIGN="bottom"
  43 ><A
  44 HREF="fcnameunparse.html"
  45 ACCESSKEY="P"
  46 >&#60;&#60;&#60; Previous</A
  47 ></TD
  48 ><TD
  49 WIDTH="80%"
  50 ALIGN="center"
  51 VALIGN="bottom"
  52 ></TD
  53 ><TD
  54 WIDTH="10%"
  55 ALIGN="right"
  56 VALIGN="bottom"
  57 >&nbsp;</TD
  58 ></TR
  59 ></TABLE
  60 ><HR
  61 ALIGN="LEFT"
  62 WIDTH="100%"></DIV
  63 ><H1
  64 ><A
  65 NAME="FCPATTERNFORMAT"
  66 ></A
  67 >FcPatternFormat</H1
  68 ><DIV
  69 CLASS="REFNAMEDIV"
  70 ><A
  71 NAME="AEN1190"
  72 ></A
  73 ><H2
  74 >Name</H2
  75 >FcPatternFormat&nbsp;--&nbsp;Format a pattern into a string according to a format specifier</DIV
  76 ><DIV
  77 CLASS="REFSYNOPSISDIV"
  78 ><A
  79 NAME="AEN1193"
  80 ></A
  81 ><H2
  82 >Synopsis</H2
  83 ><DIV
  84 CLASS="FUNCSYNOPSIS"
  85 ><P
  86 ></P
  87 ><A
  88 NAME="AEN1194"
  89 ></A
  90 ><TABLE
  91 BORDER="0"
  92 BGCOLOR="#E0E0E0"
  93 WIDTH="100%"
  94 ><TR
  95 ><TD
  96 ><PRE
  97 CLASS="FUNCSYNOPSISINFO"
  98 >#include &#60;fontconfig/fontconfig.h&#62;
  99         </PRE
 100 ></TD
 101 ></TR
 102 ></TABLE
 103 ><P
 104 ><CODE
 105 ><CODE
 106 CLASS="FUNCDEF"
 107 >FcChar8 * <TT
 108 CLASS="FUNCTION"
 109 >FcPatternFormat</TT
 110 ></CODE
 111 >(FcPattern *<TT
 112 CLASS="PARAMETER"
 113 ><I
 114 >pat</I
 115 ></TT
 116 >, const FcChar8 *<TT
 117 CLASS="PARAMETER"
 118 ><I
 119 >format</I
 120 ></TT
 121 >);</CODE
 122 ></P
 123 ><P
 124 ></P
 125 ></DIV
 126 ></DIV
 127 ><DIV
 128 CLASS="REFSECT1"
 129 ><A
 130 NAME="AEN1203"
 131 ></A
 132 ><H2
 133 >Description</H2
 134 ><P
 135 >Converts given pattern <TT
 136 CLASS="PARAMETER"
 137 ><I
 138 >pat</I
 139 ></TT
 140 > into text described by
 141 the format specifier <TT
 142 CLASS="PARAMETER"
 143 ><I
 144 >format</I
 145 ></TT
 146 >.
 147 The return value refers to newly allocated memory which should be freed by the
 148 caller using free(), or NULL if <TT
 149 CLASS="PARAMETER"
 150 ><I
 151 >format</I
 152 ></TT
 153 > is invalid.&#13;</P
 154 ><P
 155 >&#13;The format is loosely modeled after printf-style format string.
 156 The format string is composed of zero or more  directives: ordinary
 157 characters (not "%"), which are copied unchanged to the output stream;
 158 and tags which are interpreted to construct text from the pattern in a
 159 variety of ways (explained below).
 160 Special characters can be escaped
 161 using backslash.  C-string style special characters like \n and \r are
 162 also supported (this is useful when the format string is not a C string
 163 literal).
 164 It is advisable to always escape curly braces that
 165 are meant to be copied to the output as ordinary characters.&#13;</P
 166 ><P
 167 >&#13;Each tag is introduced by the character "%",
 168 followed by an optional minimum field width,
 169 followed by tag contents in curly braces ({}).
 170 If the minimum field width value is provided the tag
 171 will be expanded and the result padded to achieve the minimum width.
 172 If the minimum field width is positive, the padding will right-align
 173 the text.  Negative field width will left-align.
 174 The rest of this section describes various supported tag contents
 175 and their expansion.&#13;</P
 176 ><P
 177 >&#13;A <I
 178 CLASS="FIRSTTERM"
 179 >simple</I
 180 > tag
 181 is one where the content is an identifier.  When simple
 182 tags are expanded, the named identifier will be looked up in
 183 <TT
 184 CLASS="PARAMETER"
 185 ><I
 186 >pattern</I
 187 ></TT
 188 > and the resulting list of values returned,
 189 joined together using comma.  For example, to print the family name and style of the
 190 pattern, use the format "%{family} %{style}\n".  To extend the family column
 191 to forty characters use "%-40{family}%{style}\n".&#13;</P
 192 ><P
 193 >&#13;Simple tags expand to list of all values for an element.  To only choose
 194 one of the values, one can index using the syntax "%{elt[idx]}".  For example,
 195 to get the first family name only, use "%{family[0]}".&#13;</P
 196 ><P
 197 >&#13;If a simple tag ends with "=" and the element is found in the pattern, the
 198 name of the element followed by "=" will be output before the list of values.
 199 For example, "%{weight=}" may expand to the string "weight=80".  Or to the empty
 200 string if <TT
 201 CLASS="PARAMETER"
 202 ><I
 203 >pattern</I
 204 ></TT
 205 > does not have weight set.&#13;</P
 206 ><P
 207 >&#13;If a simple tag starts with ":" and the element is found in the pattern, ":"
 208 will be printed first.  For example, combining this with the =, the format
 209 "%{:weight=}" may expand to ":weight=80" or to the empty string
 210 if <TT
 211 CLASS="PARAMETER"
 212 ><I
 213 >pattern</I
 214 ></TT
 215 > does not have weight set.&#13;</P
 216 ><P
 217 >&#13;If a simple tag contains the string ":-", the rest of the the tag contents
 218 will be used as a default string.  The default string is output if the element
 219 is not found in the pattern.  For example, the format
 220 "%{:weight=:-123}" may expand to ":weight=80" or to the string
 221 ":weight=123" if <TT
 222 CLASS="PARAMETER"
 223 ><I
 224 >pattern</I
 225 ></TT
 226 > does not have weight set.&#13;</P
 227 ><P
 228 >&#13;A <I
 229 CLASS="FIRSTTERM"
 230 >count</I
 231 > tag
 232 is one that starts with the character "#" followed by an element
 233 name, and expands to the number of values for the element in the pattern.
 234 For example, "%{#family}" expands to the number of family names
 235 <TT
 236 CLASS="PARAMETER"
 237 ><I
 238 >pattern</I
 239 ></TT
 240 > has set, which may be zero.&#13;</P
 241 ><P
 242 >&#13;A <I
 243 CLASS="FIRSTTERM"
 244 >sub-expression</I
 245 > tag
 246 is one that expands a sub-expression.  The tag contents
 247 are the sub-expression to expand placed inside another set of curly braces.
 248 Sub-expression tags are useful for aligning an entire sub-expression, or to
 249 apply converters (explained later) to the entire sub-expression output.
 250 For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
 251 to construct the family name followed by the style, then takes the entire
 252 string and pads it on the left to be at least forty characters.&#13;</P
 253 ><P
 254 >&#13;A <I
 255 CLASS="FIRSTTERM"
 256 >filter-out</I
 257 > tag
 258 is one starting with the character "-" followed by a
 259 comma-separated list of element names, followed by a sub-expression enclosed
 260 in curly braces.  The sub-expression will be expanded but with a pattern that
 261 has the listed elements removed from it.
 262 For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
 263 with <TT
 264 CLASS="PARAMETER"
 265 ><I
 266 >pattern</I
 267 ></TT
 268 > sans the size and pixelsize elements.&#13;</P
 269 ><P
 270 >&#13;A <I
 271 CLASS="FIRSTTERM"
 272 >filter-in</I
 273 > tag
 274 is one starting with the character "+" followed by a
 275 comma-separated list of element names, followed by a sub-expression enclosed
 276 in curly braces.  The sub-expression will be expanded but with a pattern that
 277 only has the listed elements from the surrounding pattern.
 278 For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
 279 with a sub-pattern consisting only the family and family lang elements of
 280 <TT
 281 CLASS="PARAMETER"
 282 ><I
 283 >pattern</I
 284 ></TT
 285 >.&#13;</P
 286 ><P
 287 >&#13;A <I
 288 CLASS="FIRSTTERM"
 289 >conditional</I
 290 > tag
 291 is one starting with the character "?" followed by a
 292 comma-separated list of element conditions, followed by two sub-expression
 293 enclosed in curly braces.  An element condition can be an element name,
 294 in which case it tests whether the element is defined in pattern, or
 295 the character "!" followed by an element name, in which case the test
 296 is negated.  The conditional passes if all the element conditions pass.
 297 The tag expands the first sub-expression if the conditional passes, and
 298 expands the second sub-expression otherwise.
 299 For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
 300 to "pass" if <TT
 301 CLASS="PARAMETER"
 302 ><I
 303 >pattern</I
 304 ></TT
 305 > has size and dpi elements but
 306 no pixelsize element, and to "fail" otherwise.&#13;</P
 307 ><P
 308 >&#13;An <I
 309 CLASS="FIRSTTERM"
 310 >enumerate</I
 311 > tag
 312 is one starting with the string "[]" followed by a
 313 comma-separated list of element names, followed by a sub-expression enclosed
 314 in curly braces.  The list of values for the named elements are walked in
 315 parallel and the sub-expression expanded each time with a pattern just having
 316 a single value for those elements, starting from the first value and
 317 continuing as long as any of those elements has a value.
 318 For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}"
 319 will expand the pattern "%{family} (%{familylang})\n" with a pattern
 320 having only the first value of the family and familylang elements, then expands
 321 it with the second values, then the third, etc.&#13;</P
 322 ><P
 323 >&#13;As a special case, if an enumerate tag has only one element, and that element
 324 has only one value in the pattern, and that value is of type FcLangSet, the
 325 individual languages in the language set are enumerated.&#13;</P
 326 ><P
 327 >&#13;A <I
 328 CLASS="FIRSTTERM"
 329 >builtin</I
 330 > tag
 331 is one starting with the character "=" followed by a builtin
 332 name.  The following builtins are defined:
 333
 334 <P
 335 ></P
 336 ><DIV
 337 CLASS="VARIABLELIST"
 338 ><DL
 339 ><DT
 340 >unparse</DT
 341 ><DD
 342 ><P
 343 >Expands to the result of calling FcNameUnparse() on the pattern.</P
 344 ></DD
 345 ><DT
 346 >fcmatch</DT
 347 ><DD
 348 ><P
 349 >Expands to the output of the default output format of the fc-match
 350 command on the pattern, without the final newline.</P
 351 ></DD
 352 ><DT
 353 >fclist</DT
 354 ><DD
 355 ><P
 356 >Expands to the output of the default output format of the fc-list
 357 command on the pattern, without the final newline.</P
 358 ></DD
 359 ><DT
 360 >fccat</DT
 361 ><DD
 362 ><P
 363 >Expands to the output of the default output format of the fc-cat
 364 command on the pattern, without the final newline.</P
 365 ></DD
 366 ><DT
 367 >pkgkit</DT
 368 ><DD
 369 ><P
 370 >Expands to the list of PackageKit font() tags for the pattern.
 371 Currently this includes tags for each family name, and each language
 372 from the pattern, enumerated and sanitized into a set of tags terminated
 373 by newline.  Package management systems can use these tags to tag their
 374 packages accordingly.</P
 375 ></DD
 376 ></DL
 377 ></DIV
 378 >
 379
 380 For example, the format "%{+family,style{%{=unparse}}}\n" will expand
 381 to an unparsed name containing only the family and style element values
 382 from <TT
 383 CLASS="PARAMETER"
 384 ><I
 385 >pattern</I
 386 ></TT
 387 >.&#13;</P
 388 ><P
 389 >&#13;The contents of any tag can be followed by a set of zero or more
 390 <I
 391 CLASS="FIRSTTERM"
 392 >converter</I
 393 >s.  A converter is specified by the
 394 character "|" followed by the converter name and arguments.  The
 395 following converters are defined:
 396
 397 <P
 398 ></P
 399 ><DIV
 400 CLASS="VARIABLELIST"
 401 ><DL
 402 ><DT
 403 >basename</DT
 404 ><DD
 405 ><P
 406 >Replaces text with the results of calling FcStrBasename() on it.</P
 407 ></DD
 408 ><DT
 409 >dirname</DT
 410 ><DD
 411 ><P
 412 >Replaces text with the results of calling FcStrDirname() on it.</P
 413 ></DD
 414 ><DT
 415 >downcase</DT
 416 ><DD
 417 ><P
 418 >Replaces text with the results of calling FcStrDowncase() on it.</P
 419 ></DD
 420 ><DT
 421 >shescape</DT
 422 ><DD
 423 ><P
 424 >Escapes text for one level of shell expansion.
 425 (Escapes single-quotes, also encloses text in single-quotes.)</P
 426 ></DD
 427 ><DT
 428 >cescape</DT
 429 ><DD
 430 ><P
 431 >Escapes text such that it can be used as part of a C string literal.
 432 (Escapes backslash and double-quotes.)</P
 433 ></DD
 434 ><DT
 435 >xmlescape</DT
 436 ><DD
 437 ><P
 438 >Escapes text such that it can be used in XML and HTML.
 439 (Escapes less-than, greater-than, and ampersand.)</P
 440 ></DD
 441 ><DT
 442 >delete(<TT
 443 CLASS="PARAMETER"
 444 ><I
 445 >chars</I
 446 ></TT
 447 >)</DT
 448 ><DD
 449 ><P
 450 >Deletes all occurrences of each of the characters in <TT
 451 CLASS="PARAMETER"
 452 ><I
 453 >chars</I
 454 ></TT
 455 >
 456 from the text.
 457 FIXME: This converter is not UTF-8 aware yet.</P
 458 ></DD
 459 ><DT
 460 >escape(<TT
 461 CLASS="PARAMETER"
 462 ><I
 463 >chars</I
 464 ></TT
 465 >)</DT
 466 ><DD
 467 ><P
 468 >Escapes all occurrences of each of the characters in <TT
 469 CLASS="PARAMETER"
 470 ><I
 471 >chars</I
 472 ></TT
 473 >
 474 by prepending it by the first character in <TT
 475 CLASS="PARAMETER"
 476 ><I
 477 >chars</I
 478 ></TT
 479 >.
 480 FIXME: This converter is not UTF-8 aware yet.</P
 481 ></DD
 482 ><DT
 483 >translate(<TT
 484 CLASS="PARAMETER"
 485 ><I
 486 >from</I
 487 ></TT
 488 >,<TT
 489 CLASS="PARAMETER"
 490 ><I
 491 >to</I
 492 ></TT
 493 >)</DT
 494 ><DD
 495 ><P
 496 >Translates all occurrences of each of the characters in <TT
 497 CLASS="PARAMETER"
 498 ><I
 499 >from</I
 500 ></TT
 501 >
 502 by replacing them with their corresponding character in <TT
 503 CLASS="PARAMETER"
 504 ><I
 505 >to</I
 506 ></TT
 507 >.
 508 If <TT
 509 CLASS="PARAMETER"
 510 ><I
 511 >to</I
 512 ></TT
 513 > has fewer characters than
 514 <TT
 515 CLASS="PARAMETER"
 516 ><I
 517 >from</I
 518 ></TT
 519 >, it will be extended by repeating its last
 520 character.
 521 FIXME: This converter is not UTF-8 aware yet.</P
 522 ></DD
 523 ></DL
 524 ></DIV
 525 >
 526
 527 For example, the format "%{family|downcase|delete( )}\n" will expand
 528 to the values of the family element in <TT
 529 CLASS="PARAMETER"
 530 ><I
 531 >pattern</I
 532 ></TT
 533 >,
 534 lower-cased and with spaces removed.
 535             </P
 536 ></DIV
 537 ><DIV
 538 CLASS="REFSECT1"
 539 ><A
 540 NAME="AEN1313"
 541 ></A
 542 ><H2
 543 >Since</H2
 544 ><P
 545 >version 2.9.0</P
 546 ></DIV
 547 ><DIV
 548 CLASS="NAVFOOTER"
 549 ><HR
 550 ALIGN="LEFT"
 551 WIDTH="100%"><TABLE
 552 SUMMARY="Footer navigation table"
 553 WIDTH="100%"
 554 BORDER="0"
 555 CELLPADDING="0"
 556 CELLSPACING="0"
 557 ><TR
 558 ><TD
 559 WIDTH="33%"
 560 ALIGN="left"
 561 VALIGN="top"
 562 ><A
 563 HREF="fcnameunparse.html"
 564 ACCESSKEY="P"
 565 >&#60;&#60;&#60; Previous</A
 566 ></TD
 567 ><TD
 568 WIDTH="34%"
 569 ALIGN="center"
 570 VALIGN="top"
 571 ><A
 572 HREF="t1.html"
 573 ACCESSKEY="H"
 574 >Home</A
 575 ></TD
 576 ><TD
 577 WIDTH="33%"
 578 ALIGN="right"
 579 VALIGN="top"
 580 >&nbsp;</TD
 581 ></TR
 582 ><TR
 583 ><TD
 584 WIDTH="33%"
 585 ALIGN="left"
 586 VALIGN="top"
 587 >FcNameUnparse</TD
 588 ><TD
 589 WIDTH="34%"
 590 ALIGN="center"
 591 VALIGN="top"
 592 ><A
 593 HREF="x103.html#AEN242"
 594 ACCESSKEY="U"
 595 >Up</A
 596 ></TD
 597 ><TD
 598 WIDTH="33%"
 599 ALIGN="right"
 600 VALIGN="top"
 601 >&nbsp;</TD
 602 ></TR
 603 ></TABLE
 604 ></DIV
 605 ></BODY
 606 ></HTML
 607 >