/extra/s3/s3-docs.factor

http://github.com/abeaumont/factor · Factor · 121 lines · 110 code · 9 blank · 2 comment · 0 complexity · 57a95131af7783ccd9ce2d01e13084c6 MD5 · raw file

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