The [urlComp] command.

Introduction

The urlComp command lets you manipulate the elements of a Uniform Resource Locator (URL).

Synopsis

The formal syntax of the [urlComp] command is:

urlComp subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

The [create] subcommand

This subcommand builds up an URL from its constituent parts. The complete syntax is:

    urlComp create dict

The dict argument is a Tcl dictionary whose keys are the names of URL elements and values are the corresponding strings. This command takes care of properly encoding the various elements with percent escapes. The possible keys are: fragment, host, password, path, port, query, scheme, user. Not all keys need to be specified. Unknown keys are silently ignored.
If the scheme and the host keys are not specified, the command uses a "file" scheme by default. This is a convenience to easily build local file URLs by specifying only the path.

The [decode] subcommand

This subcommand decodes an url-encoded string. The complete syntax is:

    urlComp decode url

It returns a string made by replacing in the url argument all percent encoded sequences with the matching UTF-8 characters.
You must call this command only on strings that you know to be percent-encoded. Calling it on strings that are not percent-encoded can lead to misinterpreting a percent character as the beginning of a percent-encoded sequence.

The [encode] subcommand

This subcommand encodes an element of an URL by replacing some characters with percent-encoded sequences. The complete syntax is:

    urlComp encode str element

The element argument tells what part of the URL is represented by the str string. The possible values for element are: fragment, host, password, path, port, query, scheme, user. Note that no encoding applies to port and scheme elements which are returned unchanged.
Entire URL strings cannot be percent-encoded, because each URL component specifies a different set of allowed characters. For example, the query component of a URL allows the '@' character, but that character must be percent-encoded in the password component.
UTF-8 encoding is used to determine the correct percent-encoded characters.
Beware: you must not call this command on strings that are already percent-encoded as it may cause percent characters in a percent-encoded sequence to be percent-encoded twice.

The [get] subcommand

This subcommand extracts an element from an URL. The complete syntax is:

    urlComp get ?-encoded? url element

The url argument must be a valid URL (properly url-encoded as necessary). The possible values of the element argument are: fragment, host, password, path, port, query, scheme, user.
By default, the command returns the element in decoded form. If the -encoded option is specified, the element is returned in its encoded form.
If the element is not present in the URL, the command raises an error.

The [items] subcommand

This subcommand returns the different elements of an URL. The complete syntax is:

    urlComp items ?-encoded? url

The url argument must be a valid URL. It returns a dictionary containing some of the following keys: fragment, host, password, path, port, query, scheme, user. A key is present in the dictionary only if the corresponding element is present in the URL. If the -encoded option is specified, the elements are returned in their encoded form, otherwise they are converted to UTF-8 strings.

The [valid] subcommand

This subcommand tells whether a string is a valid URL. The complete syntax is:

    urlComp valid url

It returns 1 if the url argument is a string that conforms to RFC 3986, and 0 otherwise.

Examples

Here are a few basic examples which can be executed one by one in the Tcl Shell (⌘Y) in Alpha.
Retrieve the elements of an URL:

«» urlComp items "http://www.example.com:1030/dir/subir/file.html?q=val"
host www.example.com path /dir/subir/file.html port 1030 query q=val scheme http
«» urlComp items "file:///dir/subdir/file.html"
host {} path /dir/subdir/file.html scheme file

Extract an element from an URL:

«» urlComp get http://www.example.com:1030/dir/subir/file.html host
www.example.com

Build a new URL from its elements:

«» urlComp create "scheme http host www.example.com path /dir/subir/attaché.html"
http://www.example.com/dir/subir/attach%C3%A9.html
«» urlComp create "path /dir/subdir/file.html"
file:///dir/subdir/file.html

Properly encode elements of an URL:

«» urlComp encode "/dir/日本/束京.html" path
/dir/%E6%97%A5%E6%9C%AC/%E6%9D%9F%E4%BA%AC.html
«» urlComp encode "key=v@l&føø=bår" query
key=v@l&f%C3%B8%C3%B8=b%C3%A5r
«» urlComp encode "é@!" password
%C3%A9%40!

Decode an url-encoded string:

«» urlComp decode /dir/%E6%97%A5%E6%9C%AC/%E6%9D%9F%E4%BA%AC.html
/dir/日本/束京.html

Last updated 2020-10-25 15:11:02