>

>

>FcPatternFormat

>

NAME="GENERATOR"

CONTENT="Modular DocBook HTML Stylesheet Version 1.79">

REL="HOME"

HREF="t1.html">

REL="UP"

TITLE="FcPattern"

HREF="x103.html#AEN242">

REL="PREVIOUS"

TITLE="FcNameUnparse"

HREF="fcnameunparse.html">

>

CLASS="REFENTRY"

BGCOLOR="#FFFFFF"

TEXT="#000000"

LINK="#0000FF"

VLINK="#840084"

ALINK="#0000FF"

>

CLASS="NAVHEADER"

>

SUMMARY="Header navigation table"

WIDTH="100%"

BORDER="0"

CELLPADDING="0"

CELLSPACING="0"

>

>

COLSPAN="3"

ALIGN="center"

>

>

>

>

WIDTH="10%"

ALIGN="left"

VALIGN="bottom"

>

HREF="fcnameunparse.html"

ACCESSKEY="P"

><<< Previous

>

>

WIDTH="80%"

ALIGN="center"

VALIGN="bottom"

>

>

WIDTH="10%"

ALIGN="right"

VALIGN="bottom"

> 

>

>

>

ALIGN="LEFT"

WIDTH="100%">

>

>

NAME="FCPATTERNFORMAT"

>

>FcPatternFormat

>

CLASS="REFNAMEDIV"

>

NAME="AEN1190"

>

>

>Name

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

>

CLASS="REFSYNOPSISDIV"

>

NAME="AEN1193"

>

>

>Synopsis

>

CLASS="FUNCSYNOPSIS"

>

>

>

NAME="AEN1194"

>

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="FUNCSYNOPSISINFO"

>#include <fontconfig/fontconfig.h>

>

>

>

>

>

>

CLASS="FUNCDEF"

>FcChar8 * 

CLASS="FUNCTION"

>FcPatternFormat

>

>(FcPattern *

CLASS="PARAMETER"

>

>pat

>

>, const FcChar8 *

CLASS="PARAMETER"

>

>format

>

>);

>

>

>

>

>

>

CLASS="REFSECT1"

>

NAME="AEN1203"

>

>

>Description

>

>Converts given pattern 

CLASS="PARAMETER"

>

>pat

>

> into text described by

the format specifier 

CLASS="PARAMETER"

>

>format

>

>.

The return value refers to newly allocated memory which should be freed by the

caller using free(), or NULL if 

CLASS="PARAMETER"

>

>format

>

> is invalid.

>

>
The format is loosely modeled 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 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 

CLASS="FIRSTTERM"

>simple

> tag

is one where the content is an identifier.  When simple

tags are expanded, the named identifier will be looked up in

CLASS="PARAMETER"

>

>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}\n".  To extend the family 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 

CLASS="PARAMETER"

>

>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 

CLASS="PARAMETER"

>

>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 

CLASS="PARAMETER"

>

>pattern

>

> does not have weight set.

>

>
A 

CLASS="FIRSTTERM"

>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

CLASS="PARAMETER"

>

>pattern

>

> has set, which may be zero.

>

>
A 

CLASS="FIRSTTERM"

>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 followed by the style, then takes the entire

string and pads it on the left to be at least forty characters.

>

>
A 

CLASS="FIRSTTERM"

>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 

CLASS="PARAMETER"

>

>pattern

>

> sans the size and pixelsize elements.

>

>
A 

CLASS="FIRSTTERM"

>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

CLASS="PARAMETER"

>

>pattern

>

>.

>

>
A 

CLASS="FIRSTTERM"

>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 

CLASS="PARAMETER"

>

>pattern

>

> has size and dpi elements but

no pixelsize element, and to "fail" otherwise.

>

>
An 

CLASS="FIRSTTERM"

>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})\n}}"

will expand the pattern "%{family} (%{familylang})\n" 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 

CLASS="FIRSTTERM"

>builtin

> tag

is one starting with the character "=" followed by a builtin

name.  The following builtins are defined:

>

>

CLASS="VARIABLELIST"

>

>

>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}}}\n" will expand

to an unparsed name containing only the family and style element values

from 

CLASS="PARAMETER"

>

>pattern

>

>.

>

>
The contents of any tag can be followed by a set of zero or more

CLASS="FIRSTTERM"

>converter

>s.  A converter is specified by the

character "|" followed by the converter name and arguments.  The

following converters are defined:

>

>

CLASS="VARIABLELIST"

>

>

>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(

CLASS="PARAMETER"

>

>chars

>

>)

>

>

>Deletes all occurrences of each of the characters in 

CLASS="PARAMETER"

>

>chars

>

>

from the text.

FIXME: This converter is not UTF-8 aware yet.

>

>

>escape(

CLASS="PARAMETER"

>

>chars

>

>)

>

>

>Escapes all occurrences of each of the characters in 

CLASS="PARAMETER"

>

>chars

>

>

by prepending it by the first character in 

CLASS="PARAMETER"

>

>chars

>

>.

FIXME: This converter is not UTF-8 aware yet.

>

>

>translate(

CLASS="PARAMETER"

>

>from

>

>,

CLASS="PARAMETER"

>

>to

>

>)

>

>

>Translates all occurrences of each of the characters in 

CLASS="PARAMETER"

>

>from

>

>

by replacing them with their corresponding character in 

CLASS="PARAMETER"

>

>to

>

>.

If 

CLASS="PARAMETER"

>

>to

>

> has fewer characters than

CLASS="PARAMETER"

>

>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( )}\n" will expand

to the values of the family element in 

CLASS="PARAMETER"

>

>pattern

>

>,

lower-cased and with spaces removed.

>

>

CLASS="REFSECT1"

>

NAME="AEN1313"

>

>

>Since

>

>version 2.9.0

>

>

CLASS="NAVFOOTER"

>

ALIGN="LEFT"

WIDTH="100%">

SUMMARY="Footer navigation table"

WIDTH="100%"

BORDER="0"

CELLPADDING="0"

CELLSPACING="0"

>

>

WIDTH="33%"

ALIGN="left"

VALIGN="top"

>

HREF="fcnameunparse.html"

ACCESSKEY="P"

><<< Previous

>

>

WIDTH="34%"

ALIGN="center"

VALIGN="top"

>

HREF="t1.html"

ACCESSKEY="H"

>Home

>

>

WIDTH="33%"

ALIGN="right"

VALIGN="top"

> 

>

>

>

WIDTH="33%"

ALIGN="left"

VALIGN="top"

>FcNameUnparse

>

WIDTH="34%"

ALIGN="center"

VALIGN="top"

>

HREF="x103.html#AEN242"

ACCESSKEY="U"

>Up

>

>

WIDTH="33%"

ALIGN="right"

VALIGN="top"

> 

>

>

>

>

>

>