TeX::Kpathsea

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)