extra/mongodb/driver/driver-docs.factor

   1 ! Copyright (C) 2009 Sascha Matzke.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: assocs help.markup help.syntax kernel quotations ;
   4 IN: mongodb.driver
   5
   6 HELP: <mdb-collection>
   7 { $values
   8   { "name" "name of the collection" }
   9   { "collection" "mdb-collection instance" }
  10 }
  11 { $examples { $unchecked-example "USING: mongodb.driver ;" "\"mycollection\" <mdb-collection> t >>capped 1000000 >>max" "" } }
  12 { $description "Creates a new mdb-collection instance. Use this to create capped/limited collections." } ;
  13
  14 HELP: <mdb>
  15 { $values
  16   { "db" "name of the database to use" }
  17   { "host" "host name or IP address" }
  18   { "port" "port number" }
  19   { "mdb" "mdb-db instance" }
  20 }
  21 { $description "Create a new mdb-db instance and automatically resolves master/slave information in a paired MongoDB setup." }
  22 { $examples
  23   { $unchecked-example "USING: mongodb.driver ;" "\"db\" \"127.0.0.1\" 27017 <mdb>" "" } } ;
  24
  25 HELP: <query>
  26 { $values
  27   { "collection" "collection to query" }
  28   { "assoc" "query assoc" }
  29   { "mdb-query-msg" "mdb-query-msg instance" }
  30 }
  31 { $description "Creates a new mdb-query-msg instance. "
  32   "This word must be called from within a with-db scope."
  33   "For more see: "
  34   { $link with-db } }
  35 { $examples
  36   { $unchecked-example "USING: mongodb.driver ;" "\"mycollection\" H{ } <query>" "" } } ;
  37
  38 HELP: <update>
  39 { $values
  40   { "collection" "collection to update" }
  41   { "selector" "selector assoc (selects which object(s) to update" }
  42   { "object" "updated object or update instruction" }
  43   { "mdb-update-msg" "mdb-update-msg instance" }
  44 }
  45 { $description "Creates an update message for the object(s) identified by the given selector."
  46   "MongoDB supports full object updates as well as partial update modifiers such as $set, $inc or $push"
  47   "For more information see: " { $url "http://www.mongodb.org/display/DOCS/Updates" } } ;
  48
  49 HELP: >upsert
  50 { $values
  51   { "mdb-update-msg" "a mdb-update-msg" }
  52 }
  53 { $description "Marks a mdb-update-msg as upsert operation"
  54   "(inserts object identified by the update selector if it doesn't exist in the collection)" } ;
  55
  56 HELP: PARTIAL?
  57 { $values
  58   { "value" "partial?" }
  59 }
  60 { $description "key which refers to a partially loaded object" } ;
  61
  62 HELP: asc
  63 { $values
  64   { "key" "sort key" }
  65   { "spec" "sort spec" }
  66 }
  67 { $description "indicates that the values of the specified key should be sorted in ascending order" } ;
  68
  69 HELP: count
  70 { $values
  71   { "mdb-query-msg" "query" }
  72   { "result" "number of objects in the collection that match the query" }
  73 }
  74 { $description "count objects in a collection" } ;
  75
  76 HELP: create-collection
  77 { $values
  78   { "name/collection" "collection name" }
  79 }
  80 { $description "Creates a new collection with the given name." } ;
  81
  82 HELP: delete
  83 { $values
  84   { "mdb-delete-msg" "a delete msg" }
  85 }
  86 { $description "removes objects from the collection (with lasterror check)" } ;
  87
  88 HELP: delete-unsafe
  89 { $values
  90   { "mdb-delete-msg" "a delete msg" }
  91 }
  92 { $description "removes objects from the collection (without error check)" } ;
  93
  94 HELP: desc
  95 { $values
  96   { "key" "sort key" }
  97   { "spec" "sort spec" }
  98 }
  99 { $description "indicates that the values of the specified key should be sorted in descending order" } ;
 100
 101 HELP: drop-collection
 102 { $values
 103   { "name" "a collection" }
 104 }
 105 { $description "removes the collection and all objects in it from the database" } ;
 106
 107 HELP: drop-index
 108 { $values
 109   { "collection" "a collection" }
 110   { "name" "an index name" }
 111 }
 112 { $description "drops the specified index from the collection" } ;
 113
 114 HELP: ensure-collection
 115 { $values
 116   { "name" "a collection; e.g. mycollection " }
 117 }
 118 { $description "ensures that the collection exists in the database" } ;
 119
 120 HELP: ensure-index
 121 { $values
 122   { "index-spec" "an index specification" }
 123 }
 124 { $description "Ensures the existence of the given index. "
 125   "For more information on MongoDB indexes see: " { $url "http://www.mongodb.org/display/DOCS/Indexes" } }
 126 { $examples
 127   { $unchecked-example "USING: mongodb.driver ;"
 128     "\"db\" \"127.0.0.1\" 27017 <mdb>"
 129     "[ \"mycollection\" nameIdx [ \"name\" asc ] keyspec <index-spec> ensure-index ] with-db" "" }
 130   { $unchecked-example  "USING: mongodb.driver ;"
 131     "\"db\" \"127.0.0.1\" 27017 <mdb>" "[ \"mycollection\" nameIdx [ \"name\" asc ] keyspec <index-spec> t >>unique? ensure-index ] with-db" "" } } ;
 132
 133 HELP: explain.
 134 { $values
 135   { "mdb-query-msg" "a query message" }
 136 }
 137 { $description "Prints the execution plan for the given query" } ;
 138
 139 HELP: find
 140 { $values
 141   { "selector" "a mdb-query or mdb-cursor" }
 142   { "mdb-cursor/f" "a cursor (if there are more results) or f" }
 143   { "seq" "a sequences of objects" }
 144 }
 145 { $description "executes the given query" }
 146 { $examples
 147   { $unchecked-example "USING: mongodb.driver ;"
 148     "\"db\" \"127.0.0.1\" 27017 <mdb>"
 149     "[ \"mycollection\" H{ { \"name\" \"Alfred\" } } <query> find ] with-db" "" } } ;
 150
 151 HELP: find-one
 152 { $values
 153   { "mdb-query-msg" "a query" }
 154   { "result/f" "a single object or f" }
 155 }
 156 { $description "Executes the query and returns one object at most" } ;
 157
 158 HELP: hint
 159 { $values
 160   { "mdb-query-msg" "a query" }
 161   { "index-hint" "a hint to an index" }
 162 }
 163 { $description "Annotates the query with a hint to an index. "
 164   "For detailed information see: " { $url "http://www.mongodb.org/display/DOCS/Optimizing+Mongo+Performance#OptimizingMongoPerformance-Hint" } }
 165 { $examples
 166   { $unchecked-example "USING: mongodb.driver ;"
 167     "\"db\" \"127.0.0.1\" 27017 <mdb>"
 168     "[ \"mycollection\" H{ { \"name\" \"Alfred\" } { \"age\" 70 } } <query> H{ { \"name\" 1 } } hint find ] with-db" "" } } ;
 169
 170 HELP: lasterror
 171 { $values
 172
 173   { "error" "error message or f" }
 174 }
 175 { $description "Checks if the last operation resulted in an error on the MongoDB side"
 176   "For more information see: " { $url "http://www.mongodb.org/display/DOCS/Mongo+Commands#MongoCommands-LastErrorCommands" } } ;
 177
 178 HELP: limit
 179 { $values
 180   { "mdb-query-msg" "a query" }
 181   { "limit#" "number of objects that should be returned at most" }
 182 }
 183 { $description "Limits the number of returned objects to limit#" }
 184 { $examples
 185   { $unchecked-example "USING: mongodb.driver ;"
 186     "\"db\" \"127.0.0.1\" 27017 <mdb>"
 187     "[ \"mycollection\" H{ } <query> 10 limit find ] with-db" "" } } ;
 188
 189 HELP: load-collection-list
 190 { $values
 191
 192   { "collection-list" "list of collections in the current database" }
 193 }
 194 { $description "Returns a list of all collections that exist in the current database" } ;
 195
 196 HELP: load-index-list
 197 { $values
 198
 199   { "index-list" "list of indexes" }
 200 }
 201 { $description "Returns a list of all indexes that exist in the current database" } ;
 202
 203 HELP: mdb-collection
 204 { $var-description "MongoDB collection" } ;
 205
 206 HELP: mdb-cursor
 207 { $var-description "MongoDB cursor" } ;
 208
 209 HELP: mdb-error
 210 { $values
 211   { "msg" "error message" }
 212 }
 213 { $description "error class" } ;
 214
 215 HELP: r/
 216 { $values
 217   { "token" "a regexp string" }
 218   { "mdbregexp" "a mdbregexp tuple instance" }
 219 }
 220 { $description "creates a new mdbregexp instance" } ;
 221
 222 HELP: save
 223 { $values
 224   { "collection" "a collection" }
 225   { "assoc" "object" }
 226 }
 227 { $description "Saves the object to the given collection."
 228   " If the object contains a field name \"_id\" this command automatically performs an update (with upsert) instead of a plain save" } ;
 229
 230 HELP: save-unsafe
 231 { $values
 232   { "collection" "a collection" }
 233   { "assoc" "object" }
 234 }
 235 { $description "Save the object to the given collection without automatic error check" } ;
 236
 237 HELP: skip
 238 { $values
 239   { "mdb-query-msg" "a query message" }
 240   { "skip#" "number of objects to skip" }
 241 }
 242 { $description "annotates a query message with a number of objects to skip when returning the results" } ;
 243
 244 HELP: sort
 245 { $values
 246   { "mdb-query-msg" "a query message" }
 247   { "sort-quot" "a quotation with sort specifiers" }
 248 }
 249 { $description "annotates the query message for sort specifiers" } ;
 250
 251 HELP: update
 252 { $values
 253   { "mdb-update-msg" "a mdb-update message" }
 254 }
 255 { $description "performs an update" } ;
 256
 257 HELP: update-unsafe
 258 { $values
 259   { "mdb-update-msg" "a mdb-update message" }
 260 }
 261 { $description "performs an update without automatic error check" } ;
 262
 263 HELP: validate.
 264 { $values
 265   { "collection" "collection to validate" }
 266 }
 267 { $description "validates the collection" } ;
 268
 269 HELP: with-db
 270 { $values
 271   { "mdb" "mdb instance" }
 272   { "quot" "quotation to execute with the given mdb instance as context" }
 273 }
 274 { $description "executes a quotation with the given mdb instance in its context" } ;
 275
 276