TeX::Kpathsea(3pm) User Contributed Perl Documentation TeX::Kpathsea(3pm) NAME TeX::Kpathsea - Perl interface to the Kpathsea library SYNOPSIS use TeX::Kpathsea; use TeX::Kpathsea qw(:formats :functions :misc); use TeX::Kpathsea qw(:short_formats :short_functions :short_misc); DESCRIPTION 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) 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 $kpse_<type>_format, kpse_<type>_format() For each of the format types recognised by the Kpathsea library, there is a $kpse_<type>_format and kpse_<type>_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. @kpse_all_formats 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 kpse_reset_program_name($new_progname) 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. kpse_init_prog($PREFIX, $dpi, $mode, $fallback) 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. kpse_init_format($format_type) This routine initialises the search paths and other important information for the given format. The format type is one of the kpse_<type>_format variables or functions described above. kpse_maketex_option($fmtname, $enable) 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". kpse_find_file($name, $format_type, $must_exist) 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. kpse_find_glyph($font_name, $dpi, $format_type, $glyph_ref) 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); kpse_path_search($path, $name, $must_exist) 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. kpse_all_path_search($path, $name) 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. kpse_var_expand($string) 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. kpse_tilde_expand($string) 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. kpse_expand($string) This is equivalent to kpse_var_expand(kpse_tilde_expand($string)). kpse_brace_expand($path) 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. kpse_path_expand($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 $kpse_version This contains the version string from the underlying Kpathsea library. @kpse_all_format_names This array lists all of the kpse_<type>_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. @kpse_format_info This is an array indexed by the values of the $kpse_<type>_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. $kpathsea_debug and $kpse_debug 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. $kpse_program_name 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. SEE ALSO TeX::Kpsewhich(3pm) and Kpathsea library documentation (available with Web2C distributions as some of kpathsea.{texi,info,dvi}). BUGS I don't know of any yet, but this is only alpha-version software, so caveat emptor. AUTHOR This Perl extension was written by Julian Gilbey <jdg@debian.org>. The C-wrapper file was created using the SWIG system written by Dave Beazley <beazley@cs.utah.edu>, 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. COPYRIGHT 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. perl v5.8.4 2004-08-14 TeX::Kpathsea(3pm)