std/net/url

Standard Library documentation

URL parsing, escaping, and templates.

Back to Stdlib View Source

Module

Name
std/net/url
Area
Standard Library
Source
modules/std/net/url.zzm

NAME

std/net/url - URL parsing, escaping, and templates.

SYNOPSIS

  from std/net/url import *;

  let parsed := parse(
    "https://api.example.com/v1?q=tea%20time"
  );

  let encoded := escape("tea time");
  let text := unescape(encoded);

  let url := fill_template(
    "https://api.example.com/{version}/items/{id}{?q}",
    { version: "v1", id: 7, q: "tea time" }
  );

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

This module provides small URL helpers.

EXPORTS

Functions

  • escape(value)

    Parameters: value is any value. Returns: String. Percent-encodes value for use in URLs.

  • unescape(value)

    Parameters: value is URL-escaped text. Returns: String. Decodes percent-escaped text.

  • parse(url)

    Parameters: url is a URL string. Returns: Dict. Parses url and returns a dictionary with: url, scheme, authority, userinfo, host, port, path, query, fragment, and query_params.

  • fill_template(template, values)

    Parameters: template is an RFC 6570 URI Template and values is a dictionary or pair list of template variables. Returns: String. Expands the template using values.

    This is a complete implementation of RFC 6570 (all four levels), validated against the official URI Template test suite. All expression operators are supported:

    • {var} - simple string expansion;
    • {+var} - reserved expansion, leaving URI-reserved characters

      and percent-encoded triplets intact;

    • {#var} - fragment expansion;
    • {.var} - label expansion with a dot prefix;
    • {/var} - path segment expansion;
    • {;var} - path-style parameter expansion;
    • {?var} - form-style query expansion;
    • {&var} - form-style query continuation.

    Each variable in an expression may take the :N prefix modifier (expand only the first N characters of a string value, with N between 1 and 9999) or the * explode modifier (expand list and dictionary members as separate items), and expressions may name several variables separated by commas, for example {?q,page,lang}.

    Variable values may be Strings (or Numbers and Booleans, which are rendered as text), Arrays (RFC 6570 list values), or Dicts and pair lists (RFC 6570 associative values; dictionary keys are expanded in sorted order). Variables that are null, missing, or empty lists or dictionaries are undefined per RFC 6570 and are omitted from the expansion.

    Invalid templates - unbalanced braces, unknown operators, malformed variable names or modifiers, or a :N prefix applied to a list or dictionary value - throw an exception.

COPYRIGHT AND LICENCE

std/net/url is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.