Struct PathUri 

pub struct PathUri(/* private fields */);

An immutable, cross-platform representation of a file: URI.

Only the file: scheme is currently accepted. Construction validates the URL, and the URI cannot be mutated after construction. Self::basename, Self::parent, and Self::join operate on URI path segments without interpreting them using the operating system running Codex. Fallback URIs created by Self::from_abs_path are opaque to these lexical operations.

file: paths retain their URI spelling so they can be parsed independently of the current host. A local POSIX file: URI can also retain percent-encoded non-UTF-8 bytes for lossless native round trips.

Like VS Code resources, path operations use / URI separators on every host. Lexical path operations preserve a URL authority without interpreting Windows drive or UNC roots from path text. Native path normalization, filesystem aliases, symlinks, case sensitivity, and Unicode normalization are not resolved.

Serde represents a PathUri as its canonical URI string. Deserialization accepts only valid file: URI strings. These strings round-trip through their canonical URL form, including encoded non-UTF-8 path bytes.

Implementations

impl PathUri

pub fn parse(uri: &str) -> Result<Self, PathUriParseError>

Parses and validates a file: URI.

pub fn from_abs_path(path: &AbsolutePathBuf) -> Self

Converts an absolute path on the current host to a file: URI.

Paths without a valid URI representation are replaced by file:///%00/bad/path/<base64>, where <base64> is the URL-safe, unpadded encoding of the original path (Unix bytes or Windows UTF-16LE). This includes paths containing nulls and, on Windows, unsupported prefix kinds such as device and generic verbatim namespaces, non-Unicode path or UNC components, and UNC server names that are not valid URL hosts. The encoded null reserves a URI namespace that cannot collide with a real path on Unix or Windows.

pub fn from_host_native_path(path: impl AsRef<Path>) -> Result<Self>

Converts a path on the current host to a file: URI.

Relative paths are reported as invalid input. Absolute paths without a valid URI representation use the fallback documented on Self::from_abs_path.

pub fn encoded_path(&self) -> &str

Returns the percent-encoded URI path.

The URL authority is not included. For example, file://server/share/file.rs has the path /share/file.rs.

pub fn infer_path_convention(&self) -> Option<PathConvention>

Infers the native path convention represented by this URI.

A URI authority is treated as a Windows UNC host, and a leading drive-letter segment such as C: is treated as a Windows drive. All other ordinary file URIs are treated as POSIX paths. This deliberately classifies file:///C:/src as Windows even though /C:/src is also a valid POSIX path. In practice, POSIX paths with a drive-shaped first component are rare enough that recognizing foreign Windows paths is the more useful default.

Opaque fallback URIs are inspected for an absolute POSIX byte prefix or an absolute Windows UTF-16LE prefix. None is returned when their payload does not identify either convention.

TODO(anp): Once PathUri carries an environment identifier, prefer the environment’s declared convention over this spelling-based heuristic.

pub fn inferred_native_path_string(&self) -> String

Renders this URI using the native path syntax inferred from its shape.

This is independent of the current host: a Windows URI renders with Windows separators on every host. If the convention cannot be inferred or the URI cannot be represented using that convention, the canonical URI string is returned instead.

pub fn basename(&self) -> Option<String>

Returns the decoded final URI path segment, or None for the URI root or an opaque fallback URI created by Self::from_abs_path.

If the segment contains non-UTF-8 encoded bytes, its percent-encoded spelling is returned instead.

pub fn to_path_buf(&self) -> PathBuf

Renders this URI as a path-flavored string using its inferred convention.

pub fn parent(&self) -> Option<Self>

Returns the lexical parent without crossing the inferred native path root.

POSIX /, Windows drive roots, Windows UNC share roots, and opaque fallback URIs created by Self::from_abs_path have no parent.

pub fn ancestors(&self) -> impl Iterator<Item = Self>

Returns this URI and each lexical parent up to its inferred native path root.

pub fn starts_with(&self, base: &Self) -> bool

Returns true when this URI is lexically equal to or below base.

Containment is computed using URI authority and path-segment boundaries, without consulting the host filesystem. Percent-encoded native path separators fail closed because native path conversion may interpret them as segment boundaries. Opaque fallback URIs created by Self::from_abs_path only contain themselves.

pub fn join(&self, path: &str) -> Result<Self, PathUriParseError>

Lexically resolves native absolute or relative path text against this URI.

Path text is interpreted using the POSIX or Windows convention inferred from the base URI. An absolute path replaces the base URI’s path, while a relative path is appended lexically. Windows root-relative paths retain the base drive or UNC share, while drive-relative paths are rejected. Empty and . segments are ignored, while .. removes one segment without escaping the POSIX root, Windows drive, or UNC share. Literal %, ?, and # characters are percent-encoded as filename text. Paths containing a null character are rejected because they cannot be safely converted to native paths. Opaque fallback URIs created by Self::from_abs_path reject non-empty joins.

pub fn to_abs_path(&self) -> Result<AbsolutePathBuf>

Converts this file URI to a path using the current host’s path rules.

The URI’s inferred path convention must match the current host. Conversion should succeed when the URI was created from an AbsolutePathBuf on the current host, including fallback URIs created by Self::from_abs_path. Foreign conventions are rejected rather than being projected onto a syntactically valid but unrelated host path.

pub fn to_url(&self) -> Url

Returns a clone of the canonical URL.

Trait Implementations

impl Clone for PathUri

fn clone(&self) -> PathUri

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PathUri

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PathUri

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PathUri

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for PathUri

impl From<AbsolutePathBuf> for PathUri

fn from(p: AbsolutePathBuf) -> Self

Converts to this type from the input type.

impl From<PathUri> for LegacyAppPathString

fn from(path: PathUri) -> Self

Converts to this type from the input type.

impl FromStr for PathUri

type Err = PathUriParseError

The associated error which can be returned from parsing.

fn from_str(uri: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for PathUri

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl JsonSchema for PathUri

fn schema_name() -> String

The name of the generated JSON Schema.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

impl PartialEq for PathUri

fn eq(&self, other: &PathUri) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for PathUri

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for PathUri

impl TS for PathUri

type WithoutGenerics = PathUri

If this type does not have generic parameters, then WithoutGenerics should just be Self. If the type does have generic parameters, then all generic parameters must be replaced with a dummy type, e.g ts_rs::Dummy or (). The only requirement for these dummy types is that EXPORT_TO must be None.

type OptionInnerType = PathUri

If the implementing type is std::option::Option<T>, then this associated type is set to T. All other implementations of TS should set this type to Self instead.

fn ident() -> String

Identifier of this type, excluding generic parameters.

fn docs() -> Option<String>

JSDoc comment to describe this type in TypeScript - when TS is derived, docs are automatically read from your doc comments or #[doc = ".."] attributes

fn name() -> String

Name of this type in TypeScript, including generic parameters

fn decl_concrete() -> String

Declaration of this type using the supplied generic arguments. The resulting TypeScript definition will not be generic. For that, see TS::decl(). If this type is not generic, then this function is equivalent to TS::decl().

fn decl() -> String

Declaration of this type, e.g. type User = { user_id: number, ... }. This function will panic if the type has no declaration.

fn inline() -> String

Formats this types definition in TypeScript, e.g { user_id: number }. This function will panic if the type cannot be inlined.

fn inline_flattened() -> String

Flatten a type declaration.
This function will panic if the type cannot be flattened.

fn visit_generics(v: &mut impl TypeVisitor)

where Self: 'static,

Iterates over all type parameters of this type.

fn output_path() -> Option<PathBuf>

Returns the output path to where T should be exported.
The returned path does not include the base directory from TS_RS_EXPORT_DIR.

fn visit_dependencies(v: &mut impl TypeVisitor)

where Self: 'static,

Iterates over all dependency of this type.

fn dependencies() -> Vec<Dependency>

where Self: 'static,

Resolves all dependencies of this type recursively.

fn export() -> Result<(), ExportError>

where Self: 'static,

Manually export this type to the filesystem. To export this type together with all of its dependencies, use TS::export_all.

fn export_all() -> Result<(), ExportError>

where Self: 'static,

Manually export this type to the filesystem, together with all of its dependencies.
To export only this type, without its dependencies, use TS::export.

fn export_all_to(out_dir: impl AsRef<Path>) -> Result<(), ExportError>

where Self: 'static,

Manually export this type into the given directory, together with all of its dependencies.
To export only this type, without its dependencies, use TS::export.

fn export_to_string() -> Result<String, ExportError>

where Self: 'static,

Manually generate bindings for this type, returning a String.
This function does not format the output, even if the format feature is enabled.

fn default_output_path() -> Option<PathBuf>

Returns the output path to where T should be exported.

impl TryFrom<LegacyAppPathString> for PathUri

type Error = LegacyAppPathStringError

The type returned in the event of a conversion error.

fn try_from(path: LegacyAppPathString) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for PathUri

type Error = PathUriParseError

The type returned in the event of a conversion error.

fn try_from(uri: String) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Url> for PathUri

type Error = PathUriParseError

The type returned in the event of a conversion error.

fn try_from(url: Url) -> Result<Self, Self::Error>

Performs the conversion.