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, 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" } { "?" "a 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 { $subsection url-encode }
  54 { $subsection url-decode }
  55 { $subsection url-quotable? }
  56 "Encoding and decoding queries:"
  57 { $subsection assoc>query }
  58 { $subsection query>assoc }
  59 "See " { $url "http://en.wikipedia.org/wiki/Percent-encoding" } " for a description of URL encoding." ;
  60
  61 ABOUT: "url-encoding"