Struct Link

Source

pub struct Link {
    pub label: Option<String>,
    pub target: String,
    pub wikilink: bool,
}

Expand description

A parsed link string: an optional human label and the target it points at.

Fields§

§label: Option<String>

The display label, when written as [label](target) or [[target|label]].

§target: String

The target exactly as written (a relative path, an id:<id> handle, or a URL for overlay relations that point off-workspace).

§wikilink: bool

true when the scalar was written as an Obsidian wikilink ([[target]] / [[target|label]]) rather than a markdown link or bare target — preserved so render round-trips the wrapper.

Implementations§

Source §

impl Link

Source

pub fn parse(raw: &str) -> Self

Parse a raw link string. [label](target) yields both parts; anything else is a bare target with no label. A target wrapped in Markdown angle brackets (<…>, used when it contains spaces) is unwrapped only when it appears as the URL portion of a successfully parsed [label](<target>) — never when it wraps a bare, unlabeled value, which stays byte-literal (diaryx reads a bare <…> as a literal path, angle brackets and all: see parse_path_only and the link_style render tests). A [[target]] / [[target|label]] Obsidian wikilink scalar is also recognized here; use parse_path_only when the caller’s value is a frontmatter path field that must not reinterpret a literal [[…]] string as a wikilink.

Source

pub fn parse_path_only(raw: &str) -> Self

parse, but never treats "[[target]]" as an Obsidian wikilink — such a value is left exactly as written (a bare literal, or, if it happens to also match [label](target), a markdown link). This is the opt-out a frontmatter path field needs: diaryx’s own path-value parser has no wikilink convention at all, so a workspace that stores a literal "[[…]]"-shaped string in a path property (unusual, but legal input data) must round-trip it untouched rather than have parse silently reinterpret it as a link. Every other rule of parse — [label](target) splitting, balanced parens, angle-bracket unwrapping of a parsed URL — applies unchanged.

Source

pub fn render(&self) -> String

Render back to a writable link string. A labeled link keeps its label and wraps the URL in Markdown angle brackets when it holds a space or paren (so ] / ) in the path cannot break parsing); a bare target is emitted verbatim — brackets belong inside [label](…), never around a bare value (matching diaryx, which reads a bare <…> as a literal path).

Source

pub fn with_target(&self, target: impl Into<String>) -> Self

This link with a different target, keeping the label and wrapper. The rename path uses this so [Design](old.md) becomes [Design](new.md), never a bare new.md.

Source

pub fn with_label(&self, label: impl Into<String>) -> Self

This link with a different display label, keeping the target and wrapper. The retitle path uses this so [Old Title](id:abc) becomes [New Title](id:abc) when the target is renamed — the label follows the title while the (id or path) target stays exactly as written.

Source

pub fn is_external(&self) -> bool

true when the target points off-workspace (a URL or mail address) rather than at a file — such links are never resolved against the filesystem or rewritten by moves.

Source

pub fn locator(&self) -> Option<&str>

The sub-document locator this target carries — the text after a #, naming a place inside a document rather than a document.

A locator is carried, never resolved. prov strips it before resolving the target and re-attaches it on rewrite, which is the same contract §4 gives an external URL: recognized by syntax, never validated. What it means is the workspace’s business — a verse number in a chapter, a heading slug, a line range — so a locator naming nothing is not a check finding. That is the price of not teaching prov every document format’s internal address space.

None for an external target (a URL’s fragment belongs to the URL) and for a target that is only a locator (#3), which stays byte-literal — see split_locator.

Source

pub fn addressed_target(&self) -> &str

This link’s target with any locator removed — the part that names a document, and so the only part that resolves.

Source

pub fn with_path(&self, path: impl Into<String>) -> Self

This link with its document part replaced, preserving the locator.

The rewrite passes (rename, re-relativize, restyle) use this rather than with_target, which sets the target verbatim: a move changes where a document lives, never which part of it was pointed at.

Source

pub fn id_ref(&self) -> Option<IdRef>

What this link’s id:-scheme target names — local, foreign, or malformed. None when the target carries no id scheme at all (a path, an alias, a URL).

Any locator is stripped first, so id:abc1234#2-3 names the same document as id:abc1234.

Source

pub fn id_target(&self) -> Option<Id>

The stable ID this link names, when the target uses the id:<id> scheme (or the legacy colophon:<id> spelling) — the location-independent alternative to a relative path. Such targets resolve through the workspace’s ID registry, never against the filesystem, and are deliberately not rewritten by moves: staying valid across moves is their entire point.

Local ids only. A cross-workspace id:<workspace>/<id> yields None, because the registry this would be resolved against is not the one that issued the id — see id_ref. Callers asking “must a move leave this alone?” want is_path_target, which covers every id form.

Source

pub fn foreign_target(&self) -> Option<(String, Id)>

The workspace and id this link names, when it is a cross-workspace reference (id:<workspace>/<id>).

Source

pub fn is_path_target(&self) -> bool

Whether this link’s target is a path — the only kind that says where its target lives, and so the only kind a move may rewrite.

False for an external URL and for every id: reference alike (local, foreign, and malformed): none of them encodes a location, so re-relativizing one could only damage it. This is the predicate the rename, re-relativize and restyle passes filter on.