FcPatternFormat(3)
NAME
FcPatternFormat - Format a pattern into a string according to a format specifier
SYNOPSIS
#include <fontconfig/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
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 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}\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 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
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,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
element, 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})\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 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}}}\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 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( )}\n" will expand to
the values of the family element in pattern, lower-cased and with
spaces removed.
SINCE
version 2.9.0
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
