rlx-external(3) -- external executables
=======================================

## SYNOPSIS

This manual describes the function of each of the external executables.

## LANUGAGES

The external executables are available in the following languages:

* node
* perl
* python
* ruby

## BEHAVIOUR

Each executable *must* exhibit the following behaviour:

* Read and parse a JSON document from stdin
* Exit with 0 on success and >0 on error
* Must be able to parse JSON primitive types (contrary to the specification)
* Errors must be printed to the stderr stream

## EXECUTABLES

* `authdb`:

Extracts the authentication database name from the `info.authentication_db` field of a session document.

* `authenticated`:

Extracts username and roles from a session document. Exits with a 0 exit code if the user is authenticated or >0 if the user is not authenticated. The username is concatenated with the user roles and printed newline delimited.

Whether a user is authenticated is determined by the presence of the `info.authenticated` field.

* `error`:

Extract and print the *error* and *reason* fields from an error response. The output is the error concatenated with reason using a space as a delimiter. If a parse error occurs or both the error and reason fields do not exist a >0 exit code is used.

* `invert`:

Reverse the rows array from a view result query. If the input document does not have a rows field then it is printed untouched. The behaviour when a rows field is present but not an array is undefined it is likely an exception will occur.

* `keys`:

Print the top-level keys for a document with each key on a separate line, exits with a >0 exit code if a parse error occurs.

* `lint`:

Parses a JSON document and reports of parse errors. It must respect the `JSON_INDENT` environment variable which indicates the number of spaces to be used to indent the resulting document.

If `JSON_INDENT` is zero the output should be compact otherwise the output is indented.

* `method`:

Reads a function definition as a string from stdin and prints a compact JSON representation of the function.

* `paginate`:

Reads a document returned from a view query and writes to a temporary file containing information to enable pagination of the view query. This program where appropriate will remove the last entry in the *rows* array so that only the requested rows are displayed, the last row entry is used as the *startkey* and *startkey_docid* for the next page.

* `querystring`:

Parse a document describing the parameters for a view query and return a querystring suitable for sending to the server.

* `stringify [coerce]`:

Parses a string representing a primitive value and optionally coerces to a string representation if the *coerce* option is set to `true`.

* `template`:

Load a template for the same language and return a JSON representation of the template respecting the `JSON_INDENT` environment variable.

* `version`:

Extract and print the version field for a document, exits with >0 if a version field does not exist.

* `whoami`:

Print the value of the `userCtx.name` field of a session document.

## BUGS

**rlx** is written in bash and depends upon `bash >= 4.2`.

## COPYRIGHT

**rlx** is copyright (c) 2013 muji <http://xpm.io>

## SEE ALSO

rlx(1), couchdb(3)


[SYNOPSIS]: #SYNOPSIS "SYNOPSIS"
[LANUGAGES]: #LANUGAGES "LANUGAGES"
[BEHAVIOUR]: #BEHAVIOUR "BEHAVIOUR"
[EXECUTABLES]: #EXECUTABLES "EXECUTABLES"
[BUGS]: #BUGS "BUGS"
[COPYRIGHT]: #COPYRIGHT "COPYRIGHT"
[SEE ALSO]: #SEE-ALSO "SEE ALSO"


[rlx-alias(3)]: rlx-alias.3.html
[rlx-attach(3)]: rlx-attach.3.html
[rlx-auth(3)]: rlx-auth.3.html
[rlx-bulk(3)]: rlx-bulk.3.html
[rlx-config(3)]: rlx-config.3.html
[rlx-db(3)]: rlx-db.3.html
[rlx-debug(3)]: rlx-debug.3.html
[rlx-design(3)]: rlx-design.3.html
[rlx-doc(3)]: rlx-doc.3.html
[rlx-external(3)]: rlx-external.3.html
[rlx-page(3)]: rlx-page.3.html
[rlx-repl(3)]: rlx-repl.3.html
[rlx-server(3)]: rlx-server.3.html
[rlx-settings(3)]: rlx-settings.3.html
[rlx-tpl(3)]: rlx-tpl.3.html
[rlx(1)]: rlx.1.html