FcPatternFormat(3)                                                                                                              FcPatternFormat(3)

NAME

       FcPatternFormat - Format a pattern into a string according to a format specifier

SYNOPSIS

       #include <fontconfig.h>

       FcChar8 * FcPatternFormat (FcPattern *pat, const FcChar8 *format);

DESCRIPTION

       Converts  given  pattern  pat  into text described by the format specifier format.  The return value refers to newly allocated memory which
       should be freed by the caller using free(), or NULL if format is invalid.

       The format is loosely modeled after printf-style format string.  The format string is composed of zero or more  directives: ordinary  char-
       acters  (not  "%"), which are copied unchanged to the output stream; and tags which are interpreted to construct text from the pattern in a
       variety of ways (explained below).  Special characters can be escaped using backslash.  C-string style special characters like  
  and  
       are  also  supported (this is useful when the format string is not a C string literal).  It is advisable to always escape curly braces that
       are meant to be copied to the output as ordinary characters.

       Each tag is introduced by the character "%", followed by an optional minimum field width, followed by tag contents in  curly  braces  ({}).
       If  the  minimum field width value is provided the tag will be expanded and the result padded to achieve the minimum width.  If the minimum
       field width is positive, the padding will right-align the text.  Negative field width will left-align.  The rest of this section  describes
       various supported tag contents and their expansion.

       A  simple  tag is one where the content is an identifier.  When simple tags are expanded, the named identifier will be looked up in pattern
       and the resulting list of values returned, joined together using comma.  For example, to print the family name and style  of  the  pattern,
       use the format "%{family} %{style}
".  To extend the family column to forty characters use "%-40{family}%{style}
".

       Simple  tags  expand to list of all values for an element.  To only choose one of the values, one can index using the syntax "%{elt[idx]}".
       For example, to get the first family name only, use "%{family[0]}".

       If a simple tag ends with "=" and the element is found in the pattern, the name of the element followed by "=" will be  output  before  the
       list  of  values.   For example, "%{weight=}" may expand to the string "weight=80".  Or to the empty string if pattern does not have weight
       set.

       If a simple tag starts with ":" and the element is found in the pattern, ":" will be printed first.  For example, combining this  with  the
       =, the format "%{:weight=}" may expand to ":weight=80" or to the empty string if pattern does not have weight set.

       If  a simple tag contains the string ":-", the rest of the the tag contents will be used as a default string.  The default string is output
       if the element is not found in the pattern.  For example, the format "%{:weight=:-123}"  may  expand  to  ":weight=80"  or  to  the  string
       ":weight=123" if pattern does not have weight set.

       A  count  tag is one that starts with the character "#" followed by an element name, and expands to the number of values for the element in
       the pattern.  For example, "%{#family}" expands to the number of family names pattern has set, which may be zero.

       A sub-expression tag is one that expands a sub-expression.  The tag contents are the sub-expression to expand placed inside another set  of
       curly braces.  Sub-expression tags are useful for aligning an entire sub-expression, or to apply converters (explained later) to the entire
       sub-expression output.  For example, the format "%40{{%{family} %{style}}}" expands the sub-expression to construct the  family  name  fol-
       lowed by the style, then takes the entire string and pads it on the left to be at least forty characters.

       A  filter-out  tag is one starting with the character "-" followed by a comma-separated list of element names, followed by a sub-expression
       enclosed in curly braces.  The sub-expression will be expanded but with a pattern that has the listed elements removed from it.  For  exam-
       ple, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr" with pattern sans the size and pixelsize elements.

       A  filter-in  tag  is one starting with the character "+" followed by a comma-separated list of element names, followed by a sub-expression
       enclosed in curly braces.  The sub-expression will be expanded but with a pattern that only has the listed elements  from  the  surrounding
       pattern.   For  example,  the format "%{+family,familylang{sub-expr}}" will expand "sub-expr" with a sub-pattern consisting only the family
       and family lang elements of pattern.

       A conditional tag is one starting with the character "?" followed by a comma-separated list of element conditions,  followed  by  two  sub-
       expression enclosed in curly braces.  An element condition can be an element name, in which case it tests whether the element is defined in
       pattern, or the character "!" followed by an element name, in which case the test is negated.  The conditional passes if  all  the  element
       conditions pass.  The tag expands the first sub-expression if the conditional passes, and expands the second sub-expression otherwise.  For
       example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand to "pass" if pattern has size and dpi elements but no pixelsize  ele-
       ment, and to "fail" otherwise.

       An  enumerate  tag  is  one starting with the string "[]" followed by a comma-separated list of element names, followed by a sub-expression
       enclosed in curly braces.  The list of values for the named elements are walked in parallel and the sub-expression expanded each time  with
       a  pattern just having a single value for those elements, starting from the first value and continuing as long as any of those elements has
       a value.  For example, the format "%{[]family,familylang{%{family} (%{familylang})
}}"  will  expand  the  pattern  "%{family}  (%{family-
       lang})
"  with  a  pattern having only the first value of the family and familylang elements, then expands it with the second values, then
       the third, etc.

       As a special case, if an enumerate tag has only one element, and that element has only one value in the pattern, and that value is of  type
       FcLangSet, the individual languages in the language set are enumerated.

       A builtin tag is one starting with the character "=" followed by a builtin name.  The following builtins are defined:

       unparse
              Expands to the result of calling FcNameUnparse() on the pattern.

       fcmatch
              Expands to the output of the default output format of the fc-match command on the pattern, without the final newline.

       fclist Expands to the output of the default output format of the fc-list command on the pattern, without the final newline.

       fccat  Expands to the output of the default output format of the fc-cat command on the pattern, without the final newline.

       pkgkit Expands to the list of PackageKit font() tags for the pattern.  Currently this includes tags for each family name, and each language
              from the pattern, enumerated and sanitized into a set of tags terminated by newline.  Package management systems can use these  tags
              to  tag  their packages accordingly.  For example, the format "%{+family,style{%{=unparse}}}
" will expand to an unparsed name con-
              taining only the family and style element values from pattern.

       The contents of any tag can be followed by a set of zero or more converters.  A converter is specified by the character "|" followed by the
       converter name and arguments.  The following converters are defined:

       basename
              Replaces text with the results of calling FcStrBasename() on it.

       dirname
              Replaces text with the results of calling FcStrDirname() on it.

       downcase
              Replaces text with the results of calling FcStrDowncase() on it.

       shescape
              Escapes text for one level of shell expansion.  (Escapes single-quotes, also encloses text in single-quotes.)

       cescape
              Escapes text such that it can be used as part of a C string literal.  (Escapes backslash and double-quotes.)

       xmlescape
              Escapes text such that it can be used in XML and HTML.  (Escapes less-than, greater-than, and ampersand.)

       delete(chars)
              Deletes all occurrences of each of the characters in chars from the text.  FIXME: This converter is not UTF-8 aware yet.

       escape(chars)
              Escapes  all occurrences of each of the characters in chars by prepending it by the first character in chars.  FIXME: This converter
              is not UTF-8 aware yet.

       translate(from,to)
              Translates all occurrences of each of the characters in from by replacing them with their corresponding character in to.  If to  has
              fewer characters than from, it will be extended by repeating its last character.  FIXME: This converter is not UTF-8 aware yet.  For
              example, the format "%{family|downcase|delete( )}
" will expand to the values of the family element  in  pattern,  lower-cased  and
              with spaces removed.

VERSION

       Fontconfig version 2.9.0

                                                                   16 April 2012                                                FcPatternFormat(3)