Difference between revisions of "API:EPrints/List"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
+
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/List.pm|package_name=EPrints::List}}[[Category:API|List]]<!-- End of Pod2Wiki -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/List.pm|package_name=EPrints::List}}[[Category:API|LIST]][[Category:API:EPrints/List|LIST]]<div><!-- Edit below this comment -->
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::List''' - List of data objects, usually a search result.
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
<!-- Pod2Wiki=item_new -->==new==
+
==NAME==
 +
'''EPrints::List''' - List of data objects, usually a [[API:EPrints/Search|EPrints::Search]] result.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_synopsis -->
 +
==SYNOPSIS==
 +
<source lang="perl">$list = $search->execute();
 +
 
 +
$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
 +
 
 +
$new_list = $list->union( $list2, "creation_date" ) # makes a new list by adding the contents of $list to $list2. the resulting list is ordered by "creation_date"
 +
 
 +
$new_list = $list->remainder( $list2, "title" ); # makes a new list by removing the contents of $list2 from $list orders the resulting list by title
  
  $list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], ids =&gt; $ids, [encoded =&gt; $encoded], [keep_cache =&gt; $keep_cache], [order =&gt; $order] );
+
$n = $list->count() # returns the number of items in the list
  
<!-- End of Pod2Wiki -->
+
@dataobjs = $list->slice( 0, 20 );  #get the first 20 DataObjs from the list in an array
<!-- Pod2Wiki=item_new -->==new==
 
  
  $list = EPrints::List-&gt;new( session =&gt; $session, dataset =&gt; $dataset, [desc =&gt; $desc], [desc_order =&gt; $desc_order], cache_id =&gt; $cache_id );
+
$list->map( $function, $info ) # performs a function on every item in the list. This is very useful go and look at the detailed description.
  
Creates a new list object in memory only. Lists will be cached if anything method requiring order is called, or an explicit  cache() method is called.
+
$plugin_output = $list->export( "BibTeX" ); #calls Plugin::Export::BibTeX on the list.
  
encoded is the serialised version of the searchExpression which created this list, if there was one.
+
$dataset = $list->get_dataset(); #returns the dataset in which the containing objects belong</source>
  
If keep_cache is set then the cache will not be disposed of at the end of the current $session. If cache_id is set then keep_cache is automatically true.
+
<!-- Edit below this comment -->
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_reorder -->==reorder==
 
  
  $new_list = $list-&gt;reorder( $new_order );
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 +
This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.
  
Create a new list from this one, but sorted in a new way.
+
<!-- Edit below this comment -->
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_union -->==union==
 
  
  $new_list = $list-&gt;union( $list2, [$order] );
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_see_also_l_eprints_search -->
 +
==SEE ALSO [[API:EPrints/Search|EPrints::Search]]==
 +
<!-- Edit below this comment -->
  
Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_remainder -->==remainder==
+
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Edit below this comment -->
  
  $new_list = $list-&gt;remainder( $list2, [$order] );
 
  
Create a new list from this one minus another one. If order is not set then this list will not be in any certain order.
+
<!-- Pod2Wiki= -->
 +
$list = EPrints::List-&gt;new( repository =&gt; $repository, dataset =&gt; $dataset,ids =&gt; $ids, [order =&gt; $order] );
 +
$list = EPrints::List-&gt;new( repository =&gt; $repository, dataset =&gt; $dataset,[desc =&gt; $desc],[desc_order =&gt; $desc_order],cache_id =&gt; $cache_id );
 +
Note the new() method will be called very rarely since lists will usually created by an [[API:EPrints/Search|EPrints::Search]].
  
Remove all items in $list2 from $list and return the result as a new EPrints::List.
+
Creates a new list object in memory only. Lists will be cached if any method requiring order is called, or an explicit  cache() method is called.
  
<!-- End of Pod2Wiki -->
+
encoded is the serialised version of the searchExpression which created this list, if there was one.
<!-- Pod2Wiki=item_intersect -->==intersect==
 
  
  $new_list = $list-&gt;intersect( $list2, [$order] );
+
If keep_cache is set then the cache will not be disposed of at the end of the current $session. If cache_id is set then keep_cache is automatically true.
  
Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.
+
$new_list = $list-&gt;reorder( $new_order );
 +
Create a new list from this one, but sorted in a new way.
  
<!-- End of Pod2Wiki -->
+
$new_list = $list-&gt;reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date
<!-- Pod2Wiki=item_cache -->==cache==
 
  
  $list-&gt;cache
+
$new_list = $list-&gt;union( $list2, [$order] );
 +
Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.
  
Cause this list to be cached in the database.
+
$list2 - the list which is to be combined to the calling list
  
<!-- End of Pod2Wiki -->
+
$order - a field which the the resulting list will be ordered on. (optional)
<!-- Pod2Wiki=item_get_cache_id -->==get_cache_id==
 
  
  $cache_id = $list-&gt;get_cache_id
+
$new_list = $list-&gt;remainder( $list2, [$order] );
 +
Create a new list from $list with elements from $list2 removed. If order is not set then this list will not be in any certain order.
  
Return the ID of the cache table for this list, or undef.
+
Remove all items in $list2 from $list and return the result as a new EPrints::List.
  
<!-- End of Pod2Wiki -->
+
$list2 - the eprints you want to remove from the calling list
<!-- Pod2Wiki=item_dispose -->==dispose==
 
  
  $list-&gt;dispose
+
$order - the field the remaining list is to be ordered by
  
Clean up the cache table if appropriate.
+
$new_list = $list-&gt;intersect( $list2, [$order] );
 +
Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.
  
<!-- End of Pod2Wiki -->
+
$list2 - a list to intersect with the calling list
<!-- Pod2Wiki=item_count -->==count==
 
  
  $n = $list-&gt;count
+
$order -  the field the resulting list will be ordered on
  
Return the number of values in this list.
+
$list-&gt;cache
 +
Cause this list to be cached in the database.
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=end -->
<!-- Pod2Wiki=item_get_records -->==get_records==
+
InternalDoc $cache_id = $list-&gt;get_cache_id
 +
Return the ID of the cache table for this list, or undef.
  
  @dataobjs = $list-&gt;get_records( [$offset], [$count] )
+
<!-- Pod2Wiki=end -->
 +
InternalDoc $list-&gt;dispose
 +
Clean up the cache table if appropriate.
  
Return the objects described by this list. $count is the maximum to return. $offset is what index through the list to start from.
+
<!-- Pod2Wiki=end -->
 +
InternalDoc $n = $list-&gt;count
 +
Return the number of values in this list.
  
<!-- End of Pod2Wiki -->
+
$dataobj = $list-&gt;item( $offset )
<!-- Pod2Wiki=item_get_ids -->==get_ids==
+
Returns the item at offset $offset.
  
  $ids = $list-&gt;get_ids( [$offset], [$count] )
+
Returns undef if $offset is out of range of the current list of items.
  
Return a reference to an array containing the ids of the specified range from the list. This is more efficient if you just need the ids.
+
@dataobjs = $list-&gt;slice( [$offset], [$count] )
 +
Returns the DataObjs in this list as an array.  $offset - what index through the list to start from. $count - the maximum to return.
  
<!-- End of Pod2Wiki -->
+
$ids = $list-&gt;ids( [$offset], [$count] )
<!-- Pod2Wiki=item_map -->==map==
+
Return a reference to an array containing the object ids of the items  in the list. You can specify a range of ids using $offset and $count. This is more efficient if you just need the ids.
  
  $list-&gt;map( $function, $info )
+
$offset - what index through the list to start from. $count - the maximum to return.
  
 +
$list-&gt;map( $function, $info )
 
Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory  requirements.
 
Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory  requirements.
  
Line 108: Line 129:
 
Example:
 
Example:
  
my $info = { matches =&gt; 0 };
+
<pre> my $info = { matches =&gt; 0 };
 
  $list-&gt;map( \&amp;deal, $info );
 
  $list-&gt;map( \&amp;deal, $info );
 
  print "Matches: ".$info-&gt;{matches}."\n";
 
  print "Matches: ".$info-&gt;{matches}."\n";
 
    
 
    
  
 +
 
 
  sub deal
 
  sub deal
 
  {
 
  {
 
   my( $session, $dataset, $eprint, $info ) = @_;
 
   my( $session, $dataset, $eprint, $info ) = @_;
+
 
   if( $eprint-&gt;get_value( "a" ) eq $eprint-&gt;get_value( "b" ) ) {
+
   if( $eprint->get_value( "a" ) eq $eprint->get_value( "b" ) ) {
     $info-&gt;{matches} += 1;
+
     $info->{matches} += 1;
 
   }
 
   }
  }   
+
  }</pre>
 
+
 
<!-- End of Pod2Wiki -->
+
  $plugin_output = $list-&gt;export( $plugin_id, %params )
<!-- Pod2Wiki=item_export -->==export==
+
Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.
 +
 
 +
$plugin_id - the ID of the Export plugin which is to be used to process the list. e.g. "BibTeX"
 +
 
 +
$param{"fh"} = "temp_dir/my_file.txt"; - the file the results are to be output to, useful for output too large to fit into memory.
 +
 
 +
<pre></pre>
  
  $plugin_output = $list-&gt;export( $plugin_id, %params )
+
$xhtml = $list-&gt;render_description
 +
Return a DOM XHTML description of this list, if available, or an empty fragment.
  
Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.  
+
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
Copyright 2000-2011 University of Southampton.
  
<!-- End of Pod2Wiki -->
+
This file is part of EPrints http://www.eprints.org/.
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
  
  $dataset = $list-&gt;get_dataset
+
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.
  
Return the EPrints::DataSet which this list relates to.
+
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.
  
<!-- End of Pod2Wiki -->
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
<!-- Pod2Wiki=item_render_description -->==render_description==
 
  
  $xhtml = $list-&gt;render_description
+
<!-- Edit below this comment -->
  
Return a DOM XHTML description of this list, if available, or an empty fragment.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- 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::List - List of data objects, usually a EPrints::Search result.


SYNOPSIS

$list = $search->execute();

$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date

$new_list = $list->union( $list2, "creation_date" ) # makes a new list by adding the contents of $list to $list2. the resulting list is ordered by "creation_date"

$new_list = $list->remainder( $list2, "title" ); # makes a new list by removing the contents of $list2 from $list orders the resulting list by title

$n = $list->count() # returns the number of items in the list

@dataobjs = $list->slice( 0, 20 );  #get the first 20 DataObjs from the list in an array

$list->map( $function, $info ) # performs a function on every item in the list. This is very useful go and look at the detailed description.

$plugin_output = $list->export( "BibTeX" ); #calls Plugin::Export::BibTeX on the list.

$dataset = $list->get_dataset(); #returns the dataset in which the containing objects belong


DESCRIPTION

This class represents an ordered list of objects, all from the same dataset. Usually this is the results of a search.


SEE ALSO EPrints::Search

METHODS

$list = EPrints::List->new( repository => $repository, dataset => $dataset,ids => $ids, [order => $order] ); 
$list = EPrints::List->new( repository => $repository, dataset => $dataset,[desc => $desc],[desc_order => $desc_order],cache_id => $cache_id );

Note the new() method will be called very rarely since lists will usually created by an EPrints::Search.

Creates a new list object in memory only. Lists will be cached if any method requiring order is called, or an explicit cache() method is called.

encoded is the serialised version of the searchExpression which created this list, if there was one.

If keep_cache is set then the cache will not be disposed of at the end of the current $session. If cache_id is set then keep_cache is automatically true.

$new_list = $list->reorder( $new_order );

Create a new list from this one, but sorted in a new way.

$new_list = $list->reorder( "-creation_date" ); # makes a new list ordered by reverse order creation_date

$new_list = $list->union( $list2, [$order] );

Create a new list from this one plus another one. If order is not set then this list will not be in any certain order.

$list2 - the list which is to be combined to the calling list

$order - a field which the the resulting list will be ordered on. (optional)

$new_list = $list->remainder( $list2, [$order] );

Create a new list from $list with elements from $list2 removed. If order is not set then this list will not be in any certain order.

Remove all items in $list2 from $list and return the result as a new EPrints::List.

$list2 - the eprints you want to remove from the calling list

$order - the field the remaining list is to be ordered by

$new_list = $list->intersect( $list2, [$order] );

Create a new list containing only the items which are in both lists. If order is not set then this list will not be in any certain order.

$list2 - a list to intersect with the calling list

$order - the field the resulting list will be ordered on

$list->cache

Cause this list to be cached in the database.

InternalDoc $cache_id = $list->get_cache_id Return the ID of the cache table for this list, or undef.

InternalDoc $list->dispose Clean up the cache table if appropriate.

InternalDoc $n = $list->count Return the number of values in this list.

$dataobj = $list->item( $offset )

Returns the item at offset $offset.

Returns undef if $offset is out of range of the current list of items.

@dataobjs = $list->slice( [$offset], [$count] )

Returns the DataObjs in this list as an array. $offset - what index through the list to start from. $count - the maximum to return.

$ids = $list->ids( [$offset], [$count] )

Return a reference to an array containing the object ids of the items in the list. You can specify a range of ids using $offset and $count. This is more efficient if you just need the ids.

$offset - what index through the list to start from. $count - the maximum to return.

$list->map( $function, $info )

Map the given function pointer to all the items in the list, in order. This loads the items in batches of 100 to reduce memory requirements.

$info is a datastructure which will be passed to the function each time and is useful for holding or collecting state.

Example:

 my $info = { matches => 0 };
 $list->map( \&deal, $info );
 print "Matches: ".$info->{matches}."\n";
  

  
 sub deal
 {
   my( $session, $dataset, $eprint, $info ) = @_;
  
   if( $eprint->get_value( "a" ) eq $eprint->get_value( "b" ) ) {
     $info->{matches} += 1;
   }
 }
$plugin_output = $list->export( $plugin_id, %params )

Apply an output plugin to this list of items. If the param "fh" is set it will send the results to a filehandle rather than return them as a string.

$plugin_id - the ID of the Export plugin which is to be used to process the list. e.g. "BibTeX"

$param{"fh"} = "temp_dir/my_file.txt"; - the file the results are to be output to, useful for output too large to fit into memory.


$xhtml = $list->render_description

Return a DOM XHTML description of this list, if available, or an empty fragment.

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