extra/s3/s3-docs.factor

   1 ! Copyright (C) 2009 Chris Double.\r
   2 ! See http://factorcode.org/license.txt for BSD license.\r
   3 USING: assocs help.markup help.syntax kernel strings ;\r
   4 IN: s3\r
   5 \r
   6 HELP: buckets\r
   7 { $values \r
   8   { "seq" "a sequence of " { $link bucket } " objects" } \r
   9 }\r
  10 { $description \r
  11     "Returns a list of " { $link bucket } " objects containing data on the buckets available on S3."}\r
  12 { $examples\r
  13   { $unchecked-example "USING: s3 ;" "buckets ." "{ }" }\r
  14 }\r
  15 ;\r
  16 \r
  17 HELP: create-bucket\r
  18 { $values \r
  19   { "bucket" string } \r
  20 }\r
  21 { $description \r
  22     "Creates a bucket with the given name."\r
  23 } \r
  24 { $examples\r
  25   { $unchecked-example "USING: s3 ;" "\"testbucket\" create-bucket" "" }\r
  26 }\r
  27 ;\r
  28 \r
  29 HELP: delete-bucket\r
  30 { $values \r
  31   { "bucket" string } \r
  32 }\r
  33 { $description \r
  34     "Deletes the bucket with the given name."\r
  35 } \r
  36 { $examples\r
  37   { $unchecked-example "USING: s3 ;" "\"testbucket\" delete-bucket" "" }\r
  38 }\r
  39 ;\r
  40 \r
  41 HELP: keys\r
  42 { $values \r
  43   { "bucket" string } \r
  44   { "seq" "a sequence of " { $link key } " objects"} \r
  45 }\r
  46 { $description \r
  47     "Returns a sequence of " { $link key } " objects. Each object in the sequence has information about the keys contained within the bucket."\r
  48 } \r
  49 { $examples\r
  50   { $unchecked-example "USING: s3 ;" "\"testbucket\" keys . " "{ }" }\r
  51 }\r
  52 ;\r
  53 \r
  54 HELP: get-object\r
  55 { $values \r
  56   { "bucket" string }\r
  57   { "key" string }\r
  58   { "response" "The HTTP response object"}\r
  59   { "data" "The data returned from the http request"}\r
  60 }\r
  61 { $description \r
  62     "Does an HTTP request to retrieve the object in the bucket with the given key."\r
  63 } \r
  64 { $examples\r
  65   { $unchecked-example "USING: s3 ;" "\"testbucket\" \"mykey\" http-get " "" }\r
  66 }\r
  67 ;\r
  68 \r
  69 HELP: put-object\r
  70 { $values\r
  71   { "data" object }\r
  72   { "mime-type" string }\r
  73   { "bucket" string }\r
  74   { "key" string }\r
  75   { "headers" assoc }\r
  76 }\r
  77 { $description \r
  78     "Stores the object under the key in the given bucket. The object has "\r
  79 "the given mimetype. 'headers' should contain key/values for any headers to "\r
  80 "be associated with the object. 'data' is any Factor object that can be "\r
  81 "used as the 'data' slot in <post-data>. If it's a <pathname> it stores "\r
  82 "the contents of the file. If it's a stream, it's the contents of the "\r
  83 "stream, etc."\r
  84 } \r
  85 { $examples\r
  86   { $unchecked-example "USING: s3 ;" "\"hello\" binary encode \"text/plain\" \"testbucket\" \"hello.txt\" H{ { \"x-amz-acl\" \"public-read\" } } put-object" "" }\r
  87   { $unchecked-example "USING: s3 ;" "\"hello.txt\" <pathname> \"text/plain\" \"testbucket\" \"hello.txt\" H{ { \"x-amz-acl\" \"public-read\" } } put-object" "" }\r
  88 }\r
  89 ;\r
  90 \r
  91 HELP: delete-object\r
  92 { $values \r
  93   { "bucket" string }\r
  94   { "key" string }\r
  95 }\r
  96 { $description \r
  97     "Deletes the object in the bucket with the given key."\r
  98 } \r
  99 { $examples\r
 100   { $unchecked-example "USING: s3 ;" "\"testbucket\" \"mykey\" delete-object" "" }\r
 101 }\r
 102 ;\r
 103 \r
 104 ARTICLE: "s3" "Amazon S3"\r
 105 "The " { $vocab-link "s3" } " vocabulary provides a wrapper to the Amazon "\r
 106 "Simple Storage Service API."\r
 107 $nl\r
 108 "To use the api you must set the variables " { $link key-id } " and " \r
 109 { $link secret-key } " to your Amazon S3 key and secret key respectively. Once "\r
 110 "this is done you can call any of the words below."\r
 111 { $subsections buckets\r
 112     create-bucket\r
 113     delete-bucket\r
 114     keys\r
 115     get-object\r
 116     put-object\r
 117     delete-object\r
 118 }\r
 119 ;\r
 120 \r
 121 ABOUT: "s3"\r