Module pathname 

helper methods for file system paths

Structs

PathnameFindOptions

configuration for filesystem search. Mirrors Perl LaTeXML::Util::Pathname::pathname_find’s named-arg options; kpsewhich-fallback is NOT one of them — that lives in higher-level LaTeXML::Package::FindFile_aux, which calls pathname_kpsewhich after pathname_find returns empty. Keep this struct directory-search-only for parity.

Enums

KpathseaBackend

Which kpathsea backend this process resolved. Reported by kpathsea_backend so a host-resolution problem is diagnosable from the log instead of surfacing only as indistinguishable “can’t find file” errors.

Functions

absolute

convert a (possibly relative) file path to an absolute one

ambient_kpsewhich_version

The ambient kpsewhich --version banner (full stdout), memoized for the process. It is a global property of the host TeX install, and several consumers read it — kpathsea backend selection (select_kpaths) and ambient-year detection (in latexml_engine; the year-based latex-dump staleness check in turn consumes that detected year) — so kpsewhich is spawned at most once. Returns None if kpsewhich is absent or the call fails.

candidate_pathnames

It’s presumably cheep to concatinate all the pathnames, relative to the cost of testing for files, and this simplifies overall.

canonical

Canonicalize a pathname by simplifying redundant separators, . and .. components. Matches Perl’s pathname_canonical from Pathname.pm.

clear_kpsewhich_memo

Clear the per-thread kpsewhich memo. Called at the start of every conversion (prepare_session): the persistent (non-harness) cortex_worker runs many papers per thread, and a cached cwd-relative MISS from paper A (kpathsea’s path spec includes .) would wrongly persist into paper B (PR_READINESS should-fix 12).

concat

combine a directory and a base name into a full path

cwd

returns the current working directory

directory

obtain the directory portion of a pathname (via Path::parent) Matches Perl’s pathname_directory.

extension

obtain the extension portion of a pathname (via Path::extension). Perl’s pathname_type preserves case; callers that need a lowercased form should apply .to_ascii_lowercase() themselves.

file_name

transform to a canonical file name, via Path::file_name

file_stem

transform to a base name (via Path::file_stem) Note: Perl’s pathname_name returns the stem without extension and without case change.

find

find the requested pathname using the options search configuration. Mirrors Perl pathname_find (LaTeXML/Util/Pathname.pm L376-392): directory search with strict-case match preferred, falling back to a case-insensitive directory scan. The fallback is required for arxiv papers shipping uppercase filenames (e.g. PASJ95.STY referenced as PASJ95.sty) — Perl’s regex pair pushes both strict and /i matches and returns the strict ones if any exist, otherwise the case-insensitive matches. kpsewhich is the caller’s responsibility (see LaTeXML::Package::FindFile_aux).

findall

Find all matching files (like pathname_findall). Port of Perl’s pathname_findall($pathname, %options).

is_absolute

absolute paths start with the filesystem root - check if this is one

is_literaldata

checks if the path starts with the “literal:” protocol

is_nasty

check if pathname contains dangerous pieces

is_raw

Check whether a pathname is a raw TeX source or definition file. Perl: pathname_is_raw

is_reloadable

check whether a pathname is reloadable as a TeX definition

is_url

checks if the path is a conforming URL string

kpathsea_backend

The backend this process resolved, with a short reason. Forces the KPSE initialization so the answer is always the real one.

kpsewhich

make

Compose a pathname from dir, name, type components. Port of Perl’s pathname_make(%pieces).

prewarm_kpathsea

Force-initialize the kpathsea global state and warm up the per- format suffix tables.

protocol

Note that this returns ONLY recognized protocols!

relative

Make a pathname relative to a base directory. Port of Perl’s pathname_relative($pathname, $base).

report_unavailable_kpathsea

search for a list of candidate names via the external kpsewhich utility returning the first path that is found

split

Split the pathname into components (dir,name,type). If pathname is absolute, dir starts with volume or ‘/’

url_split

Simple logic for splitting a URL into protocol://base/path