Paths and URIs#

nupp.io.Path and nupp.io.URI are immutable value objects, nested under nupp.io alongside the other byte and filesystem facilities. Their public API contains only Nupp values; parsing and normalization are delegated to a feature-gated Rust provider. Selecting either builds the shared provider once with only the required Cargo features.

Paths#

A path is platform-native UTF-8 text. Constructing joins components using the current platform's rules:

nupp.io.newPath is a constructor on nupp.io rather than a static on the Path type itself: Path is a nested type, and its statics would otherwise share a name with it.

join appends components. normalize removes lexical . and .. components without touching the filesystem. absolute resolves against the current working directory; resolve(parts...) makes absolute, appends parts and normalizes. canonicalize asks the filesystem for the real path and therefore can fail. relativeTo(base) computes a relative path when both values share a coordinate system. Fallible operations return nil, reason.

parent returns another Path or nil. fileName, stem, and extension return component strings or nil. withFileName and withExtension replace one component and reject separators in the replacement. isAbsolute and isRelative classify without accessing the filesystem.

Path equality compares its native text. tostring(path) and path:toString() are equivalent.

URIs#

nupp.io.newURI parses and normalizes one absolute URI. It returns nil, reason for malformed input. nupp.io.validate checks without retaining an object; nupp.io.isURI distinguishes URI objects from strings and records.

The accessors are scheme, authority, username, password, userInfo, host, port, path, query, and fragment. Optional components return nil. toString returns the normalized complete URI.

Every with... method returns a new URI and leaves the original unchanged:

A malformed replacement passed to withScheme, withUserInfo, withHost, withPort, withPath, withQuery, withFragment, concatPath, or withEndpoint raises at the call site. Use newURI, validate, and resolve when the text came from an untrusted source and must be handled as a fallible value. Ports must be integers from 0 through 65535. Supplying a component equal to its current normalized value returns the receiver itself.

concatPath joins path text without interpreting it as a reference. resolve applies RFC URL-reference resolution. withEndpoint(endpoint) replaces scheme and authority with another URI while retaining the receiver's path, query and fragment; it is useful when a request URI must be rerouted through a configured service endpoint.

A component record can be passed instead of text:

The input record type is nupp.io.URI.Components, the one type still nested inside URI itself. Components are URI text, not filesystem paths. Use Path for filesystem semantics and URI for network/resource identity.

URI equality compares normalized values, so case normalization in a host or scheme does not make two otherwise identical URIs unequal.