203 lines
7.3 KiB
Factor
203 lines
7.3 KiB
Factor
USING: assocs hashtables help.markup help.syntax
|
|
io.streams.string io.files io.pathnames kernel strings present
|
|
math multiline ;
|
|
IN: urls
|
|
|
|
HELP: url
|
|
{ $class-description "The class of URLs. The slots correspond to the standard components of a URL." } ;
|
|
|
|
HELP: <url>
|
|
{ $values { "url" url } }
|
|
{ $description "Creates an empty URL." } ;
|
|
|
|
HELP: >url
|
|
{ $values { "obj" object } { "url" url } }
|
|
{ $description "Converts an object into a URL. If the object is already a URL, does nothing; if it is a string, then it is parsed as a URL." }
|
|
{ $errors "Throws an error if the object is of the wrong type, or if it is a string which is not a valid URL." }
|
|
{ $examples
|
|
"If we convert a string to a URL and print it out again, it will print similarly to the input string, except some normalization may have occurred:"
|
|
{ $example
|
|
"USING: accessors prettyprint urls ;"
|
|
"\"http://www.apple.com\" >url ."
|
|
"URL\" http://www.apple.com/\""
|
|
}
|
|
"We can examine the URL object:"
|
|
{ $example
|
|
"USING: accessors io urls ;"
|
|
"\"http://www.apple.com\" >url host>> print"
|
|
"www.apple.com"
|
|
}
|
|
"A relative URL does not have a protocol, host or port:"
|
|
{ $example
|
|
"USING: accessors prettyprint urls ;"
|
|
"\"file.txt\" >url protocol>> ."
|
|
"f"
|
|
}
|
|
} ;
|
|
|
|
HELP: URL"
|
|
{ $syntax "URL\" url...\"" }
|
|
{ $description "URL literal syntax." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: accessors prettyprint urls ;"
|
|
"URL\" http://factorcode.org:80\" port>> ."
|
|
"80"
|
|
}
|
|
} ;
|
|
|
|
HELP: derive-url
|
|
{ $values { "base" url } { "url" url } { "url'" url } }
|
|
{ $description "Builds a URL by filling in missing components of " { $snippet "url" } " from " { $snippet "base" } "." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: prettyprint urls ;"
|
|
"URL\" http://factorcode.org\""
|
|
"URL\" binaries.fhtml\" derive-url ."
|
|
"URL\" http://factorcode.org/binaries.fhtml\""
|
|
}
|
|
{ $example
|
|
"USING: prettyprint urls ;"
|
|
"URL\" http://www.truecasey.com/drinks/kombucha\""
|
|
"URL\" master-cleanser\" derive-url ."
|
|
"URL\" http://www.truecasey.com/drinks/master-cleanser\""
|
|
}
|
|
} ;
|
|
|
|
HELP: ensure-port
|
|
{ $values { "url" url } }
|
|
{ $description "If the URL does not specify a port number, fill in the default for the URL's protocol. If the protocol is unknown, the port number is not changed." }
|
|
{ $side-effects "url" }
|
|
{ $examples
|
|
{ $example
|
|
"USING: accessors prettyprint urls ;"
|
|
"URL\" https://concatenative.org\" ensure-port port>> ."
|
|
"443"
|
|
}
|
|
} ;
|
|
|
|
HELP: parse-host
|
|
{ $values { "string" string } { "host" string } { "port" { $maybe integer } } }
|
|
{ $description "Splits a string of the form " { $snippet "host:port" } " into a host and a port number. If the port number is not specified, outputs " { $link f } "." }
|
|
{ $notes "This word is used by " { $link >url } ". It can also be used directly to parse " { $snippet "host:port" } " strings which are not full URLs." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: prettyprint urls kernel ;"
|
|
"\"sbcl.org:80\" parse-host .s 2drop"
|
|
"\"sbcl.org\"\n80"
|
|
}
|
|
} ;
|
|
|
|
HELP: protocol-port
|
|
{ $values { "protocol" "a protocol string" } { "port" { $maybe integer } } }
|
|
{ $description "Outputs the port number associated with a protocol, or " { $link f } " if the protocol is unknown." } ;
|
|
|
|
HELP: query-param
|
|
{ $values
|
|
{ "url" url } { "key" string }
|
|
{ "value" { $maybe string } } }
|
|
{ $description "Outputs the URL-decoded value of a URL query parameter." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: io urls ;"
|
|
"URL\" http://food.com/calories?item=French+Fries\""
|
|
"\"item\" query-param print"
|
|
"French Fries"
|
|
}
|
|
} ;
|
|
|
|
HELP: set-query-param
|
|
{ $values { "url" url } { "value" object } { "key" string } }
|
|
{ $description "Sets a query parameter. The value can be any object supported by " { $link present } ", or " { $link f } ", in which case the key is removed." }
|
|
{ $notes "This word always returns the same URL object that was input. This allows for a ``pipeline'' coding style, where several query parameters are set in a row. Since it mutates the input object, you must " { $link clone } " it first if it is literal, as in the below example."
|
|
}
|
|
{ $examples
|
|
{ $code
|
|
<" USING: kernel http.client urls ;
|
|
URL" http://search.yahooapis.com/WebSearchService/V1/webSearch" clone
|
|
"concatenative programming (NSFW)" "query" set-query-param
|
|
"1" "adult_ok" set-query-param
|
|
http-get">
|
|
}
|
|
"(For a complete Yahoo! search web service implementation, see the " { $vocab-link "yahoo" } " vocabulary.)"
|
|
}
|
|
{ $side-effects "url" } ;
|
|
|
|
HELP: relative-url
|
|
{ $values { "url" url } { "url'" url } }
|
|
{ $description "Outputs a new URL with the same path and query components as the input value, but with the protocol, host and port set to " { $link f } "." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: prettyprint urls ;"
|
|
"URL\" http://factorcode.org/binaries.fhtml\""
|
|
"relative-url ."
|
|
"URL\" /binaries.fhtml\""
|
|
}
|
|
} ;
|
|
|
|
HELP: relative-url?
|
|
{ $values
|
|
{ "url" url }
|
|
{ "?" "a boolean" } }
|
|
{ $description "Tests whether a URL is relative." } ;
|
|
|
|
HELP: secure-protocol?
|
|
{ $values { "protocol" string } { "?" "a boolean" } }
|
|
{ $description "Tests if protocol connections must be made with secure sockets (SSL/TLS)." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: prettyprint urls ;"
|
|
"\"https\" secure-protocol? ."
|
|
"t"
|
|
}
|
|
} ;
|
|
|
|
HELP: url-addr
|
|
{ $values { "url" url } { "addr" "an address specifier" } }
|
|
{ $description "Outputs an address specifier for use with " { $link "network-connection" } "." }
|
|
{ $examples
|
|
{ $example
|
|
"USING: prettyprint urls ;"
|
|
"URL\" ftp://ftp.cdrom.com\" url-addr ."
|
|
"T{ inet { host \"ftp.cdrom.com\" } { port 21 } }"
|
|
}
|
|
} ;
|
|
|
|
HELP: url-append-path
|
|
{ $values { "path1" string } { "path2" string } { "path" string } }
|
|
{ $description "Like " { $link append-path } ", but intended for use with URL paths and not filesystem paths." } ;
|
|
|
|
ARTICLE: "url-utilities" "URL implementation utilities"
|
|
{ $subsection parse-host }
|
|
{ $subsection secure-protocol? }
|
|
{ $subsection url-append-path } ;
|
|
|
|
ARTICLE: "urls" "URL objects"
|
|
"The " { $vocab-link "urls" } " vocabulary implements a URL data type. The benefit of using a data type to prepresent URLs rather than a string is that the parsing, printing and escaping logic is encapsulated and reused, rather than re-implemented in a potentially buggy manner every time."
|
|
$nl
|
|
"URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
|
|
$nl
|
|
"The class of URLs, and a constructor:"
|
|
{ $subsection url }
|
|
{ $subsection <url> }
|
|
"Converting strings to URLs:"
|
|
{ $subsection >url }
|
|
"URLs can be converted back to strings using the " { $link present } " word."
|
|
$nl
|
|
"URL literal syntax:"
|
|
{ $subsection POSTPONE: URL" }
|
|
"Manipulating URLs:"
|
|
{ $subsection derive-url }
|
|
{ $subsection relative-url }
|
|
{ $subsection ensure-port }
|
|
{ $subsection query-param }
|
|
{ $subsection set-query-param }
|
|
"Creating " { $link "network-addressing" } " from URLs:"
|
|
{ $subsection url-addr }
|
|
"The URL implemention encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
|
|
{ $subsection "url-encoding" }
|
|
"Utility words used by the URL implementation:"
|
|
{ $subsection "url-utilities" } ;
|
|
|
|
ABOUT: "urls"
|