Difference between revisions of "API:EPrints/Plugin/Convert"
| (9 intermediate revisions by the same user not shown) | |||
| Line 18: | Line 18: | ||
Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing). | Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing). | ||
| − | Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given [[API:EPrints/DataObj/Document| | + | Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given [[API:EPrints/DataObj/Document|EPrints::DataObj::Document]]. |
To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs. | To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs. | ||
| Line 28: | Line 28: | ||
<!-- Pod2Wiki=head_synopsis --> | <!-- Pod2Wiki=head_synopsis --> | ||
==SYNOPSIS== | ==SYNOPSIS== | ||
| − | <source lang="perl">my $root = $ | + | <source lang="perl">my $root = $repo->plugin( 'Convert' ); |
| + | # Get the the available conversions for all plugins | ||
my %available = $root->can_convert( $document ); | my %available = $root->can_convert( $document ); | ||
| − | # | + | # Get a conversion scheme for text/plain |
my $txt_tool = $available{'text/plain'}; | my $txt_tool = $available{'text/plain'}; | ||
| − | my $plugin = $txt_tool->{ plugin }; | + | |
| + | # Use the plugin to convert the document to text/plain | ||
| + | my $plugin = $txt_tool->{'plugin'}; | ||
$plugin->convert( $eprint, $document, 'text/plain' );</source> | $plugin->convert( $eprint, $document, 'text/plain' );</source> | ||
| Line 49: | Line 52: | ||
</source> | </source> | ||
| − | + | Create a new plugin object using OPTIONS (should only be called by [[API:EPrints/Session|EPrints::Session]]). | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
| Line 61: | Line 64: | ||
</source> | </source> | ||
| − | + | Return the name of this plugin as a chunk of XHTML. | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
| Line 73: | Line 76: | ||
</source> | </source> | ||
| − | + | Returns whether this plugin is visible at level (currently 'all' or ''). | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
| Line 85: | Line 88: | ||
</source> | </source> | ||
| − | + | Returns a hash of types that this plugin can convert the document $doc to. The key is the type. The value is a hash ref containing: | |
| − | + | ||
* plugin | * plugin | ||
| − | + | : The object that can do the conversion. | |
| − | + | ||
* encoding | * encoding | ||
| − | + | : The encoding this conversion generates (e.g. 'utf-8'). | |
| − | + | ||
* phraseid | * phraseid | ||
| − | + | : A unique phrase id for this conversion. | |
| − | + | ||
* preference | * preference | ||
| − | + | : A value between 0 and 1 representing the 'quality' or confidence in this conversion. | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
| Line 109: | Line 112: | ||
</source> | </source> | ||
| − | + | Convert $doc to $type and export it to $dir. Returns a list of file names that resulted from the conversion. The main file (if there is one) is the first file name returned. Returns empty list on failure. | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
| Line 121: | Line 124: | ||
</source> | </source> | ||
| − | + | Convert $doc to format $type (as returned by can_convert). Stores the resulting $doc in $eprint, and returns the new document or undef on failure. | |
| − | + | ||
| − | + | Optionally initialise the new document with $epdata. Specifying 'files' in $epdata will cause the converted file content to be discarded. | |
| − | + | ||
<!-- Edit below this comment --> | <!-- Edit below this comment --> | ||
Latest revision as of 09:56, 22 January 2013
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::Plugin::Convert - Convert EPrints::DataObj::Document into different formats
DESCRIPTION
This plugin and its dependents allow EPrints to convert documents from one format into another format. Convert plugins are also used by the full-text indexer to extract plain-text from documents.
Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing).
Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given EPrints::DataObj::Document.
To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs.
SYNOPSIS
my $root = $repo->plugin( 'Convert' );
# Get the the available conversions for all plugins
my %available = $root->can_convert( $document );
# Get a conversion scheme for text/plain
my $txt_tool = $available{'text/plain'};
# Use the plugin to convert the document to text/plain
my $plugin = $txt_tool->{'plugin'};
$plugin->convert( $eprint, $document, 'text/plain' );
METHODS
new
new OPTIONS
Create a new plugin object using OPTIONS (should only be called by EPrints::Session).
render_name
$xhtml = $plugin->render_name
Return the name of this plugin as a chunk of XHTML.
is_visible
$plugin->is_visible( $level )
Returns whether this plugin is visible at level (currently 'all' or ).
can_convert
%types = $p->can_convert( $doc, [$type], [%params] )
Returns a hash of types that this plugin can convert the document $doc to. The key is the type. The value is a hash ref containing:
- plugin
- The object that can do the conversion.
- encoding
- The encoding this conversion generates (e.g. 'utf-8').
- phraseid
- A unique phrase id for this conversion.
- preference
- A value between 0 and 1 representing the 'quality' or confidence in this conversion.
export
@filelist = $p->export( $dir, $doc, $type )
Convert $doc to $type and export it to $dir. Returns a list of file names that resulted from the conversion. The main file (if there is one) is the first file name returned. Returns empty list on failure.
convert
$doc = $p->convert( $eprint, $doc, $type [, $epdata ] )
Convert $doc to format $type (as returned by can_convert). Stores the resulting $doc in $eprint, and returns the new document or undef on failure.
Optionally initialise the new document with $epdata. Specifying 'files' in $epdata will cause the converted file content to be discarded.
COPYRIGHT
Copyright 2000-2011 University of Southampton.
This file is part of EPrints http://www.eprints.org/.
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.
