Skip to contents

Classify the scheme of each URL as WHATWG special or not

Source: R/accessors.R
get_scheme_class.Rd

Companion helper for the url_standard selector: reports whether each URL's resolved scheme is a WHATWG “special scheme” ("special"), one rurl supports but WHATWG does not treat specially ("non-special"), or absent/unparseable ("missing-or-error" – an unsupported scheme, a scheme-relative URL under the default scheme_relative_handling = "keep", or an input that failed to parse at all).

Usage

get_scheme_class(
  url,
  url_standard = NULL,
  scheme_policy = c("infer", "require"),
  scheme_acceptance = c("web", "general")
)

Arguments

url

A character vector of URLs.

url_standard

Standard profile gating the classification: NULL (default; no classification, returns NA), "rfc3986", or "whatwg". The gate is semantic, not stylistic: "special" is a WHATWG notion, so without a selector there is no fact to report. 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.

scheme_policy

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.

scheme_acceptance

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.

Value

A character vector the same length as url, each element one of "special", "non-special", or "missing-or-error", or NA when no selector is given.

Details

Unlike get_host_type, the classification itself does not vary between "rfc3986" and "whatwg" – “special scheme” is a WHATWG concept describing a fixed property of the scheme string, not something RFC 3986 redefines. url_standard instead gates whether the metadata is exposed at all, mirroring get_host_type()'s contract: pass NULL (the default) and every element is NA.

Within rurl's allowlist (http/https/ftp/ftps/ file), http, https, ftp, and file are WHATWG special schemes; ftps (FTP-over-TLS, rurl's own addition) is not. This is metadata only – it does not add ws/wss to rurl's allowed schemes and does not change what safe_parse_url accepts.

Under the default scheme_acceptance = "web" an opaque scheme such as mailto: is outside rurl's web allowlist and classifies as "missing-or-error". Pass scheme_acceptance = "general" to run the general parser, under which such a scheme resolves and classifies as "non-special" (it is not a WHATWG special scheme).

See also

get_host_type, get_scheme

Examples

get_scheme_class("http://example.com/", url_standard = "whatwg")
#> [1] "special"
get_scheme_class("ftps://example.com/", url_standard = "whatwg")
#> [1] "non-special"
get_scheme_class("//example.com/path", url_standard = "whatwg")
#> [1] "missing-or-error"
get_scheme_class(
  "mailto:jane@example.com",
  url_standard = "rfc3986", scheme_acceptance = "general"
)
#> [1] "non-special"