Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.url

    URL.parse

    Parses an absolute URL with the URL Standard model and returns a URL or an explanatory Err.

    parse(text: string) -> Result<URL, string>
    Module
    std.url
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.url in language mode 5.21.

    The current compiler selects std/url.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Not applicable

    Parameter constraints

    Additional contracts are Pending.

    URL.parse takes a string and applies the WHATWG URL parser with UTF-8 input and no base URL. A successful parse returns Ok containing an immutable URL. Relative references need a base and therefore return Err.

    A parser failure returns Err containing a nonempty string. Missing or invalid schemes, invalid hosts, and ports outside 0 through 65535 fail. Error wording is explanatory text and has no fixed spelling.

    URL preprocessing removes leading and trailing code points from U+0000 through U+0020. It then removes U+0009, U+000A, and U+000D throughout the input. Other characters are processed by the URL parser. A validation warning that permits parsing does not become an Err.

    Schemes use lowercase. Special-scheme domain hosts use ASCII domain serialization. Default ports disappear and hierarchical dot segments are removed. Opaque paths retain their distinct path interpretation.

    The default ports are 21 for ftp, 80 for http and ws, and 443 for https and wss. Other valid ports survive serialization as decimal integers. The file scheme has no port.

    URL.toString serializes every stored component. It preserves user information, nondefault ports, query order, and explicit empty query and fragment delimiters. Existing percent escapes retain their spelling. Newly escaped characters use percent-encoded UTF-8 bytes with uppercase hexadecimal digits.

    Parsing the serialization produces the same serialization and component values. Reading a URL does not modify it. Parsing evaluates its argument once before validation and performs no network or filesystem operation.

    Related rule: Parse and serialize absolute URLs

    Result

    Additional contracts are Pending.

    The declared result type is Result<URL, string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Parses an absolute URL with the URL Standard model and returns a URL or an explanatory Err.

    Resolved contracts

    Link

    Related entries

    Link

    std.url

    Parse and serialize absolute URLs

    Link
    Ruletopaz.stdlib.contract.url-parse.rule

    Parse and serialize absolute URLs

    URL.parse takes a string and applies the WHATWG URL parser with UTF-8 input and no base URL. A successful parse returns Ok containing an immutable URL. Relative references need a base and therefore return Err.

    A parser failure returns Err containing a nonempty string. Missing or invalid schemes, invalid hosts, and ports outside 0 through 65535 fail. Error wording is explanatory text and has no fixed spelling.

    URL preprocessing removes leading and trailing code points from U+0000 through U+0020. It then removes U+0009, U+000A, and U+000D throughout the input. Other characters are processed by the URL parser. A validation warning that permits parsing does not become an Err.

    Schemes use lowercase. Special-scheme domain hosts use ASCII domain serialization. Default ports disappear and hierarchical dot segments are removed. Opaque paths retain their distinct path interpretation.

    The default ports are 21 for ftp, 80 for http and ws, and 443 for https and wss. Other valid ports survive serialization as decimal integers. The file scheme has no port.

    URL.toString serializes every stored component. It preserves user information, nondefault ports, query order, and explicit empty query and fragment delimiters. Existing percent escapes retain their spelling. Newly escaped characters use percent-encoded UTF-8 bytes with uppercase hexadecimal digits.

    Parsing the serialization produces the same serialization and component values. Reading a URL does not modify it. Parsing evaluates its argument once before validation and performs no network or filesystem operation.

    Why

    A single established parser gives URL text one interpretation. Parsing without a hidden base makes acceptance independent of the working directory and browser location. Stable serialization keeps resource identifiers reusable in text and typeset links.

    Examples Normalize the scheme, host, port, and pathHandle invalid absolute URL text as dataCheck both port boundaries and the first invalid portApply URL preprocessing and escape a path spacePreserve serialized escapes and empty components through parsingEvaluate the input once before reporting a parse errorReject a forbidden domain character

    Source evidence

    Normalize the scheme, host, port, and path

    Link

    run · running · Verification: not-run

    main.tpzNormalize the scheme, host, port, and pathOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("HTTPS://Example.COM:443/a/./b/../c?x=1#part")) {
    5. case Ok(value) => io.writeLine(value.toString())
    6. case Err(_) => io.writeLine("parse failed")
    7. }
    Expected outputexit 0
    https://example.com/a/c?x=1#part
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. https://example.com/a/c?x=1#part

    This exact example has not been executed.

    Source evidence

    Handle invalid absolute URL text as data

    Link

    run · running · Verification: not-run

    main.tpzHandle invalid absolute URL text as dataOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["", "../guide", "1bad:x", "https://", "https://example.com:wrong"]) {
    5. match (URL.parse(text)) {
    6. case Err(message) => io.writeLine("{message != ""}")
    7. case Ok(_) => io.writeLine("accepted")
    8. }
    9. }
    Expected outputexit 0
    true
true
true
true
true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true
    2. true
    3. true
    4. true
    5. true

    This exact example has not been executed.

    Source evidence

    Check both port boundaries and the first invalid port

    Link

    run · running · Verification: not-run

    main.tpzCheck both port boundaries and the first invalid portOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["https://example.com:0", "https://example.com:65535", "https://example.com:65536"]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => io.writeLine(value.toString())
    7. case Err(_) => io.writeLine("invalid port")
    8. }
    9. }
    Expected outputexit 0
    https://example.com:0/
https://example.com:65535/
invalid port
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. https://example.com:0/
    2. https://example.com:65535/
    3. invalid port

    This exact example has not been executed.

    Source evidence

    Apply URL preprocessing and escape a path space

    Link

    run · running · Verification: not-run

    main.tpzApply URL preprocessing and escape a path spaceOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse(" \thttps://EXAMPLE.com/a b\n")) {
    5. case Ok(value) => io.writeLine(value.toString())
    6. case Err(_) => io.writeLine("parse failed")
    7. }
    Expected outputexit 0
    https://example.com/a%20b
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. https://example.com/a%20b

    This exact example has not been executed.

    Source evidence

    Preserve serialized escapes and empty components through parsing

    Link

    run · running · Verification: not-run

    main.tpzPreserve serialized escapes and empty components through parsingOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["https://example.com/a%2fb?x=%2b#p%2fq", "https://example.com/?#"]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => {
    7. io.writeLine(value.toString())
    8. match (URL.parse(value.toString())) {
    9. case Ok(again) => io.writeLine(again.toString())
    10. case Err(_) => io.writeLine("second parse failed")
    11. }
    12. }
    13. case Err(_) => io.writeLine("first parse failed")
    14. }
    15. }
    Expected outputexit 0
    https://example.com/a%2fb?x=%2b#p%2fq
https://example.com/a%2fb?x=%2b#p%2fq
https://example.com/?#
https://example.com/?#
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. https://example.com/a%2fb?x=%2b#p%2fq
    2. https://example.com/a%2fb?x=%2b#p%2fq
    3. https://example.com/?#
    4. https://example.com/?#

    This exact example has not been executed.

    Source evidence

    Evaluate the input once before reporting a parse error

    Link

    run · running · Verification: not-run

    main.tpzEvaluate the input once before reporting a parse errorOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. function inputText() -> string {
    5. io.writeLine("input")
    6. return "../chapter"
    7. }
    8. match (URL.parse(inputText())) {
    9. case Err(_) => io.writeLine("invalid URL")
    10. case Ok(_) => io.writeLine("accepted")
    11. }
    Expected outputexit 0
    input
invalid URL
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. input
    2. invalid URL

    This exact example has not been executed.

    Source evidence

    Reject a forbidden domain character

    Link

    run · running · Verification: not-run

    main.tpzReject a forbidden domain characterOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("https://exa[mple.com/")) {
    5. case Err(_) => io.writeLine("invalid host")
    6. case Ok(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    invalid host
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid host

    This exact example has not been executed.

    Source evidence

    Menu

    Download