API:EPrints/Plugin/Convert - Revision history

Tdb01r at 09:56, 22 January 2013

2013-01-22T09:56:40Z

← Older revision		Revision as of 09:56, 22 January 2013
Line 28:		Line 28:
	<!-- Pod2Wiki=head_synopsis -->		<!-- Pod2Wiki=head_synopsis -->
	==SYNOPSIS==		==SYNOPSIS==
	<source lang="perl">my $root = $~~session~~->plugin( 'Convert' );		<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 );

	# ~~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->{ 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 88:		Line 91:

	* 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 -->		<!-- Edit below this comment -->

Tdb01r at 12:42, 15 March 2012

2012-03-15T12:42:49Z

← Older revision		Revision as of 12:42, 15 March 2012
Line 131:		Line 131:
	<!-- Pod2Wiki=head_copyright -->		<!-- Pod2Wiki=head_copyright -->
	==COPYRIGHT==		==COPYRIGHT==
	~~<tt>~~Copyright 2000-2011 University of Southampton.		Copyright 2000-2011 University of Southampton.

	~~</tt><tt>~~This file is part of EPrints http://www.eprints.org/.		This file is part of EPrints http://www.eprints.org/.

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

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

	~~</tt><tt>~~You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.		You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

	~~</tt>~~<!-- Edit below this comment -->		<!-- Edit below this comment -->

Tdb01r at 12:41, 15 March 2012

2012-03-15T12:41:54Z

← Older revision		Revision as of 12:41, 15 March 2012
Line 131:		Line 131:
	<!-- Pod2Wiki=head_copyright -->		<!-- Pod2Wiki=head_copyright -->
	==COPYRIGHT==		==COPYRIGHT==
	<~~pre~~>Copyright 2000-2011 University of Southampton.		<tt>Copyright 2000-2011 University of Southampton.

	</~~pre~~><~~pre~~>This file is part of EPrints http://www.eprints.org/.		</tt><tt>This file is part of EPrints http://www.eprints.org/.

	</~~pre~~><~~pre~~>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.		</tt><tt>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.

	</~~pre~~><~~pre~~>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.		</tt><tt>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.

	</~~pre~~><~~pre~~>You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.		</tt><tt>You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

	</~~pre~~><!-- Edit below this comment -->		</tt><!-- Edit below this comment -->

Tdb01r at 12:41, 15 March 2012

2012-03-15T12:41:02Z

← Older revision		Revision as of 12:41, 15 March 2012
Line 131:		Line 131:
	<!-- Pod2Wiki=head_copyright -->		<!-- Pod2Wiki=head_copyright -->
	==COPYRIGHT==		==COPYRIGHT==
	Copyright 2000-2011 University of Southampton.		<pre>Copyright 2000-2011 University of Southampton.

	This file is part of EPrints http://www.eprints.org/.		</pre><pre>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.		</pre><pre>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.		</pre><pre>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/.		</pre><pre>You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

	<!-- Edit below this comment -->		</pre><!-- Edit below this comment -->

Tdb01r at 12:37, 15 March 2012

2012-03-15T12:37:32Z

← Older revision		Revision as of 12:37, 15 March 2012
Line 49:		Line 49:

	</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 -->
Line 61:		Line 61:

	</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 -->
Line 73:		Line 73:

	</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 -->
Line 85:		Line 85:

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

	** 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 -->		<!-- Edit below this comment -->
Line 109:		Line 109:

	</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 -->
Line 121:		Line 121:

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

Tdb01r at 12:36, 15 March 2012

2012-03-15T12:36:42Z

← Older revision		Revision as of 12:36, 15 March 2012
Line 87:		Line 87:
	: 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:

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

Tdb01r at 12:35, 15 March 2012

2012-03-15T12:35:57Z

← Older revision		Revision as of 12:35, 15 March 2012
Line 49:		Line 49:

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

Line 61:		Line 61:

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

Line 73:		Line 73:

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

Line 85:		Line 85:

	</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:
	:
	* 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 -->		<!-- Edit below this comment -->

Line 109:		Line 109:

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

Line 121:		Line 121:

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

Tdb01r at 12:31, 15 March 2012

2012-03-15T12:31:06Z

← Older revision		Revision as of 12:31, 15 March 2012
Line 49:		Line 49:

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

Line 61:		Line 61:

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

Line 73:		Line 73:

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

Line 85:		Line 85:

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

	~~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.~~
	:		:
			* 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.
			::
	<!-- Edit below this comment -->		<!-- Edit below this comment -->

Line 109:		Line 109:

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

Line 121:		Line 121:

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

Tdb01r at 12:30, 15 March 2012

2012-03-15T12:30:25Z

← Older revision		Revision as of 12:30, 15 March 2012
Line 49:		Line 49:

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

Line 61:		Line 61:

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

Line 73:		Line 73:

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

Line 85:		Line 85:

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

			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.
	:		:
	* 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.~~
	::
	<!-- Edit below this comment -->		<!-- Edit below this comment -->

Line 109:		Line 109:

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

Line 121:		Line 121:

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

Tdb01r at 12:25, 15 March 2012

2012-03-15T12:25:39Z

← Older revision		Revision as of 12:25, 15 March 2012
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\|~~<tt>~~EPrints::DataObj::Document~~</tt>~~]].		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 49:		Line 49:

	</source>		</source>
	:Create a new plugin object using OPTIONS (should only be called by [[API:EPrints/Session\|~~<tt>~~EPrints::Session~~</tt>~~]]).		: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 -->