URL.Components

URL.Components tools for allowing for correct generation and interpreation of URL instances, dealing with the specific different quoting rules for each specific part of the URL.

(Link to the related Apple developer documentation.)

Constructors

Class Functions

Instance Functions

The urlRelativeTo( ) function is used to derive the URL to locations within a site or sub-site:

Derive URL Relative to Base URL


mainURL = URL.fromString("https://www.omnigroup.com") urlComps = new URL.Components() urlComps.path = "blog" urlComps.urlRelativeTo(mainURL).string //--> "https://www.omnigroup.com/blog"

Deriving URLs can be done in mass by changing the value of the path property of the URL.Components instance:

Deriving URLs Relative to Base URL


mainURL = URL.fromString("https://www.omnigroup.com") urlComps = new URL.Components() siteLocations = ["omnifocus", "omnioutliner", "omniplan", "omnigraffle"].sort() siteURLs = siteLocations.map(location => { urlComps.path = location return urlComps.urlRelativeTo(mainURL).string }) //--> ["https://www.omnigroup.com/omnifocus", "https://www.omnigroup.com/omnigraffle", "https://www.omnigroup.com/omnioutliner", "https://www.omnigroup.com/omniplan"]

A variation of the previous script, that generates markdown links to the derived locations:

Generate Links in Markdown


mainURL = URL.fromString("https://www.omnigroup.com") urlComps = new URL.Components() sectionTitles = ["OmniFocus", "OmniOutliner", "OmniPlan", "OmniGraffle"].sort() markdownLinks = sectionTitles.map(sectionTitle => { urlComps.path = sectionTitle.toLowerCase() url = urlComps.urlRelativeTo(mainURL).string return `[${sectionTitle}](${url})` }) markdown = markdownLinks.join("\n") //--> "[OmniFocus](https://www.omnigroup.com/omnifocus) [OmniGraffle](https://www.omnigroup.com/omnigraffle) [OmniOutliner](https://www.omnigroup.com/omnioutliner) [OmniPlan](https://www.omnigroup.com/omniplan)"

Instance Properties

NOTE: The getter for some of these properties will remove any percent encoding this component may have (if the component allows percent encoding). Setting some of these properties assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).

Deriving URL with Anchor (fragment)


baseURL = URL.fromString("https://omni-automation.com") urlComps = URL.Components.fromURL(baseURL, true) urlComps.path = "/shared/url-components-query.html" urlComps.fragment = "QueryItem" urlComps.url.string //--> "https://omni-automation.com/shared/url-components-query.html#QueryItem"

Note that the value of the path property in the above example begins with a slash (/)

The following example demonstrates creating a URL containing the user/password login information:

Create Basic Log-in URL


urlComps = new URL.Components() urlComps.scheme = "https" urlComps.host = "omni-automation.com" urlComps.user = "Otto Automator" urlComps.password = "aut0mati0nRu1es" urlComps.port = 80 urlComps.url.string //--> "https://Otto%20Automator:aut0mati0nRu1es@omni-automation.com:80"
Simple Query


urlComps = new URL.Components() urlComps.scheme = "https" urlComps.host = "omni-automation.com" urlComps.query = "notification rules" urlComps.url.string //--> "https://omni-automation.com?notification%20rules"
 

URL.QueryItem

A single name-value pair from the query portion of a URL.

Note that a name may appear more than once in a single query string, so the name values are not guaranteed to be unique. If the URL.Components instance has an empty query component, returns an empty array. If the URL.Components instance has no query component, returns nil.

Constructors

Instance Properties

The setter combines an array containing any number of URL.QueryItems, each of which represents a single key-value pair, into a query string and sets the URLComponents query property. Passing an empty array sets the query component of the URLComponents to an empty string. Passing nil removes the query component of the URL.Components instance.

NOTE: If a name-value pair in a query is empty (i.e. the query string starts with ‘&’, ends with ‘&’, or has “&&” within it), you get a URL.QueryItem with a zero-length name and a nil value. If a query’s name-value pair has nothing before the equals sign, you get a zero-length name. If a query’s name-value pair has nothing after the equals sign, you get a zero-length value. If a query’s name-value pair has no equals sign, the query name-value pair string is the name and you get a nil value.

Complex Query


q1 = new URL.QueryItem("color", "red") q2 = new URL.QueryItem("make", "Chevy") q3 = new URL.QueryItem("model", "Bolt EV") urlComps = new URL.Components() urlComps.scheme = "https" urlComps.host = "omni-automation.com" urlComps.queryItems = [q1, q2, q3] urlComps.url.string //--> "https://omni-automation.com?color=red&make=Chevy&model=Bolt%20EV"
Extracting Query Items


urlStr = "https://omni-automation.com?color=red&make=Chevy&model=Bolt%20EV" urlComps = URL.Components.fromString(urlStr) urlComps.queryItems.forEach(qItem => { console.log(qItem.name + ":", qItem.value) }) //--> color: red //--> make: Chevy //--> model: Bolt EV