1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Copyright 2015 Alexandre Terrasa <alexandre@moz-code.org>
5 # Licensed under the Apache License, Version 2.0 (the "License");
6 # you may not use this file except in compliance with the License.
7 # You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
17 # Native wrapper for the MongoDB C Driver
19 # See [mongoc](http://api.mongodb.org/c/1.1.4/index.html).
20 module native_mongodb
is pkgconfig
"libmongoc-1.0"
28 # Wrapper for `bson_t`.
30 # All data manipulated by `mongoc` are BSON formated.
32 # The `bson_t` structure represents a BSON document.
33 # This structure manages the underlying BSON encoded buffer.
34 # For mutable documents, it can append new data to the document.
36 # See [`bson_t`](http://api.mongodb.org/libbson/current/bson_t.html).
37 extern class NativeBSON `{ bson_t * `}
39 # Wrapper for `bson_new
()`.
41 # The `bson_new
()` function shall create a new `bson_t
` structure on the heap.
42 # It should be freed with `bson_destroy
()` when it is no longer in use.
43 new `{ return bson_new(); `}
45 # Wrapper for `bson_new_from_json()`.
47 # The `bson_new_from_json()` function allocates and initialize a new `bson_t`
48 # by parsing the JSON found in `data`.
49 # Only a single JSON object may exist in data or an error will be set and
51 new from_json_string
(data
: NativeString) import set_mongoc_error
`{
54 bson = bson_new_from_json(data, -1, &error);
56 NativeBSON_set_mongoc_error(bson, &error);
62 # Wrapper for `bson_as_json()`.
64 # The `bson_as_json()` function shall encode bson as a JSON encoded UTF-8 string.
65 # The caller is responsible for freeing the resulting UTF-8 encoded string
66 # by calling `bson_free()` with the result.
67 fun to_native_string
: NativeString `{ return bson_as_json(self, NULL); `}
69 # Wrapper for `bson_destroy
()`.
71 # The `bson_destroy
()` function shall free an allocated `bson_t
` structure.
72 # This function should always be called when you are done with a `bson_t
`
73 # unless otherwise specified.
75 # This instance should not be used beyond this point!
76 fun destroy `{ bson_destroy(self); `}
78 # Utility method to set `Sys.last_mongoc_error`.
79 fun set_mongoc_error
(err
: BSONError) do sys
.last_mongoc_error
= err
82 # Wrapper for `bson_error_t`.
84 # The `bson_error_t` structure is used to encapsulate information about an error.
86 # See [`bson_error_t`](http://api.mongodb.org/libbson/current/bson_error_t.html).
87 extern class BSONError `{ bson_error_t * `}
89 # Wrapper for `error
.domain
`.
91 # The `error
.domain
` field contains the logical domain within a library that
93 fun domain: Int `{ return self->domain; `}
95 # Wrapper for `error.code`.
97 # The `error.code` field contains the domain specific error code.
98 fun code
: Int `{ return self->code; `}
100 # Wrapper for `error
.message
`.
102 # The `error
.message
` field contains a human printable error message.
103 fun message: NativeString `{ return self->message; `}
107 # Last error raised by `monogdb::MongoClient`.
109 # See `MongoClient::last_error`.
110 var last_mongoc_error
: nullable BSONError = null
113 # Wrapper for `char**`.
115 # Used to handle array of NativeString returned by MongoDB.
116 redef class NativeCStringArray
119 # This instance should not be used beyond this point!
120 fun destroy
`{ free(self); `}
123 # Wrapper for `mongoc_client_t
`.
125 # `mongoc_client_t
` is an opaque type that provides access to a MongoDB node,
126 # replica-set, or sharded-cluster.
127 # It maintains management of underlying sockets and routing to individual nodes.
129 # See [`mongoc_client_t
`](http://api.mongodb.org/c/current/mongoc_client_t.html).
130 extern class NativeMongoClient `{ mongoc_client_t * `}
132 # Wrapper for `mongoc_client_new()`.
134 # Creates a new `mongoc_client_t` using the `uri` string provided.
135 new(uri
: NativeString) `{
137 return mongoc_client_new(uri);
140 # Wrapper for `mongoc_client_get_server_status()`.
142 # Queries the server for the current server status.
143 # Returns `null` if an error occured.
144 fun server_status
: nullable NativeBSON import set_mongoc_error
, NativeBSON.as nullable `{
146 bson_t *reply = bson_new();
147 if(!mongoc_client_get_server_status(self, NULL, reply, &error)){
148 NativeMongoClient_set_mongoc_error(self, &error);
149 return null_NativeBSON();
151 return NativeBSON_as_nullable(reply);
154 # Wrapper for `mongoc_client_get_database_names()`.
156 # This function queries the MongoDB server for a list of known databases.
157 # Returns `null` if an error occured.
158 fun database_names
: nullable NativeCStringArray
159 import set_mongoc_error
, NativeCStringArray, NativeCStringArray.as nullable `{
162 if(strv = mongoc_client_get_database_names(self, &error)) {
163 return NativeCStringArray_as_nullable(strv);
165 NativeMongoClient_set_mongoc_error(self, &error);
166 return null_NativeCStringArray();
169 # Wrapper for `mongoc_client_destroy()`.
171 # This instance should not be used beyond this point!
173 mongoc_client_destroy(self);
177 # Utility method to set `Sys.last_mongoc_error`.
178 fun set_mongoc_error
(err
: BSONError) do sys
.last_mongoc_error
= err
181 # Wrapper for `mongoc_database_t`.
183 # `mongoc_database_t` provides access to a MongoDB database.
184 # This handle is useful for actions a particular database object.
185 # It is not a container for `mongoc_collection_t` structures.
187 # See [`mongoc_database_t`](http://api.mongodb.org/c/current/mongoc_database_t.html).
188 extern class NativeMongoDb `{ mongoc_database_t * `}
190 # Wrapper for `mongoc_client_get_database
()`.
192 # Get a newly allocated `mongoc_database_t
` for the database named name.
194 # Database are automatically created on the MongoDB server upon insertion of
195 # the first document into a collection.
196 # There is no need to create a database manually.
197 new(client: NativeMongoClient, db_name: NativeString) `{
198 return mongoc_client_get_database
(client
, db_name
);
201 # Wrapper for `mongoc_database_get_collection_names
()`.
203 # Fetches a `NULL` terminated array of `NULL-byte
` terminated `char
*` strings
204 # containing the names of all of the collections in database.
205 fun collection_names: nullable NativeCStringArray
206 import set_mongoc_error, NativeCStringArray, NativeCStringArray.as nullable `{
209 if(strv
= mongoc_database_get_collection_names
(self, &error
)) {
210 return NativeCStringArray_as_nullable(strv
);
212 NativeMongoDb_set_mongoc_error(self, &error
);
213 return null_NativeCStringArray
();
216 # Wrapper for `mongoc_database_get_collection
()`.
218 # Allocates a new `mongoc_collection_t
` structure for the collection named
219 # `name
` in database.
220 fun collection(name: NativeString): NativeMongoCollection `{
221 return mongoc_database_get_collection
(self, name
);
224 # Wrapper for `mongoc_database_has_collection
()`.
226 # This function checks to see if a collection exists on the MongoDB server
228 fun has_collection(name: NativeString): Bool import set_mongoc_error `{
230 if(!mongoc_database_has_collection
(self, name
, &error
)) {
231 NativeMongoDb_set_mongoc_error(self, &error
);
237 # Wrapper for `mongoc_database_drop
()`.
239 # This function attempts to drop a database on the MongoDB server.
240 fun drop: Bool import set_mongoc_error `{
242 if(!mongoc_database_drop
(self, &error
)) {
243 NativeMongoDb_set_mongoc_error(self, &error
);
249 # Wrapper for `mongoc_database_destroy
()`.
251 # This instance should not be used beyond this point!
252 fun destroy `{ mongoc_database_destroy(self); `}
254 # Utility method to set `Sys.last_mongoc_error`.
255 fun set_mongoc_error
(err
: BSONError) do sys
.last_mongoc_error
= err
258 # Wrapper for `mongoc_collection_t`.
260 # `mongoc_collection_t` provides access to a MongoDB collection.
261 # This handle is useful for actions for most CRUD operations,
262 # I.e. insert, update, delete, find, etc.
264 # It is an error to call `mongoc_collection_destroy()` on a collection that has
265 # operations pending.
266 # It is required that you release `mongoc_cursor_t` structures before calling
267 # `mongoc_collection_destroy()`.
269 # See [`mongoc_collection_t`](http://api.mongodb.org/c/current/mongoc_collection_t.html).
270 extern class NativeMongoCollection `{ mongoc_collection_t * `}
272 # Wrapper for `mongoc_client_get_collection
()`.
274 # Get a newly allocated `mongoc_collection_t
` for the collection named
275 # `collection
` in the database named `db
`.
277 # Collections are automatically created on the MongoDB server upon insertion
278 # of the first document.
279 # There is no need to create a collection manually.
280 new(client: NativeMongoClient, db, collection: NativeString) `{
281 return mongoc_client_get_collection
(client
, db
, collection
);
284 # Wrapper for `mongoc_collection_insert
()`.
286 # This function shall insert `document
` into the collection.
287 # If no `_id
` element is found in document, then a `bson_oid_t
` will be
288 # generated locally and added to the document.
290 # You can retrieve a generated `_id
` from `mongoc_collection_get_last_error
()`.
291 fun insert(doc: NativeBSON): Bool import set_mongoc_error `{
293 if(!mongoc_collection_insert
(self, MONGOC_INSERT_NONE, doc
, NULL, &error
)) {
294 NativeMongoCollection_set_mongoc_error(self, &error
);
300 # Wrapper for `mongoc_collection_save
()`.
302 # This function shall save a document into the collection.
303 # If the document has an `_id
` field it will be updated.
304 # Otherwise it will be inserted.
305 fun save(document: NativeBSON): Bool import set_mongoc_error `{
307 if(!mongoc_collection_save
(self, document
, NULL, &error
)) {
308 NativeMongoCollection_set_mongoc_error(self, &error
);
314 # Wrapper for `mongoc_collection_remove
(MONGOC_REMOVE_SINGLE_REMOVE)`.
316 # This function shall remove the first document in the collection that matches
318 # The bson selector is not validated, simply passed along as appropriate to the server.
319 fun remove(selector: NativeBSON): Bool import set_mongoc_error `{
321 if(!mongoc_collection_remove
(self, MONGOC_REMOVE_SINGLE_REMOVE, selector
, NULL, &error
)) {
322 NativeMongoCollection_set_mongoc_error(self, &error
);
328 # Wrapper for `mongoc_collection_remove
(MONGOC_REMOVE_NONE)`.
330 # This function shall remove documents in the collection that match `selector
`.
331 fun remove_all(selector: NativeBSON): Bool import set_mongoc_error `{
333 if(!mongoc_collection_remove
(self, MONGOC_REMOVE_NONE, selector
, NULL, &error
)) {
334 NativeMongoCollection_set_mongoc_error(self, &error
);
340 # Wrapper for `mongoc_collection_update
(MONGOC_UPDATE_NONE)`.
342 # This function shall update the first document in the collection that
343 # matches `selector
`.
344 fun update(selector, update: NativeBSON): Bool import set_mongoc_error `{
346 if(!mongoc_collection_update
(self, MONGOC_UPDATE_NONE, selector
, update
, NULL, &error
)) {
347 NativeMongoCollection_set_mongoc_error(self, &error
);
353 # Wrapper for `mongoc_collection_update
(MONGOC_UPDATE_MULTI_UPDATE)`.
355 # This function shall update documents in the collection that match `selector
`.
356 fun update_all(selector, update: NativeBSON): Bool import set_mongoc_error `{
358 if(!mongoc_collection_update
(self, MONGOC_UPDATE_MULTI_UPDATE, selector
, update
, NULL, &error
)) {
359 NativeMongoCollection_set_mongoc_error(self, &error
);
365 # Wrapper for `mongoc_collection_count
()`.
367 # This function shall execute a count `query
` on the underlying collection.
368 fun count(query: NativeBSON): Int import set_mongoc_error `{
370 int64_t count
= mongoc_collection_count
(self, MONGOC_QUERY_NONE, query
, 0, 0, NULL, &error
);
372 NativeMongoCollection_set_mongoc_error(self, &error
);
378 # Wrapper for `mongoc_collection_find
()`.
380 # This function shall execute a `query
` on the underlying collection.
382 # If no options are necessary, `query
` can simply contain a query such as `{a:1}`.
384 # If you would like to specify options such as a sort order,
385 # the query must be placed inside of `{"$query": {}}`.
386 fun find(query: NativeBSON): nullable NativeMongoCursor import
387 NativeMongoCursor.as nullable, set_mongoc_error `{
389 mongoc_cursor_t
*cursor
;
390 cursor
= mongoc_collection_find
(self, MONGOC_QUERY_NONE, 0, 0, 0, query
, NULL, NULL);
392 if (mongoc_cursor_error
(cursor
, &error
)) {
393 NativeMongoCollection_set_mongoc_error(self, &error
);
394 return null_NativeMongoCursor
();
397 return NativeMongoCursor_as_nullable(cursor
);
400 # Wrapper for `mongoc_collection_stats
()`.
402 # This function is a helper to retrieve statistics about the collection.
403 fun stats: nullable NativeBSON import set_mongoc_error, NativeBSON.as nullable `{
405 bson_t
*reply
= bson_new
();
406 if(!mongoc_collection_stats
(self, NULL, reply
, &error
)){
407 NativeMongoCollection_set_mongoc_error(self, &error
);
408 return null_NativeBSON
();
410 return NativeBSON_as_nullable(reply
);
413 # Wrapper for `mongoc_collection_drop
()`.
415 # This function requests that the `collection
` be dropped,
416 # including all indexes associated with the collection.
417 fun drop: Bool import set_mongoc_error `{
419 if(!mongoc_collection_drop
(self, &error
)) {
420 NativeMongoCollection_set_mongoc_error(self, &error
);
426 # Wrapper for `mongoc_collection_rename
()`.
428 # This function is a helper to rename an existing collection on a MongoDB server.
429 # The name of the collection will also be updated internally so it is safe
430 # to continue using this collection after the rename.
431 # Additional operations will occur on renamed collection.
432 fun rename(new_database, new_name: NativeString): Bool `{
434 if(!mongoc_collection_rename
(self, new_database
, new_name
, false, &error
)){
435 NativeMongoCollection_set_mongoc_error(self, &error
);
441 # Wrapper for `mongoc_collection_destroy
()`.
443 # This instance should not be used beyond this point!
444 fun destroy `{ mongoc_collection_destroy(self); `}
446 # Utility method to set `Sys.last_mongoc_error`.
447 fun set_mongoc_error
(err
: BSONError) do sys
.last_mongoc_error
= err
450 # Wrapper for `mongoc_cursor_t`.
452 # `mongoc_cursor_t` provides access to a MongoDB query cursor.
453 # It wraps up the wire protocol negotation required to initiate a query and
454 # retreive an unknown number of documents.
456 # Cursors are lazy, meaning that no network traffic occurs until the first call
457 # to mongoc_cursor_next().
459 # At that point we can:
460 # * Retreive more records with repeated calls to `mongoc_cursor_next()`.
461 # * Test for more records with `mongoc_cursor_more()`.
462 # * Retrieve the document under the cursor with `mongoc_cursor_current()`.
464 # See [`mongoc_cursor_t`](http://api.mongodb.org/c/current/mongoc_cursor_t.html).
465 extern class NativeMongoCursor `{ mongoc_cursor_t* `}
467 # Wrapper for `mongoc_cursor_current
()`.
469 # Fetches the cursors current document or NULL if there has been an error.
470 fun current: NativeBSON `{ return (bson_t*) mongoc_cursor_current(self); `}
472 # Wrapper for `mongoc_cursor_next()`.
474 # This function shall iterate the underlying cursor, setting `current` to the next
477 # This function is a blocking function.
480 return mongoc_cursor_next(self, &doc);
483 # Wrapper for `mongoc_cursor_more()`.
485 # This function shall indicate if there is more data to be read from the cursor.
486 fun more
: Bool `{ return mongoc_cursor_more(self); `}
488 # Wrapper for `mongoc_cursor_destroy
()`.
490 # This instance should not be used beyond this point!
491 fun destroy `{ mongoc_cursor_destroy(self); `}