extra/s3/s3-docs.factor

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