Editing Perl 101 for EPrints (section)

==Using Perl in EPrints==

===Retrieving data from a config file===

Example of a data config file under /cfg/cfg.d/example.pl

The data structure is an array of hashes (http://perldoc.perl.org/perldsc.html#ARRAYS-OF-HASHES)

<source lang="perl">
$c->{etd_ms}->{fields} = [
	{ tagname => 'etd_ms:type', type=> 'constant', value => "Electronic Thesis or Dissertation" },
	{ tagname => 'etd_ms:degree', type => 'compound', parts => [
		{ tagname => 'etd_ms:name', type => 'simple_text', eprint_fieldname => 'thesis_degree_name' },
		{ tagname => 'etd_ms:level', type => 'simple_text', eprint_fieldname => 'thesis_type' },
		{ tagname => 'etd_ms:discipline', type => 'simple_text', eprint_fieldname => 'department' },
		{ tagname => 'etd_ms:grantor', type => 'simple_text', eprint_fieldname => 'institution' },
	] },
];
</source>

Retrieving values from this config file in an "Example" export plugin under /plugins/EPrints/Plugin/Export/example.pm

<source lang="perl">
               package EPrints::Plugin::Export::Example;
               use EPrints::Plugin::Export;
               @ISA = ( "EPrints::Plugin::Export" );
               [...]
               my $fields = $session->get_conf('etd_ms','fields');					
               foreach my $field_conf (@{$fields})
		{
		   my $tags = $plugin->generate_tag($eprint, $field_conf);			
		   foreach my $tag (@{$tags})
		   {
					push @dcdata, ($tag) if $tag; 
		   }
		}
</source>

Supporting function that returns an arrayref

<source lang="perl">
sub generate_tag {
	my ($plugin, $eprint, $field_conf) = @_;

	#Constant value
	if ($field_conf->{type} eq 'constant')
	{
		return $plugin->generate_constant_tag($eprint, $field_conf);
	}
}
</source>

Supporting function that generates a tag

<source lang="perl">
sub generate_constant_tag{
	my ($plugin, $eprint, $field_conf) = @_;

	my $tag = $plugin->_simple_tag($field_conf, $field_conf->{value});
	return [ $tag ];
}
</source>

===Function parameters===
In perl, the following: <source lang="perl">$obj->function($arg1, $arg2)</source> is equivalent to: <source lang="perl">Class::function($obj, $arg1,$arg2)</source> 
In the example above, when we call:
<source lang="perl">
my $tags = $plugin->generate_tag($eprint, $field_conf);
</source>
It is equivalent to:
<source lang="perl">
my $tags = Example::generate_tag($plugin, $eprint, $field_conf);
</source>
This explains the three parameters listed in the top of the generate_tag function definition:
<source lang="perl">
sub generate_tag {
my ($plugin, $eprint, $field_conf) = @_;
</source>

=== Tips and tricks ===

==== Creating a session ====
Creating a session with eprints is now done via EPrints->new() however many scripts (and examples still use the legacy EPrints::Session->new() interface.

See "perl_lib/EPrints/BackCompatibility.pm" line 424 for details of the compatibility wrapper and "perl_lib/EPrints.pm" for full usage of Eprints methods.

Old style:
<source lang="perl">
# When using this interface both values are required - 1 (to indicate this is a script not CGI) and repo id (second val). Attempting to run without the repo ID results in the following errors:
# Use of uninitialized value $repository_id in string eq at /usr/share/eprints/perl_lib/EPrints.pm line 551.
# Can't call method "get_database" on an undefined value at /usr/share/eprints/perl_lib/EPrints/DataObj.pm line 132.

my $session = EPrints::Session->new( 1, 'REPOID');
</source>

New style:
<source lang="perl">
# Note specifying CGI is not required via this interface.
my $ep = EPrints->new( cleanup=>0 );
my $session = $ep->repository( 'epprod');
</source>

==== Usage of get_config ====

EPrints::Repository::get_config (accessed via $session->get_repository->get_conf()) can be used with two or three parameters.

With only two (key and value) returns a hash 
$session->get_repository->get_conf( "datacitedoi", "typesallowed")

With three values (key and two values) will return 1 (true) if the last item is found in the list of the second entry - config_entry below
$session->get_repository->get_conf( "datacitedoi", "config_entry", 'Thesis')


get_config is a thin wrapper around config()

See also "perl_lib/EPrints/Repository.pm" line 1611