/extra/s3/s3-docs.factor

  1! Copyright (C) 2009 Chris Double.
  2! See http://factorcode.org/license.txt for BSD license.
  3USING: help.markup help.syntax ;
  4IN: s3
  5
  6HELP: 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
 17HELP: create-bucket
 18{ $values 
 19  { "bucket" "a 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
 29HELP: delete-bucket
 30{ $values 
 31  { "bucket" "a 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
 41HELP: keys
 42{ $values 
 43  { "bucket" "a 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
 54HELP: get-object
 55{ $values 
 56  { "bucket" "a string" } 
 57  { "key" "a 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
 69HELP: put-object
 70{ $values 
 71  { "data" "an object" } 
 72  { "mime-type" "a string" } 
 73  { "bucket" "a string"} 
 74  { "key" "a string"} 
 75  { "headers" "an 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
 91HELP: delete-object
 92{ $values 
 93  { "bucket" "a string"} 
 94  { "key" "a 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
104ARTICLE: "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
121ABOUT: "s3"