#[non_exhaustive]pub struct FlakeRef { /* private fields */ }Expand description
The General Flake Ref Schema
Implementations§
Source§impl FlakeRef
impl FlakeRef
Sourcepub fn new(kind: FlakeRefType) -> Self
pub fn new(kind: FlakeRefType) -> Self
Construct a FlakeRef around kind with no fragment and an empty
LocationParameters block. Use the consuming with_* builders or
the set_* mutators to fill in the rest.
Sourcepub fn kind(&self) -> &FlakeRefType
pub fn kind(&self) -> &FlakeRefType
Read access to the kind. Pattern-matching consumers go through this accessor rather than the (private) field directly.
Sourcepub fn kind_mut(&mut self) -> &mut FlakeRefType
pub fn kind_mut(&mut self) -> &mut FlakeRefType
Mutable access to the kind for in-place edits. The consuming
Self::with_kind builder is the right tool when chaining;
reach for kind_mut only when you must rewrite a field on a
borrowed FlakeRef.
Sourcepub fn id(&self) -> Option<&str>
pub fn id(&self) -> Option<&str>
The repo identifier for the kind (repo for GitForge, the trailing
path segment of a Resource(Git) URL); None otherwise.
Sourcepub fn owner(&self) -> Option<&str>
pub fn owner(&self) -> Option<&str>
Owner (organisation/user) for the kind, when applicable. Returns
Some for GitForge and for Resource(Git) URLs that look like
domain/owner/repo; None for Path, Indirect, and other
resources.
Sourcepub fn repo(&self) -> Option<&str>
pub fn repo(&self) -> Option<&str>
Repository name for the kind, when applicable. See Self::owner
for the kinds that produce Some.
Sourcepub fn domain(&self) -> Option<&str>
pub fn domain(&self) -> Option<&str>
Domain (host) for the kind, when applicable. Returns the canonical
host string for git-forge platforms (github.com, gitlab.com,
git.sr.ht) – or the ?host= override for self-hosted instances
– and the host portion of a Resource(Git) URL (with :port
retained when the port is non-default for the scheme); None
otherwise.
Matches Nix’s per-scheme host resolution: the host attr
defaults to the canonical domain.
Sourcepub fn forge_identity(&self) -> Option<ForgeIdentity>
pub fn forge_identity(&self) -> Option<ForgeIdentity>
Bundled identity for git-forge kinds. Returns Some only for
FlakeRefType::GitForge; Resource(Git) URLs do not have a
guaranteed-parseable owner/repo/domain triple, and Path /
Indirect have no identity at all.
Honours the ?host= override (matching Nix’s per-scheme host
resolution); falls back to the platform’s canonical domain when
no override is set. The SourceHut canonical default stays
git.sr.ht rather than the apex sr.ht, which does not serve
git over HTTPS.
Sourcepub fn ref_(&self) -> Option<&str>
pub fn ref_(&self) -> Option<&str>
The ref_ (branch or tag name) for kinds that carry one, borrowed.
Sourcepub fn rev(&self) -> Option<&str>
pub fn rev(&self) -> Option<&str>
The rev (40-hex commit hash) for kinds that carry one, borrowed.
Sourcepub fn ref_or_rev(&self) -> Option<&str>
pub fn ref_or_rev(&self) -> Option<&str>
Whichever of rev / ref_ is set, preferring rev when pinned;
the typical “what does this ref resolve to?” answer. Returns
borrowed &str; callers wanting an owned String use
.map(str::to_owned).
Sourcepub fn ref_kind(&self) -> RefKind
pub fn ref_kind(&self) -> RefKind
Discriminates which of ref_ / rev are populated; useful when the
caller needs to switch on the four-way combination without writing
nested Option matches.
Sourcepub fn is_pinned_to_rev(&self) -> bool
pub fn is_pinned_to_rev(&self) -> bool
true when the kind has a rev set (canonical Nix’s “pinned to a
commit”). False for refs-by-name and for kinds that don’t carry
rev at all.
Sourcepub fn ref_source_location(&self) -> RefLocation
pub fn ref_source_location(&self) -> RefLocation
Where the kind’s ref/rev is rendered. Reads the kind’s RefLocation
directly; Path is fixed at QueryParameter because its rev has no
path-component spelling in Nix’s grammar.
Sourcepub fn params(&self) -> &LocationParameters
pub fn params(&self) -> &LocationParameters
Read-only access to the query-string parameters.
Sourcepub fn fragment(&self) -> Option<&str>
pub fn fragment(&self) -> Option<&str>
Trailing #fragment retained verbatim. Nix uses fragments to select
an attribute path inside a flake (e.g. github:nixos/nixpkgs#hello);
the raw string is preserved without interpretation.
Sourcepub fn set_ref(&mut self, new_ref: Option<String>)
pub fn set_ref(&mut self, new_ref: Option<String>)
Write new_ref into the kind’s typed ref_ slot. Silently no-op for
kinds that do not carry ref/rev. For FlakeRefType::Resource,
writing a non-None value also flips ref_location to
RefLocation::QueryParameter; Resource has no path-component
ref/rev representation, so leaving it as PathComponent would cause
Display to drop the value silently.
Sourcepub fn set_rev(&mut self, new_rev: Option<String>)
pub fn set_rev(&mut self, new_rev: Option<String>)
Write new_rev into the kind’s typed rev slot. See Self::set_ref
for the Resource ref_location flip rationale.
Sourcepub fn set_fragment(&mut self, fragment: Option<String>)
pub fn set_fragment(&mut self, fragment: Option<String>)
Write fragment (the #suffix) into the typed slot.
Sourcepub fn set_ref_location(&mut self, loc: RefLocation)
pub fn set_ref_location(&mut self, loc: RefLocation)
Set RefLocation on the kind’s ref_location slot. Renamed from
set_location, which was easy to misread as “modify the URL
location string”; this method writes the routing tag that controls
whether ref/rev render as ?ref= or as a path component.
Sourcepub fn set_shallow(&mut self, shallow: bool)
pub fn set_shallow(&mut self, shallow: bool)
Typed mutator for the shallow query parameter. true enables a
shallow clone (mapped to ?shallow=1 on Display); false writes
?shallow=0. Pass through LocationParameters::set_shallow to
clear the slot entirely.
Sourcepub fn set_submodules(&mut self, submodules: bool)
pub fn set_submodules(&mut self, submodules: bool)
Typed mutator for the submodules query parameter; behaves like
Self::set_shallow.
Sourcepub fn set_nar_hash(&mut self, hash: Option<String>)
pub fn set_nar_hash(&mut self, hash: Option<String>)
Typed mutator for the narHash query parameter.
Sourcepub fn set_last_modified(&mut self, ts: Option<String>)
pub fn set_last_modified(&mut self, ts: Option<String>)
Typed mutator for the lastModified query parameter.
Sourcepub fn set_rev_count(&mut self, count: Option<String>)
pub fn set_rev_count(&mut self, count: Option<String>)
Typed mutator for the revCount query parameter.
Sourcepub fn with_ref(self, r: Option<String>) -> Self
pub fn with_ref(self, r: Option<String>) -> Self
Consuming builder variant of Self::set_ref. Silently no-ops
on kinds without a ref_ slot (FlakeRefType::Path); see
Self::try_with_ref for the loud opt-in alternative that
surfaces a typed error instead.
Sourcepub fn with_rev(self, r: Option<String>) -> Self
pub fn with_rev(self, r: Option<String>) -> Self
Consuming builder variant of Self::set_rev. See
Self::try_with_rev for the fallible variant kept for API
symmetry with Self::try_with_ref.
Sourcepub fn try_with_ref(self, new_ref: Option<String>) -> Result<Self, NixUriError>
pub fn try_with_ref(self, new_ref: Option<String>) -> Result<Self, NixUriError>
Fallible variant of Self::with_ref: returns
NixUriError::Unsupported when the kind cannot carry a ref per
Nix’s per-scheme attribute rules.
Surfaces UnsupportedReason::Field for kinds outside the
ref-bearing set (FlakeRefType::Path, ResourceType::File
and ResourceType::Tarball). Setting a ref on these kinds via
Self::with_ref is a silent no-op (Path) or renders a string
the parser would reject (File/Tarball, breaking the round-trip
invariant); try_with_ref lets callers diagnose the mismatch at
the call site.
try_with_ref(None) is always Ok: clearing has no Nix-level
implications.
Sourcepub fn try_with_rev(self, new_rev: Option<String>) -> Result<Self, NixUriError>
pub fn try_with_rev(self, new_rev: Option<String>) -> Result<Self, NixUriError>
Fallible variant of Self::with_rev. All current kinds permit
rev per Nix’s per-scheme attribute rules, so this method always
returns Ok. It exists for API symmetry with
Self::try_with_ref so callers can write the same
fallible-builder shape regardless of which slot they are
writing.
Sourcepub fn with_fragment(self, fragment: Option<String>) -> Self
pub fn with_fragment(self, fragment: Option<String>) -> Self
Consuming builder variant of Self::set_fragment.
Sourcepub fn with_kind(self, kind: FlakeRefType) -> Self
pub fn with_kind(self, kind: FlakeRefType) -> Self
Consuming builder that sets the kind in a chain.
Sourcepub fn with_params(self, params: LocationParameters) -> Self
pub fn with_params(self, params: LocationParameters) -> Self
Consuming builder that installs a fresh LocationParameters block.
For incremental edits, use the typed set_* mutators instead.
Sourcepub fn without_pin(self) -> Self
pub fn without_pin(self) -> Self
Clear the rev slot (the “pin”); leaves ref_ alone. Useful when
the caller wants the named branch/tag rather than a specific
commit.
Sourcepub fn pin_to_rev(self, rev: String) -> Self
pub fn pin_to_rev(self, rev: String) -> Self
Pin to a specific commit, clearing any pre-existing ref_ first.
with_rev(Some(rev)) writes only the rev slot, leaving any
ref_ already on the kind in place. The GitForge Display arm
renders ref_.or(rev) when RefLocation::PathComponent is
active, so a ref_-bearing forge URL with a freshly written
rev round-trips back to the named ref and silently drops the
pinned commit. pin_to_rev is the atomic builder that performs
the clear-ref-then-set-rev sequence callers want.
For kinds without a ref_ slot (FlakeRefType::Path), this
only writes the rev; there is no ref to clear.
Sourcepub fn into_uri(self) -> String
pub fn into_uri(self) -> String
Consume and render to a String; the same output as to_string
but without an intermediate clone when the caller already owns
self.
Sourcepub fn to_canonical_string(&self) -> String
pub fn to_canonical_string(&self) -> String
Canonical wire form of this FlakeRef, matching the URL Nix
would emit for the same input.
Pairs with Display (and the equivalent Self::into_uri),
which preserves the input verbatim for byte-stable round-trips.
to_canonical_string instead emits the form Nix would produce,
normalising every shape that Nix collapses on the way out:
GitForge(github:/gitlab:/sourcehut:): renders as<scheme>:<owner>/<repo>[/<ref-or-rev>]regardless of where the parsed value came from.revwins overref_when both are populated, matching Nix’s behaviour (Nix asserts that ref and rev are never both set on a git-archive URL, so the both-set case is nonsensical for consumers). The query carries onlyhostandnarHashwhen set.Resource(Git): emitsrefandrevalways when set, and the typed booleans (shallow,lfs,submodules,exportIgnore,verifyCommit) only for the truthy branch.allRefsis never emitted because Nix’s git scheme does not include it on canonical output.narHash,lastModified,revCount,dir,host, and arbitrary keys are dropped.Resource(Mercurial): emits onlyrefandrev.Indirect,Path,Resource(File),Resource(Tarball): delegated toDisplay; their existing form already matches Nix byte-for-byte.
Use this when handing a string to a Nix consumer that expects
the canonical spelling; reach for Display / Self::into_uri
when round-tripping a user-supplied URL byte-for-byte.