extra/mongodb/driver/driver-docs.factor

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