Add S3 docs

[factor.git] / extra / s3 / s3-docs.factor

diff --git a/extra/s3/s3-docs.factor b/extra/s3/s3-docs.factor
new file mode 100644 (file)
index 0000000..dda3e7f
--- /dev/null
+++ b/extra/s3/s3-docs.factor
@@ -0,0 +1,120 @@
+! Copyright (C) 2009 Chris Double.\r
+! See http://factorcode.org/license.txt for BSD license.\r
+USING: help.markup help.syntax ;\r
+IN: s3\r
+\r
+HELP: buckets\r
+{ $values \r
+  { "seq" "a sequence of " { $link bucket } " objects" } \r
+}\r
+{ $description \r
+    "Returns a list of " { $link bucket } " objects containing data on the buckets available on S3."}\r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "buckets ." "{ }" }\r
+}\r
+;\r
+\r
+HELP: create-bucket\r
+{ $values \r
+  { "bucket" "a string" } \r
+}\r
+{ $description \r
+    "Creates a bucket with the given name."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"testbucket\" create-bucket" "" }\r
+}\r
+;\r
+\r
+HELP: delete-bucket\r
+{ $values \r
+  { "bucket" "a string" } \r
+}\r
+{ $description \r
+    "Deletes the bucket with the given name."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"testbucket\" delete-bucket" "" }\r
+}\r
+;\r
+\r
+HELP: keys\r
+{ $values \r
+  { "bucket" "a string" } \r
+  { "seq" "a sequence of " { $link key } " objects"} \r
+}\r
+{ $description \r
+    "Returns a sequence of " { $link key } " objects. Each object in the sequence has information about the keys contained within the bucket."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"testbucket\" keys . " "{ }" }\r
+}\r
+;\r
+\r
+HELP: get-object\r
+{ $values \r
+  { "bucket" "a string" } \r
+  { "key" "a string" } \r
+  { "response" "The HTTP response object"} \r
+  { "data" "The data returned from the http request"} \r
+}\r
+{ $description \r
+    "Does an HTTP request to retrieve the object in the bucket with the given key."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"testbucket\" \"mykey\" http-get " "" }\r
+}\r
+;\r
+\r
+HELP: put-object\r
+{ $values \r
+  { "data" "an object" } \r
+  { "mime-type" "a string" } \r
+  { "bucket" "a string"} \r
+  { "key" "a string"} \r
+  { "headers" "an assoc"} \r
+}\r
+{ $description \r
+    "Stores the object under the key in the given bucket. The object has "\r
+"the given mimetype. 'headers' should contain key/values for any headers to "\r
+"be associated with the object. 'data' is any Factor object that can be "\r
+"used as the 'data' slot in <post-data>. If it's a <pathname> it stores "\r
+"the contents of the file. If it's a stream, it's the contents of the "\r
+"stream, etc."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"hello\" binary encode \"text/plain\" \"testbucket\" \"hello.txt\" H{ { \"x-amz-acl\" \"public-read\" } } put-object" "" }\r
+  { $unchecked-example "USING: s3 ;" "\"hello.txt\" <pathname> \"text/plain\" \"testbucket\" \"hello.txt\" H{ { \"x-amz-acl\" \"public-read\" } } put-object" "" }\r
+}\r
+;\r
+\r
+HELP: delete-object\r
+{ $values \r
+  { "bucket" "a string"} \r
+  { "key" "a string"} \r
+}\r
+{ $description \r
+    "Deletes the object in the bucket with the given key."\r
+} \r
+{ $examples\r
+  { $unchecked-example "USING: s3 ;" "\"testbucket\" \"mykey\" delete-object" "" }\r
+}\r
+;\r
+\r
+ARTICLE: "s3" "Amazon S3"\r
+"The " { $vocab-link "s3" } " vocabulary provides a wrapper to the Amazon "\r
+"Simple Storage Service API."\r
+$nl\r
+"To use the api you must set the variables " { $link key-id } " and " \r
+{ $link secret-key } " to your Amazon S3 key and secret key respectively. Once "\r
+"this is done you can call any of the words below."\r
+{ $subsection buckets }\r
+{ $subsection create-bucket }\r
+{ $subsection delete-bucket }\r
+{ $subsection keys }\r
+{ $subsection get-object }\r
+{ $subsection put-object }\r
+{ $subsection delete-object }\r
+;\r
+\r
+ABOUT: "s3"
\ No newline at end of file