Add S3 docs

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

diff --git a/extra/s3/s3.factor b/extra/s3/s3.factor
index faeb8df2ecb6217b474945c9096a3cca3f62d4ad..e4677e11679168ca4971aab943ebb872e73666d0 100644 (file)
--- a/extra/s3/s3.factor
+++ b/extra/s3/s3.factor
@@ -26,6 +26,8 @@ IN: s3
 SYMBOL: key-id
 SYMBOL: secret-key
 
+<PRIVATE
+
 TUPLE: s3-request path mime-type date method headers  bucket data ;
 
 : hashtable>headers ( hashtable -- seq )
@@ -81,23 +83,31 @@ TUPLE: s3-request path mime-type date method headers  bucket data ;
     "PUT" <s3-request> dup s3-url swapd <put-request> 
     sign-http-request http-request ;
 
+PRIVATE>
+
 TUPLE: bucket name date ;
 
+<PRIVATE
+
 : (buckets) ( xml -- seq )
     "Buckets" tag-named 
     "Bucket" tags-named [
         [ "Name" tag-named children>string ] 
         [ "CreationDate" tag-named children>string ] bi bucket boa
     ] map ;
+PRIVATE>
  
 : buckets ( -- seq )
     f "/" H{ } clone s3-get nip >string string>xml (buckets) ;
 
+<PRIVATE
 : bucket-url ( bucket -- string )
     [ "http://" % % ".s3.amazonaws.com/" % ] "" make ;
+PRIVATE>
 
 TUPLE: key name last-modified size ;
 
+<PRIVATE
 : (keys) ( xml -- seq )
     "Contents" tags-named [
       [ "Key" tag-named children>string ]
@@ -105,12 +115,13 @@ TUPLE: key name last-modified size ;
       [ "Size" tag-named children>string ]
       tri key boa
   ] map ;
+PRIVATE>
  
 : keys ( bucket -- seq )
     "/" H{ } clone s3-get
     nip >string string>xml (keys) ;
 
-: object-get ( bucket key -- response data )
+: get-object ( bucket key -- response data )
     s3-request new
         swap "/" prepend >>path
         swap >>bucket
@@ -128,7 +139,7 @@ TUPLE: key name last-modified size ;
     "/" H{ } clone "DELETE" <s3-request>
     dup s3-url <delete-request> sign-http-request http-request 2drop ;
  
-: put-object ( object type bucket key headers -- )
+: put-object ( data mime-type bucket key headers -- )
     [ "/" prepend ] dip "PUT" <s3-request> 
     over >>mime-type
     [ <post-data> swap >>data ] dip
@@ -140,14 +151,3 @@ TUPLE: key name last-modified size ;
 : delete-object ( bucket key -- )
     "/" prepend H{ } clone "DELETE" <s3-request>
     dup s3-url <delete-request> sign-http-request http-request 2drop ;
-
-! "testbucket" create-bucket
-! "testbucket" delete-bucket
-! buckets
-! "testbucket" keys 
-! "hello world" binary encode "text/plain" "testbucket" "hello.txt" 
-! H{ { "x-amz-acl" "public-read" } } put-object
-! "hello.txt" <pathname> "text/plain" "testbucket" "hello.txt" 
-! H{ { "x-amz-acl" "public-read" } } put-object
-! "testbucket" "hello.txt" object-get
-! Need to write docs...