Extendedj 1

bin/builder_data.py

@@ -87,6 +87,7 @@
      ('$(rst-include)/table-sql-to-mongo-update-examples', 'sql'),
      ('$(rst-include)/table-sql-to-mongo-delete-examples', 'sql'),
      ('$(rst-include)/table-lock-behavior-per-operation', 'concurrency'),
+     ('$(rst-include)/table-mongodb-extended-json', 'json'),
 ]
 
 sphinx = [

bin/mongodb_domain.py

@@ -136,6 +136,8 @@ def get_index_text(self, objectname, name_obj):
             return _('%s (JavaScript shell macro)') % (name)
         elif self.objtype == 'limit':
             return _('%s (MongoDB system limit)') % (name)
+        elif self.objtype == 'bsontype':
+            return _('%s (BSON type)') % (name)            
         return ''
 
     def run(self):
@@ -213,6 +215,7 @@ class MongoDBDomain(Domain):
         'error':        ObjType(l_('error'),       'error'),
         'macro':        ObjType(l_('macro'),       'macro'),
         'limit':        ObjType(l_('limit'),       'limit'),
+        'bsontype':     ObjType(l_('bsontype'),    'bsontype'),
     }
 
     directives = {
@@ -230,6 +233,7 @@ class MongoDBDomain(Domain):
         'error':         MongoDBObject,
         'macro':         MongoDBObject,
         'limit':         MongoDBObject,
+        'bsontype':      MongoDBObject,
     }
     roles = {
         'dbcommand':   MongoDBXRefRole(),
@@ -246,6 +250,7 @@ class MongoDBDomain(Domain):
         'error':       MongoDBXRefRole(),
         'macro':       MongoDBXRefRole(),
         'limit':       MongoDBXRefRole(),
+        'bsontype':    MongoDBXRefRole(),
     }
     initial_data = {
         'objects': {}, # fullname -> docname, objtype

source/includes/table-mongodb-extended-json.yaml

@@ -0,0 +1,197 @@
+# table structure. all content symbolic.
+section: layout
+header: [ meta.header1, meta.header2, meta.header3, meta.header4, meta.header5 ]
+rows: 
+  - 1: [ content.bson_bin, content.strict_bin, content.js_bin, content.mongo_bin, content.notes_bin ]
+  - 2: [ content.bson_date, content.strict_date, content.js_date, content.mongo_date, content.notes_date ]
+  - 3: [ content.bson_ts, content.strict_ts, content.js_ts, content.mongo_ts, content.notes_ts ]
+  - 4: [ content.bson_regex, content.strict_regex, content.js_regex, content.mongo_regex, content.notes_regex ]
+  - 5: [ content.bson_oid, content.strict_oid, content.js_oid, content.mongo_oid, content.notes_oid ]
+  - 6: [ content.bson_ref, content.strict_ref, content.js_ref, content.mongo_ref, content.notes_ref ]
+  - 7: [ content.bson_undef, content.strict_undef, content.js_undef, content.mongo_undef, content.notes_undef ]
+---
+# table metadata, as meta.<key>
+section: meta
+header1: "BSON Data Type"
+header2: "Strict Mode"
+header3: "JavaScript Mode"
+header4: "mongo Shell Mode"
+header5: "Notes"
+---
+# table content, as content.<key>
+section: content
+bson_bin: ".. bsontype:: data_binary"
+strict_bin: |
+            .. code-block:: javascript
+
+               {
+                 "$binary": "<bindata>",
+                 "$type": "<t>"
+               }
+js_bin: |
+        .. code-block:: javascript
+
+           {
+             "$binary": "<bindata>",
+             "$type": "<t>"
+           }
+mongo_bin: |
+            .. code-block:: javascript
+
+               {
+                 "$binary": "<bindata>",
+                 "$type": "<t>"
+               }
+notes_bin: |
+           ``<bindata>`` is the base64 representation of a binary
+           string.
+
+           ``<t>`` is the hexadecimal representation of a single byte
+           that indicates the data type.
+bson_date: ".. bsontype:: data_date"
+strict_date: |
+             .. code-block:: javascript
+
+                {
+                  "$date": <date>
+                }
+js_date: |
+         .. code-block:: javascript
+
+            Date( <date> )
+mongo_date: |
+            .. code-block:: javascript
+
+               Date ( <date> )
+notes_date: |
+            ``<date>`` is the JSON representation of a 64-bit signed
+            integer for milliseconds since epoch (unsigned before
+            version 1.9.1). 
+bson_ts: ".. bsontype:: data_timestamp"
+strict_ts: |
+             .. code-block:: javascript
+
+                {
+                  "$timestamp":
+                       {
+                         "t": <t>,
+                         "i": <i>
+                       }
+                }
+js_ts: |
+       .. code-block:: javascript
+
+          {
+            "$timestamp":
+                 {
+                   "t": <t>,
+                   "i": <i>
+                 }
+          }
+mongo_ts: |
+          .. code-block:: javascript
+
+             Timestamp( <t>, <i> )
+notes_ts: |
+          ``<t>`` is the JSON representation 
+          of a 32-bit unsigned integer
+          for seconds since epoch.
+
+          ``<i>`` is a 32-bit unsigned 
+          integer for the increment.
+bson_regex: ".. bsontype:: data_regex"
+strict_regex: |
+              .. code-block:: javascript
+
+                 {
+                   "$regex": "<sRegex>",
+                   "$options": "<sOptions>"
+                 }
+js_regex: |
+          .. code-block:: javascript
+
+             /<jRegex>/<jOptions>
+mongo_regex: |
+             .. code-block:: javascript
+
+                /<jRegex>/<jOptions>
+notes_regex: |
+             ``<sRegex>`` is a string of valid JSON characters.
+
+             ``<jRegex>`` is a string that may contain valid JSON
+             characters and unescaped double quote (``"``) characters, but may not
+             contain unescaped forward slash (``/``) characters.
+
+             ``<sOptions>`` is a string containing the regex options
+             represented by the letters of the alphabet.
+
+             ``<jOptions>`` is a string that may contain only the
+             characters 'g', 'i', 'm' and 's' (added in v1.9). Because
+             the ``JavaScript`` and ``mongo Shell`` representations
+             support a limited range of options, any nonconforming
+             options will be dropped when converting to this
+             representation.
+bson_oid: ".. bsontype:: data_oid"
+strict_oid: |
+              .. code-block:: javascript
+
+                 {
+                   "$oid": "<id>"
+                 }
+js_oid: |
+          .. code-block:: javascript
+
+             {
+               "$oid": "<id>"
+             }
+mongo_oid: |
+             .. code-block:: javascript
+
+                ObjectId( "<id>" )
+notes_oid: |
+           ``<id>`` is a 24-character hexadecimal string.
+bson_ref: ".. bsontype:: data_ref"
+strict_ref: |
+              .. code-block:: javascript
+
+                 {
+                   "$ref": "<name>",
+                   "$id": "<id>"
+                 }
+js_ref: |
+          .. code-block:: javascript
+
+             {
+               "$ref" : "<name>",
+               "$id" : "<id>"
+             }
+mongo_ref: |
+             .. code-block:: javascript
+
+                DBRef("<name>", "<id>")
+notes_ref: |
+           ``<name>`` is a string of valid JSON characters. 
+
+           ``<id>`` is a 24-character hexadecimal string. In the Strict
+           and JS representations, the Strict representation for a
+           :bsontype:`data_oid` can be used as the value.
+
+bson_undef: ".. bsontype:: data_undefined"
+strict_undef: |
+              .. code-block:: javascript
+
+                 {
+                   "$undefined": true
+                 }
+js_undef: |
+          .. code-block:: javascript
+
+             undefined
+
+mongo_undef: |
+             .. code-block:: javascript
+
+                undefined
+notes_undef: |
+             The representation for the JavaScript/BSON undefined type.
+...

source/reference.txt

@@ -92,6 +92,7 @@ General Reference
    :maxdepth: 1
 
    reference/limits
+   reference/mongodb-extended-json
    reference/glossary
 
 .. seealso:: The :ref:`genindex` may provide useful insight into the

source/reference/mongodb-extended-json.txt

@@ -0,0 +1,30 @@
+=====================
+MongoDB Extended BSON 
+=====================
+
+.. default-domain:: mongodb
+
+MongoDB :doc:`import and export utilities
+</administration/import-export>` and MongoDB :wiki:`REST
+Interfaces<Http Interface>` support JSON-style access to MongoDB
+:term:`BSON` documents.
+
+The REST interface supports three different modes for document output:
+
+- *Strict* mode that produces output that conforms to the `JSON RFC
+  specifications <http://www.json.org>`_.
+
+- *JavaScript* mode that produces output that can be processed by most
+  JavaScript interpreters.
+
+- *mongo Shell* mode produces output that the :program:`mongo` shell
+  understands. This is basically an enhanced JavaScript format.
+
+MongoDB can understand all of these representations in REST input.
+
+Special representations are used for :term:`BSON types` that do not
+have obvious JSON mappings, and multiple representations are allowed
+for some of these types. These types are displayed in the following
+table:
+
+.. include:: /includes/table-mongodb-extended-json.rst