NAME

Contentment::Transform - Applies file content transformation

SYNOPSIS

  use Contentment::Transform;
  use IO::NestedCapture 'capture_in_out';

  my $transformer = $context->transformer;

  my $in = IO::NestedCapture->get_next_in;
  # print the input to $in...

  capture_in_out {
      $transformer->apply_transformation(
          from => 'LaTeX',
          to   => 'PDF',
      );
  };

  # $out here contains the output of the transformation
  my $out = IO::NestedCapture->get_last_out;

DESCRIPTION

This module performs several tasks. The primary purpose of this module is to take generated content in some format A and find a way to transform that data into format A'.

The current format of the content is assumed to be that of the value stored in the top_level() accessor of Contentment::Response. The "kind" is just a name for the file format (often a MIME-type might be convenient, but it's just a string name). The goal for the transformation plugin is to find the cheapest translation possible to get from this kind into the final kind. The final kind is determined by the final_kind() accessor of Contentment::Request. This module attempts to find zero or more transformations that will coerce the document of the original kind into a document of the final kind.

Each transformer accepts data from a given input kind and produces a document of a given output kind. (Given when the transformer is registered using the add_transformation() method.) Transformers are subroutines similar to hook handlers (see Contentment::Hooks), except they are registered using the add_transformation() method of this class. Each transformation defines a cost attribute, which associates a numeric cost to the transformation---the higher the value the more "costly" the transformation. This module will attempt to use the cheapest transformation available, but may use any found.

PATH FINDING

When searching for the best choice of transformers to get from original kind A to final kind A', we use Dijkstra's shortest path algorithm. (That is, an A* search with the heuristic value (H) set to zero for all nodes.)

$transformer->apply_transformation(%args)

Attempts to transform the input in STDIN from one type to another and places that output on STDOUT. Currently accepts two arguments in %args:

to

If given, this chooses the kind it will attempt to change the input into. Otherwise it will default to the value of Contentment::Request->final_kind.

from

If given, this chooses the kind it will assume the output is currently in. Otherwise it will default to the value of Contentment::Response->top_kind.

CONTEXT

This class adds the following methods to the context:

$transformer = $context->transformer

Returns the current instance of the transformation object.

HOOK HANDLERS

Contentment::Transform::transform

This handler is for the "Contentment::Response::filter" hook.

Contentment::Transform::begin

This handler is the for the "Contentment::begin" hook and is used to call the "Contentment::Transform::begin" hook.

HOOKS

Contentment::Transform::begin

Handlers for this hook receive the current context as the only argument. The purpose of this hook is to allow handlers the opportunity to register transformers.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.