Man Pages

FcPatternFormat(3) - phpMan FcPatternFormat(3) - phpMan

Command: man perldoc info search(apropos)  


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);
       .fi

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 modelled after printf-style format string.  The format string is composed of zero or more
       directives:  ordinary characters (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 \n and \r 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 tags is introduced by the character "%", followed by an optional minimum field width, followed by tag con-
       tents 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  exam-
       ple,  to print the family name and style the pattern, use the format "%{family} %{style}\n". To extend the fam-
       ily column to forty characters use "%-40{family}%{style}\n".

       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 exam-
       ple, 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-expres-
       sion, or to apply  converters  (explained  later)  on  an  entire  sub-expression.   For  example,  the  format
       "%40{{%{family} %{style}}}" expands the sub-expression to construct the family name followed 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  example,  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,family-
       lang{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 condi-
       tions, 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 element, and to "fail" otherwise.

       An enumerate tag is one starting with the string "[]" followed by a comma-separated list of element names, fol-
       lowed 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 ele-
       ments, 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})\n}}" will expand the pattern "%{family} (%{family-
       lang})\n" with a pattern having only the first value of the family and familylang elemtns, 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 pat-
       tern, 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.

       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}}}\n" will expand to an unparsed name containing 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 amper-
              sand.)

       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 char-
              acter.  FIXME: This converter is not UTF-8 aware yet.

       For example, the format "%{family|downcase|delete( )}\n" will expand to the values of  the  family  element  in
       pattern, lower-cased and with spaces removed.

VERSION
       Fontconfig version 2.8.0



                               18 November 2009             FcPatternFormat(3)