Package {rurl}

A data frame containing URLs for the left side of the join.

A data frame containing URLs for the right side of the join.

Character string, the name of the column in data_A that contains URLs. Defaults to "URL".

Character string, the name of the column in data_B that contains URLs. Defaults to "URL".

Character string, suffix to append to data_A columns (excluding the URL column) in the output. Defaults to "_A".

Character string, suffix to append to data_B columns (excluding the URL column) in the output. Defaults to "_B".

Character string, the name of the output column holding the original data_A URLs. Defaults to NULL, in which case the name is derived from the data_A argument expression via deparse(substitute()). Supply an explicit value for stable output names when piping or passing anonymous inputs (e.g. canonical_join(df[df$x > 1, ], get_b())).

Character string, the name of the output column holding the original data_B URLs. Defaults to NULL; behaves like name_A for data_B.

Join type: "inner", "left", "right", or "full". Defaults to "inner".

How to handle duplicate canonical keys within inputs. "first" keeps the first row per key, "all" keeps all rows (many-to-many), and "error" stops on duplicates. Defaults to "first".

How to handle URLs that fail canonicalization. "keep" retains them as unmatched rows (for left/right/full joins), "drop" removes them before joining, and "error" stops. Defaults to "keep".

Which parse statuses yield joinable canonical keys. "ok" (default) joins only rows whose parse_status begins with "ok" ("ok", "ok-ftp", "ok-scheme-relative"). "ok_or_warning" additionally treats parseable-but-suspicious warning-* statuses ("warning-no-tld", "warning-invalid-tld", "warning-public-suffix") as joinable. Joining on warning statuses can increase false-positive matches between distinct hosts that both fail TLD derivation.

Additional arguments forwarded to safe_parse_urls, controlling canonicalization (e.g., protocol_handling, www_handling, trailing_slash_handling, index_page_handling, path_normalization, scheme_relative_handling, host_encoding, path_encoding, the url_standard selector, and the profile bundle). When url_standard is set, forwarding a governed low-level knob it would override (e.g. path_normalization) is an error, exactly as in safe_parse_url; the orthogonal path_encoding and host_encoding presentation knobs layer freely on any profile. A profile (e.g. "seo", "whatwg") may also be forwarded: like safe_parse_url, it bundles several knobs, expands only into knobs you did not supply, and an explicit knob always overrides it (so the url_standard conflict check is skipped on the profile path). Inspect a bundle with url_profile. See "Legacy presentation dials" below for the arguments that warn.

A character vector of URLs.

A character vector of one or more rules to score, drawn from "url", "dns", "web", "registrable", "seo" (all five by default). See is_valid_host for each rule's meaning.

Standard profile governing host interpretation: "whatwg" (default) or "rfc3986".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs.

Optional character vector of schemes the caller will act on, compared case-insensitively. When supplied, the result gains a logical allowed column (FALSE for a URL with no parsed scheme) and the token "not-in-allowlist" where it is FALSE. When NULL (default) no allowed column is emitted and no allowlist judgement is made.

Standard profile governing scheme interpretation: "whatwg" (default) or "rfc3986". Unlike most of the package this argument has a non-NULL default, because a scheme classification is undefined without a named standard.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs.

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

A character vector containing URLs to be parsed.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

Which PSL source to use: "all", "private", or "icann". Subdomain trimming depends on which section is consulted, so pass source = "icann" to exclude private suffixes (e.g. github.io).

A character string specifying how to handle the case of the cleaned URL. Defaults to "lower_host", the RFC 3986 §6.2.2.1 normalization (scheme and host are case-insensitive and folded to lowercase; the path is case-sensitive and preserved).

• "lower_host": (Default) Lowercases scheme and host only; the path keeps its original casing.

• "keep": Preserves casing of the reconstructed URL.

• "lower": Converts the cleaned URL to lowercase.

• "upper": Converts the cleaned URL to uppercase.

A character string specifying how to handle trailing slashes in the path component of the cleaned URL. Defaults to "none".

• "none": (Default) No specific handling is applied. Path remains as is after initial parsing.

• "keep": Ensures a trailing slash. If a path exists and doesn't end with one, it's added. If path is just "/", it's kept.

• "strip": Removes a trailing slash if present, unless the path is solely "/".

A character string specifying how to handle index/default pages. Defaults to "keep".

• "keep": (Default) Leave index/default page segments untouched.

• "strip": Remove a trailing index.* or default.* segment (case-insensitive).

How to normalize path structure. Defaults to "none". rurl owns dot-segment resolution: the path is read from the input verbatim (never from a pre-normalized path), so "none" preserves . / .. segments (/a/../b stays /a/../b) and only the settings below change them. Resolution follows RFC 3986 section 5.2.4 and acts on literal ./.. segments only — a percent-encoded %2e is a normal path byte, never a dot segment, so it is never treated as traversal.

• "none": (Default) No normalization; dot and slash structure is preserved exactly as written.

• "collapse_slashes": Collapse duplicate slashes in the path.

• "dot_segments": Resolve . and .. segments per RFC 3986.

• "both": Apply both collapse_slashes and dot_segments.

How to handle URLs starting with "//". Defaults to "keep".

• "keep": Parse using http but return scheme as NA and set status to "ok-scheme-relative".

• "http": Assume http for parsing and output.

• "https": Assume https for parsing and output.

• "error": Treat scheme-relative URLs as invalid.

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

How to present the path percent-encoding in clean_url — the readable-vs-browser rendering choice (the path analog of host_encoding). Defaults to "keep". This is an orthogonal presentation knob: it is independent of url_standard and layers on top of any profile (e.g. ⁠url_standard = "whatwg", path_encoding = "encode"⁠ emits the WHATWG-parsed path in browser form), exactly like host_encoding. Only "keep" preserves a profile's canonical identity path verbatim; "encode" and "decode" are presentation forms that may re-encode or decode reserved octets (so ⁠%2F⁠ may fold to a path-separating /), independent of whether a profile is set.

• "keep": Leave the path percent-encoding untouched (the path is preserved as written in the URL, so ⁠%2F⁠ stays ⁠%2F⁠ rather than decoding into a path-separating /). With no url_standard, rurl keeps its historical RFC-style percent-hex case canonicalization, so ⁠%2f⁠ becomes ⁠%2F⁠. Under url_standard = "rfc3986", the profile's RFC 3986 §6.2.2.2 normalization applies: a triplet encoding an unreserved byte is decoded, every other triplet stays encoded with uppercased hex, so ⁠%7E⁠ becomes ~ while ⁠%2F⁠ stays ⁠%2F⁠. Under url_standard = "whatwg", existing percent-triplet spelling is preserved byte-for-byte. Use "encode" to additionally normalize which bytes are encoded.

• "encode": The browser/percent-encoded rendering. Decodes the path first, then percent-encodes each segment (slashes preserved), so a readable non-ASCII path is emitted in its percent-encoded UTF-8 form.

• "decode": The readable rendering. Percent-decodes UTF-8 sequences in the path, so a percent-encoded segment is shown as readable text.

A character string controlling whether (and how) the query string is included in clean_url. Defaults to "drop", which preserves the historical query-free clean_url. The raw query result field is never affected by this option — it always reports the faithful original query.

• "drop": (Default) clean_url carries no query, exactly as before.

• "filter": Keep contentful params, dropping known trackers via a built-in denylist (e.g. ⁠utm_*⁠, fbclid, gclid). params_drop extends the denylist; params_keep rescues names (winning over both the denylist and empty-dropping).

• "allow": Keep only params whose names match params_keep; all others are dropped. Here params_keep is an inclusion criterion only, not an empty-rescue.

• "keep": Keep every param, re-encoded into canonical form (not the verbatim original — that stays on the query field).

In every non-"drop" mode the surviving query is re-encoded canonically (uppercase percent-hex, spaces as ⁠%20⁠) and appended after the path. The query is intentionally EXEMPT from case_handling (query values are case-sensitive — tokens, IDs, signatures), so under case_handling = "lower" or "upper" the clean_url is no longer uniformly cased: scheme/host/path fold but the query keeps its original case. Because clean_url is the canonical_join key, any non-"drop" mode also brings the query into that join key (so ?id=1 and ?id=2 stop collapsing, while utm-only differences still collapse under "filter").

Character vector of parameter-name globs (only * is special), or NULL (default). In "filter" mode this is the rescue list; in "allow" mode it is the allowlist. Ignored in "drop"/"keep".

Character vector of parameter-name globs to add to the built-in denylist in "filter" mode, or NULL (default). Ignored in "drop"/"allow"/"keep".

Logical (default FALSE). Controls whether the denylist and params_keep/params_drop matching is case-sensitive.

Logical (default FALSE). When TRUE, surviving params are stably sorted by decoded key. Active in "filter"/"allow"/"keep".

One of "keep" (default) or "drop". "drop" removes empty-valued params (e.g. ⁠?ref=⁠), except those rescued by params_keep in "filter" mode.

Logical (default FALSE). When TRUE, + in query values is treated as a space (HTML-form decoding) before percent-decoding. FALSE keeps + literal (RFC 3986 generic behavior).

A character string controlling whether the port appears in clean_url. Defaults to "exclude", today's only historical behavior. This knob is standalone and standard-independent (editorial, like www_handling) – url_standard never governs whether it may be set.

• "exclude": (Default) The port never appears in clean_url.

• "strip_all": Explicit alias of "exclude".

• "keep": Include the syntactic port when present, including a default port under url_standard = "whatwg". This is an explicit non-parity override for callers that need the input's port spelling.

• "strip_default": Keep only non-default ports (using the same scheme-default table), independent of url_standard. Default-ness is judged on the scheme the input was parsed with, never on the scheme protocol_handling renders: ⁠http://example.com:443/a⁠ under protocol_handling = "https" keeps ⁠:443⁠, and ⁠http://example.com:80/a⁠ drops ⁠:80⁠ (RFC 3986 §6.2.3; WHATWG URL Standard port state; RUL-016). This is the value profile = "seo" pins.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

Optional named profile bundling several knobs at once: NULL (default; behaves exactly as the individual arguments select, fully backward compatible), "browser", "whatwg", "rfc-syntax", "seo", or the "seo" alias "canonical". A profile is separate from url_standard (it bundles acceptance, interpretation, leniency, and canonicalization together) and expands only into arguments you did not supply explicitly — an explicit argument always overrides the profile. "browser" is a browser-like fix-up posture (http-prepending; not Chrome-faithful); "whatwg" is the absolute-URL no-base posture that rejects scheme-less input (unlike a bare url_standard = "whatwg"); "rfc-syntax" is RFC 3986 generic syntax as parsing, not normalization (case and dot-segments are preserved); "seo"/"canonical" is rurl's origin-cleaning intent — a lossy policy projection of a WHATWG-parsed URL (ADR 0017), which claims no resource equivalence: url_standard = "whatwg" underneath (which also resolves ./.. folder segments), https, a Unicode host regardless of the input spelling, strip www / trailing slash / index page, drop the whole query, and drop a default port only (port_handling = "strip_default": a non-default port names a different origin and survives). Inspect the resolved bundle with url_profile. Also accepted by canonical_join (forwarded through its ...).

How clean_url treats a URL whose parsed authority carried a userinfo delimiter (⁠user@⁠, ⁠user:password@⁠, a bare @, or a repeated @). Defaults to "strip". A policy dial on the clean surface (ADR 0017, mutation-table row 12; RUL-001), not a standards axis: it composes with every url_standard, including NULL, and never touches the user / password columns, parse_status, the diagnostics, serialize_url or get_url_key.

• "strip": (Default) The userinfo is dropped and the rest of the URL is emitted, exactly as before this argument existed.

• "reject": clean_url is NA for such a row. RFC 3986 section 3.2.1 deprecates the user:password form and lets an application reject it; sections 7.5 and 7.6 describe the credential leak and the ⁠https://example.com@evil.example/⁠ semantic attack a silently collapsed clean URL would hide. Use this when a cleaned URL that looks like the credential-free original would be misleading.

There is no "keep": serialize_url already preserves credentials under both standards, and format_url redacts them for display.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

Which PSL source to use: "all", "private", or "icann".

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

Which PSL source to use: "all", "private", or "icann". Subdomain trimming depends on which section is consulted, so pass source = "icann" to exclude private suffixes (e.g. github.io).

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

How to handle casing of the returned host. Defaults to "lower".

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

A character vector of URLs.

Standard profile governing host interpretation: either "rfc3986" or "whatwg". Required, with no default (ADR 0015). The requirement is semantic, not stylistic: whether a host is an IPv4 literal or a registered name is a question only a standard answers, so there is no profile-neutral classification a default could stand for. get_parse_verdicts is deliberately not gated this way — its layers describe the parse that actually ran, which is defined with or without a selector.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs. Non-mailto: URLs (and, under scheme_acceptance = "web", all mailto: URLs, which the web allowlist does not accept) contribute no rows.

Standard profile passed to the general parser. A mailto: path is opaque, so this does not affect the classification; it defaults to "rfc3986" because the general parser requires a selector.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Logical; when TRUE, compute the opt-in SMTP wire-projection columns (see the corresponding section). Defaults to FALSE.

A character vector of URLs to be parsed.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

Which PSL source to use: "all", "private", or "icann". Warning statuses such as warning-no-tld, warning-invalid-tld, and warning-public-suffix depend on which PSL section is consulted, so pass source = "icann" to use only ICANN-managed TLDs.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

Standard profile governing interpretation: NULL (default), "rfc3986", or "whatwg". Unlike the other companion helpers this argument does not gate the result.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

How to handle URLs starting with "//". Defaults to "keep".

• "keep": Parse using http but return scheme as NA and set status to "ok-scheme-relative".

• "http": Assume http for parsing and output.

• "https": Assume https for parsing and output.

• "error": Treat scheme-relative URLs as invalid.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Which TLD source to use for TLD extraction: "all", "icann", or "private". Defaults to "all".

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

How to handle casing of the returned path. Defaults to "lower_host", which preserves the path's original casing (paths are case-sensitive per RFC 3986 §6.2.2.1). Use "lower"/"upper" to force a case.

A character string specifying how to handle trailing slashes in the path component of the cleaned URL. Defaults to "none".

• "none": (Default) No specific handling is applied. Path remains as is after initial parsing.

• "keep": Ensures a trailing slash. If a path exists and doesn't end with one, it's added. If path is just "/", it's kept.

• "strip": Removes a trailing slash if present, unless the path is solely "/".

A character string specifying how to handle index/default pages. Defaults to "keep".

• "keep": (Default) Leave index/default page segments untouched.

• "strip": Remove a trailing index.* or default.* segment (case-insensitive).

How to normalize path structure. Defaults to "none". rurl owns dot-segment resolution: the path is read from the input verbatim (never from a pre-normalized path), so "none" preserves . / .. segments (/a/../b stays /a/../b) and only the settings below change them. Resolution follows RFC 3986 section 5.2.4 and acts on literal ./.. segments only — a percent-encoded %2e is a normal path byte, never a dot segment, so it is never treated as traversal.

• "none": (Default) No normalization; dot and slash structure is preserved exactly as written.

• "collapse_slashes": Collapse duplicate slashes in the path.

• "dot_segments": Resolve . and .. segments per RFC 3986.

• "both": Apply both collapse_slashes and dot_segments.

How to present the path percent-encoding in clean_url — the readable-vs-browser rendering choice (the path analog of host_encoding). Defaults to "keep". This is an orthogonal presentation knob: it is independent of url_standard and layers on top of any profile (e.g. ⁠url_standard = "whatwg", path_encoding = "encode"⁠ emits the WHATWG-parsed path in browser form), exactly like host_encoding. Only "keep" preserves a profile's canonical identity path verbatim; "encode" and "decode" are presentation forms that may re-encode or decode reserved octets (so ⁠%2F⁠ may fold to a path-separating /), independent of whether a profile is set.

• "keep": Leave the path percent-encoding untouched (the path is preserved as written in the URL, so ⁠%2F⁠ stays ⁠%2F⁠ rather than decoding into a path-separating /). With no url_standard, rurl keeps its historical RFC-style percent-hex case canonicalization, so ⁠%2f⁠ becomes ⁠%2F⁠. Under url_standard = "rfc3986", the profile's RFC 3986 §6.2.2.2 normalization applies: a triplet encoding an unreserved byte is decoded, every other triplet stays encoded with uppercased hex, so ⁠%7E⁠ becomes ~ while ⁠%2F⁠ stays ⁠%2F⁠. Under url_standard = "whatwg", existing percent-triplet spelling is preserved byte-for-byte. Use "encode" to additionally normalize which bytes are encoded.

• "encode": The browser/percent-encoded rendering. Decodes the path first, then percent-encodes each segment (slashes preserved), so a readable non-ASCII path is emitted in its percent-encoded UTF-8 form.

• "decode": The readable rendering. Percent-decodes UTF-8 sequences in the path, so a percent-encoded segment is shown as readable text.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Return format: "string" (default) or "list" for parsed elements.

Logical; if TRUE (default), percent-decodes the query (the whole string for format="string", keys/values for format="list"). Set FALSE to obtain the query as written: the raw query for the default query_handling = "keep", or the canonical re-encoded form (uppercase hex, ⁠%20⁠, ⁠%26⁠/⁠%3D⁠) once any filtering is requested.

A character string controlling whether (and how) the query string is included in clean_url. Defaults to "drop", which preserves the historical query-free clean_url. The raw query result field is never affected by this option — it always reports the faithful original query.

• "drop": (Default) clean_url carries no query, exactly as before.

• "filter": Keep contentful params, dropping known trackers via a built-in denylist (e.g. ⁠utm_*⁠, fbclid, gclid). params_drop extends the denylist; params_keep rescues names (winning over both the denylist and empty-dropping).

• "allow": Keep only params whose names match params_keep; all others are dropped. Here params_keep is an inclusion criterion only, not an empty-rescue.

• "keep": Keep every param, re-encoded into canonical form (not the verbatim original — that stays on the query field).

In every non-"drop" mode the surviving query is re-encoded canonically (uppercase percent-hex, spaces as ⁠%20⁠) and appended after the path. The query is intentionally EXEMPT from case_handling (query values are case-sensitive — tokens, IDs, signatures), so under case_handling = "lower" or "upper" the clean_url is no longer uniformly cased: scheme/host/path fold but the query keeps its original case. Because clean_url is the canonical_join key, any non-"drop" mode also brings the query into that join key (so ?id=1 and ?id=2 stop collapsing, while utm-only differences still collapse under "filter").

Character vector of parameter-name globs (only * is special), or NULL (default). In "filter" mode this is the rescue list; in "allow" mode it is the allowlist. Ignored in "drop"/"keep".

Character vector of parameter-name globs to add to the built-in denylist in "filter" mode, or NULL (default). Ignored in "drop"/"allow"/"keep".

Logical (default FALSE). Controls whether the denylist and params_keep/params_drop matching is case-sensitive.

Logical (default FALSE). When TRUE, surviving params are stably sorted by decoded key. Active in "filter"/"allow"/"keep".

One of "keep" (default) or "drop". "drop" removes empty-valued params (e.g. ⁠?ref=⁠), except those rescued by params_keep in "filter" mode.

Logical (default FALSE). When TRUE, + in query values is treated as a space (HTML-form decoding) before percent-decoding. FALSE keeps + literal (RFC 3986 generic behavior).

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

How to handle URLs starting with "//". Defaults to "keep".

• "keep": Parse using http but return scheme as NA and set status to "ok-scheme-relative".

• "http": Assume http for parsing and output.

• "https": Assume https for parsing and output.

• "error": Treat scheme-relative URLs as invalid.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

Standard profile under which each URL is parsed before its scheme is classified: either "rfc3986" or "whatwg". Required, with no default (ADR 0015). The three tokens below do not differ between the profiles, but the parse that resolves the scheme does, so the profile has to be named. get_parse_verdicts is deliberately not gated this way — its layers describe the parse that actually ran, which is defined with or without a selector.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

Which PSL source to use: "all", "private", or "icann".

Logical; if FALSE (default), removes a leading www/⁠www[0-9]*⁠ label only when it is the sole subdomain label.

Return format: "string" (default) or "labels" for a character vector of labels.

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

A character vector of URLs.

Which TLD source to use: "all", "icann", or "private".

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

A character vector of URLs.

Standard profile governing interpretation: either "rfc3986" or "whatwg". Required, with no default (ADR 0015): the vocabulary is profile-dependent — several tokens fire under one standard only — so there is no profile-neutral set of findings a default could stand for.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs. Factors are coerced.

A rurl_url_key_policy object from url_key_policy(), which is also the default. The policy is scalar and is never recycled.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

A character vector of URLs.

A single rule to test. One of:

"web"

(default) usable as an HTTP-authority host: an IP literal, or a strict letter-digit-hyphen (LDH) name host (labels 1–63 octets, no leading/trailing hyphen, no underscore, name \le 253).

"dns"

a legal DNS owner-name shape — the "web" rule but the underscore is permitted anywhere (as _dmarc, _dkim, SRV owner names require).

"registrable"

the host has a Public Suffix List registrable domain (equivalently get_host_type is "domain"); IP literals and single-label / unknown-suffix hosts are FALSE.

"seo"

SEO-safe: "web" and "registrable" and carrying no host-shape footgun diagnostic (e.g. an IPv4 written in a numeric or non-decimal shorthand).

"url"

the loosest rule: the selected standard admitted a host at all.

Standard profile governing host interpretation: "whatwg" (default; the living web standard) or "rfc3986". The verdict can depend on the standard — 2130706433 is an "ipv4" host (web = TRUE) under "whatwg" but a reg-name under "rfc3986".

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

A character vector of URLs.

One of "param" (default) for one row per distinct parameter name, or "value" for one row per distinct (parameter, value) pair.

Character vector of parameter-name globs (only * is special), or NULL (default). In "filter" mode this is the rescue list; in "allow" mode it is the allowlist. Ignored in "drop"/"keep".

Character vector of parameter-name globs to add to the built-in denylist in "filter" mode, or NULL (default). Ignored in "drop"/"allow"/"keep".

Logical (default FALSE). Controls whether the denylist and params_keep/params_drop matching is case-sensitive.

One of "keep" (default) or "drop". "drop" removes empty-valued params (e.g. ⁠?ref=⁠), except those rescued by params_keep in "filter" mode.

Logical (default FALSE). When TRUE, + in query values is treated as a space (HTML-form decoding) before percent-decoding. FALSE keeps + literal (RFC 3986 generic behavior).

A character vector of URL references to resolve. Each may be relative ("../b", "?q=1", "#frag", "//host/p") or already absolute ("https://host/p"); an absolute reference ignores base_url.

A character vector of base URLs, recycled against relative_or_absolute. Each base must itself be an absolute URL (carry a scheme); a relative reference resolved against a scheme-less or NA base yields NA.

Optional standard profile forwarded to the parse: NULL (default), "rfc3986", or "whatwg". See safe_parse_url for the axes it governs, and Reference resolution is standard-aware for the reference-parsing rules "whatwg" adds ahead of the merge. Required (non-NULL) when output = "serialized".

Which output surface to return: "clean" (default, today's canonical clean_url bytes) or "serialized" (the selected standard's full-string serialization of the resolved absolute URL, via serialize_url). See Which output surface you want.

For output = "serialized" with url_standard = "rfc3986" only, the RFC posture forwarded to serialize_url: "source" (default, source-preserving) or "normalized". Ignored for "whatwg", whose serializer has a single spec-defined form, and ignored under output = "clean", whose rendering is driven by the cleaning dials instead – the same argument-is-inert-where-it-does-not-apply contract serialize_url itself holds for form.

Additional arguments forwarded to safe_parse_urls (e.g. port_handling, query_handling, host_encoding). Passing a governed low-level knob that conflicts with url_standard errors, exactly as it does for safe_parse_url. These are presentation dials consumed by the "clean" path only; supplying any of them together with output = "serialized" is an error, because serialize_url takes no presentation arguments and the dial could not be honored.

Logical; enable/disable the full URL parse cache.

Logical; enable/disable the IDNA/Punycode encode cache.

Logical; enable/disable the Punycode decode cache.

A single number (\ge 1) or Inf bounding the full_parse cache.

A single URL string to be parsed. For vectors, use safe_parse_urls.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

Which TLD source to use for TLD extraction: "all", "icann", or "private". Defaults to "all".

A character string specifying how to handle the case of the cleaned URL. Defaults to "lower_host", the RFC 3986 §6.2.2.1 normalization (scheme and host are case-insensitive and folded to lowercase; the path is case-sensitive and preserved).

• "lower_host": (Default) Lowercases scheme and host only; the path keeps its original casing.

• "keep": Preserves casing of the reconstructed URL.

• "lower": Converts the cleaned URL to lowercase.

• "upper": Converts the cleaned URL to uppercase.

A character string specifying how to handle trailing slashes in the path component of the cleaned URL. Defaults to "none".

• "none": (Default) No specific handling is applied. Path remains as is after initial parsing.

• "keep": Ensures a trailing slash. If a path exists and doesn't end with one, it's added. If path is just "/", it's kept.

• "strip": Removes a trailing slash if present, unless the path is solely "/".

A character string specifying how to handle index/default pages. Defaults to "keep".

• "keep": (Default) Leave index/default page segments untouched.

• "strip": Remove a trailing index.* or default.* segment (case-insensitive).

How to normalize path structure. Defaults to "none". rurl owns dot-segment resolution: the path is read from the input verbatim (never from a pre-normalized path), so "none" preserves . / .. segments (/a/../b stays /a/../b) and only the settings below change them. Resolution follows RFC 3986 section 5.2.4 and acts on literal ./.. segments only — a percent-encoded %2e is a normal path byte, never a dot segment, so it is never treated as traversal.

• "none": (Default) No normalization; dot and slash structure is preserved exactly as written.

• "collapse_slashes": Collapse duplicate slashes in the path.

• "dot_segments": Resolve . and .. segments per RFC 3986.

• "both": Apply both collapse_slashes and dot_segments.

How to handle URLs starting with "//". Defaults to "keep".

• "keep": Parse using http but return scheme as NA and set status to "ok-scheme-relative".

• "http": Assume http for parsing and output.

• "https": Assume https for parsing and output.

• "error": Treat scheme-relative URLs as invalid.

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

How to present the path percent-encoding in clean_url — the readable-vs-browser rendering choice (the path analog of host_encoding). Defaults to "keep". This is an orthogonal presentation knob: it is independent of url_standard and layers on top of any profile (e.g. ⁠url_standard = "whatwg", path_encoding = "encode"⁠ emits the WHATWG-parsed path in browser form), exactly like host_encoding. Only "keep" preserves a profile's canonical identity path verbatim; "encode" and "decode" are presentation forms that may re-encode or decode reserved octets (so ⁠%2F⁠ may fold to a path-separating /), independent of whether a profile is set.

• "keep": Leave the path percent-encoding untouched (the path is preserved as written in the URL, so ⁠%2F⁠ stays ⁠%2F⁠ rather than decoding into a path-separating /). With no url_standard, rurl keeps its historical RFC-style percent-hex case canonicalization, so ⁠%2f⁠ becomes ⁠%2F⁠. Under url_standard = "rfc3986", the profile's RFC 3986 §6.2.2.2 normalization applies: a triplet encoding an unreserved byte is decoded, every other triplet stays encoded with uppercased hex, so ⁠%7E⁠ becomes ~ while ⁠%2F⁠ stays ⁠%2F⁠. Under url_standard = "whatwg", existing percent-triplet spelling is preserved byte-for-byte. Use "encode" to additionally normalize which bytes are encoded.

• "encode": The browser/percent-encoded rendering. Decodes the path first, then percent-encodes each segment (slashes preserved), so a readable non-ASCII path is emitted in its percent-encoded UTF-8 form.

• "decode": The readable rendering. Percent-decodes UTF-8 sequences in the path, so a percent-encoded segment is shown as readable text.

A character string controlling whether (and how) the query string is included in clean_url. Defaults to "drop", which preserves the historical query-free clean_url. The raw query result field is never affected by this option — it always reports the faithful original query.

• "drop": (Default) clean_url carries no query, exactly as before.

• "filter": Keep contentful params, dropping known trackers via a built-in denylist (e.g. ⁠utm_*⁠, fbclid, gclid). params_drop extends the denylist; params_keep rescues names (winning over both the denylist and empty-dropping).

• "allow": Keep only params whose names match params_keep; all others are dropped. Here params_keep is an inclusion criterion only, not an empty-rescue.

• "keep": Keep every param, re-encoded into canonical form (not the verbatim original — that stays on the query field).

In every non-"drop" mode the surviving query is re-encoded canonically (uppercase percent-hex, spaces as ⁠%20⁠) and appended after the path. The query is intentionally EXEMPT from case_handling (query values are case-sensitive — tokens, IDs, signatures), so under case_handling = "lower" or "upper" the clean_url is no longer uniformly cased: scheme/host/path fold but the query keeps its original case. Because clean_url is the canonical_join key, any non-"drop" mode also brings the query into that join key (so ?id=1 and ?id=2 stop collapsing, while utm-only differences still collapse under "filter").

Character vector of parameter-name globs (only * is special), or NULL (default). In "filter" mode this is the rescue list; in "allow" mode it is the allowlist. Ignored in "drop"/"keep".

Character vector of parameter-name globs to add to the built-in denylist in "filter" mode, or NULL (default). Ignored in "drop"/"allow"/"keep".

Logical (default FALSE). When TRUE, surviving params are stably sorted by decoded key. Active in "filter"/"allow"/"keep".

One of "keep" (default) or "drop". "drop" removes empty-valued params (e.g. ⁠?ref=⁠), except those rescued by params_keep in "filter" mode.

Logical (default FALSE). Controls whether the denylist and params_keep/params_drop matching is case-sensitive.

Logical (default FALSE). When TRUE, + in query values is treated as a space (HTML-form decoding) before percent-decoding. FALSE keeps + literal (RFC 3986 generic behavior).

A character string controlling whether the port appears in clean_url. Defaults to "exclude", today's only historical behavior. This knob is standalone and standard-independent (editorial, like www_handling) – url_standard never governs whether it may be set.

• "exclude": (Default) The port never appears in clean_url.

• "strip_all": Explicit alias of "exclude".

• "keep": Include the syntactic port when present, including a default port under url_standard = "whatwg". This is an explicit non-parity override for callers that need the input's port spelling.

• "strip_default": Keep only non-default ports (using the same scheme-default table), independent of url_standard. Default-ness is judged on the scheme the input was parsed with, never on the scheme protocol_handling renders: ⁠http://example.com:443/a⁠ under protocol_handling = "https" keeps ⁠:443⁠, and ⁠http://example.com:80/a⁠ drops ⁠:80⁠ (RFC 3986 §6.2.3; WHATWG URL Standard port state; RUL-016). This is the value profile = "seo" pins.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

Optional named profile bundling several knobs at once: NULL (default; behaves exactly as the individual arguments select, fully backward compatible), "browser", "whatwg", "rfc-syntax", "seo", or the "seo" alias "canonical". A profile is separate from url_standard (it bundles acceptance, interpretation, leniency, and canonicalization together) and expands only into arguments you did not supply explicitly — an explicit argument always overrides the profile. "browser" is a browser-like fix-up posture (http-prepending; not Chrome-faithful); "whatwg" is the absolute-URL no-base posture that rejects scheme-less input (unlike a bare url_standard = "whatwg"); "rfc-syntax" is RFC 3986 generic syntax as parsing, not normalization (case and dot-segments are preserved); "seo"/"canonical" is rurl's origin-cleaning intent — a lossy policy projection of a WHATWG-parsed URL (ADR 0017), which claims no resource equivalence: url_standard = "whatwg" underneath (which also resolves ./.. folder segments), https, a Unicode host regardless of the input spelling, strip www / trailing slash / index page, drop the whole query, and drop a default port only (port_handling = "strip_default": a non-default port names a different origin and survives). Inspect the resolved bundle with url_profile. Also accepted by canonical_join (forwarded through its ...).

How clean_url treats a URL whose parsed authority carried a userinfo delimiter (⁠user@⁠, ⁠user:password@⁠, a bare @, or a repeated @). Defaults to "strip". A policy dial on the clean surface (ADR 0017, mutation-table row 12; RUL-001), not a standards axis: it composes with every url_standard, including NULL, and never touches the user / password columns, parse_status, the diagnostics, serialize_url or get_url_key.

• "strip": (Default) The userinfo is dropped and the rest of the URL is emitted, exactly as before this argument existed.

• "reject": clean_url is NA for such a row. RFC 3986 section 3.2.1 deprecates the user:password form and lets an application reject it; sections 7.5 and 7.6 describe the credential leak and the ⁠https://example.com@evil.example/⁠ semantic attack a silently collapsed clean URL would hide. Use this when a cleaned URL that looks like the credential-free original would be misleading.

There is no "keep": serialize_url already preserves credentials under both standards, and format_url redacts them for display.

A character vector of URLs to be parsed.

A character string specifying how to handle protocols. Defaults to "keep". Regardless of this option, rurl only processes authority-based URLs whose scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any other scheme (e.g. mailto:, tel:, ws:) yields parse_status = "error". Scheme inference (below) also requires the input to be host-shaped: a scheme-less string that is not a host (e.g. "asdfghjkl", "12345", "/path") or is a non-canonical IP literal (integer/hex/octal/short forms, or leading-zero octets like "192.168.010.1") is rejected as "error" rather than having a scheme fabricated for it.

• "keep": If a supported scheme exists (http, https, ftp, ftps), it's used. If no scheme and the input is host-shaped, "http://" is added; otherwise the input is not a URL and yields "error".

• "none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).

• "strip": Any existing scheme is removed (scheme component will be NA).

• "http": The scheme is forced to be "http".

• "https": The scheme is forced to be "https".

A character string specifying how to handle "www" and www[number] prefixes in the host. Defaults to "none".

• "none": (Default) Leaves the host's www prefix (or lack thereof) untouched.

• "strip": Removes any "www." or ⁠www[number].⁠ prefix.

• "keep": Ensures the host starts with "www.". If it has ⁠www[number].⁠, it's normalized to "www.". If no www prefix, "www." is added. An empty input host remains empty.

• "if_no_subdomain": If the host is a bare registered domain (e.g., "example.com"), "www." is added. If the host already has a "www." or ⁠www[number].⁠ prefix, it is normalized to "www." (e.g., "www1.example.com" becomes "www.example.com"; "www1.sub.example.com" becomes "www.sub.example.com"). If a non-www subdomain exists (e.g., "sub.example.com" or the normalized "www.sub.example.com"), the host is not further altered. An empty input host remains empty.

Which TLD source to use for TLD extraction: "all", "icann", or "private". Defaults to "all".

A character string specifying how to handle the case of the cleaned URL. Defaults to "lower_host", the RFC 3986 §6.2.2.1 normalization (scheme and host are case-insensitive and folded to lowercase; the path is case-sensitive and preserved).

• "lower_host": (Default) Lowercases scheme and host only; the path keeps its original casing.

• "keep": Preserves casing of the reconstructed URL.

• "lower": Converts the cleaned URL to lowercase.

• "upper": Converts the cleaned URL to uppercase.

A character string specifying how to handle trailing slashes in the path component of the cleaned URL. Defaults to "none".

• "none": (Default) No specific handling is applied. Path remains as is after initial parsing.

• "keep": Ensures a trailing slash. If a path exists and doesn't end with one, it's added. If path is just "/", it's kept.

• "strip": Removes a trailing slash if present, unless the path is solely "/".

A character string specifying how to handle index/default pages. Defaults to "keep".

• "keep": (Default) Leave index/default page segments untouched.

• "strip": Remove a trailing index.* or default.* segment (case-insensitive).

How to normalize path structure. Defaults to "none". rurl owns dot-segment resolution: the path is read from the input verbatim (never from a pre-normalized path), so "none" preserves . / .. segments (/a/../b stays /a/../b) and only the settings below change them. Resolution follows RFC 3986 section 5.2.4 and acts on literal ./.. segments only — a percent-encoded %2e is a normal path byte, never a dot segment, so it is never treated as traversal.

• "none": (Default) No normalization; dot and slash structure is preserved exactly as written.

• "collapse_slashes": Collapse duplicate slashes in the path.

• "dot_segments": Resolve . and .. segments per RFC 3986.

• "both": Apply both collapse_slashes and dot_segments.

How to handle URLs starting with "//". Defaults to "keep".

• "keep": Parse using http but return scheme as NA and set status to "ok-scheme-relative".

• "http": Assume http for parsing and output.

• "https": Assume https for parsing and output.

• "error": Treat scheme-relative URLs as invalid.

An integer or NULL. Determines how many levels of subdomains are kept, in addition to any 'www.' prefix handled by www_handling.

• NULL: (Default) No specific subdomain stripping is performed beyond www_handling.

• 0: All subdomains are stripped. If www_handling preserved or added 'www.', it remains (e.g., 'www.sub.example.com' becomes 'www.example.com'; 'sub.example.com' becomes 'example.com').

• N > 0: Keeps up to N levels of subdomains, counted from right-to-left (closest to the registered domain), in addition to any 'www.' prefix. E.g., if N=1, 'three.two.one.example.com' becomes 'one.example.com'; 'www.three.two.one.example.com' (post www_handling) becomes 'www.one.example.com'.

How to present the host in clean_url. Defaults to "keep".

• "keep": Leave the host as parsed (may preserve original case).

• "idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.

• "unicode": Decode Punycode labels to Unicode for the cleaned URL.

Under url_standard = "whatwg" every value renders the UTS-46-mapped host, because mapping is part of WHATWG host parsing rather than a feature of the idna dial (BÜCHER.example presents as bücher.example; RUL-002). There "keep" preserves only whether the input was written as an A-label (xn--...), so get_host() and get_domain() agree on the same row. "rfc3986" and NULL are unaffected.

How to present the path percent-encoding in clean_url — the readable-vs-browser rendering choice (the path analog of host_encoding). Defaults to "keep". This is an orthogonal presentation knob: it is independent of url_standard and layers on top of any profile (e.g. ⁠url_standard = "whatwg", path_encoding = "encode"⁠ emits the WHATWG-parsed path in browser form), exactly like host_encoding. Only "keep" preserves a profile's canonical identity path verbatim; "encode" and "decode" are presentation forms that may re-encode or decode reserved octets (so ⁠%2F⁠ may fold to a path-separating /), independent of whether a profile is set.

• "keep": Leave the path percent-encoding untouched (the path is preserved as written in the URL, so ⁠%2F⁠ stays ⁠%2F⁠ rather than decoding into a path-separating /). With no url_standard, rurl keeps its historical RFC-style percent-hex case canonicalization, so ⁠%2f⁠ becomes ⁠%2F⁠. Under url_standard = "rfc3986", the profile's RFC 3986 §6.2.2.2 normalization applies: a triplet encoding an unreserved byte is decoded, every other triplet stays encoded with uppercased hex, so ⁠%7E⁠ becomes ~ while ⁠%2F⁠ stays ⁠%2F⁠. Under url_standard = "whatwg", existing percent-triplet spelling is preserved byte-for-byte. Use "encode" to additionally normalize which bytes are encoded.

• "encode": The browser/percent-encoded rendering. Decodes the path first, then percent-encodes each segment (slashes preserved), so a readable non-ASCII path is emitted in its percent-encoded UTF-8 form.

• "decode": The readable rendering. Percent-decodes UTF-8 sequences in the path, so a percent-encoded segment is shown as readable text.

A character string controlling whether (and how) the query string is included in clean_url. Defaults to "drop", which preserves the historical query-free clean_url. The raw query result field is never affected by this option — it always reports the faithful original query.

• "drop": (Default) clean_url carries no query, exactly as before.

• "filter": Keep contentful params, dropping known trackers via a built-in denylist (e.g. ⁠utm_*⁠, fbclid, gclid). params_drop extends the denylist; params_keep rescues names (winning over both the denylist and empty-dropping).

• "allow": Keep only params whose names match params_keep; all others are dropped. Here params_keep is an inclusion criterion only, not an empty-rescue.

• "keep": Keep every param, re-encoded into canonical form (not the verbatim original — that stays on the query field).

In every non-"drop" mode the surviving query is re-encoded canonically (uppercase percent-hex, spaces as ⁠%20⁠) and appended after the path. The query is intentionally EXEMPT from case_handling (query values are case-sensitive — tokens, IDs, signatures), so under case_handling = "lower" or "upper" the clean_url is no longer uniformly cased: scheme/host/path fold but the query keeps its original case. Because clean_url is the canonical_join key, any non-"drop" mode also brings the query into that join key (so ?id=1 and ?id=2 stop collapsing, while utm-only differences still collapse under "filter").

Character vector of parameter-name globs (only * is special), or NULL (default). In "filter" mode this is the rescue list; in "allow" mode it is the allowlist. Ignored in "drop"/"keep".

Character vector of parameter-name globs to add to the built-in denylist in "filter" mode, or NULL (default). Ignored in "drop"/"allow"/"keep".

Logical (default FALSE). When TRUE, surviving params are stably sorted by decoded key. Active in "filter"/"allow"/"keep".

One of "keep" (default) or "drop". "drop" removes empty-valued params (e.g. ⁠?ref=⁠), except those rescued by params_keep in "filter" mode.

Logical (default FALSE). Controls whether the denylist and params_keep/params_drop matching is case-sensitive.

Logical (default FALSE). When TRUE, + in query values is treated as a space (HTML-form decoding) before percent-decoding. FALSE keeps + literal (RFC 3986 generic behavior).

A character string controlling whether the port appears in clean_url. Defaults to "exclude", today's only historical behavior. This knob is standalone and standard-independent (editorial, like www_handling) – url_standard never governs whether it may be set.

• "exclude": (Default) The port never appears in clean_url.

• "strip_all": Explicit alias of "exclude".

• "keep": Include the syntactic port when present, including a default port under url_standard = "whatwg". This is an explicit non-parity override for callers that need the input's port spelling.

• "strip_default": Keep only non-default ports (using the same scheme-default table), independent of url_standard. Default-ness is judged on the scheme the input was parsed with, never on the scheme protocol_handling renders: ⁠http://example.com:443/a⁠ under protocol_handling = "https" keeps ⁠:443⁠, and ⁠http://example.com:80/a⁠ drops ⁠:80⁠ (RFC 3986 §6.2.3; WHATWG URL Standard port state; RUL-016). This is the value profile = "seo" pins.

Controls whether scheme-less, host-shaped input is accepted (an input-acceptance axis, distinct from protocol_handling, which only controls how the scheme is presented, and from url_standard, which controls interpretation). Defaults to "infer".

• "infer": (Default) Fabricate ⁠http://⁠ for scheme-less host-shaped input (e.g. example.com parses as ⁠http://example.com⁠), a browser-omnibox-style affordance. This is the historical behavior.

• "require": Reject scheme-less input — a scheme-less host-shaped value becomes parse_status = "error" rather than gaining a fabricated scheme. Use this for a strict, pure-parser posture. Note this governs only bare host input; scheme-relative ⁠//host⁠ input is governed separately by scheme_relative_handling.

Which scheme tokens may enter parsing (a scheme-acceptance axis, distinct from scheme_policy, which governs scheme-less input, and from url_standard, which governs interpretation). Defaults to "web".

• "web": (Default) Only the curated web-scheme allowlist (http/https/ftp/ftps/file) is admitted; a scheme-bearing input outside it is parse_status = "error". This is the historical, byte-for-byte compatible behavior.

• "general": Admit any syntactically valid scheme token and parse opaque (mailto:x), non-special (⁠foo://host⁠), and RFC-generic URLs. Requires an explicit url_standard ("rfc3986" or "whatwg"), which decides the interpretation; general with url_standard = NULL is an error. Non-special / opaque hosts receive no www-stripping, no domain/TLD derivation, and are never run through the IDNA/punycode helpers. A non-special scheme with no ⁠//⁠ is an opaque path: it has no authority, so host, user, port and the domain/tld columns are all NA and the entire remainder is the path (query/fragment are still split off). This includes ⁠mailto:⁠ — the recipient's @ never re-triggers authority parsing. To decompose a ⁠mailto:⁠ recipient, use the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7) or get_mailto_recipients(); those deliberately return a recipient's parts where this table presents NA, because a recipient domain is extraction metadata, not the URL's authority.

Note that ⁠file:⁠ is admitted under both values, including the default. A ⁠file:⁠ URL denotes local-filesystem access, and one with a non-empty host (⁠file://server/share/x⁠) is a UNC path on Windows, so dereferencing it reaches a remote SMB share. rurl parses ⁠file:⁠ URLs; it never opens them. Restricting schemes before anything dereferences them is the caller's job — see SECURITY.md.

Optional top-level standard profile: NULL (default), "rfc3986", or "whatwg". With NULL the behavior is exactly what the individual low-level options select (fully backward compatible). When set, it selects a coherent set of standard-conformant behaviors for the axes it governs — path percent/dot handling, the host IPv4/reg-name model, and case_handling — so callers do not have to hand-assemble the low-level knobs. Passing a governed low-level knob (path_normalization or case_handling) with a value the selected profile would not choose is an error; passing the value the profile would pick is accepted (only case_handling = "lower_host" is accepted under a selector — "keep", "lower", and "upper" all conflict, since "lower" also lowercases the path, which neither standard sanctions). Added as the last argument so existing positional calls keep their meaning; always pass it by name. Under "whatwg" the selector additionally recognizes a literal backslash as a path separator for WHATWG-special schemes (http/https/ftp) and nulls default ports in parse output; use port_handling = "strip_default" for spec-style clean URL port rendering. See resolve_url for url_standard-governed reference resolution. The selector does not govern whether port_handling may be set (it is a standalone editorial knob), nor does it govern path_encoding (an orthogonal path-presentation knob that layers on any profile), IDNA rendering, or query handling.

Optional pslr engine controlling which Public Suffix List backs domain / TLD / subdomain extraction: NULL (default) resolves against pslr's session-global default list — exactly the historical behavior — while a pslr::psl_engine() snapshot resolves against that specific list, per request, without mutating any global state (never call pslr::psl_use() for this). Use it to pin a particular list version or to load an alternate list via pslr::psl_engine(source = "path", path = ...). Process-local: an engine holds a C++ external pointer that does not serialize across R sessions or parallel workers — build it in the process that uses it; never cache it to disk or send it to a worker (rebuild one per process instead). Only the domain-derived outputs (domain, tld, and the subdomain-trimmed host / clean_url) depend on it.

Optional named profile bundling several knobs at once: NULL (default; behaves exactly as the individual arguments select, fully backward compatible), "browser", "whatwg", "rfc-syntax", "seo", or the "seo" alias "canonical". A profile is separate from url_standard (it bundles acceptance, interpretation, leniency, and canonicalization together) and expands only into arguments you did not supply explicitly — an explicit argument always overrides the profile. "browser" is a browser-like fix-up posture (http-prepending; not Chrome-faithful); "whatwg" is the absolute-URL no-base posture that rejects scheme-less input (unlike a bare url_standard = "whatwg"); "rfc-syntax" is RFC 3986 generic syntax as parsing, not normalization (case and dot-segments are preserved); "seo"/"canonical" is rurl's origin-cleaning intent — a lossy policy projection of a WHATWG-parsed URL (ADR 0017), which claims no resource equivalence: url_standard = "whatwg" underneath (which also resolves ./.. folder segments), https, a Unicode host regardless of the input spelling, strip www / trailing slash / index page, drop the whole query, and drop a default port only (port_handling = "strip_default": a non-default port names a different origin and survives). Inspect the resolved bundle with url_profile. Also accepted by canonical_join (forwarded through its ...).

How clean_url treats a URL whose parsed authority carried a userinfo delimiter (⁠user@⁠, ⁠user:password@⁠, a bare @, or a repeated @). Defaults to "strip". A policy dial on the clean surface (ADR 0017, mutation-table row 12; RUL-001), not a standards axis: it composes with every url_standard, including NULL, and never touches the user / password columns, parse_status, the diagnostics, serialize_url or get_url_key.

• "strip": (Default) The userinfo is dropped and the rest of the URL is emitted, exactly as before this argument existed.

• "reject": clean_url is NA for such a row. RFC 3986 section 3.2.1 deprecates the user:password form and lets an application reject it; sections 7.5 and 7.6 describe the credential leak and the ⁠https://example.com@evil.example/⁠ semantic attack a silently collapsed clean URL would hide. Use this when a cleaned URL that looks like the credential-free original would be misleading.

There is no "keep": serialize_url already preserves credentials under both standards, and format_url redacts them for display.

A character vector of URLs.

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".

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

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

Data frames to join.

The URL columns to key on: either one column name present on both sides ("URL"), or the named form c(x_col = "y_col") when they differ.

A rurl_url_key_policy from url_key_policy(), applied symmetrically to both sides. Side-specific rules are prohibited: equality has to stay symmetric and transitive.

Length-2 character vector disambiguating column names present on both sides. Default c(".x", ".y"). If the result would still contain a duplicate name, the join errors rather than repairing it silently.

Optional column name under which to expose the comparison key. NULL (default) hides it. The exposed value is the classed key from get_url_key(), never a URL-looking string, and a name that collides with an output column is an error.

Cardinality you assert about matching keys, checked before the result is materialized: "none" (default, no check), "one-to-one", "one-to-many", "many-to-one", or "many-to-many" (no constraint, declared explicitly).

How many y rows a matching x row may take: "all" (default, lossless) or the separately named lossy narrowings "first" / "last", which take the first or last match in y row order.

What to do with rows that cannot be keyed: "keep" (default), "drop" or "error".

What to do with rows that parsed with a warning: "allow" (default), "reject" (ineligible to match, but retained) or "error".

Optional psl_engine object from pslr::psl_engine() for per-request Public Suffix List resolution. NULL (default) uses the session-global engine. It cannot affect the comparison key – identity frames no public-suffix component – but it can affect which rows count as warning rows under warnings = "reject".

The standard whose identity semantics apply: "whatwg" (default) or "rfc3986". Unlike the parse surface, NULL is not accepted – an unnamed standard cannot freeze key bytes.

How strictly schemes compare. "exact" (default) compares the normalized scheme identity. "http_https" additionally collapses http and https into one class, so ⁠http://h/⁠ and ⁠https://h/⁠ compare equal; every other scheme stays exact, including the ws/wss pair. "http_https_missing" is accepted by the vocabulary but not implemented, and errors – see Details.

A single profile name: one of "browser", "whatwg", "rfc-syntax", "seo", or the "seo" alias "canonical".

Optional explicit knob overrides (e.g. scheme_policy = "require"), named as in safe_parse_url. Each override that the profile also sets replaces the profile's value and marks the result customized.