diff options
author | Dirkjan Ochtman <djc@apache.org> | 2013-05-21 21:45:27 +0200 |
---|---|---|
committer | Dirkjan Ochtman <djc@apache.org> | 2013-05-21 21:45:41 +0200 |
commit | 310050a42cef3d79b5d0b4fea76326e4cb542c9b (patch) | |
tree | ec3fa3eb638e83a98f0e8c833cd1e506e6ff620c | |
parent | 1c450ac2405d4812abfa1393ec6947d97febf38d (diff) | |
download | couchdb-310050a42cef3d79b5d0b4fea76326e4cb542c9b.tar.gz |
docs: merge separate CommonJS sections
-rw-r--r-- | share/doc/build/Makefile.am | 3 | ||||
-rw-r--r-- | share/doc/src/commonjs.rst | 56 | ||||
-rw-r--r-- | share/doc/src/index.rst | 1 | ||||
-rw-r--r-- | share/doc/src/query-servers.rst | 84 |
4 files changed, 20 insertions, 124 deletions
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index 416c8ceca..73de281c8 100644 --- a/share/doc/build/Makefile.am +++ b/share/doc/build/Makefile.am @@ -56,7 +56,6 @@ html_files = \ html/_sources/api-basics.txt \ html/_sources/changelog.txt \ html/_sources/changes.txt \ - html/_sources/commonjs.txt \ html/_sources/config_reference.txt \ html/_sources/configuring.txt \ html/_sources/contributing.txt \ @@ -102,7 +101,6 @@ html_files = \ html/api-basics.html \ html/changelog.html \ html/changes.html \ - html/commonjs.html \ html/config_reference.html \ html/configuring.html \ html/ddocs.html \ @@ -146,7 +144,6 @@ src_files = \ ../src/api-basics.rst \ ../src/changelog.rst \ ../src/changes.rst \ - ../src/commonjs.rst \ ../src/config_reference.rst \ ../src/configuring.rst \ ../src/contributing.rst \ diff --git a/share/doc/src/commonjs.rst b/share/doc/src/commonjs.rst deleted file mode 100644 index 49ccaa632..000000000 --- a/share/doc/src/commonjs.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. Licensed under the Apache License, Version 2.0 (the "License"); you may not -.. use this file except in compliance with the License. You may obtain a copy of -.. the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -.. License for the specific language governing permissions and limitations under -.. the License. - -.. _commonjs: - -CommonJS support for map functions -================================== - -CommonJS support allows you to use `CommonJS notation <http://commonjs.org/specs>`_ -inside map and reduce functions, but only of libraries that are stored -inside the views part of the design doc. - -So you could continue to access CommonJS code in design\_doc.foo, from -your list functions etc, but we'd add the ability to require CommonJS -modules within map and reduce, but only from ``design_doc.views.lib``. - -There's no worry here about namespace collisions, as Couch just plucks -``views.*.map`` and ``views.*.reduce`` out of the design doc. So you -could have a view called ``lib`` if you wanted, and still have CommonJS -stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted. - -The implementation is simplified by enforcing that CommonJS modules to -be used in map functions be stored in views.lib. - -A sample design doc (taken from the test suite in Futon) is below: - -.. code-block:: javascript - - { - "views" : { - "lib" : { - "baz" : "exports.baz = 'bam';", - "foo" : { - "zoom" : "exports.zoom = 'yeah';", - "boom" : "exports.boom = 'ok';", - "foo" : "exports.foo = 'bar';" - } - }, - "commonjs" : { - "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" - } - }, - "_id" : "_design/test" - } - -The ``require()`` statement is relative to the design document, but -anything loaded form outside of ``views/lib`` will fail. diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst index 06f79a6d3..48df77cae 100644 --- a/share/doc/src/index.rst +++ b/share/doc/src/index.rst @@ -34,7 +34,6 @@ Contents replication ddocs query-servers - commonjs errors changes release diff --git a/share/doc/src/query-servers.rst b/share/doc/src/query-servers.rst index 64f9bfb97..a40468d90 100644 --- a/share/doc/src/query-servers.rst +++ b/share/doc/src/query-servers.rst @@ -236,7 +236,7 @@ modules and functions: :param obj: JSON encodable object :return: JSON string - +.. _commonjs: CommonJS Modules ---------------- @@ -249,61 +249,11 @@ Here's a CommonJS module that checks user permissions: .. code-block:: javascript - function user_context(userctx, secobj){ - var is_admin = function(){ + function user_context(userctx, secobj) { + var is_admin = function() { return userctx.indexOf('_admin') != -1; } - var is_db_admin = function(){ - if (is_admin() || !secobj){ - return true; - } - if (secobj.admins.names.indexOf(userctx.name) != -1){ - return true; - } - for (var idx in userctx.roles){ - if (secobj.admins.roles.indexOf(userctx.roles[idx]) != -1){ - return true; - } - } - return false; - } - var is_db_member = function(){ - if (is_admin() || is_db_admin() || !secobj){ - return true; - } - if (secobj.members.names.indexOf(userctx.name) != -1){ - return true; - } - for (var idx in userctx.roles){ - if (secobj.members.roles.indexOf(userctx.roles[idx]) != -1){ - return true; - } - } - return false; - } - var has_all_roles = function(roles){ - for (var idx in roles){ - if (userctx.roles.indexOf(roles[idx]) == -1){ - return false; - } - } - return true; - } - var has_any_role = function(roles){ - for (var idx in roles){ - if (userctx.roles.indexOf(roles[idx]) != -1){ - return true; - } - } - return false; - } - return { - 'is_admin': is_admin, - 'is_db_admin': is_db_admin, - 'is_db_member': is_db_member, - 'has_all_roles': has_all_roles, - 'has_any_role': has_any_role - } + return {'is_admin': is_admin} } exports['user'] = user_context @@ -319,21 +269,27 @@ Each module has access to additional global variables: - **exports** (`object`): Shortcut to the ``module.exports`` object -This module can be used after adding it to the design document, for example, -under the `lib/validate` path. We may then use it in our view functions: +The CommonJS module can be added to a design document, like so: .. code-block:: javascript - function(newdoc, olddoc, userctx, secobj){ - user = require('lib/validate').user(userctx, secobj); - if (user.is_admin()){ - return true; - } - if (newdoc.author != olddoc.author){ - throw({'forbidden': 'unable to update `author` field'}); - } + { + "views": { + "lib": { + "security": "function user_context(userctx, secobj) { ... }" + }, + "validate_doc_update": "function(newdoc, olddoc, userctx, secobj) { + user = require('lib/security').user(userctx, secobj); + return user.is_admin(); + }" + }, + "_id": "_design/test" } +Modules paths are relative to the design document's ``views`` object, but +modules can only be loaded from the object referenced via ``lib``. The +``lib`` structure can still be used for view functions as well, by simply +storing view functions at e.g. ``views.lib.map``, ``views.lib.reduce``, etc. .. _queryserver_erlang: |