Documentation updates
Slava Pestov
parent
b4137bd5fe
commit
d64808b5d0
|
|
@ -0,0 +1,13 @@
|
|||
IN: present
|
||||
USING: help.markup help.syntax kernel strings ;
|
||||
|
||||
ARTICLE: "present" "Converting objects to human-readable strings"
|
||||
"A word for converting an object into a human-readable string:"
|
||||
{ $subsection present } ;
|
||||
|
||||
HELP: present
|
||||
{ $values { "object" object } { "string" string } }
|
||||
{ $contract "Outputs a human-readable string from an object." }
|
||||
{ $notes "New methods can be defined by user code. Most often, this is done so that the object can be used with various words in the " { $link "html.components" } " or " { $link "urls" } " vocabularies." } ;
|
||||
|
||||
ABOUT: "present"
|
||||
|
|
@ -1,12 +1,13 @@
|
|||
IN: summary
|
||||
USING: kernel strings help.markup help.syntax ;
|
||||
|
||||
ARTICLE: "summary" "Summary"
|
||||
ARTICLE: "summary" "Converting objects to summary strings"
|
||||
"A word for getting very brief descriptions of words and general objects:"
|
||||
{ $subsection summary } ;
|
||||
|
||||
HELP: summary
|
||||
{ $values { "object" object } { "string" string } }
|
||||
{ $contract "Outputs a brief description of the object." } ;
|
||||
{ $contract "Outputs a brief description of the object." }
|
||||
{ $notes "New methods can be defined by user code. Most often, this is used with error classes so that " { $link "debugger" } " can print friendlier error messages." } ;
|
||||
|
||||
ABOUT: "summary"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,248 @@
|
|||
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 io urls ;"
|
||||
"\"http://www.apple.com\" >url ."
|
||||
"URL\" 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 or host component:"
|
||||
{ $example
|
||||
"USING: accessors io 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
|
||||
{ "hash" hashtable }
|
||||
{ "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
|
||||
"{ { \"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/kamboocha\""
|
||||
"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"
|
||||
|
|
@ -8,8 +8,6 @@ strings.parser lexer prettyprint.backend hashtables present ;
|
|||
IN: urls
|
||||
|
||||
: url-quotable? ( ch -- ? )
|
||||
#! In a URL, can this character be used without
|
||||
#! URL-encoding?
|
||||
{
|
||||
[ letter? ]
|
||||
[ LETTER? ]
|
||||
|
|
@ -20,8 +18,10 @@ IN: urls
|
|||
<PRIVATE
|
||||
|
||||
: push-utf8 ( ch -- )
|
||||
1string utf8 encode
|
||||
[ CHAR: % , >hex 2 CHAR: 0 pad-left % ] each ;
|
||||
dup CHAR: \s = [ drop "+" % ] [
|
||||
1string utf8 encode
|
||||
[ CHAR: % , >hex 2 CHAR: 0 pad-left % ] each
|
||||
] if ;
|
||||
|
||||
PRIVATE>
|
||||
|
||||
|
|
@ -86,7 +86,7 @@ PRIVATE>
|
|||
] keep
|
||||
] when ;
|
||||
|
||||
: assoc>query ( hash -- str )
|
||||
: assoc>query ( assoc -- str )
|
||||
[
|
||||
dup array? [ [ present ] map ] [ present 1array ] if
|
||||
] assoc-map
|
||||
|
|
@ -152,7 +152,6 @@ M: string >url
|
|||
{
|
||||
{ "http" [ 80 ] }
|
||||
{ "https" [ 443 ] }
|
||||
{ "feed" [ 80 ] }
|
||||
{ "ftp" [ 21 ] }
|
||||
[ drop f ]
|
||||
} case ;
|
||||
|
|
@ -168,8 +167,6 @@ M: string >url
|
|||
[ port>> ] [ port>> ] [ protocol>> protocol-port ] tri =
|
||||
[ drop f ] when ;
|
||||
|
||||
PRIVATE>
|
||||
|
||||
: unparse-host-part ( url protocol -- )
|
||||
%
|
||||
"://" %
|
||||
|
|
@ -180,6 +177,8 @@ PRIVATE>
|
|||
[ path>> "/" head? [ "/" % ] unless ]
|
||||
} cleave ;
|
||||
|
||||
PRIVATE>
|
||||
|
||||
M: url present
|
||||
[
|
||||
{
|
||||
|
|
@ -224,10 +223,15 @@ PRIVATE>
|
|||
"https" = ;
|
||||
|
||||
: url-addr ( url -- addr )
|
||||
[ [ host>> ] [ port>> ] bi <inet> ] [ protocol>> ] bi
|
||||
[
|
||||
[ host>> ]
|
||||
[ port>> ]
|
||||
[ protocol>> protocol-port ]
|
||||
tri or <inet>
|
||||
] [ protocol>> ] bi
|
||||
secure-protocol? [ <secure> ] when ;
|
||||
|
||||
: ensure-port ( url -- url' )
|
||||
: ensure-port ( url -- url )
|
||||
dup protocol>> '[ _ protocol-port or ] change-port ;
|
||||
|
||||
! Literal syntax
|
||||
|
|
|
|||
Loading…
Reference in New Issue