basis/urls/urls-docs.factor

   1 USING: assocs hashtables help.markup help.syntax
   2 io.streams.string io.files kernel strings present math multiline
   3 ;
   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 } }
  69 { $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." }
  70 { $side-effects "url" }
  71 { $examples
  72     { $example
  73         "USING: accessors prettyprint urls ;"
  74         "URL\" https://concatenative.org\" ensure-port port>> ."
  75         "443"
  76     }
  77 } ;
  78
  79 HELP: parse-host
  80 { $values { "string" string } { "host" string } { "port" { $maybe integer } } }
  81 { $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 } "." }
  82 { $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." }
  83 { $examples
  84     { $example
  85         "USING: prettyprint urls ;"
  86         "\"sbcl.org:80\" parse-host .s"
  87         "\"sbcl.org\"\n80"
  88     }
  89 } ;
  90
  91 HELP: protocol-port
  92 { $values { "protocol" "a protocol string" } { "port" { $maybe integer } } }
  93 { $description "Outputs the port number associated with a protocol, or " { $link f } " if the protocol is unknown." } ;
  94
  95 HELP: query-param
  96 { $values
  97      { "url" url } { "key" string }
  98     { "value" { $maybe string } } }
  99 { $description "Outputs the URL-decoded value of a URL query parameter." }
 100 { $examples
 101     { $example
 102         "USING: io urls ;"
 103         "URL\" http://food.com/calories?item=French+Fries\""
 104         "\"item\" query-param print"
 105         "French Fries"
 106     }
 107 } ;
 108
 109 HELP: set-query-param
 110 { $values { "url" url } { "value" object } { "key" string } }
 111 { $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." }
 112 { $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."
 113 }
 114 { $examples
 115     { $code
 116         <" USING: kernel http.client urls ;
 117 URL" http://search.yahooapis.com/WebSearchService/V1/webSearch" clone
 118     "concatenative programming (NSFW)" "query" set-query-param
 119     "1" "adult_ok" set-query-param
 120 http-get">
 121     }
 122     "(For a complete Yahoo! search web service implementation, see the " { $vocab-link "yahoo" } " vocabulary.)"
 123 }
 124 { $side-effects "url" } ;
 125
 126 HELP: relative-url
 127 { $values { "url" url } { "url'" url } }
 128 { $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 } "." }
 129 { $examples
 130     { $example
 131         "USING: prettyprint urls ;"
 132         "URL\" http://factorcode.org/binaries.fhtml\""
 133         "relative-url ."
 134         "URL\" /binaries.fhtml\""
 135     }
 136 } ;
 137
 138 HELP: relative-url?
 139 { $values
 140      { "url" url }
 141      { "?" "a boolean" } }
 142 { $description "Tests whether a URL is relative." } ;
 143
 144 HELP: secure-protocol?
 145 { $values { "protocol" string } { "?" "a boolean" } }
 146 { $description "Tests if protocol connections must be made with secure sockets (SSL/TLS)." }
 147 { $examples
 148     { $example
 149         "USING: prettyprint urls ;"
 150         "\"https\" secure-protocol? ."
 151         "t"
 152     }
 153 } ;
 154
 155 HELP: url-addr
 156 { $values { "url" url } { "addr" "an address specifier" } }
 157 { $description "Outputs an address specifier for use with " { $link "network-connection" } "." }
 158 { $examples
 159     { $example
 160         "USING: prettyprint urls ;"
 161         "URL\" ftp://ftp.cdrom.com\" url-addr ."
 162         "T{ inet { host \"ftp.cdrom.com\" } { port 21 } }"
 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 { $subsection parse-host }
 172 { $subsection secure-protocol? }
 173 { $subsection url-append-path } ;
 174
 175 ARTICLE: "urls" "URL objects"
 176 "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."
 177 $nl
 178 "URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
 179 $nl
 180 "The class of URLs, and a constructor:"
 181 { $subsection url }
 182 { $subsection <url> }
 183 "Converting strings to URLs:"
 184 { $subsection >url }
 185 "URLs can be converted back to strings using the " { $link present } " word."
 186 $nl
 187 "URL literal syntax:"
 188 { $subsection POSTPONE: URL" }
 189 "Manipulating URLs:"
 190 { $subsection derive-url }
 191 { $subsection relative-url }
 192 { $subsection ensure-port }
 193 { $subsection query-param }
 194 { $subsection set-query-param }
 195 "Creating " { $link "network-addressing" } " from URLs:"
 196 { $subsection url-addr }
 197 "The URL implemention encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
 198 { $subsection "url-encoding" }
 199 "Utility words used by the URL implementation:"
 200 { $subsection "url-utilities" } ;
 201
 202 ABOUT: "urls"