NAME

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

SYNOPSIS

  In C<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 C<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 I<databaseName> as:
  
    C<http://myserver/databaseName/_my_process/hello_world/?greeting_target=Sally>

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

    C<Hello, Sally!>

  The power really comes when the External Process API is used to generate and
  parse JSON requests.

  See L<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 C<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:

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

INTERNAL METHODS

_process

 Process a request.

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

_meta

 Returns metadata about the methods we're providing

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