id       = "fontconfig"
name     = "Fontconfig"
homepage = "https://www.freedesktop.org/wiki/Software/fontconfig/"
description = "Fontconfig is a library designed to provide system-wide font configuration, customization and application access."
executables   = ["fc-list", "fc-match", "fc-cache", "fc-conflist", "fc-query"]
platforms = ["macos", "linux"]

[dotfiles]

# fonts-conf(5) (https://man.archlinux.org/man/fonts-conf.5), "FILES": the
# per-user configuration is $XDG_CONFIG_HOME/fontconfig/fonts.conf with the
# per-user directory $XDG_CONFIG_HOME/fontconfig/conf.d, and the older
# ~/.fonts.conf and ~/.fonts.conf.d beside them — the man page marks both of
# the latter deprecated: "~/.fonts.conf is deprecated now. it will not be read
# by default in the future version". Both shapes are listed, since a machine
# set up years ago still has the dotted one and fontconfig still reads it.
#
# fontconfig implements XDG itself rather than following a platform
# convention, so the XDG root is right on macOS too: a Homebrew fontconfig on
# a Mac reads ~/.config/fontconfig, not ~/Library.
paths = [
  "[configHome]/fontconfig/fonts.conf",
  "[configHome]/fontconfig/conf.d/",
  "~/.fonts.conf",
  "~/.fonts.conf.d/",
]

# The same FILES section: "$XDG_CACHE_HOME/fontconfig/*.cache-*" and the
# deprecated "~/.fontconfig/*.cache-*" are the per-user font cache, rebuilt by
# fc-cache from the fonts actually installed on this machine.
exclude = [
  "[xdgCache]/fontconfig/",
  "~/.fontconfig/",
]

# Font aliases and rendering preferences. Nothing here is a credential.
secret = []

# No machine_lines: a user's fonts.conf is aliases, rendering settings
# (hinting, antialias, rgba) and match rules, all of which are the preferences
# they want everywhere. <dir> elements do name absolute paths, but the ones
# people write are $HOME-relative or system font directories that exist on
# every machine of that platform, and marking the element would strip a font
# path far more often than it would strip a machine-specific one.

[commands]
format = 1
label = "List fonts"
description = "List installed fonts with fc-list, optionally filtered by a fontconfig pattern and formatted. Other fontconfig tools (fc-match, fc-cache, fc-query) are not covered."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.source]]
id = "help"
kind = "help"
revision = "fc-list --help (fontconfig 2.x)"
evidence = """
usage: fc-list [-vbqVh] [-f FORMAT] [--verbose] [--brief] [--format=FORMAT] [--quiet] [--version] [--help] [pattern] {element ...}
List fonts matching [pattern]
  -v, --verbose        display entire font pattern verbosely
  -b, --brief          display entire font pattern briefly
  -f, --format=FORMAT  use the given output format
  -q, --quiet          suppress all normal output, exit 1 if no fonts matched
"""

[[commands.field]]
id = "pattern"
label = "Pattern"
description = "Fontconfig pattern such as `monospace`, `:lang=ja` or `Fira Code:style=Bold`. Empty lists every font."
type = "string"
position = 0
sources = ["help"]

[[commands.field]]
id = "elements"
label = "Elements to print"
description = "Pattern elements to show, e.g. family, style, file."
type = "string"
position = 1
multiple = true
sources = ["help"]

[[commands.field]]
id = "format"
label = "Output format"
description = "A fontconfig format string, e.g. %{family}\\n."
type = "string"
option = ["--format", "-f"]
sources = ["help"]

[[commands.field]]
id = "brief"
label = "Brief pattern"
type = "boolean"
option = ["--brief", "-b"]
sources = ["help"]

[[commands.field]]
id = "verbose"
label = "Verbose pattern"
type = "boolean"
option = ["--verbose", "-v"]
sources = ["help"]

[[commands.field]]
id = "quiet"
label = "Quiet (exit status only)"
type = "boolean"
option = ["--quiet", "-q"]
sources = ["help"]

[[commands.task]]
id = "list"
label = "List matching fonts"
fields = ["pattern", "format"]
required = []

[[commands.task]]
id = "check"
label = "Check a font exists"
fields = ["pattern", "quiet"]
required = ["pattern"]
set = { quiet = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["pattern", "elements", "format"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["brief", "verbose", "quiet"]