factor/basis/urls/urls-docs.factor

USING: assocs hashtables help.markup help.syntax
io.streams.string io.files 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: assoc>query
{ $values { "assoc" assoc } { "str" string } }
{ $description "Converts an assoc of query parameters into a query string, performing URL encoding." }
{ $notes "This word is used to implement the " { $link present } " method on URLs; it is also used by the HTTP client to encode POST requests." }
{ $examples
    { $example
        "USING: io urls ;"
        "{ { \"from\" \"Lead\" } { \"to\" \"Gold, please\" } }"
        "assoc>query print"
        "from=Lead&to=Gold%2c+please"
    }
} ;

HELP: query>assoc
{ $values { "query" string } { "assoc" assoc } }
{ $description "Parses a URL query string and URL-decodes each component." }
{ $notes "This word is used to implement " { $link >url } ". It is also used by the HTTP server to parse POST requests." }
{ $examples
    { $unchecked-example
        "USING: prettyprint urls ;"
        "\"gender=female&agefrom=22&ageto=28&location=Omaha+NE\""
        "query>assoc ."
        <" H{
    { "gender" "female" }
    { "agefrom" "22" }
    { "ageto" "28" }
    { "location" "Omaha NE" }
}">
    }
} ;

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" "an " { $link integer } " or " { $link f } } }
{ $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 ;"
        "\"sbcl.org:80\" parse-host .s"
        "\"sbcl.org\"\n80"
    }
} ;

HELP: protocol-port
{ $values { "protocol" "a protocol string" } { "port" "an " { $link integer } " or " { $link f } } }
{ $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" "a " { $link string } " or " { $link f } } }
{ $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: 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." } ;

HELP: url-decode
{ $values { "str" string } { "decoded" string } }
{ $description "Decodes a URL-encoded string." } ;

HELP: url-encode
{ $values { "str" string } { "encoded" string } }
{ $description "URL-encodes a string." } ;

HELP: url-quotable?
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests if a character be used without URL-encoding in a URL." } ;

ARTICLE: "url-encoding" "URL encoding and decoding"
"URL encoding and decoding strings:"
{ $subsection url-encode }
{ $subsection url-decode }
{ $subsection url-quotable? }
"The URL implemention encodes and decodes components of " { $link url } " instances automatically, but sometimes it is required for non-URL strings. See " { $url "http://en.wikipedia.org/wiki/Percent-encoding" } " for a description of URL encoding." ;

ARTICLE: "url-utilities" "URL implementation utilities"
{ $subsection assoc>query }
{ $subsection query>assoc }
{ $subsection parse-host }
{ $subsection secure-protocol? }
{ $subsection url-append-path } ;

ARTICLE: "urls" "URLs"
"The " { $vocab-link "urls" } " 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 }
"Additional topics:"
{ $subsection "url-utilities" }
{ $subsection "url-encoding" } ;

ABOUT: "urls"