The font-discovery Reference Manual

Table of Contents

The font-discovery Reference Manual

This is the font-discovery Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:46:27 2022 GMT+0.

1 Introduction

## About Font-Discovery
This is a library to find system font files. It works on systems with DirectWrite (Windows), CoreText (macOS, iOS), and FontConfig (Linux, BSD). It does not have any foreign dependencies that aren't already directly available on the system.

## How To
You can list all fonts by using ``list-fonts``, or find a specific font using ``find-font``. Both of these functions take a number of arguments to query for fonts with specific properties (``family``, ``slant``, ``weight``, ``spacing``, ``stretch``). Both of them return ``font`` instances, from which you can query the precise properties, as well as their font file location with ``file``.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 font-discovery

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/font-discovery

License

zlib

Description

Find system font files matching a font spec.

Version

1.0.0

Defsystem Dependency

trivial-features

Dependencies

• documentation-utils
• trivial-indent
• com-on (for feature windows)
• cffi

Source

font-discovery.asd (file)

Components

• package.lisp (file)
• common.lisp (file)
• fontconfig.lisp (file)
• linux.lisp (file)
• coretext.lisp (file)
• macos.lisp (file)
• directwrite.lisp (file)
• windows.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 font-discovery.asd

Location

font-discovery.asd

Systems

font-discovery (system)

3.1.2 font-discovery/package.lisp

Parent

font-discovery (system)

Location

package.lisp

Packages

org.shirakumo.font-discovery

3.1.3 font-discovery/common.lisp

Dependency

package.lisp (file)

Parent

font-discovery (system)

Location

common.lisp

Exported Definitions

• family (method)
• file (method)
• font (class)
• slant (method)
• spacing (method)
• stretch (method)
• weight (method)

Internal Definitions

• maybe-enum (function)
• maybe-enum-val (function)
• parse-file (function)
• with-protection (macro)

3.1.4 font-discovery/fontconfig.lisp

If Feature

linux

Dependency

common.lisp (file)

Parent

font-discovery (system)

Location

fontconfig.lisp

Internal Definitions

• +family+ (special variable)
• +file+ (special variable)
• +size+ (special variable)
• +slant+ (special variable)
• +spacing+ (special variable)
• +weight+ (special variable)
• +width+ (special variable)
• config-destroy (function)
• config-substitute (function)
• create-pattern (function)
• create-range (function)
• default-substitute (function)
• destroy-pattern (function)
• destroy-range (function)
• destroy-set (function)
• fini (function)
• font-match (function)
• font-set-fonts (function)
• (setf font-set-fonts) (function)
• font-set-nfont (function)
• (setf font-set-nfont) (function)
• font-set-sfont (function)
• (setf font-set-sfont) (function)
• font-set-tclass (class)
• font-sort (function)
• init-load-config-and-fonts (function)
• pattern-add-integer (function)
• pattern-add-range (function)
• pattern-add-string (function)
• pattern-get-double (function)
• pattern-get-integer (function)
• pattern-get-range (function)
• pattern-get-string (function)
• range-get (function)

3.1.5 font-discovery/linux.lisp

If Feature

linux

Dependencies

• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

linux.lisp

Exported Definitions

• deinit (function)
• find-font (function)
• init (function)
• list-fonts (function)
• refresh (function)

Internal Definitions

• *config* (special variable)
• init-pattern (function)
• translate-match (function)
• with-result (macro)

3.1.6 font-discovery/coretext.lisp

If Feature

darwin

Dependencies

• linux.lisp (file)
• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

coretext.lisp

3.1.7 font-discovery/macos.lisp

If Feature

darwin

Dependencies

• coretext.lisp (file)
• linux.lisp (file)
• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

macos.lisp

3.1.8 font-discovery/directwrite.lisp

If Feature

win32

Dependencies

• macos.lisp (file)
• coretext.lisp (file)
• linux.lisp (file)
• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

directwrite.lisp

3.1.9 font-discovery/windows.lisp

If Feature

win32

Dependencies

• directwrite.lisp (file)
• macos.lisp (file)
• coretext.lisp (file)
• linux.lisp (file)
• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

windows.lisp

3.1.10 font-discovery/documentation.lisp

Dependencies

• windows.lisp (file)
• directwrite.lisp (file)
• macos.lisp (file)
• coretext.lisp (file)
• linux.lisp (file)
• fontconfig.lisp (file)
• common.lisp (file)

Parent

font-discovery (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 org.shirakumo.font-discovery

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• deinit (function)
• family (generic function)
• family (method)
• file (generic function)
• file (method)
• find-font (function)
• font (class)
• init (function)
• list-fonts (function)
• refresh (function)
• slant (generic function)
• slant (method)
• spacing (generic function)
• spacing (method)
• stretch (generic function)
• stretch (method)
• weight (generic function)
• weight (method)

Internal Definitions

• *config* (special variable)
• +family+ (special variable)
• +file+ (special variable)
• +size+ (special variable)
• +slant+ (special variable)
• +spacing+ (special variable)
• +weight+ (special variable)
• +width+ (special variable)
• config-destroy (function)
• config-substitute (function)
• create-pattern (function)
• create-range (function)
• default-substitute (function)
• destroy-pattern (function)
• destroy-range (function)
• destroy-set (function)
• fini (function)
• font-match (function)
• font-set-fonts (function)
• (setf font-set-fonts) (function)
• font-set-nfont (function)
• (setf font-set-nfont) (function)
• font-set-sfont (function)
• (setf font-set-sfont) (function)
• font-set-tclass (class)
• font-sort (function)
• init-load-config-and-fonts (function)
• init-pattern (function)
• maybe-enum (function)
• maybe-enum-val (function)
• parse-file (function)
• pattern-add-integer (function)
• pattern-add-range (function)
• pattern-add-string (function)
• pattern-get-double (function)
• pattern-get-integer (function)
• pattern-get-range (function)
• pattern-get-string (function)
• range-get (function)
• translate-match (function)
• with-protection (macro)
• with-result (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: deinit ()

Uninitializes the library.

This will shut down foreign libraries and deallocate cache memory. Returns T if it did so.

It will not close the foreign libraries that were opened by INIT.

It is safe to call this function multiple times.

See INIT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Function: find-font &rest ARGS &key FAMILY SLANT WEIGHT SPACING STRETCH

Attempts to find a font with specifications that match the query as close as possible.

Returns a FONT instance, or NIL if no match can be found.
Note that on some systems the returned font may not be an exact
match, but rather a closest approximation.

For the possible values of the arguments, see the FONT class and its
reader functions.

Doing this will automatically call INIT.

See LIST-FONTS
See INIT
See FONT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Function: init ()

Initializes the library for use.

This will load foreign libraries and set up internal state if necessary. Returns T if it did so.

It is safe to call this function multiple times.

See REFRESH
See DEINIT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Function: list-fonts &rest ARGS &key FAMILY SLANT WEIGHT SPACING STRETCH

Returns a list of fonts with specifications that match the query.

Returns a list of FONT instances that match the query.

For the possible values of the arguments, see the FONT class and its reader functions.

Doing this will automatically call INIT.

See FIND-FONT
See INIT
See FONT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Function: refresh ()

Refreshes the font cache.

This should cause new system fonts to be recognised. You should call this function whenever you think the list of system fonts might have changed. Returns T if the cache was updated.

Doing this will automatically call INIT.

See INIT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

5.1.2 Generic functions

Generic Function: family OBJECT

Returns the font family name.

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: family (FONT font)

automatically generated reader method

Source

common.lisp (file)

Generic Function: file OBJECT

Returns the pathname to the font file.

This may be a TTF or OTF file.

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: file (FONT font)

automatically generated reader method

Source

common.lisp (file)

Generic Function: slant OBJECT

Returns the slant of the font.

This may be one of the following keywords, in order of increasing slant, or a system-dependent numeric value for the font’s slant.

:ROMAN
:ITALIC
:OBLIQUE

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: slant (FONT font)

automatically generated reader method

Source

common.lisp (file)

Generic Function: spacing OBJECT

Returns the font’s spacing.

This may be one of the following keywords, in order of increasing spacing, or a system-dependent numeric value for the font’s spacing.

:PROPORTIONAL
:DUALSPACE
:MONOSPACE
:CHARCELL

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: spacing (FONT font)

automatically generated reader method

Source

common.lisp (file)

Generic Function: stretch OBJECT

Returns the font’s stretch factor.

This may be one of the following keywords, in order of increasing stretch factor, or a system-dependent numeric value for the font’s stretch factor.

:ULTRA-CONDENSED
:EXTRA-CONDENSED
:CONDENSED
:SEMI-CONDENSED
:NORMAL
:SEMI-EXPANDED
:EXPANDED
:EXTRA-EXPANDED
:ULTRA-EXPANDED

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: stretch (FONT font)

automatically generated reader method

Source

common.lisp (file)

Generic Function: weight OBJECT

Returns the weight of the font.

This may be one of the following keywords, in order of increasing weight, or a system-dependent numeric value for the font’s weight.

:THIN
:EXTRA-LIGHT
:LIGHT
:SEMI-LIGHT
:BOOK
:REGULAR
:MEDIUM
:SEMI-BOLD
:BOLD
:EXTRA-BOLD
:BLACK
:EXTRA-BLACK

See FONT

Package

org.shirakumo.font-discovery

Methods

Method: weight (FONT font)

automatically generated reader method

Source

common.lisp (file)

5.1.3 Classes

Class: font ()

A representation of a system font and its font attributes.

See FILE
See FAMILY
See SLANT
See WEIGHT
See SPACING
See STRETCH

Package

org.shirakumo.font-discovery

Source

common.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• print-object (method)
• stretch (method)
• spacing (method)
• weight (method)
• slant (method)
• family (method)
• file (method)

Direct slots

Slot: file

Initargs

:file

Initform

(error "file required.")

Readers

file (generic function)

Slot: family

Initargs

:family

Initform

(error "family required.")

Readers

family (generic function)

Slot: slant

Initargs

:slant

Initform

:roman

Readers

slant (generic function)

Slot: weight

Initargs

:weight

Initform

:regular

Readers

weight (generic function)

Slot: spacing

Initargs

:spacing

Initform

:proportional

Readers

spacing (generic function)

Slot: stretch

Initargs

:stretch

Initform

:normal

Readers

stretch (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *config*

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Special Variable: +family+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +file+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +size+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +slant+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +spacing+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +weight+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Special Variable: +width+

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

5.2.2 Macros

Macro: with-protection UNWIND &body PROTECTED

Package

org.shirakumo.font-discovery

Source

common.lisp (file)

Macro: with-result RESULT &body SUCCESS

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

5.2.3 Functions

Function: config-destroy CONFIG

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: config-substitute CONFIG PATTERN KIND

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: create-pattern ()

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: create-range BEGIN END

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: default-substitute PATTERN

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: destroy-pattern PATTERN

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: destroy-range RANGE

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: destroy-set SET

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: fini ()

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: font-match CONFIG PATTERN RESULT

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: font-set-fonts POINTER-TO-FONT-SET

Function: (setf font-set-fonts) VALUE POINTER-TO-FONT-SET

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: font-set-nfont POINTER-TO-FONT-SET

Function: (setf font-set-nfont) VALUE POINTER-TO-FONT-SET

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: font-set-sfont POINTER-TO-FONT-SET

Function: (setf font-set-sfont) VALUE POINTER-TO-FONT-SET

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: font-sort CONFIG PATTERN TRIM CHARSET RESULT

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: init-load-config-and-fonts ()

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: init-pattern PATTERN &key FAMILY SLANT WEIGHT SPACING STRETCH

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

Function: maybe-enum TYPE THING

Package

org.shirakumo.font-discovery

Source

common.lisp (file)

Function: maybe-enum-val TYPE THING

Package

org.shirakumo.font-discovery

Source

common.lisp (file)

Function: parse-file STRING

Package

org.shirakumo.font-discovery

Source

common.lisp (file)

Function: pattern-add-integer PATTERN OBJECT I

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-add-range PATTERN OBJECT RANGE

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-add-string PATTERN OBJECT STRING

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-get-double PATTERN OBJECT N DOUBLE

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-get-integer PATTERN OBJECT N INTEGER

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-get-range PATTERN OBJECT ID RANGE

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: pattern-get-string PATTERN OBJECT N STRING

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: range-get RANGE BEGIN END

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Function: translate-match FONT

Package

org.shirakumo.font-discovery

Source

linux.lisp (file)

5.2.4 Classes

Class: font-set-tclass ()

Package

org.shirakumo.font-discovery

Source

fontconfig.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types