#!/usr/local/bin/perl -w

# EutilsExampleRJW.pl
# -------------------
# This version modified by Richard White
# 20 December 2005  displays warning if data cannot be retrieved
# 13 January  2006  eSearch and eFetch output separated more clearly
# 25 November 2009  retrieval loop displays only one result at a time

# ===========================================================================
#
#                            PUBLIC DOMAIN NOTICE
#               National Center for Biotechnology Information
#
#  This software/database is a "United States Government Work" under the
#  terms of the United States Copyright Act.  It was written as part of
#  the author's official duties as a United States Government employee and
#  thus cannot be copyrighted.  This software/database is freely available
#  to the public for use. The National Library of Medicine and the U.S.
#  Government have not placed any restriction on its use or reproduction.
#
#  Although all reasonable efforts have been taken to ensure the accuracy
#  and reliability of the software and data, the NLM and the U.S.
#  Government do not and cannot warrant the performance or results that
#  may be obtained by using this software or data. The NLM and the U.S.
#  Government disclaim all warranties, express or implied, including
#  warranties of performance, merchantability or fitness for any particular
#  purpose.
#
#  Please cite the author in any work or product based on this material.
#
# ===========================================================================
#
# Author:  Oleg Khovayko http://olegh.spedia.net

# File Description: eSearch/eFetch calling example
#  
# ---------------------------------------------------------------------------
# Subroutine to prompt user for variables in the next section

sub ask_user 
# Ask user to enter details of search required
{ print "$_[0] [default value is $_[1]]: ";
  my $rc = <>;
  chomp $rc;
  if($rc eq "") { $rc = $_[1]; }
  return $rc;
}

sub carry_on
# Ask user whether to continue
{ print  "\n------------------------------------------"
       . "\nPress ENTER to continue or Ctrl-C to stop!"
       . "\n------------------------------------------\n";
  <>;
}

# ---------------------------------------------------------------------------
# Define library for the 'get' function used in the next section.
# $utils contains route for the utilities.
# $db, $query, and $report may be supplied by the user when prompted; 
# if not answered, default values, will be assigned as shown below.

use LWP::Simple;

my $utils = "http://eutils.ncbi.nlm.nih.gov/entrez/eutils";

print "\nPerl program EutilsExampleRJW.pl at your service ...\n\n";

my $db     = ask_user("Database to search", "Pubmed");
my $query  = ask_user("Query (search for)", "Cirencester");
my $report = ask_user("Report (format)   ", "abstract");

# ---------------------------------------------------------------------------
# $esearch contains the PATH & parameters for the ESearch call
# $esearch_result contains the result of the ESearch call
# the results are displayed and parsed into variables 
# $Count, $QueryKey, and $WebEnv for later use and then displayed.

# Construct the search request URL
my $esearch = "$utils/esearch.fcgi?db=$db&retmax=1&usehistory=y&term=$query";

my $esearch_result = get($esearch);

if (! defined $esearch_result) { die "Cannot fetch data from NCBI Entrez eSearch";  } 

print "\n---------------"
    . "\nESearch result:"
    . "\n---------------"
    . "\n$esearch_result\n";

$esearch_result =~ 
  m|<Count>(\d+)</Count>.*<QueryKey>(\d+)</QueryKey>.*<WebEnv>(\S+)</WebEnv>|s;

my $Count    = $1;
my $QueryKey = $2;
my $WebEnv   = $3;

print "\n-----------------"
    . "\nExtracted values:"
    . "\n-----------------"
    . "\nCount = $Count\nQueryKey = $QueryKey\nWebEnv = $WebEnv\n";

carry_on();

# ---------------------------------------------------------------------------
# this area defines a loop which will display one result from 
# Efetch each time the the Enter Key is pressed, after a prompt.

my $number;

for($number = 0; $number < $Count; $number++) 
{ # Construct the fetch request URL
  my $efetch = "$utils/efetch.fcgi?" .
               "rettype=$report&retmode=text&retstart=$number&retmax=1&" .
               "db=$db&query_key=$QueryKey&WebEnv=$WebEnv";
	
  print "\nConstructed EFetch query\n$efetch\n";     

  my $efetch_result = get($efetch);
  
  if (! defined $esearch_result) { die "Cannot fetch data from NCBI Entrez eFetch";  } 

  print "\n------------------------------"
      . "\nEFetch result number " . ($number+1) . " of $Count:"
      . "\n------------------------------\n"
      . $efetch_result;

  carry_on();
}

print "Perl program EutilsExampleRJW.pl has finished.\n\n";