basis/urls/urls-docs.factor

   1 USING: assocs hashtables help.markup help.syntax
   2 io.streams.string io.files io.pathnames kernel strings present
   3 math ;
   4 IN: urls
   5
   6 HELP: url
   7 { $class-description "The class of URLs. The slots correspond to the standard components of a URL." } ;
   8
   9 HELP: <url>
  10 { $values { "url" url } }
  11 { $description "Creates an empty URL." } ;
  12
  13 HELP: >url
  14 { $values { "obj" object } { "url" url } }
  15 { $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." }
  16 { $errors "Throws an error if the object is of the wrong type, or if it is a string which is not a valid URL." }
  17 { $examples
  18     "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:"
  19     { $example
  20         "USING: accessors prettyprint urls ;"
  21         "\"http://www.apple.com\" >url ."
  22         "URL\" http://www.apple.com/\""
  23     }
  24     "We can examine the URL object:"
  25     { $example
  26         "USING: accessors io urls ;"
  27         "\"http://www.apple.com\" >url host>> print"
  28         "www.apple.com"
  29     }
  30     "A relative URL does not have a protocol, host or port:"
  31     { $example
  32         "USING: accessors prettyprint urls ;"
  33         "\"file.txt\" >url protocol>> ."
  34         "f"
  35     }
  36 } ;
  37
  38 HELP: URL"
  39 { $syntax "URL\" url...\"" }
  40 { $description "URL literal syntax." }
  41 { $examples
  42     { $example
  43         "USING: accessors prettyprint urls ;"
  44         "URL\" http://factorcode.org:80\" port>> ."
  45         "80"
  46     }
  47 } ;
  48
  49 HELP: derive-url
  50 { $values { "base" url } { "url" url } { "url'" url } }
  51 { $description "Builds a URL by filling in missing components of " { $snippet "url" } " from " { $snippet "base" } "." }
  52 { $examples
  53     { $example
  54         "USING: prettyprint urls ;"
  55         "URL\" http://factorcode.org\""
  56         "URL\" binaries.fhtml\" derive-url ."
  57         "URL\" http://factorcode.org/binaries.fhtml\""
  58     }
  59     { $example
  60         "USING: prettyprint urls ;"
  61         "URL\" http://www.truecasey.com/drinks/kombucha\""
  62         "URL\" master-cleanser\" derive-url ."
  63         "URL\" http://www.truecasey.com/drinks/master-cleanser\""
  64     }
  65 } ;
  66
  67 HELP: ensure-port
  68 { $values { "url" url } { "url'" url } }
  69 { $description "If the URL does not specify a port number, create a new URL which is equal except the port number is set to the default for the URL's protocol. If the protocol is unknown, outputs an exact copy of the input URL." }
  70 { $examples
  71     { $example
  72         "USING: accessors prettyprint urls ;"
  73         "URL\" https://concatenative.org\" ensure-port port>> ."
  74         "443"
  75     }
  76 } ;
  77
  78 HELP: parse-host
  79 { $values { "string" string } { "host" string } { "port" { $maybe integer } } }
  80 { $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 } "." }
  81 { $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." }
  82 { $examples
  83     { $example
  84         "USING: arrays kernel prettyprint urls ;"
  85         "\"sbcl.org:80\" parse-host 2array ."
  86         "{ \"sbcl.org\" 80 }"
  87     }
  88 } ;
  89
  90 HELP: protocol-port
  91 { $values { "protocol" "a protocol string" } { "port" { $maybe integer } } }
  92 { $description "Outputs the port number associated with a protocol, or " { $link f } " if the protocol is unknown." } ;
  93
  94 HELP: query-param
  95 { $values
  96      { "url" url } { "key" string }
  97     { "value" { $maybe string } } }
  98 { $description "Outputs the URL-decoded value of a URL query parameter." }
  99 { $examples
 100     { $example
 101         "USING: io urls ;"
 102         "URL\" http://food.com/calories?item=French+Fries\""
 103         "\"item\" query-param print"
 104         "French Fries"
 105     }
 106 } ;
 107
 108 HELP: set-query-param
 109 { $values { "url" url } { "value" object } { "key" string } }
 110 { $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." }
 111 { $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."
 112 }
 113 { $examples
 114     { $code
 115         """USING: kernel http.client urls ;
 116 URL" http://search.yahooapis.com/WebSearchService/V1/webSearch" clone
 117     "concatenative programming (NSFW)" "query" set-query-param
 118     "1" "adult_ok" set-query-param
 119 http-get"""
 120     }
 121     "(For a complete Yahoo! search web service implementation, see the " { $vocab-link "yahoo" } " vocabulary.)"
 122 }
 123 { $side-effects "url" } ;
 124
 125 HELP: relative-url
 126 { $values { "url" url } { "url'" url } }
 127 { $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 } "." }
 128 { $examples
 129     { $example
 130         "USING: prettyprint urls ;"
 131         "URL\" http://factorcode.org/binaries.fhtml\""
 132         "relative-url ."
 133         "URL\" /binaries.fhtml\""
 134     }
 135 } ;
 136
 137 HELP: relative-url?
 138 { $values
 139      { "url" url }
 140      { "?" "a boolean" } }
 141 { $description "Tests whether a URL is relative." } ;
 142
 143 HELP: secure-protocol?
 144 { $values { "protocol" string } { "?" "a boolean" } }
 145 { $description "Tests if protocol connections must be made with secure sockets (SSL/TLS)." }
 146 { $examples
 147     { $example
 148         "USING: prettyprint urls ;"
 149         "\"https\" secure-protocol? ."
 150         "t"
 151     }
 152 } ;
 153
 154 HELP: url-addr
 155 { $values { "url" url } { "addr" "an address specifier" } }
 156 { $description "Outputs an address specifier for use with " { $link "network-connection" } "." }
 157 { $examples
 158     { $example
 159         "USING: prettyprint urls ;"
 160         "URL\" ftp://ftp.cdrom.com\" url-addr ."
 161         "T{ inet { host \"ftp.cdrom.com\" } { port 21 } }"
 162     }
 163 } ;
 164
 165 HELP: url-append-path
 166 { $values { "path1" string } { "path2" string } { "path" string } }
 167 { $description "Like " { $link append-path } ", but intended for use with URL paths and not filesystem paths." } ;
 168
 169 ARTICLE: "url-utilities" "URL implementation utilities"
 170 { $subsections
 171     parse-host
 172     secure-protocol?
 173     url-append-path
 174 } ;
 175
 176 ARTICLE: "urls" "URL objects"
 177 "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."
 178 $nl
 179 "URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
 180 $nl
 181 "The class of URLs, and a constructor:"
 182 { $subsections
 183     url
 184     <url>
 185 }
 186 "Converting strings to URLs:"
 187 { $subsections >url }
 188 "URLs can be converted back to strings using the " { $link present } " word."
 189 $nl
 190 "URL literal syntax:"
 191 { $subsections POSTPONE: URL" }
 192 "Manipulating URLs:"
 193 { $subsections
 194     derive-url
 195     relative-url
 196     ensure-port
 197     query-param
 198     set-query-param
 199 }
 200 "Creating " { $link "network-addressing" } " from URLs:"
 201 { $subsections url-addr }
 202 "The URL implemention encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
 203 { $subsections "url-encoding" }
 204 "Utility words used by the URL implementation:"
 205 { $subsections "url-utilities" } ;
 206
 207 ABOUT: "urls"