NAME

CouchDB::ExternalProcess - Make creating Perl-based external processs for CouchDB easy

SYNOPSIS

In MyProcess.pm:

  package MyProcess;
  use base qw/CouchDB::ExternalProcess/;

  sub _before {
      my ($self, $request) = @_;
      # Do something with the hashref $request
      return $request;
  }

  sub hello_world :Action {
      my ($self, $req) = @_;
      my $response = {
          body => "Hello, " . $req->{query}->{greeting_target} . "!"
      };
      return $response;
  }

  sub _after {
      my ($self,$response) = @_;
      # Do something with the hashref $response
      return $response;
  }

In CouchDB's local.ini:

  [external]
  my_process = perl -MMyProcess -e 'MyProcess->new->run'

  [httpd_db_handlers]
  _my_process = {couch_httpd_external, handle_external_req, <<"my_process">>}

Now queries to the database databaseName as:

  http://myserver/databaseName/_my_process/hello_world/?greeting_target=Sally

Will return a document with Content-Type "text/html" and a body containing:

  Hello, Sally!

For more information, including the request and response data structure formats, see:

http://wiki.apache.org/couchdb/ExternalProcesses

DESCRIPTION

This module makes creating CouchDB External Processes simple and concise.

USAGE

METHODS

new

Create an external process, just needs run() to be called to start processing STDIN.

run

Run the action, read lines from STDIN and process them one by one

Named arguments can be passed to run like run(a => 1, c => 2).

Accepted arguments are:

in_fh

File Handle to read input from. *STDIN by default

out_fh

File handle to write output to. *STDOUT by default

jsonParser

getter/setter for the JSON::Any instance used for an instance.

All methods of an ExternalProcess class should use this processor so they can share the same magical 'true' and 'false' markers.

CHILD CLASS METHODS

These methods may be overridden by child classes to add processing to various parts of the script and request handling lifecycle

_init

Called at program startup before any requests are processed.

_destroy

Called when STDIN is closed, or at program termination (if possible)

_before

Receives, and can manipulate or replace, the JSON request as hash reference produced by JSON::Any before the requested action is processed.

_after

Passed the return value of whatever action was called, as a hash reference parseable by JSON::Any. May modify or replace it.

_error

Passed any errors that occur during processing. Returns a hash reference to be used as the response.

The default response for an error $error is:

  {
      code => 500,
      json => {
          error => $error
      }
  }

_extract_action_name

Extracts the name of the action to handle a request.

Receives the request object. Defaults to:

$req-{path}->[2]>

PROVIDED ACTIONS

_meta

Returns metadata about the methods we're providing

If your module has the following Actions:

  sub foo :Action :Description("Foo!") :Args("Some data") {
    # ... 
  }

  sub bar :Action
          :Description("Get your Bar on!")
          :Args({name => "Name of something", color => "RGB Color Value"}) 
  {
    # ... 
  }

Then requesting the '_meta' action will return the following JSON:

  {
    "foo": {
        "description": "Foo!",
        "args": "Some data"
    },
    "bar": }
        "description": "Get your Bar on!",
        "args": "Some data"
    }
  }

INTERNAL METHODS - Ignore these!

_process

Process a request.

Receives one argument, a JSON string, does all CouchDB::ExternalProcess processing and returns a valid External Process response.

Action

Processes 'Action' Attribute

Description

Processes 'Description' Attribute

Args

Processes 'Args' Attribute

attrArgs

Helper method to process Attribute::Handlers arguments

BUGS

SUPPORT

AUTHOR

    Mike Walker
    CPAN ID: FANSIPANS
    mike-cpan-couchdb-externalprocess@napkindrawing.com
    http://napkindrawing.com/

COPYRIGHT

This program is free software licensed under the...

        The BSD License

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).

CouchDB ExternalProcesses http://wiki.apache.org/couchdb/ExternalProcesses

cpanm CouchDB::ExternalProcess

perl -MCPAN -e shell
install CouchDB::ExternalProcess