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

new URL.Components( ) → (URL.Components) • Returns a new URL.Components instance.

Class Functions

fromString(string: String) → (URL.Components or null) • Parses the string into URL.Components. If the string is not a valid URL, null is returned.
fromURL(url: URL, resolvingAgainstBaseURL: Boolean) → (URL.Components or null) • Parses the string represenation of the URL. If the URL’s string is malformed, null is returned. If resolve is true and the given url is relative, its base URL’s components are considered.

Instance Functions

urlRelativeTo(base: URL or null) → (URL or null) • Returns a URL relative to the base URL and the components or null.

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).

fragment (String or null) • Any anchor string: #anchorIdentifer.
host (String or null) • The host subcomponent. For example: omni-automation.com
password (String or null) • The password string.
path (String or null) • If a file URL, the path to the item.
port (Number or null) • If used, the port number (preceded by a colon in the URL): 80
query (String or null) • The search string, if any.
queryItems (Array of URL.QueryItem or null) • The query of the URL.Components as individual components. [{"name":"id", "value":"12345RTY"}]
scheme (String or null) • The schema of the URL: https
url (URL or null r/o) • Returns a URL for the components or null.
user (String or null) • If used, the name of the user.

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

new URL.QueryItem(name: String, value: String or null) → (URL.QueryItem) • Returns a new URL.QueryItem with the given name and value.

Instance Properties

name (String r/o) • The key for the query
value (String or null r/o) • The value (if any) for the query

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