Difference between revisions of "API:EPrints/Plugin/Convert"

From EPrints Documentation
Jump to: navigation, search
 
(32 intermediate revisions by the same user not shown)
Line 28: Line 28:
 
<!-- Pod2Wiki=head_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
−
<pre> my $root = $session-&gt;plugin( 'Convert' );</pre>
+
<source lang="perl">my $root = $repo->plugin( 'Convert' );
  
−
<pre>  my %available = $root-&gt;can_convert( $document );</pre>
+
# Get the the available conversions for all plugins
 +
my %available = $root->can_convert( $document );
  
−
<pre>  # Convert a document to plain-text
+
# Get a conversion scheme for text/plain
−
  my $txt_tool = $available{'text/plain'};
+
my $txt_tool = $available{'text/plain'};
−
  my $plugin = $txt_tool-&gt;{ plugin };
+
 
−
  $plugin-&gt;convert( $eprint, $document, 'text/plain' );</pre>
+
# Use the plugin to convert the document to text/plain
 +
my $plugin = $txt_tool->{'plugin'};
 +
$plugin->convert( $eprint, $document, 'text/plain' );</source>
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 43: Line 46:
 
<!-- Pod2Wiki=head_methods -->
 
<!-- Pod2Wiki=head_methods -->
 
==METHODS==
 
==METHODS==
−
<!-- Edit below this comment -->
+
<!-- Pod2Wiki=head_new -->
−
 
 
−
 
 
−
<!-- Pod2Wiki= -->
 
−
<!-- Pod2Wiki=item_new -->
 
 
===new===
 
===new===
  
Line 53: Line 52:
  
 
</source>
 
</source>
−
:Create a new plugin object using OPTIONS (should only be called by [[API:EPrints/Session|EPrints::Session]]).
+
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 -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_render_name -->
+
<!-- Pod2Wiki=head_render_name -->
 
===render_name===
 
===render_name===
  
Line 65: Line 64:
  
 
</source>
 
</source>
−
:Return the name of this plugin as a chunk of XHTML.
+
Return the name of this plugin as a chunk of XHTML.
−
:
+
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_is_visible -->
+
<!-- Pod2Wiki=head_is_visible -->
 
===is_visible===
 
===is_visible===
  
Line 77: Line 76:
  
 
</source>
 
</source>
−
:Returns whether this plugin is visible at level (currently 'all' or '').
+
Returns whether this plugin is visible at level (currently 'all' or '').
−
:
+
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_can_convert -->
+
<!-- Pod2Wiki=head_can_convert -->
 
===can_convert===
 
===can_convert===
  
Line 89: 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:
+
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:
−
:
 
−
<!-- Edit below this comment -->
 
−
 
 
  
−
<!-- Pod2Wiki= -->
 
 
* plugin
 
* plugin
 +
: The object that can do the conversion.
  
−
::The object that can do the conversion.
 
−
::
 
 
* encoding
 
* encoding
 +
: The encoding this conversion generates (e.g. 'utf-8').
  
−
::The encoding this conversion generates (e.g. 'utf-8').
 
−
::
 
 
* phraseid
 
* phraseid
 +
: A unique phrase id for this conversion.
  
−
::A unique phrase id for this conversion.
 
−
::
 
 
* preference
 
* preference
 +
: A value between 0 and 1 representing the 'quality' or confidence in this conversion.
  
−
::A value between 0 and 1 representing the 'quality' or confidence in this conversion.
+
<!-- Edit below this comment -->
−
::
+
 
−
<!-- Pod2Wiki=item_export -->
+
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_export -->
 
===export===
 
===export===
  
Line 117: 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.
+
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 -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_convert -->
+
<!-- Pod2Wiki=head_convert -->
 
===convert===
 
===convert===
  
Line 129: 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.
+
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.
+
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

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


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/.



Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Plugin/Convert&oldid=10703’