=pod

=head1 NAME

Webservice::InterMine::Cookbook::Lists::Recipe1 - Uploading Lists

=head1 SYNOPSIS

  use Webservice::InterMine 'www.flymine.org/query', "SOMETOKEN";

  my $service = Webservice::InterMine->get_service;
  my $list = $service->new_list(content => $filename, type => 'Gene', name=> 'My-New-List');

  # Have a look at the contents of the new list.
  $list->show();

  my $other_list = $service->list('Other List');

  # Make a new list by combining two or more
  my $combined_list = $list + $combined_list;
  $combined_list->rename("Combination");

  # Make a new list which is a clone of another list
  my $copy = $service->new_list($list, name => "Copy of my list");

=head1 DESCRIPTION 

InterMine web applications offer a facility termed 'lists', which are 
typed collections of data from the database, essentially collections of objects. 
You can see them as saved result-sets, or little tables you can alter by adding 
and subtracting.

Note, you must authenticate with the webservice in order to use this facility.

Lists can be created in two broad ways: either by matching 
items from the database against a set of identifiers, or by defining a 
result set with a query.

=head2 Creating Lists from Sets of identifiers

The identifiers can be located in:

=over

=item A file

=item An array-ref

=item A string

=back

However, the mechanism for using them is the same:

  $list = $service->new_list(content => $content, type => $class_name);

Where the content is a filename, array-ref of identifiers, or a string to parse
for identifiers. The above shows the minimal use case, here creating a list
that will be deleted when the program exists. If a name is provided, it will persist
and be visible in your web-app's history when you next care to look:

  $list = $service->new_list(content => $content, type => $class_name, name => 'My great list');

=head2 Creating Lists from Queries

This is basically the same with exactly the same syntax as the other forms 
of list construction, the only difference is the need to define a query first:

  my $query = $service->new_query(class => 'Gene')->where('pathways.name' => '*embryonic*');
  $list = $service->new_list(content => $query, type => $class_name, name => 'My great list');

Note that for this purpose there is no need to define a view - the root class of the query
is used to determine the list type and every unique item of that type in the result set 
will be included in the resulting list.

=head2 Copying Lists

Lists can be copied within the same service by simply passing the list to copy from as the 
first parameter to C<new_list>. This makes a new list (with a default name if none is supplied)
with the same content as the original.

=head2 Combining Lists

Lists can be combined in several ways (see Recipe2 for more operations). One of these
is to join two or more lists together. This can be done in a number of ways:

  my $new_list = $listA + $listB; # Addition as union
  $new_list = $listA | $listB;    # Union as this or that
  $new_list = $listA + $query;    # OK to combine lists and queries.
  $new_list = $service->join_lists([$listA, $listB, $query], "Combination") # Use the service

The main benefit of using the service method is being able to supply a name
at creation time, rather than using the C<rename> method, as well as being able 
to supply as many lists and queries as you wish.

The syntax is much the same for the other operations, more details of which can be found in
Recipe2.

=head2 Retrieving Results

Lists may be treated much like queries, and this is explored in more depth in 
Recipe3. Methods that work on queries and lists include:

  $list->show();
  $list->show_first();
  $list->print_results();
  while (<$list>) { 
    # Iteration
  }
  $list->results_iterator;

=head1 CONCLUSION

The syntax for creating lists is the same for all the different 
content types, and many of the same operations that can be performed on 
queries can be performed on Lists as well.

=head1 AUTHOR

Alex Kalderimis C<dev@intermine.org>

=head1 BUGS

Please report any bugs or feature requests to C<dev@intermine.org>.

=head1 SUPPORT

You can find information about InterMine at:

=over 4

=item * InterMine

L<http://www.intermine.org>

=item * Documentation

L<http://intermine.org/wiki/PerlWebServiceAPI>

=back

=head1 COPYRIGHT AND LICENSE

Copyright 2006 - 2011 FlyMine, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.