|
Packit |
352660 |
.\" auto-generated by docbook2man-spec from docbook-utils package
|
|
Packit |
352660 |
.TH "FcPatternFormat" "3" "30 8月 2018" "Fontconfig 2.13.1" ""
|
|
Packit |
352660 |
.SH NAME
|
|
Packit |
352660 |
FcPatternFormat \- Format a pattern into a string according to a format specifier
|
|
Packit |
352660 |
.SH SYNOPSIS
|
|
Packit |
352660 |
.nf
|
|
Packit |
352660 |
\fB#include <fontconfig/fontconfig.h>
|
|
Packit |
352660 |
.sp
|
|
Packit |
352660 |
FcChar8 * FcPatternFormat (FcPattern *\fIpat\fB, const FcChar8 *\fIformat\fB);
|
|
Packit |
352660 |
.fi\fR
|
|
Packit |
352660 |
.SH "DESCRIPTION"
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
Converts given pattern \fIpat\fR into text described by
|
|
Packit |
352660 |
the format specifier \fIformat\fR\&.
|
|
Packit |
352660 |
The return value refers to newly allocated memory which should be freed by the
|
|
Packit |
352660 |
caller using free(), or NULL if \fIformat\fR is invalid.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
The format is loosely modeled after printf-style format string.
|
|
Packit |
352660 |
The format string is composed of zero or more directives: ordinary
|
|
Packit |
352660 |
characters (not "%"), which are copied unchanged to the output stream;
|
|
Packit |
352660 |
and tags which are interpreted to construct text from the pattern in a
|
|
Packit |
352660 |
variety of ways (explained below).
|
|
Packit |
352660 |
Special characters can be escaped
|
|
Packit |
352660 |
using backslash. C-string style special characters like \\n and \\r are
|
|
Packit |
352660 |
also supported (this is useful when the format string is not a C string
|
|
Packit |
352660 |
literal).
|
|
Packit |
352660 |
It is advisable to always escape curly braces that
|
|
Packit |
352660 |
are meant to be copied to the output as ordinary characters.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
Each tag is introduced by the character "%",
|
|
Packit |
352660 |
followed by an optional minimum field width,
|
|
Packit |
352660 |
followed by tag contents in curly braces ({}).
|
|
Packit |
352660 |
If the minimum field width value is provided the tag
|
|
Packit |
352660 |
will be expanded and the result padded to achieve the minimum width.
|
|
Packit |
352660 |
If the minimum field width is positive, the padding will right-align
|
|
Packit |
352660 |
the text. Negative field width will left-align.
|
|
Packit |
352660 |
The rest of this section describes various supported tag contents
|
|
Packit |
352660 |
and their expansion.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIsimple\fR tag
|
|
Packit |
352660 |
is one where the content is an identifier. When simple
|
|
Packit |
352660 |
tags are expanded, the named identifier will be looked up in
|
|
Packit |
352660 |
\fIpattern\fR and the resulting list of values returned,
|
|
Packit |
352660 |
joined together using comma. For example, to print the family name and style of the
|
|
Packit |
352660 |
pattern, use the format "%{family} %{style}\\n". To extend the family column
|
|
Packit |
352660 |
to forty characters use "%-40{family}%{style}\\n".
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
Simple tags expand to list of all values for an element. To only choose
|
|
Packit |
352660 |
one of the values, one can index using the syntax "%{elt[idx]}". For example,
|
|
Packit |
352660 |
to get the first family name only, use "%{family[0]}".
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
If a simple tag ends with "=" and the element is found in the pattern, the
|
|
Packit |
352660 |
name of the element followed by "=" will be output before the list of values.
|
|
Packit |
352660 |
For example, "%{weight=}" may expand to the string "weight=80". Or to the empty
|
|
Packit |
352660 |
string if \fIpattern\fR does not have weight set.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
If a simple tag starts with ":" and the element is found in the pattern, ":"
|
|
Packit |
352660 |
will be printed first. For example, combining this with the =, the format
|
|
Packit |
352660 |
"%{:weight=}" may expand to ":weight=80" or to the empty string
|
|
Packit |
352660 |
if \fIpattern\fR does not have weight set.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
If a simple tag contains the string ":-", the rest of the the tag contents
|
|
Packit |
352660 |
will be used as a default string. The default string is output if the element
|
|
Packit |
352660 |
is not found in the pattern. For example, the format
|
|
Packit |
352660 |
"%{:weight=:-123}" may expand to ":weight=80" or to the string
|
|
Packit |
352660 |
":weight=123" if \fIpattern\fR does not have weight set.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIcount\fR tag
|
|
Packit |
352660 |
is one that starts with the character "#" followed by an element
|
|
Packit |
352660 |
name, and expands to the number of values for the element in the pattern.
|
|
Packit |
352660 |
For example, "%{#family}" expands to the number of family names
|
|
Packit |
352660 |
\fIpattern\fR has set, which may be zero.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIsub-expression\fR tag
|
|
Packit |
352660 |
is one that expands a sub-expression. The tag contents
|
|
Packit |
352660 |
are the sub-expression to expand placed inside another set of curly braces.
|
|
Packit |
352660 |
Sub-expression tags are useful for aligning an entire sub-expression, or to
|
|
Packit |
352660 |
apply converters (explained later) to the entire sub-expression output.
|
|
Packit |
352660 |
For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
|
|
Packit |
352660 |
to construct the family name followed by the style, then takes the entire
|
|
Packit |
352660 |
string and pads it on the left to be at least forty characters.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIfilter-out\fR tag
|
|
Packit |
352660 |
is one starting with the character "-" followed by a
|
|
Packit |
352660 |
comma-separated list of element names, followed by a sub-expression enclosed
|
|
Packit |
352660 |
in curly braces. The sub-expression will be expanded but with a pattern that
|
|
Packit |
352660 |
has the listed elements removed from it.
|
|
Packit |
352660 |
For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
|
|
Packit |
352660 |
with \fIpattern\fR sans the size and pixelsize elements.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIfilter-in\fR tag
|
|
Packit |
352660 |
is one starting with the character "+" followed by a
|
|
Packit |
352660 |
comma-separated list of element names, followed by a sub-expression enclosed
|
|
Packit |
352660 |
in curly braces. The sub-expression will be expanded but with a pattern that
|
|
Packit |
352660 |
only has the listed elements from the surrounding pattern.
|
|
Packit |
352660 |
For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
|
|
Packit |
352660 |
with a sub-pattern consisting only the family and family lang elements of
|
|
Packit |
352660 |
\fIpattern\fR\&.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIconditional\fR tag
|
|
Packit |
352660 |
is one starting with the character "?" followed by a
|
|
Packit |
352660 |
comma-separated list of element conditions, followed by two sub-expression
|
|
Packit |
352660 |
enclosed in curly braces. An element condition can be an element name,
|
|
Packit |
352660 |
in which case it tests whether the element is defined in pattern, or
|
|
Packit |
352660 |
the character "!" followed by an element name, in which case the test
|
|
Packit |
352660 |
is negated. The conditional passes if all the element conditions pass.
|
|
Packit |
352660 |
The tag expands the first sub-expression if the conditional passes, and
|
|
Packit |
352660 |
expands the second sub-expression otherwise.
|
|
Packit |
352660 |
For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
|
|
Packit |
352660 |
to "pass" if \fIpattern\fR has size and dpi elements but
|
|
Packit |
352660 |
no pixelsize element, and to "fail" otherwise.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
An \fIenumerate\fR tag
|
|
Packit |
352660 |
is one starting with the string "[]" followed by a
|
|
Packit |
352660 |
comma-separated list of element names, followed by a sub-expression enclosed
|
|
Packit |
352660 |
in curly braces. The list of values for the named elements are walked in
|
|
Packit |
352660 |
parallel and the sub-expression expanded each time with a pattern just having
|
|
Packit |
352660 |
a single value for those elements, starting from the first value and
|
|
Packit |
352660 |
continuing as long as any of those elements has a value.
|
|
Packit |
352660 |
For example, the format "%{[]family,familylang{%{family} (%{familylang})\\n}}"
|
|
Packit |
352660 |
will expand the pattern "%{family} (%{familylang})\\n" with a pattern
|
|
Packit |
352660 |
having only the first value of the family and familylang elements, then expands
|
|
Packit |
352660 |
it with the second values, then the third, etc.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
As a special case, if an enumerate tag has only one element, and that element
|
|
Packit |
352660 |
has only one value in the pattern, and that value is of type FcLangSet, the
|
|
Packit |
352660 |
individual languages in the language set are enumerated.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
A \fIbuiltin\fR tag
|
|
Packit |
352660 |
is one starting with the character "=" followed by a builtin
|
|
Packit |
352660 |
name. The following builtins are defined:
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBunparse\fR
|
|
Packit |
352660 |
Expands to the result of calling FcNameUnparse() on the pattern.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBfcmatch\fR
|
|
Packit |
352660 |
Expands to the output of the default output format of the fc-match
|
|
Packit |
352660 |
command on the pattern, without the final newline.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBfclist\fR
|
|
Packit |
352660 |
Expands to the output of the default output format of the fc-list
|
|
Packit |
352660 |
command on the pattern, without the final newline.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBfccat\fR
|
|
Packit |
352660 |
Expands to the output of the default output format of the fc-cat
|
|
Packit |
352660 |
command on the pattern, without the final newline.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBpkgkit\fR
|
|
Packit |
352660 |
Expands to the list of PackageKit font() tags for the pattern.
|
|
Packit |
352660 |
Currently this includes tags for each family name, and each language
|
|
Packit |
352660 |
from the pattern, enumerated and sanitized into a set of tags terminated
|
|
Packit |
352660 |
by newline. Package management systems can use these tags to tag their
|
|
Packit |
352660 |
packages accordingly.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
For example, the format "%{+family,style{%{=unparse}}}\\n" will expand
|
|
Packit |
352660 |
to an unparsed name containing only the family and style element values
|
|
Packit |
352660 |
from \fIpattern\fR\&.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
The contents of any tag can be followed by a set of zero or more
|
|
Packit |
352660 |
\fIconverter\fRs. A converter is specified by the
|
|
Packit |
352660 |
character "|" followed by the converter name and arguments. The
|
|
Packit |
352660 |
following converters are defined:
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBbasename\fR
|
|
Packit |
352660 |
Replaces text with the results of calling FcStrBasename() on it.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBdirname\fR
|
|
Packit |
352660 |
Replaces text with the results of calling FcStrDirname() on it.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBdowncase\fR
|
|
Packit |
352660 |
Replaces text with the results of calling FcStrDowncase() on it.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBshescape\fR
|
|
Packit |
352660 |
Escapes text for one level of shell expansion.
|
|
Packit |
352660 |
(Escapes single-quotes, also encloses text in single-quotes.)
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBcescape\fR
|
|
Packit |
352660 |
Escapes text such that it can be used as part of a C string literal.
|
|
Packit |
352660 |
(Escapes backslash and double-quotes.)
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBxmlescape\fR
|
|
Packit |
352660 |
Escapes text such that it can be used in XML and HTML.
|
|
Packit |
352660 |
(Escapes less-than, greater-than, and ampersand.)
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBdelete(\fIchars\fB)\fR
|
|
Packit |
352660 |
Deletes all occurrences of each of the characters in \fIchars\fR
|
|
Packit |
352660 |
from the text.
|
|
Packit |
352660 |
FIXME: This converter is not UTF-8 aware yet.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBescape(\fIchars\fB)\fR
|
|
Packit |
352660 |
Escapes all occurrences of each of the characters in \fIchars\fR
|
|
Packit |
352660 |
by prepending it by the first character in \fIchars\fR\&.
|
|
Packit |
352660 |
FIXME: This converter is not UTF-8 aware yet.
|
|
Packit |
352660 |
.TP
|
|
Packit |
352660 |
\fBtranslate(\fIfrom\fB,\fIto\fB)\fR
|
|
Packit |
352660 |
Translates all occurrences of each of the characters in \fIfrom\fR
|
|
Packit |
352660 |
by replacing them with their corresponding character in \fIto\fR\&.
|
|
Packit |
352660 |
If \fIto\fR has fewer characters than
|
|
Packit |
352660 |
\fIfrom\fR, it will be extended by repeating its last
|
|
Packit |
352660 |
character.
|
|
Packit |
352660 |
FIXME: This converter is not UTF-8 aware yet.
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
For example, the format "%{family|downcase|delete( )}\\n" will expand
|
|
Packit |
352660 |
to the values of the family element in \fIpattern\fR,
|
|
Packit |
352660 |
lower-cased and with spaces removed.
|
|
Packit |
352660 |
.SH "SINCE"
|
|
Packit |
352660 |
.PP
|
|
Packit |
352660 |
version 2.9.0
|