---
name: "LaTeXML::Util::Pathname"
section: "3pm"
platform: "linux"
package: "latexml"
version: "0.8.8-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/LaTeXML::Util::Pathname"
---

# LaTeXML::Util::Pathname(3pm)

portable pathname and file-system utilities

## 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.