You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/07/24 14:24:52 UTC
[15/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to fa11c25
Split query-servers article into the group.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/57e35fe9
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/57e35fe9
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/57e35fe9
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 57e35fe95563a921331894f3f057ca0fed03d2ea
Parents: 82478ae
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Jul 23 23:09:03 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Jul 24 10:48:37 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 12 +-
share/doc/src/config/query-servers.rst | 4 +-
share/doc/src/ddocs.rst | 4 +-
share/doc/src/index.rst | 2 +-
share/doc/src/query-server/erlang.rst | 138 ++++++++
share/doc/src/query-server/index.rst | 38 +++
share/doc/src/query-server/javascript.rst | 288 +++++++++++++++++
share/doc/src/query-servers.rst | 418 -------------------------
8 files changed, 478 insertions(+), 426 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index a8c8fca..a85db77 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -68,6 +68,9 @@ html_files = \
html/_sources/config/services.txt \
html/_sources/config/intro.txt \
html/_sources/config/proxying.txt \
+ html/_sources/query-server/index.txt \
+ html/_sources/query-server/erlang.txt \
+ html/_sources/query-server/javascript.txt \
html/_sources/replications/conflicts.txt \
html/_sources/replications/index.txt \
html/_sources/replications/intro.txt \
@@ -80,7 +83,6 @@ html_files = \
html/_sources/index.txt \
html/_sources/intro.txt \
html/_sources/json-structure.txt \
- html/_sources/query-servers.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
html/_static/comment-bright.png \
@@ -127,6 +129,9 @@ html_files = \
html/config/services.html \
html/config/intro.html \
html/config/proxying.html \
+ html/query-server/index.html \
+ html/query-server/erlang.html \
+ html/query-server/javascript.html \
html/replications/conflicts.html \
html/replications/index.html \
html/replications/intro.html \
@@ -138,7 +143,6 @@ html_files = \
html/index.html \
html/intro.html \
html/json-structure.html \
- html/query-servers.html \
html/objects.inv \
html/genindex.html \
html/search.html \
@@ -184,6 +188,9 @@ src_files = \
../src/config/services.rst \
../src/config/intro.rst \
../src/config/proxying.rst \
+ ../src/query-server/index.rst \
+ ../src/query-server/erlang.rst \
+ ../src/query-server/javascript.rst \
../src/replication/conflicts.rst \
../src/replication/index.rst \
../src/replication/intro.rst \
@@ -196,7 +203,6 @@ src_files = \
../src/index.rst \
../src/intro.rst \
../src/json-structure.rst \
- ../src/query-servers.rst \
../src/conf.py
src_files_html = \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/config/query-servers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/query-servers.rst b/share/doc/src/config/query-servers.rst
index 92d7ede..5462753 100644
--- a/share/doc/src/config/query-servers.rst
+++ b/share/doc/src/config/query-servers.rst
@@ -50,7 +50,7 @@ Where:
- ``ARGS``: optionally, you may specify additional command line arguments for
the executable ``PATH``.
-The default query server is written in :ref:`Javascript <queryserver_js>`,
+The default query server is written in :ref:`JavaScript <query-server/js>`,
running via `Mozilla SpiderMonkey`_::
[query_servers]
@@ -140,7 +140,7 @@ First, you'll need to edit your `local.ini` to include a
erlang = {couch_native_process, start_link, []}
To see these changes you will also need to restart the server.
-To test out using :ref:`Erlang views <queryserver_erlang>`, visit the
+To test out using :ref:`Erlang views <query-server/erlang>`, visit the
`Futon` admin interface, create a new database and open a temporary view.
You should now be able to select ``erlang`` from the language drop-down.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/ddocs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/ddocs.rst b/share/doc/src/ddocs.rst
index 0bb2c9d..45a3773 100644
--- a/share/doc/src/ddocs.rst
+++ b/share/doc/src/ddocs.rst
@@ -19,7 +19,7 @@ Design Docs
===========
In this section we'll show how to write design documents, using the built-in
-:ref:`JavaScript Query Server <queryserver_js>`.
+:ref:`JavaScript Query Server <query-server/js>`.
But before we start to write our first function, let's take a look at the list
of common objects that will be used during our code journey - we'll be using
@@ -30,7 +30,7 @@ them extensively within each function:
- :ref:`Response object <response_object>`
- :ref:`UserCtx object <userctx_object>`
- :ref:`Database Security object <security_object>`
-- :ref:`Guide to JavaScript Query Server <queryserver_js>`
+- :ref:`Guide to JavaScript Query Server <query-server/js>`
.. _viewfun:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 1ff3d40..2fcdb00 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -31,7 +31,7 @@ Contents
config/index
replication/index
ddocs
- query-servers
+ query-server/index
changes
api/index
json-structure
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/query-server/erlang.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/erlang.rst b/share/doc/src/query-server/erlang.rst
new file mode 100644
index 0000000..21f2399
--- /dev/null
+++ b/share/doc/src/query-server/erlang.rst
@@ -0,0 +1,138 @@
+.. 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.
+
+
+.. _query-server/erlang:
+
+Erlang
+======
+
+.. note::
+
+ The Erlang query server is disabled by default.
+ Read :ref:`configuration guide <config/native_query_servers>` about
+ reasons why and how to enable it.
+
+.. function:: Emit(Id, Value)
+
+ Emits `key`-`value` pairs to view indexer process.
+
+ .. code-block:: erlang
+
+ fun({Doc}) ->
+ <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
+ V = proplists:get_value(<<"_id">>, Doc, null),
+ Emit(<<K>>, V)
+ end.
+
+
+.. function:: FoldRows(Fun, Acc)
+
+ Helper to iterate over all rows in a list function.
+
+ :param Fun: Function object.
+ :param Acc: The value previously returned by `Fun`.
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Fun = fun({Row}, Acc) ->
+ Id = couch_util:get_value(<<"id">>, Row),
+ Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))),
+ Send(list_to_binary(io_lib:format("Current doc id: ~p~n", [Id]))),
+ {ok, Id}
+ end,
+ FoldRows(Fun, nil),
+ ""
+ end.
+
+
+.. function:: GetRow()
+
+ Retrieves the next row from a related view result.
+
+ .. code-block:: erlang
+
+ %% FoldRows background implementation.
+ %% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368
+ %%
+ foldrows(GetRow, ProcRow, Acc) ->
+ case GetRow() of
+ nil ->
+ {ok, Acc};
+ Row ->
+ case (catch ProcRow(Row, Acc)) of
+ {ok, Acc2} ->
+ foldrows(GetRow, ProcRow, Acc2);
+ {stop, Acc2} ->
+ {ok, Acc2}
+ end
+ end.
+
+.. function:: Log(Msg)
+
+ :param Msg: Log a message at the `INFO` level.
+
+ .. code-block:: erlang
+
+ fun({Doc}) ->
+ <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
+ V = proplists:get_value(<<"_id">>, Doc, null),
+ Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))),
+ Emit(<<K>>, V)
+ end.
+
+ After the map function has run, the following line can be found in
+ CouchDB logs (e.g. at `/var/log/couchdb/couch.log`):
+
+ .. code-block:: text
+
+ [Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc!
+
+
+.. function:: Send(Chunk)
+
+ Sends a single string `Chunk` in response.
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Send("Hello,"),
+ Send(" "),
+ Send("Couch"),
+ "!"
+ end.
+
+ The function above produces the following response:
+
+ .. code-block:: text
+
+ Hello, Couch!
+
+
+.. function:: Start(Headers)
+
+ :param Headers: Proplist of :ref:`response object<response_object>`.
+
+ Initialize :ref:`listfun` response. At this point, response code and headers
+ may be defined. For example, this function redirects to the CouchDB web site:
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Start({[{<<"code">>, 302},
+ {<<"headers">>, {[
+ {<<"Location">>, <<"http://couchdb.apache.org">>}]
+ }}
+ ]}),
+ "Relax!"
+ end.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/query-server/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/index.rst b/share/doc/src/query-server/index.rst
new file mode 100644
index 0000000..8112549
--- /dev/null
+++ b/share/doc/src/query-server/index.rst
@@ -0,0 +1,38 @@
+.. 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.
+
+
+============
+Query Server
+============
+
+The `Query server` is an external process that communicates with CouchDB by JSON
+protocol through stdio interface and processed all
+:ref:`design functions <ddocs>` calls:
+:ref:`views <viewfun>`, :ref:`shows <showfun>`, :ref:`lists <listfun>` and more.
+
+The default query server is written in
+:ref:`JavaScript <query-server/js>`, running via `Mozilla SpiderMonkey`_.
+You can use other languages by setting a Query server key in the ``language``
+property of a design document or the `Content-Type` header of a
+`temporary view`. Design documents that do not specify a ``language`` property
+are assumed to be of type `javascript`, as are ad hoc queries that are POSTed to
+:ref:`_temp_view <api/db/temp_view>` without a `Content-Type` header.
+
+.. _Mozilla SpiderMonkey: https://developer.mozilla.org/en/docs/SpiderMonkey
+
+.. toctree::
+ :maxdepth: 2
+
+ javascript
+ erlang
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/query-server/javascript.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/javascript.rst b/share/doc/src/query-server/javascript.rst
new file mode 100644
index 0000000..16590d6
--- /dev/null
+++ b/share/doc/src/query-server/javascript.rst
@@ -0,0 +1,288 @@
+.. 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.
+
+.. default-domain:: js
+
+.. _query-server/js:
+
+JavaScript
+==========
+
+.. note:: While every design function has access to all JavaScript objects,
+ the table below describes appropriate usage cases. For example,
+ you may use :func:`emit` in :ref:`listfun`, but :func:`getRow` is not permitted during :ref:`mapfun`.
+
++--------------------------------+---------------------------------------------+
+| JS Function | Reasonable to use in design doc functions |
++================================+=============================================+
+| :func:`emit` | :ref:`mapfun` |
++--------------------------------+---------------------------------------------+
+| :func:`getRow` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :data:`JSON` | any |
++--------------------------------+---------------------------------------------+
+| :func:`isArray` | any |
++--------------------------------+---------------------------------------------+
+| :func:`log` | any |
++--------------------------------+---------------------------------------------+
+| :func:`provides` | :ref:`showfun`, :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`registerType` | :ref:`showfun`, :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`require` | any, except :ref:`reducefun` |
++--------------------------------+---------------------------------------------+
+| :func:`send` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`start` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`sum` | any |
++--------------------------------+---------------------------------------------+
+| :func:`toJSON` | any |
++--------------------------------+---------------------------------------------+
+
+Design functions context
+------------------------
+
+Each design function executes in a special context of predefined objects,
+modules and functions:
+
+
+.. function:: emit(key, value)
+
+ Emits a `key`-`value` pair for further processing by CouchDB after the map
+ function is done.
+
+ :param key: The view key
+ :param value: The `key`'s associated value
+
+ .. code-block:: javascript
+
+ function(doc){
+ emit(doc._id, doc._rev);
+ }
+
+
+.. function:: getRow()
+
+ Extracts the next row from a related view result.
+
+ :return: View result row
+ :rtype: object
+
+ .. code-block:: javascript
+
+ function(head, req){
+ send('[');
+ row = getRow();
+ if (row){
+ send(toJSON(row));
+ while(row = getRow()){
+ send(',');
+ send(toJSON(row));
+ }
+ }
+ return ']';
+ }
+
+
+.. data:: JSON
+
+ `JSON2 <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=share/server/json2.js>`_
+ object.
+
+
+.. function:: isArray(obj)
+
+ A helper function to check if the provided value is an `Array`.
+
+ :param obj: Any Javascript value
+ :return: ``true`` if `obj` is `Array`-typed, ``false`` otherwise
+ :rtype: boolean
+
+
+.. function:: log(message)
+
+ Log a message to the CouchDB log (at the `INFO` level).
+
+ :param message: Message to be logged
+
+ .. code-block:: javascript
+
+ function(doc){
+ log('Procesing doc ' + doc['_id']);
+ emit(doc['_id'], null);
+ }
+
+ After the map function has run, the following line can be found in CouchDB
+ logs (e.g. at `/var/log/couchdb/couch.log`):
+
+ .. code-block:: text
+
+ [Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467
+
+
+.. function:: provides(key, func)
+
+ Registers callable handler for specified MIME key.
+
+ :param key: MIME key previously defined by :func:`registerType`
+ :param func: MIME type handler
+
+
+.. function:: registerType(key, *mimes)
+
+ Registers list of MIME types by associated `key`.
+
+ :param key: MIME types
+ :param mimes: MIME types enumeration
+
+ Predefined mappings (`key`-`array`):
+
+ - **all**: ``*/*``
+ - **text**: ``text/plain; charset=utf-8``, ``txt``
+ - **html**: ``text/html; charset=utf-8``
+ - **xhtml**: ``application/xhtml+xml``, ``xhtml``
+ - **xml**: ``application/xml``, ``text/xml``, ``application/x-xml``
+ - **js**: ``text/javascript``, ``application/javascript``,
+ ``application/x-javascript``
+ - **css**: ``text/css``
+ - **ics**: ``text/calendar``
+ - **csv**: ``text/csv``
+ - **rss**: ``application/rss+xml``
+ - **atom**: ``application/atom+xml``
+ - **yaml**: ``application/x-yaml``, ``text/yaml``
+ - **multipart_form**: ``multipart/form-data``
+ - **url_encoded_form**: ``application/x-www-form-urlencoded``
+ - **json**: ``application/json``, ``text/x-json``
+
+
+.. function:: require(path)
+
+ Loads CommonJS module by a specified `path`. The path should not start with
+ a slash.
+
+ :param path: A CommonJS module path started from design document root
+ :return: Exported statements
+
+
+.. function:: send(chunk)
+
+ Sends a single string `chunk` in response.
+
+ :param chunk: Text chunk
+
+ .. code-block:: javascript
+
+ function(head, req){
+ send('Hello,');
+ send(' ');
+ send('Couch');
+ return !
+ }
+
+
+.. function:: start(init_resp)
+
+ Initiates chunked response. As an option, a custom
+ :ref:`response <response_object>` object may be sent at this point.
+ For `list`-functions only!
+
+ .. note::
+
+ list functions may set the `HTTP response code` and `headers` by calling
+ this function. This function must be called before :func:`send`,
+ :func:`getRow` or a `return` statement; otherwise, the query server will
+ implicitly call this function with the empty object (``{}``).
+
+ .. code-block:: javascript
+
+ function(head, req){
+ start({
+ "code": 302,
+ "headers": {
+ "Location": "http://couchdb.apache.org"
+ }
+ });
+ return "Relax!";
+ }
+
+
+.. function:: sum(arr)
+
+ Sum `arr`'s items.
+
+ :param arr: Array of numbers
+ :rtype: number
+
+
+.. function:: toJSON(obj)
+
+ Encodes `obj` to JSON string. This is an alias for the ``JSON.stringify``
+ method.
+
+ :param obj: JSON encodable object
+ :return: JSON string
+
+.. _commonjs:
+
+CommonJS Modules
+----------------
+
+Support for `CommonJS Modules <http://wiki.commonjs.org/wiki/Modules/1.1.1>`_
+(introduced in CouchDB 0.11.0) allows you to create modular design functions
+without the need for duplication of functionality.
+
+Here's a CommonJS module that checks user permissions:
+
+.. code-block:: javascript
+
+ function user_context(userctx, secobj) {
+ var is_admin = function() {
+ return userctx.indexOf('_admin') != -1;
+ }
+ return {'is_admin': is_admin}
+ }
+
+ exports['user'] = user_context
+
+Each module has access to additional global variables:
+
+- **module** (`object`): Contains information about the stored module
+
+ - **id** (`string`): The module id; a JSON path in ddoc context
+ - **current** (`code`): Compiled module code object
+ - **parent** (`object`): Parent frame
+ - **exports** (`object`): Export statements
+
+- **exports** (`object`): Shortcut to the ``module.exports`` object
+
+The CommonJS module can be added to a design document, like so:
+
+.. code-block:: javascript
+
+ {
+ "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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/57e35fe9/share/doc/src/query-servers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-servers.rst b/share/doc/src/query-servers.rst
deleted file mode 100644
index 82a3c0e..0000000
--- a/share/doc/src/query-servers.rst
+++ /dev/null
@@ -1,418 +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.
-
-.. default-domain:: js
-
-=============
-Query Servers
-=============
-
-.. _queryserver_js:
-
-JavaScript
-==========
-
-.. note:: While every design function has access to all JavaScript objects,
- the table below describes appropriate usage cases. For example,
- you may use :func:`emit` in :ref:`listfun`, but :func:`getRow` is not permitted during :ref:`mapfun`.
-
-+--------------------------------+---------------------------------------------+
-| JS Function | Reasonable to use in design doc functions |
-+================================+=============================================+
-| :func:`emit` | :ref:`mapfun` |
-+--------------------------------+---------------------------------------------+
-| :func:`getRow` | :ref:`listfun` |
-+--------------------------------+---------------------------------------------+
-| :data:`JSON` | any |
-+--------------------------------+---------------------------------------------+
-| :func:`isArray` | any |
-+--------------------------------+---------------------------------------------+
-| :func:`log` | any |
-+--------------------------------+---------------------------------------------+
-| :func:`provides` | :ref:`showfun`, :ref:`listfun` |
-+--------------------------------+---------------------------------------------+
-| :func:`registerType` | :ref:`showfun`, :ref:`listfun` |
-+--------------------------------+---------------------------------------------+
-| :func:`require` | any, except :ref:`reducefun` |
-+--------------------------------+---------------------------------------------+
-| :func:`send` | :ref:`listfun` |
-+--------------------------------+---------------------------------------------+
-| :func:`start` | :ref:`listfun` |
-+--------------------------------+---------------------------------------------+
-| :func:`sum` | any |
-+--------------------------------+---------------------------------------------+
-| :func:`toJSON` | any |
-+--------------------------------+---------------------------------------------+
-
-Design functions context
-------------------------
-
-Each design function executes in a special context of predefined objects,
-modules and functions:
-
-
-.. function:: emit(key, value)
-
- Emits a `key`-`value` pair for further processing by CouchDB after the map
- function is done.
-
- :param key: The view key
- :param value: The `key`'s associated value
-
- .. code-block:: javascript
-
- function(doc){
- emit(doc._id, doc._rev);
- }
-
-
-.. function:: getRow()
-
- Extracts the next row from a related view result.
-
- :return: View result row
- :rtype: object
-
- .. code-block:: javascript
-
- function(head, req){
- send('[');
- row = getRow();
- if (row){
- send(toJSON(row));
- while(row = getRow()){
- send(',');
- send(toJSON(row));
- }
- }
- return ']';
- }
-
-
-.. data:: JSON
-
- `JSON2 <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=share/server/json2.js>`_
- object.
-
-
-.. function:: isArray(obj)
-
- A helper function to check if the provided value is an `Array`.
-
- :param obj: Any Javascript value
- :return: ``true`` if `obj` is `Array`-typed, ``false`` otherwise
- :rtype: boolean
-
-
-.. function:: log(message)
-
- Log a message to the CouchDB log (at the `INFO` level).
-
- :param message: Message to be logged
-
- .. code-block:: javascript
-
- function(doc){
- log('Procesing doc ' + doc['_id']);
- emit(doc['_id'], null);
- }
-
- After the map function has run, the following line can be found in CouchDB
- logs (e.g. at `/var/log/couchdb/couch.log`):
-
- .. code-block:: text
-
- [Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467
-
-
-.. function:: provides(key, func)
-
- Registers callable handler for specified MIME key.
-
- :param key: MIME key previously defined by :func:`registerType`
- :param func: MIME type handler
-
-
-.. function:: registerType(key, *mimes)
-
- Registers list of MIME types by associated `key`.
-
- :param key: MIME types
- :param mimes: MIME types enumeration
-
- Predefined mappings (`key`-`array`):
-
- - **all**: ``*/*``
- - **text**: ``text/plain; charset=utf-8``, ``txt``
- - **html**: ``text/html; charset=utf-8``
- - **xhtml**: ``application/xhtml+xml``, ``xhtml``
- - **xml**: ``application/xml``, ``text/xml``, ``application/x-xml``
- - **js**: ``text/javascript``, ``application/javascript``,
- ``application/x-javascript``
- - **css**: ``text/css``
- - **ics**: ``text/calendar``
- - **csv**: ``text/csv``
- - **rss**: ``application/rss+xml``
- - **atom**: ``application/atom+xml``
- - **yaml**: ``application/x-yaml``, ``text/yaml``
- - **multipart_form**: ``multipart/form-data``
- - **url_encoded_form**: ``application/x-www-form-urlencoded``
- - **json**: ``application/json``, ``text/x-json``
-
-
-.. function:: require(path)
-
- Loads CommonJS module by a specified `path`. The path should not start with
- a slash.
-
- :param path: A CommonJS module path started from design document root
- :return: Exported statements
-
-
-.. function:: send(chunk)
-
- Sends a single string `chunk` in response.
-
- :param chunk: Text chunk
-
- .. code-block:: javascript
-
- function(head, req){
- send('Hello,');
- send(' ');
- send('Couch');
- return !
- }
-
-
-.. function:: start(init_resp)
-
- Initiates chunked response. As an option, a custom
- :ref:`response <response_object>` object may be sent at this point.
- For `list`-functions only!
-
- .. note::
-
- list functions may set the `HTTP response code` and `headers` by calling
- this function. This function must be called before :func:`send`,
- :func:`getRow` or a `return` statement; otherwise, the query server will
- implicitly call this function with the empty object (``{}``).
-
- .. code-block:: javascript
-
- function(head, req){
- start({
- "code": 302,
- "headers": {
- "Location": "http://couchdb.apache.org"
- }
- });
- return "Relax!";
- }
-
-
-.. function:: sum(arr)
-
- Sum `arr`'s items.
-
- :param arr: Array of numbers
- :rtype: number
-
-
-.. function:: toJSON(obj)
-
- Encodes `obj` to JSON string. This is an alias for the ``JSON.stringify``
- method.
-
- :param obj: JSON encodable object
- :return: JSON string
-
-.. _commonjs:
-
-CommonJS Modules
-----------------
-
-Support for `CommonJS Modules <http://wiki.commonjs.org/wiki/Modules/1.1.1>`_
-(introduced in CouchDB 0.11.0) allows you to create modular design functions
-without the need for duplication of functionality.
-
-Here's a CommonJS module that checks user permissions:
-
-.. code-block:: javascript
-
- function user_context(userctx, secobj) {
- var is_admin = function() {
- return userctx.indexOf('_admin') != -1;
- }
- return {'is_admin': is_admin}
- }
-
- exports['user'] = user_context
-
-Each module has access to additional global variables:
-
-- **module** (`object`): Contains information about the stored module
-
- - **id** (`string`): The module id; a JSON path in ddoc context
- - **current** (`code`): Compiled module code object
- - **parent** (`object`): Parent frame
- - **exports** (`object`): Export statements
-
-- **exports** (`object`): Shortcut to the ``module.exports`` object
-
-The CommonJS module can be added to a design document, like so:
-
-.. code-block:: javascript
-
- {
- "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:
-
-Erlang
-======
-
-.. note::
-
- The Erlang query server is disabled by default.
- Read :ref:`configuration guide <config/native_query_servers>` about
- reasons why and how to enable it.
-
-.. function:: Emit(Id, Value)
-
- Emits `key`-`value` pairs to view indexer process.
-
- .. code-block:: erlang
-
- fun({Doc}) ->
- <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
- V = proplists:get_value(<<"_id">>, Doc, null),
- Emit(<<K>>, V)
- end.
-
-
-.. function:: FoldRows(Fun, Acc)
-
- Helper to iterate over all rows in a list function.
-
- :param Fun: Function object.
- :param Acc: The value previously returned by `Fun`.
-
- .. code-block:: erlang
-
- fun(Head, {Req}) ->
- Fun = fun({Row}, Acc) ->
- Id = couch_util:get_value(<<"id">>, Row),
- Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))),
- Send(list_to_binary(io_lib:format("Current doc id: ~p~n", [Id]))),
- {ok, Id}
- end,
- FoldRows(Fun, nil),
- ""
- end.
-
-
-.. function:: GetRow()
-
- Retrieves the next row from a related view result.
-
- .. code-block:: erlang
-
- %% FoldRows background implementation.
- %% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368
- %%
- foldrows(GetRow, ProcRow, Acc) ->
- case GetRow() of
- nil ->
- {ok, Acc};
- Row ->
- case (catch ProcRow(Row, Acc)) of
- {ok, Acc2} ->
- foldrows(GetRow, ProcRow, Acc2);
- {stop, Acc2} ->
- {ok, Acc2}
- end
- end.
-
-.. function:: Log(Msg)
-
- :param Msg: Log a message at the `INFO` level.
-
- .. code-block:: erlang
-
- fun({Doc}) ->
- <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
- V = proplists:get_value(<<"_id">>, Doc, null),
- Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))),
- Emit(<<K>>, V)
- end.
-
- After the map function has run, the following line can be found in
- CouchDB logs (e.g. at `/var/log/couchdb/couch.log`):
-
- .. code-block:: text
-
- [Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc!
-
-
-.. function:: Send(Chunk)
-
- Sends a single string `Chunk` in response.
-
- .. code-block:: erlang
-
- fun(Head, {Req}) ->
- Send("Hello,"),
- Send(" "),
- Send("Couch"),
- "!"
- end.
-
- The function above produces the following response:
-
- .. code-block:: text
-
- Hello, Couch!
-
-
-.. function:: Start(Headers)
-
- :param Headers: Proplist of :ref:`response object<response_object>`.
-
- Initialize :ref:`listfun` response. At this point, response code and headers
- may be defined. For example, this function redirects to the CouchDB web site:
-
- .. code-block:: erlang
-
- fun(Head, {Req}) ->
- Start({[{<<"code">>, 302},
- {<<"headers">>, {[
- {<<"Location">>, <<"http://couchdb.apache.org">>}]
- }}
- ]}),
- "Relax!"
- end.