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/f" { $maybe string } } { "port/f" { $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: query-param
  91 { $values
  92     { "url" url } { "key" string }
  93     { "value" { $maybe string } } }
  94 { $description "Outputs the URL-decoded value of a URL query parameter." }
  95 { $examples
  96     { $example
  97         "USING: io urls ;"
  98         "URL\" http://food.com/calories?item=French+Fries\""
  99         "\"item\" query-param print"
 100         "French Fries"
 101     }
 102 } ;
 103
 104 HELP: set-query-param
 105 { $values { "url" url } { "value" object } { "key" string } }
 106 { $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." }
 107 { $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."
 108 }
 109 { $examples
 110     { $code
 111         "USING: kernel http.client urls ;
 112 URL\" http://search.yahooapis.com/WebSearchService/V1/webSearch\" clone
 113     \"concatenative programming (NSFW)\" \"query\" set-query-param
 114     \"1\" \"adult_ok\" set-query-param
 115 http-get"
 116     }
 117     "(For a complete Yahoo! search web service implementation, see the " { $vocab-link "yahoo" } " vocabulary.)"
 118 }
 119 { $side-effects "url" } ;
 120
 121 HELP: relative-url
 122 { $values { "url" url } { "url'" url } }
 123 { $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 } "." }
 124 { $examples
 125     { $example
 126         "USING: prettyprint urls ;"
 127         "URL\" http://factorcode.org/binaries.fhtml\""
 128         "relative-url ."
 129         "URL\" /binaries.fhtml\""
 130     }
 131 } ;
 132
 133 HELP: relative-url?
 134 { $values
 135     { "url" url }
 136     { "?" boolean } }
 137 { $description "Tests whether a URL is relative." } ;
 138
 139 HELP: redacted-url
 140 { $values { "url" url } { "url'" url } }
 141 { $description "Outputs a new URL with the password (if specified) replaced with " { $snippet "xxxxx" } ". This is useful for logging utilities where you want to avoid printing out the password in the logs." } ;
 142
 143 HELP: secure-protocol?
 144 { $values { "protocol" string } { "?" 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     { $example
 164         "USING: io.sockets.secure prettyprint urls ;"
 165         "URL\" https://google.com/\" url-addr ."
 166         "T{ secure\n    { addrspec T{ inet { host \"google.com\" } { port 443 } } }\n    { hostname \"google.com\" }\n}"
 167     }
 168 } ;
 169
 170 HELP: url-append-path
 171 { $values { "path1" string } { "path2" string } { "path" string } }
 172 { $description "Like " { $link append-path } ", but intended for use with URL paths and not filesystem paths." } ;
 173
 174 ARTICLE: "url-utilities" "URL implementation utilities"
 175 { $subsections
 176     parse-host
 177     secure-protocol?
 178     url-append-path
 179 } ;
 180
 181 ARTICLE: "urls" "URL objects"
 182 "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."
 183 $nl
 184 "URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
 185 $nl
 186 "The class of URLs, and a constructor:"
 187 { $subsections
 188     url
 189     <url>
 190 }
 191 "Converting strings to URLs:"
 192 { $subsections >url }
 193 "URLs can be converted back to strings using the " { $link present } " word."
 194 $nl
 195 "URL literal syntax:"
 196 { $subsections POSTPONE: URL" }
 197 "Manipulating URLs:"
 198 { $subsections
 199     derive-url
 200     relative-url
 201     ensure-port
 202     query-param
 203     set-query-param
 204 }
 205 "Creating " { $link "network-addressing" } " from URLs:"
 206 { $subsections url-addr }
 207 "The URL implementation encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
 208 { $subsections "url-encoding" }
 209 "Utility words used by the URL implementation:"
 210 { $subsections "url-utilities" } ;
 211
 212 ABOUT: "urls"