NAME

       "LaTeXML::Util::Pathname"  - portable pathname and file-system utilities

DESCRIPTION

       This module combines the functionality File::Spec and File::Basename to give a consistent set of filename
       utilities for LaTeXML.  A pathname is represented by a simple string.

   Pathname Manipulations
       "$path = pathname_make(%peices);"
           Constructs a pathname from the keywords in pieces
             dir   : directory
             name  : the filename (possibly with extension)
             type  : the filename extension

       "($dir,$name,$type) = pathname_split($path);"
           Splits the pathname $path into the components: directory, name and type.

       "$path = pathname_canonical($path);"
           Canonicallizes  the  pathname $path by simplifying repeated slashes, dots representing the current or
           parent directory, etc.

       "$dir = pathname_directory($path);"
           Returns the directory component of the pathname $path.

       "$name = pathname_name($path);"
           Returns the name component of the pathname $path.

       "$type = pathname_type($path);"
           Returns the type component of the pathname $path.

       "$path = pathname_concat($dir,$file);"
           Returns the pathname resulting from concatenating the directory $dir and filename $file.

       "$boole = pathname_is_absolute($path);"
           Returns whether the pathname $path appears to be an absolute pathname.

       "$boole = pathname_is_url($path);"
           Returns whether the pathname $path appears to be a url, rather than local file.

       "$boole = pathname_is_literaldata($path);"
           Returns whether the pathname $path is actually a blob of literal  data,  with  a  leading  "literal:"
           protocol.

       "$boole = pathname_is_raw($path);"
           Check if pathname indicates a raw TeX source or definition file.

       "$rel = pathname_is_contained($path,$base);"
           Checks  whether $path is underneath the directory $base; if so it returns the pathname $path relative
           to $base; otherwise returns undef.

       "$path = pathname_relative($path,$base);"
           If $path is an absolute, non-URL pathname, returns the pathname  relative  to  the  directory  $base,
           otherwise simply returns the canonical form of $path.

       "$path = pathname_absolute($path,$base);"
           Returns the absolute pathname resulting from interpretting $path relative to the directory $base.  If
           $path is already absolute, it is returned unchanged.

       "$relative_url = pathname_to_url($path);"
           Creates  a local, relative URL for a given pathname, also ensuring proper path separators on non-Unix
           systems.

   File System Operations
       "$modtime = pathname_timestamp($path);"
           Returns the modification time of the file named by $path, or undef if the file does not exist.

       "$path = pathname_cwd();"
           Returns the current working directory.

       "$dir = pathname_mkdir($dir);"
           Creates the directory $dir and all missing ancestors.  It returns $dir if successful, else undef.

       "$dest = pathname_copy($source,$dest);"
           Copies the file $source to $dest if needed; ie. if $dest  is  missing  or  older  than  $source.   It
           preserves the timestamp of $source.

       "$path = pathname_find($name,%options);"
           Finds  the  first  file  named  $name  that exists and that matches the specification in the keywords
           %options.  An absolute pathname is returned.

           If $name is not already an absolute pathname, then  the  option  "paths"  determines  directories  to
           recursively search.  It should be a list of pathnames, any relative paths are interpreted relative to
           the current directory.  If "paths" is omitted, then the current directory is searched.

           If  the  option  "installation_subdir"  is given, it indicates, in addition to the above, a directory
           relative to the LaTeXML installation directory to  search.   This  allows  files  included  with  the
           distribution to be found.

           The  "types"  option specifies a list of filetypes to search for.  If not supplied, then the filename
           must match exactly.  The type "*" matches any extension.

       "@paths = pathname_findall($name,%options);"
           Like "pathname_find", but returns all matching (absolute) paths that exist.

       "$path = pathname_kpsewhich(@names);"
           Attempt to find a candidate name  via  the  external  "kpsewhich"  capability  of  the  system's  TeX
           toolchain. If "kpsewhich" is not available, or the file is not found, returns a Perl undefined value.

AUTHOR

       Bruce Miller <bruce.miller@nist.gov>

COPYRIGHT

       Public  domain  software,  produced as part of work done by the United States Government & not subject to
       copyright in the US.

perl v5.38.2                                       2024-02-27                       LaTeXML::Util::Pathname(3pm)