LaTeXML...Pathname(3)

🌸 NAME 🌸

okay bestie, meet LaTeXML::Util::Pathname — portable pathname and file-system utilities 💅. It's part of the User Contributed Perl Documentation crew, and it's here to make path stuff feel a little less chaotic ✨

💖 DESCRIPTION 💖

lowkey iconic: 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. periodt 🫶

🧚 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 pathname $path into the components: directory, name and type. clean split, no crumbs ✨
• $path = pathname_canonical($path); — canonicalizes pathname $path by simplifying repeated slashes, dots representing current or parent directory, etc. so tidy 🎀
• $dir = pathname_directory($path); — returns the directory component of pathname $path. that folder bit 📁
• $name = pathname_name($path); — returns the name component of pathname $path. that filename bit 🏷️
• $type = pathname_type($path); — returns the type component of pathname $path. that extension bit 🍑
• $path = pathname_concat($dir,$file); — returns the pathname resulting from concatenating directory $dir and filename $file. glue those bits together 🫶
• $boole = pathname_is_absolute($path); — returns whether pathname $path appears to be an absolute pathname. absolute vibes check ⭐
• $boole = pathname_is_url($path); — returns whether pathname $path appears to be a url, rather than local file. url or local? iykyk 🌐
• $boole = pathname_is_literaldata($path); — returns whether pathname $path is actually a blob of literal data, with a leading "literal:" protocol. literal data moment 🧚
• $boole = pathname_is_raw($path); — check if pathname indicates a raw TeX source or definition file. raw TeX realness 🔥
• $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. contained or not contained, that is the question 🦋
• $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. relative realness 🌈
• $path = pathname_absolute($path,$base); — returns the absolute pathname resulting from interpreting $path relative to the directory $base. If $path is already absolute, it is returned unchanged. absolute and unbothered 👑
• $relative_url = pathname_to_url($path); — creates a local, relative URL for a given pathname, also ensuring proper path separators on non-Unix systems. url-ify it, bestie 💅

🦋 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. timestamp check ⏰
• $path = pathname_cwd(); — returns the current working directory. where are we? iconic 📍
• $dir = pathname_mkdir($dir); — creates the directory $dir and all missing ancestors. It returns $dir if successful, else undef. make the whole directory tree happen 🌱
• $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. copy with timestamp preservation 🍓
• $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. the search begins 🔎
  • 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. collect all the matches, no crumbs left behind 💖
• $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. kpsewhich said what it said 🧚

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

💖 that’s the tea, bestie — this page comes from perl v5.42.3, dated 2024-02-26, under the page tag LaTeXML...Pathname(3). go forth and pathname slay 💅✨