basis/urls/encoding/encoding-docs.factor

   1 IN: urls.encoding
   2 USING: strings help.markup help.syntax assocs multiline ;
   3
   4 HELP: url-decode
   5 { $values { "str" string } { "decoded" string } }
   6 { $description "Decodes a URL-encoded string." } ;
   7
   8 HELP: url-encode
   9 { $values { "str" string } { "encoded" string } }
  10 { $description "URL-encodes a string." } ;
  11
  12 HELP: url-quotable?
  13 { $values { "ch" "a character" } { "?" "a boolean" } }
  14 { $description "Tests if a character be used without URL-encoding in a URL." } ;
  15
  16 HELP: assoc>query
  17 { $values { "assoc" assoc } { "str" string } }
  18 { $description "Converts an assoc of query parameters into a query string, performing URL encoding." }
  19 { $notes "This word is used by the implementation of " { $link "urls" } ". It is also used by the HTTP client to encode POST requests." }
  20 { $examples
  21     { $example
  22         "USING: io urls.encoding ;"
  23         "{ { \"from\" \"Lead\" } { \"to\" \"Gold, please\" } }"
  24         "assoc>query print"
  25         "from=Lead&to=Gold%2c%20please"
  26     }
  27 } ;
  28
  29 HELP: query>assoc
  30 { $values { "query" string } { "assoc" assoc } }
  31 { $description "Parses a URL query string and URL-decodes each component." }
  32 { $notes "This word is used by the implementation of " { $link "urls" } ". It is also used by the HTTP server to parse POST requests." }
  33 { $examples
  34     { $unchecked-example
  35         "USING: prettyprint urls.encoding ;"
  36         "\"gender=female&agefrom=22&ageto=28&location=Omaha+NE\""
  37         "query>assoc ."
  38         <" H{
  39     { "gender" "female" }
  40     { "agefrom" "22" }
  41     { "ageto" "28" }
  42     { "location" "Omaha NE" }
  43 }">
  44     }
  45 } ;
  46
  47 ARTICLE: "url-encoding" "URL encoding and decoding"
  48 "URL encoding and decoding strings:"
  49 { $subsection url-encode }
  50 { $subsection url-decode }
  51 { $subsection url-quotable? }
  52 "Encoding and decoding queries:"
  53 { $subsection assoc>query }
  54 { $subsection query>assoc }
  55 "See " { $url "http://en.wikipedia.org/wiki/Percent-encoding" } " for a description of URL encoding." ;
  56
  57 ABOUT: "url-encoding"