basis/urls/encoding/encoding-docs.factor

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