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)