--- name: "TeX::Kpathsea" section: "3pm" platform: "linux" package: "libkpathsea-perl" version: "3.4.5.1-1" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/TeX::Kpathsea" --- # TeX::Kpathsea(3pm) TeX::Kpathsea - Perl interface to the Kpathsea library ``` use TeX::Kpathsea; use TeX::Kpathsea qw(:formats :functions :misc); use TeX::Kpathsea qw(:short_formats :short_functions :short_misc); ``` This module provides an interface to Karl Berry's Kpathsea library from Perl. Kpathsea is a path-searching library intended to find inputs files for TeX and friends in a coherent fashion. This Perl library is intended to provide the functionality required to write a Perl version of [*kpsewhich*(1)](/kpsewhich/1.md) and little more. If you do not know what the Kpathsea library is, or how to use the low-level functions provided in it, then this library is probably not for you. If you just want the functionality of the **kpsewhich** program within your Perl code, have a look at the *TeX::Kpsewhich* module instead, which provides a nice interface to this module. Furthermore, this module does not provide an interface to the whole Kpathsea library, but only to a subset of it which is more than adequate to implement the functionality of **kpsewhich**. More functionality may be added in later versions. In the list of functions and variables below, the \`:formats', \`:functions' and \`:misc' tags provide the standard names, and the \`short\_\*' variants provide the names with the initial \`kpse\_' removed from the name. (Except for $*kpse\_version*, which is the same in the \`short\_misc' variant.) Either form may be used to refer to a variable or function with a fully package-qualified name. No functions or variables are exported by default. This documentation does not attempt to provide full documentation of what the library functions do, but only enough to understand how to use them in Perl. Please consult the Kpathsea documentation for full details.\ **Initialisation of library** The *kpse\_set\_program\_name* function is called during initialisation, although the *kpse\_reset\_program\_name* function may be used to change the apparent program name (stored in $*kpse\_program\_name*) for use by functions such as *kpse\_find\_file*. It may be appropriate to call the *kpse\_init\_prog* function before calling certain font-searching routines, as described in the Kpathsea documentation. Also, if appropriate, make certain to initialise the format info for a given format using *kpse\_init\_format* before trying to read data from the structure.\ **Variables exported by the \`:formats' tag** For each of the format types recognised by the Kpathsea library, there is a $*kpse\_\\_format* and *kpse\_\\_format*() defined, both of which return the correct value for input into the various path-searching functions described below. Note that *kpse\_last\_format* is not available, as the array described next makes this redundant. A list of all of the format type is found in the *tex-file.h* header file. This array contains a list of all of the recognised formats in their internal representation, allowing them to be used in a loop such as: ``` use TeX::Kpathsea qw(:functions :formats); foreach $fmt (@kpse_all_formats) { kpse_init_format($fmt); } ``` **List of functions exported by the \`:functions' tag** This changes the value of $*kpse\_program\_name*, which is the program name assumed for performing searches, to $*new\_progname*. It resets all of the currently cached search paths so that they will not interfere with subsequent searches. If the program is going to perform font searches, then this routine should be called. The environment variables *PREFIX*{**FONTS**, **HEADERS**, **MAKEPK**, **SIZES**} are looked at for program-specific paths and settings, and then the *mktex\** environment variables **MAKETEX\_BASE\_DPI** and **MAKETEX\_MODE** are set to the values of dpi and mode, respectively. fallback is a font to use if all else fails. Both mode and fallback may be set to the integer scalar 0 to use the defaults. A typical use of this function would be something like ``` kpse_init_prog(uc($kpse_program_name), $dpi, $mode, 0); ``` where $*dpi* and $*mode* have been set appropriately. This routine initialises the search paths and other important information for the given format. The format type is one of the *kpse\_\\_format* variables or functions described above. Depending on whether $*enable* is true or not, this enables or disables the calling of a *mktex...* script for the given format type if a "must-exist" search is performed. $*fmtname* is currently one of the strings: "pk", "mf", "tex", "tfm", "ofm", "ocp". This function tries to locate the given filename $*name* in the search path appropriate to its format type, given by $*format\_type* as for *kpse\_init\_format*. If $*must\_exist* is true, then the disk will be searched if the file is not listed in the *ls-R* database, and if necessary, an appropriate *mktex...* program will be invoked. It is not necessary to call *kpse\_init\_format* before calling this function, as the search paths will be initialised if necessary. The function returns the absolute filename of the first match found, if any. Note that the value of $*kpse\_program\_name* will be taken into account, so this might need to be set appropriately using *kpse\_reset\_program\_name*. The same applies to the other functions described below. This function acts in a similar way to *kpse\_find\_file*, but will find glyph files, taking into account tolerance in the resolution, the fallback sizes, the fallback font, alias files and so on. All of the details are described in the Kpathsea manual -- check there for details. The first three arguments are the font's name (without the resolution), the resolution required and the format type to search for (probably $*kpse\_pk\_format*, $*kpse\_gf\_format* or $*kpse\_any\_glyph\_format*). The last argument is a pointer to a *kpse\_glyph\_file\_type* structure. I have made no attempt to make the contents of this structure available, as they are unlikely to be of use to users of this module, although this may change in the future. However, it is a necessary parameter, so the calling code for this function should be something like the following: ``` $glyph_ret = kpse_glyph_file_type->new(); $found_glyph=kpse_find_glyph('cmr10', 300, $kpse_pk_format, $glyph_ret); ``` This is a lower level searching function than *kpse\_find\_file*. It requires an explicit search path to be given, which is subject to variable and then tilde expansion. It searches for the file with the given name (ignoring $*path* if $*name* is an absolute filename). The $*must\_exist* parameter has the same meaning as in *kpse\_find\_file*. The function returns the absolute filename of the first match found, if any. This is identical to *kpse\_path\_search*, except that **all** matching files found will be returned, and the disk will be scanned in any event. The return value from this function is a reference to an array of the absolute filenames found. This function performs variable expansion ($VAR and ${VAR} occurrences in $*string*) and returns an expanded (new) string. $*string* remains untouched. The expansion is performed by looking for a VAR wnvironment variable and then in the *texmf.cnf* files for a value. Failing that, an empty string replaces the variable. This function is identical to *kpse\_var\_expand* except that it replaces ~ and ~name in $*string* by the environment variable HOME or name's home directory respectively. This is equivalent to *kpse\_var\_expand*(*kpse\_tilde\_expand*($*string*)). This function expands braces in $*path*, converting `"x{a,b}y"` to two path components `"xay"` and `"xby"`. It then runs *kpse\_expand* on each component, returning the fully expanded path. This runs *kpse\_brace\_expand* on $*path*, and then expands any occurrences of `"//"` in the resulting path, replacing then with a list of all possible directories which match the pattern.\ **List of variables exported by the \`:misc' tag** This contains the version string from the underlying Kpathsea library. This array lists all of the *kpse\_\\_format* names. It is probably not very useful except for reference purposes, as the @*kpse\_all\_sormats* probably provides the functionality you are looking for. This is an array indexed by the values of the $*kpse\_\\_format* variables. Each index entry points to a *kpse\_format\_info\_type* struct, with fields which you will know if you need to use it. The fields are accessed as follows: ``` $fmt=kpse_tex_format(); # for ease kpse_init_format($fmt); $type = $kpse_format_info[$fmt]->{'type'}; # the "->" is optional $rsuffix = $kpse_format_info[$fmt]{'suffix'}; # this is a reference to # the suffix array ``` The two fields which return references to arrays are *suffix* and *alt\_suffix*. There is currently no way to access the *program\_enable\_level* field; support may be added later for this. These two equivalent variables can be used to set the Kpathsea debugging status. In the \`:short\_misc' version, there are still two equivalent variables: $*kpathsea\_debug* and $*debug*. This variable stores the (base)name of the program we are pretending to be, and is used to select appropriate search paths based on the function name. It is initially set to the basename of the invoked program, but maybe changed by using the *kpse\_reset\_program\_name* function. [*TeX::Kpsewhich*(3pm)](/TeX::Kpsewhich/3pm.md) and Kpathsea library documentation (available with Web2C distributions as some of kpathsea.{texi,info,dvi}). I don't know of any yet, but this is only alpha-version software, so caveat emptor. This Perl extension was written by Julian Gilbey \. The C-wrapper file was created using the SWIG system written by Dave Beazley \, with help from Dave and other people on the SWIG mailing list. It is highly likely that at some stage there will also be significant input from the tex-k and teTeX mailing list readers. This software is Copyright Julian Gilbey 1999 and is released under the GNU General Public License version 2 or later. There is no warranty of any kind.