TeX::Kpsewhich - Perl implementation of the kpsewhich program
use TeX::Kpsewhich;use TeX::Kpsewhich qw(kpsewhich);
This module provides the functionality of the kpsewhich program which uses Karl Berry's Kpathsea library to search for TeX-related files. There are two available interfaces to the routines: one very similar to the command line interface to kpsewhich and one object oriented method. Since the database is not reloaded between calls to this module within one invocation, it is significantly faster than spawning multiple instances of the kpsewhich program. If multiple results are requested, either by listing multiple filenames or by using the find-all option, then an array of results will be returned. If, however, this is done in scalar context, only the first result will be returned, and a warning will be issued.
Command-line-like invocation The kpsewhich() function may be invoked as follows:
kpsewhich( { opt1 => val1, opt2 => val2, ... }, name1, name2, ...)
which sets the options as requested and then searches for the given files using the options specified. This is exactly like the command line invocation:
kpsewhich --opt1=val1 --opt2=val2 ... name1 name2 ...
There are certain restrictions though: only one of the options which produces output (expand-* and show-path) may be used in any call to kpsewhich, and if one is, then no filenames to search for may be given. The reference to a hash of options is itself optional; the function kpsewhich(name1, name2, ...) will look for the files using the default search path and so on.
Object-oriented use There is a class new method, which creates an object which remembers its selected options. At this time, there is no way of changing the options of an object once it has been created, but it is safe to use mutiple objects with different options. (At least it will be in Web2C 7.3 and onwards; earlier releases had some bugs connected to changing the program name which could cause incorrect search paths to be used following a change of program name.) An object is created by:
$obj = TeX::Kpsewhich->new(opt1 => val1, opt2 => val2, ...);
and then used in the standard way:
$result = $obj->method(...);
For the object-oriented model, these are called as object methods; for the command-line model, they are options like any other. Every method besides find takes precisely one argument; find can take an arbitrary number. Find the files given as arguments, subject to the other options supplied, This is the default function of the command-line model, and there is no `find' option. This function performs variable expansion ($VAR and ${VAR} occurrences in its argument) and returns the expanded result. The expansion is performed by looking for VAR_progname and VAR wnvironment variables, and then in the texmf.cnf files for a value. Failing that, an empty string replaces the variable. This function expands braces in its argument, converting "x{a,b}y" to two path components "xay" and "xby". It then replaces occurrences of tildes in the result by the appropriate home directories and finally performs a full variable expansion, returning the result. This performs similarly to expand_braces on its argument, except that it then fully expands any occurrences of "//" in the resulting path, replacing then with a list of all possible directories which match the pattern. This shows the search path which will be used to search for files of the given format type (as described under format below). The path is tilde, brace and variable expanded, but is not path-expanded in the sense that it may still have instances of "//" present. Returns version and author information. Options may be given in any of the forms debug, -debug or --debug, and every option takes a value. In the case of boolean options such as must-exist, the value is either a true value or a false value, in the Perl sense of truth.
Searching options The program (base)name to pretend we are when searching for files. Be warned, though, that this option did not work properly prior to Web2C version 7.3. Default: the basename of the currently running program. The type of file being searched for. This specifies the search path which will be used, and may be given in either the long form or in the suffix form. The valid values for this option are given by the output of kpsewhich --help. For example, 'type1 fonts' and '.pfa' both specify the same format. There is no default, although if a file is being searched for and its format cannot be deduced from its name, it will be assumed to be a TeX input file. This option cannot be used together with the path option. An explicit path to use for searching. This option conflicts with the format option. If this option is set to true, then the disk will be searched if the file does not appear in the database, otherwise the disk will only be searched if the database does not exist. Default: false. If this option is set to true, then all found occurrences of the file will be returned, rather than just the first match. This option being true implies that the disk will be searched, regardless of the value of must-exist. Default: false. This sets the value of the kpathsea_debug variable to specify the level of debugging output to produce. See the documentation of the Kpathsea library for more information on debugging output. Default: 0.
Font searching options The nature of font searching is slightly different, as we may want to create fonts that we are unable to find. The default is not to, but the following options can be used to affect this behaviour. The value of this option is a reference to an array listing the types of file for which mktex... should be called if they are not found. The possible entries are currently: "pk", "mf", "tex", "tfm", "ofm", "ocp". The default may depend on environment variables and suchlike. Like mktex, but lists those file types for which a mktex... program should not be called. The creation mode to be used, such as "ljfour". This is calculated from the base DPI by default. This sets the base resolution of the device being used when creating fonts. Default: 600. This Perl extension was written by Julian Gilbey <[email protected]>. 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.