This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

4.13. Interfaces for URI manipulation

An interface that has a complement of URI decomposition attributes will have seven attributes with the following definitions:

           attribute DOMString protocol;
           attribute DOMString host;
           attribute DOMString hostname;
           attribute DOMString port;
           attribute DOMString pathname;
           attribute DOMString search;
           attribute DOMString hash;

The attributes defined to be URI decomposition attributes must act as described for the attributes with the same corresponding names in this section.

In addition, an interface with a complement of URI decomposition attributes will define an input, which is a URI that the attributes act on, and a common setter action, which is a set of steps invoked when any of the attributes' setters are invoked.

The seven URI decomposition attributes have similar requirements.

On getting, if the input fulfills the condition given in the "getter condition" column corresponding to the attribute in the table below, the user agent must return the part of the input URI given in the "component" column, with any prefixes specified in the "prefix" column appropriately added to the start of the string and any suffixes specified in the "suffix" column appropriately added to the end of the string. Otherwise, the attribute must return the empty string.

On setting, the new value must first be mutated as described by the "setter preprocessor" column, then mutated by %-escaping any characters in the new value that are not valid in the relevant component as given by the "component" column. Then, if the resulting new value fulfills the condition given in the "setter condition" column, the user agent must make a new string output by replacing the component of the URI given by the "component" column in the input URI with the new value; otherwise, the user agent must let output be equal to the input. Finally, the user agent must invoke the common setter action with the value of output.

The rules for parsing and constructing URIs are described in RFC 3986 and RFC 3987. [RFC3986] [RFC3987]

Attribute Component Getter Condition Prefix Suffix Setter Preprocessor Setter Condition
protocol <scheme> U+003A COLON (":") Remove all trailing U+003A COLON (":") characters The new value is not the empty string
host <hostport> input is hierarchical and uses a server-based naming authority
hostname <host>/<ihost> input is hierarchical and uses a server-based naming authority Remove all leading U+002F SOLIDUS ("/") characters
port <port> input is hierarchical and uses a server-based naming authority Remove any characters in the new value that are not in the range U+0030 DIGIT ZERO .. U+0039 DIGIT NINE The new value is not the empty string
pathname <abs_path> input is hierarchical If it has no leading U+002F SOLIDUS ("/") character, prepend a U+002F SOLIDUS ("/") character to the new value
search <query> input is hierarchical U+003F QUESTION MARK ("?") Remove one leading U+003F QUESTION MARK ("?") character, if any
hash <fragment> Fragment identifier is longer than zero characters U+0023 NUMBER SIGN ("#") Remove one leading U+0023 NUMBER SIGN ("#") character, if any

The <hostport> component is defined as being the <host>/<ihost> component, followed by a colon and the <port> component, but with the colon and <port> component omitted if the given port matches the default port for the protocol given by the <scheme> component.