rurl (version 3.0.1)

serialize_url: Serialize URLs to a standard's own full-string form

Description

Renders each URL as the selected standard would serialize it: the full string, credentials and fragment included, with a present-but-empty ? or # delimiter preserved. This is rurl's standard serialization surface, and it is deliberately not get_clean_url().

Usage

serialize_url(
  url,
  standard = c("whatwg", "rfc3986"),
  form = c("source", "normalized"),
  engine = NULL
)

Value

A character vector the same length as url. NA_character_ for input the selected standard's parser does not accept.

Arguments

url

A character vector of URLs.

standard

The standard to serialize to: "whatwg" (default) or "rfc3986". Unlike the parse surface, NULL is not accepted: the parse surface's url_standard = NULL is a frozen legacy profile that names no standard (ADR 0007), so there is nothing to serialize as. Passing NULL is an error rather than a silent "whatwg".

form

For standard = "rfc3986" only, the RFC posture: "source" (default, source-preserving) or "normalized". Ignored for "whatwg", whose serializer has a single spec-defined form.

engine

Optional psl_engine object from pslr::psl_engine() for per-request Public Suffix List resolution. NULL (default) uses the session-global engine.

Which surface you want

serialize_url() answers "what does this URL look like under the URL Standard / RFC 3986?". get_clean_url() answers "what is the canonical, tidied form of this URL for SEO or deduplication?". They are different products, not two settings of one:

• serialize_url() preserves userinfo, the fragment, and empty delimiters; takes no presentation options; and is the substrate rurl's conformance claims are measured on.

• get_clean_url() drops userinfo and the fragment by design, and is driven by cleaning policy (www_handling, trailing_slash_handling, index_page_handling, query filtering, port handling, and so on).

Because a standard serialization is an identity, serialize_url() accepts no presentation arguments at all. There is no port_handling, trailing_slash_handling or path_encoding to pass; asking a serializer to strip a trailing slash would be a category error.

Parse posture

Each standard is parsed under its own spec posture -- the "whatwg" and "rfc-syntax" profiles (see url_profile()). Both accept any scheme, and both require a scheme: neither standard defines a base-URL-free parse of example.com/x, so scheme-less input returns NA rather than being silently upgraded to https://. Input that the standard's parser rejects also returns NA.

Standards and forms

standard = "whatwg"

The WHATWG URL Standard's URL serializer (#concept-url-serializer). Spec-exact, which makes credentials lossy in one direction: WHATWG appends credentials only when the username or password is non-empty, so http://@h/ serializes as http://h/ and http://u:@h/ as http://u@h/. Both are pinned by the Web Platform Tests. form is ignored.

standard = "rfc3986", form = "source"

RFC 3986 section 5.3 component recomposition with no normalization: source bytes are preserved and the undivided userinfo slice is emitted verbatim (RFC 3986 has no username/password split), so every credential spelling u@, u:@, :p@, @ -- survives.

standard = "rfc3986", form = "normalized"

Adds RFC 3986 section 6.2.2 syntax-based normalization (scheme and host case, percent-encoding triplet case and unreserved-octet decoding, dot-segment removal) and the section 6.2.3 default-port elision.

Both RFC forms are exposed because choosing one would forfeit either the round-trip oracle (source) or the normalized comparison substrate (normalized).

See Also

get_clean_url() for the cleaning surface, safe_parse_url() for the parsed components, and url_profile() for the parse postures used here.

Examples

# The fragment and credentials survive; clean_url drops both by design.
serialize_url("http://user:[email protected]:80/a/../b?q=1#frag")
get_clean_url("http://user:[email protected]:80/a/../b?q=1#frag")

# A present-but-empty delimiter carries information and is preserved.
serialize_url(c("http://example.com/", "http://example.com/#",
                "http://example.com/?"))

# RFC 3986: source-preserving versus normalized.
serialize_url("HTTP://Example.COM:80/a/%7Euser/../x", standard = "rfc3986")
serialize_url("HTTP://Example.COM:80/a/%7Euser/../x", standard = "rfc3986",
              form = "normalized")

# Any scheme is accepted; no scheme is not.
serialize_url(c("urn:ietf:rfc:2648", "mailto:[email protected]", "foo://h/x"))
serialize_url("example.com/x")