Files
craft-libs/crates/docpath
aiongg dffc61a7e0 Merge storytold main 832883b5 (sync 16 Nov)
961 upstream commits since 7bb6c900. Resolutions:
- Test-only conflicts: upstream tests from before the base that our side
  cut stay cut; tests new upstream are kept (audio aac/config, layout,
  encode_format; cms lutfile; media mux; print windows_native, ticket;
  update self_update; xml hostile).
- Code our side moved, with upstream's change carried to the new place:
  craft-media mux roll sample groups (mux/boxes.rs) and writer-start
  offsets with overflow checks (mux/progressive.rs); craft-print's
  shrink-to-fit scale guard (sheets/plan.rs); craft-update's nextest
  archive detection (self_update/detect.rs); craft-vectorcraft-format's
  Tail::write_to_with (container.rs); craft-i18n's pedantic fixes
  (bidi.rs, negotiation.rs).
- craft-ui: the old crate's modules stay removed; gpu_test_lock guarded
  their per-test wgpu renderers, which the snapshot kit does not have.
- New upstream tests in crates that build their integration tests into
  the library's test executable are modules of tests/main.rs (audio
  flac_decode and qoa_oracle, cms, docpath, pcraft-format,
  vectorcraft-format).
- The 22 new crates are optional members of the craft facade.
2026-11-16 01:52:09 +00:00
..

craft-docpath

Decides whether a file path or file URL stored in a document may be opened, read or written, and makes safe file names from user text. No dependencies beyond the standard library.

Item Responsibility
classify, is_local, resolve, resolve_absolute A lexical check of a stored path: local files, and files on the share the document came from, are followed; other computers, device paths and non-file URLs are refused (PathKind, Refused). It does no I/O and gives the same answer on every platform apart from colons.
links Linked files: Link, LinkIdentity and LinkStatus, status per link, check_candidate and rank for a file picked to replace a missing one, derive_remap and Remap to relink the others, folder_matches, and LinkSearch to search a folder tree as a job. File access goes only through LinkFiles (SystemLinkFiles; FakeLinkFiles in stories and tests).
names File names made from user text: a document title as the suggested name of an export, a page range as a set of file names, an attachment's stored name as a Save suggestion; natural_cmp is the order file names are listed in. The rules hold on every platform, so a name made on Linux also works on Windows.

Names

  • safe_file_name(text, fallback): path separators, reserved characters (/ \ : * ? " < > |) and control characters become _; bidirectional controls are dropped; leading whitespace and trailing dots and whitespace are trimmed; Windows device names (CON, NUL, COM0–COM9, LPT0–LPT9, CONIN$, CONOUT$, superscript forms, with any extension) get a leading _. The result is cut to MAX_NAME_BYTES (200) at a character boundary; a short extension (under 100 bytes) is kept and the stem is cut instead. fallback is returned, as given, when nothing is left.
  • safe_file_stem(text, extension): the same rules for a name whose extension the app adds; a trailing .<extension> in any case is removed first.
  • is_plain_file_name and is_reserved_device_name: the checks the two functions use.
  • unique_file_name(name, CopyNumbering, taken): the first free name 2.ext (Space, Finder) or name (2).ext (Parenthesized, Explorer and GNOME Files; CopyNumbering::platform() picks the platform's), numbered before the last extension; Parenthesized counts on from a trailing (n), Space keeps a trailing number as part of the name (Chapter 1 2.docx).