Skip to content

global kpse

This library provides two separate, but nearly identical interfaces to the kpathsea file search functionality: there is a “normal” procedural interface that shares its kpathsea instance with LuaTeX itself, and an object oriented interface that is completely on its own.

😱 Types incomplete or incorrect? 🙏 Please contribute!

methods

kpse.default_texmfcnf

function kpse.default_texmfcnf() ->  string

@return - returns the value of the C preprocessor macro DEFAULT_TEXMFCNF without initializing anything else from kpathsea, for example {$SELFAUTOLOC,$SELFAUTOLOC/share/texmf-local/web2c,...}

😱 Types incomplete or incorrect? 🙏 Please contribute!

The way the library looks up variables is driven by the texmf.cmf file where the currently set program name acts as filter. You can check what file is used by with default_texmfcnf.

Reference:

kpse.set_program_name

function kpse.set_program_name(
  name: string,
  progname: string?
)

Initialize the kpathsea library by setting the program name. The optional string allows explicit progname setting.

Before the search library can be used at all, its database has to be initialized. There are three possibilities, two of which belong to the procedural interface.

First, when LuaTeX is used to typeset documents, this initialization happens automatically and the kpathsea executable and program names are set to luatex (that is, unless explicitly prohibited by the user's startup script.)

Second, in TeXLUA mode, the initialization has to be done explicitly via the kpse.set_program_name function, which sets the kpathsea executable (and optionally program) name.

The second argument controls the use of the “dotted” values in the texmf.cnf configuration file, and defaults to the first argument.

Third, if you prefer the object oriented interface, you have to call a different function. It has the same arguments, but it returns a userdata variable.

kpse.new

function kpse.new(
  name: string,
  progname: string?
) ->  userdata

Create a new kpathsea library instance.

The optional string allows explicit progname setting.

Reference:

kpse.record_input_file

function kpse.record_input_file(name: string)

Register used files.

Because callbacks can load files themselves you might need these helpers (if you use recording at all).

Reference:

kpse.record_output_file

function kpse.record_output_file(name: string)

Register used files.

Because callbacks can load files themselves you might need these helpers (if you use recording at all).

Reference:

kpse.find_file

function kpse.find_file(filename: string) ->  string
@param filename - the name of the file you want to find, with or without extension.

Find a file.

The optional string is the file type as supported by the standalone kpsewhich program (default is `tex, no autodiscovery takes place). The optional boolean indicates wether the file must exist. The optional number is the dpi value for PK files.

The most often used function in the library is find_file:

If --output-directory is specified and the value is a relative pathname, the file is searched first here and if it fails it will be searched in the standard tree.

References:

kpse.find_file

function kpse.find_file(
  filename: string,
  ftype: KpseFtype
) ->  string
@param filename - the name of the file you want to find, with or without extension.

@param ftype - maps to the -format argument of kpsewhich. The supported ftype values are the same as the ones supported by the standalone kpsewhich program. The default type is tex. Note: this is different from kpsewhich, which tries to deduce the file type itself from looking at the supplied extension.

Find a file.

The optional string is the file type as supported by the standalone kpsewhich program (default is `tex, no autodiscovery takes place). The optional boolean indicates wether the file must exist. The optional number is the dpi value for PK files.

The most often used function in the library is find_file:

If --output-directory is specified and the value is a relative pathname, the file is searched first here and if it fails it will be searched in the standard tree.

References:

kpse.find_file

function kpse.find_file(
  filename: string,
  ftype: KpseFtype,
  mustexist: boolean
) ->  string
@param filename - the name of the file you want to find, with or without extension.

@param ftype - maps to the -format argument of kpsewhich. The supported ftype values are the same as the ones supported by the standalone kpsewhich program. The default type is tex. Note: this is different from kpsewhich, which tries to deduce the file type itself from looking at the supplied extension.

@param mustexist - is similar to kpsewhich's -must-exist, and the default is false. If you specify true (or a non-zero integer), then the kpse library will search the disk as well as the ls-R databases.

Find a file.

The optional string is the file type as supported by the standalone kpsewhich program (default is `tex, no autodiscovery takes place). The optional boolean indicates wether the file must exist. The optional number is the dpi value for PK files.

The most often used function in the library is find_file:

If --output-directory is specified and the value is a relative pathname, the file is searched first here and if it fails it will be searched in the standard tree.

References:

kpse.find_file

function kpse.find_file(
  filename: string,
  ftype: KpseFtype,
  dpi: number
) ->  string
@param filename - the name of the file you want to find, with or without extension.

@param ftype - maps to the -format argument of kpsewhich. The supported ftype values are the same as the ones supported by the standalone kpsewhich program. The default type is tex. Note: this is different from kpsewhich, which tries to deduce the file type itself from looking at the supplied extension.

@param dpi - This is used for the size argument of the formats pk, gf, and bitmap font.

Find a file.

The optional string is the file type as supported by the standalone kpsewhich program (default is `tex, no autodiscovery takes place). The optional boolean indicates wether the file must exist. The optional number is the dpi value for PK files.

The most often used function in the library is find_file:

If --output-directory is specified and the value is a relative pathname, the file is searched first here and if it fails it will be searched in the standard tree.

References:

kpse.lookup

function kpse.lookup(
  filename: string,
  options: KpseLookupOptions {
    debug = number,
    format = string,
    dpi = number,
    path = string,
    all = boolean,
    mustexist = boolean,
    mktexpk = boolean,
    mktextex = boolean,
    mktexmf = boolean,
    mktextfm = boolean,
    subdir = (string|table),
}
) ->  string
@param filename - the name of the file you want to find, with or without extension.

Find a file (extended interface).

A more powerful (but slower) generic method for finding files is also available. It returns a string for each found file.

If --output-directory is specified and the value is a relative pathname, the file is searched first here and then in the standard tree.

References:

kpse.init_prog

function kpse.init_prog(
  prefix: string,
  base_dpi: number,
  mfmode: string,
  fallback: string
)

Initialize a PK generation program. The optional string is the metafont mode fallback name.

Extra initialization for programs that need to generate bitmap fonts.

References:

kpse.readable_file

function kpse.readable_file(name: string) -> f string?

@return f - The return value is the actual absolute filename you should use, because the disk name is not always the same as the requested name, due to aliases and system-specific handling under e.g. MS Dos Returns nil if the file does not exist or is not readable.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Returns true if a file exists and is readable.

Test if an (absolute) file name is a readable file.

References:

kpse.expand_path

function kpse.expand_path(s: string) -> r string

Expand a path.

Output the complete expansion of string, with each element separated by the usual path separator on the current system (; on Windows, : otherwise). This may be useful to construct a custom search path for a format not otherwise supported. Like kpsewhich’s -expand-path.

References:

kpse.expand_var

function kpse.expand_var(s: string) -> r string

Expand a variable.

Output the variable and tilde expansion of string. For example, with the usual texmf.cnf, kpse.expand_var('$TEXMF') returns the TeX system hierarchy root(s). The specified string can contain anything, though, not just variable references. This calls kpse_var_expand (see Programming with config files). Like kpsewhich’s -expand-var:

References:

kpse.expand_braces

function kpse.expand_braces(s: string) -> r string

Expand the braces in a variable.

Output variable, tilde, and brace expansion of string, which is assumed to be a single path element. Like kpsewhich’s -expand-braces

References:

kpse.show_path

function kpse.show_path(file_type: string) -> search_path string

List the search path for a specific file type.

Show the path that would be used for file lookups of file type name. Either a filename extension (pk, .vf, etc.) or an integer can be used, just as with --format, described in the previous section.

Like kpsewhich’s -show-path

References:

kpse.var_value

function kpse.var_value(variable: string) -> value string

Return the value of a variable.

Outputs the value of variable (a simple identifier like TEXMFDIST, with no $ or other constructs), expanding $ (see Variable expansion) and ~ (see Tilde expansion) constructs in the value. ‘~` expansion happens at the beginning of the overall value and at the beginning of a variable expansion, but not arbitrarily within the string. Braces are not expanded.

Like kpsewhich’s -var-value

References:

kpse.version

function kpse.version() -> version string

@return version - For example kpathsea version 6.3.4

😱 Types incomplete or incorrect? 🙏 Please contribute!

Return the kpathsea version string.

Reference:

kpse.check_permission

function kpse.check_permission(name: string)
 -> okay boolean
 -> found string

local okay, found = kpse.check_permission(name)
if okay and found then
  return io.popen(found,...)
end

Reference: