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: secure-protocol?
 140 { $values { "protocol" string } { "?" boolean } }
 141 { $description "Tests if protocol connections must be made with secure sockets (SSL/TLS)." }
 142 { $examples
 143     { $example
 144         "USING: prettyprint urls ;"
 145         "\"https\" secure-protocol? ."
 146         "t"
 147     }
 148 } ;
 149
 150 HELP: url-addr
 151 { $values { "url" url } { "addr" "an address specifier" } }
 152 { $description "Outputs an address specifier for use with " { $link "network-connection" } "." }
 153 { $examples
 154     { $example
 155         "USING: prettyprint urls ;"
 156         "URL\" ftp://ftp.cdrom.com\" url-addr ."
 157         "T{ inet { host \"ftp.cdrom.com\" } { port 21 } }"
 158     }
 159     { $example
 160         "USING: io.sockets.secure prettyprint urls ;"
 161         "URL\" https://google.com/\" url-addr ."
 162         "T{ secure\n    { addrspec T{ inet { host \"google.com\" } { port 443 } } }\n}"
 163     }
 164 } ;
 165
 166 HELP: url-append-path
 167 { $values { "path1" string } { "path2" string } { "path" string } }
 168 { $description "Like " { $link append-path } ", but intended for use with URL paths and not filesystem paths." } ;
 169
 170 ARTICLE: "url-utilities" "URL implementation utilities"
 171 { $subsections
 172     parse-host
 173     secure-protocol?
 174     url-append-path
 175 } ;
 176
 177 ARTICLE: "urls" "URL objects"
 178 "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."
 179 $nl
 180 "URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
 181 $nl
 182 "The class of URLs, and a constructor:"
 183 { $subsections
 184     url
 185     <url>
 186 }
 187 "Converting strings to URLs:"
 188 { $subsections >url }
 189 "URLs can be converted back to strings using the " { $link present } " word."
 190 $nl
 191 "URL literal syntax:"
 192 { $subsections POSTPONE: URL" }
 193 "Manipulating URLs:"
 194 { $subsections
 195     derive-url
 196     relative-url
 197     ensure-port
 198     query-param
 199     set-query-param
 200 }
 201 "Creating " { $link "network-addressing" } " from URLs:"
 202 { $subsections url-addr }
 203 "The URL implementation encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
 204 { $subsections "url-encoding" }
 205 "Utility words used by the URL implementation:"
 206 { $subsections "url-utilities" } ;
 207
 208 ABOUT: "urls"