Provided by: libbio-perl-run-perl_1.7.3-9_all bug

NAME

       Bio::DB::SoapEUtilities::Result - Accessor object for SoapEUtilities results

SYNOPSIS

        $fac = Bio::DB::SoapEUtilities->new();
        $result = $fac->esearch( -db => 'gene', -term => 'hedgehog')->run;
        $count = $result->count; # case important; $result->Count could be arrayref
        @ids = $result->ids;

DESCRIPTION

       This module attempts to make Entrez Utilities SOAP responses as user-friendly and
       intuitive as possible. These responses can be complex structures with much useful data;
       but users will generally desire the values of some key fields. The Result object provides
       access to all response values via systematically named accessor methods, and commonly used
       values as convenience methods. The 'raw' SOAP message (a SOAP::SOM object as returned by
       SOAP::Lite) is also provided.

       Convenience accessors
           If a list of record ids is returned by the call, "ids()" will return these as an array
           reference:

            @seq_ids = $result->ids;

           The total count of returned records is provided by "count()":

            $num_recs = $result->count;

           If "usehistory" was specified in the SOAP call, the NCBI-assigned web environment
           (that can be used in future calls) is available in "webenv", and the query key
           assigned to the result in "query_key":

            $next_result = $fac->efetch( -WebEnv => $result->webenv,
                                         -QueryKey => $result->query_key );

       Walking the response
           This module uses "AUTOLOAD" to provide accessor methods for all response data.  Here
           is an example of a SOAP response as returned by a "method()" call off the SOAP::SOM
           object:

               DB<5> x $result->som->method
            0  HASH(0x2eac9a4)
               'Count' => 148
               'IdList' => HASH(0x4139578)
                 'Id' => 100136227
               'QueryKey' => 1
               'QueryTranslation' => 'sonic[All Fields] AND hedgehog[All Fields]'
               'RetMax' => 20
               'RetStart' => 0
               'TranslationSet' => ''
               'TranslationStack' => HASH(0x4237b4c)
                  'OP' => 'GROUP'
                  'TermSet' => HASH(0x42c43bc)
                     'Count' => 2157
                     'Explode' => 'Y'
                     'Field' => 'All Fields'
                     'Term' => 'hedgehog[All Fields]'
               'WebEnv' => 'NCID_1_150423569_130.14.22.101_9001_1262703782'

           Some of the data values here (at the tips of the data structure) are actually arrays
           of values ( e.g., the tip "IdList =" Id> ), other tips are simple scalars. With this
           in mind, "Result" accessor methods work as follows:

           Data values (at the tips of the response structure) are acquired by calling a method
           with the structure keys separated by underscores (if necessary):

            $query_key = $result->QueryKey; # $query_key == 1
            $ids = $result->IdList_Id;      # @$ids is an array of record ids

           Data sets below a particular node in the response structure can also be obtained with
           similarly constructed method names. These 'internal node accessors' return a hashref,
           containing all data leaves below the node, keyed by the accessor names:

               $data_hash = $result->TranslationStack

               DB<3> x $data_hash
            0  HASH(0x43569d4)
               'TranslationStack_OP' => ARRAY(0x42d9988)
                  0  'AND'
                  1  'GROUP'
               'TranslationStack_TermSet_Count' => ARRAY(0x4369c64)
                  0  148
                  1  148
                  2  2157
               'TranslationStack_TermSet_Explode' => ARRAY(0x4368998)
                  0  'Y'
                  1  'Y'
               'TranslationStack_TermSet_Field' => ARRAY(0x4368260)
                  0  'All Fields'
                  1  'All Fields'
               'TranslationStack_TermSet_Term' => ARRAY(0x436c97c)
                  0  'sonic[All Fields]'
                  1  'hedgehog[All Fields]'

           Similarly, the call " $result-"TranslationStack_TermSet > would return a similar hash
           containing the last 4 elements of the example hash above.

           Creating accessors is somewhat costly, especially for fetch responses which can be
           deep and complex (not unlike BioPerl developers). Portions of the response tree can be
           ignored by setting "-prune_at_node" to a arrayref of nodes to skip. Nodes should be
           specified in SOAP::SOM format, e.g.

            ...::Result->new( -prune_at_nodes => ['//GBSeq_references'] );

           Accessor creation can be skipped altogether by passing "-no_parse =" 1> to the
           "Result" constructor. This is recommended if a result is being passed to a
           Bio::DB::SoapEUtilities::FetchAdaptor. The original SOAP message with all data is
           always available in "$result-"som>.

       Other methods

       accessors()
           An array of available data accessor names. This contains only the data "tips". The
           internal node accessors are autoloaded.

       ok()
           True if no SOAP fault.

       errstr()
           Returns the SOAP fault error string.

       som()
           The original "SOAP::SOM" message.

       util()
           The EUtility associated with the result.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
       http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         http://redmine.open-bio.org/projects/bioperl/

AUTHOR - Mark A. Jensen

       Email maj -at- fortinbras -dot- us

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   parse_methods()
        Title   : parse_methods
        Usage   :
        Function: parse out the accessor methods
        Returns : self (Result object)
        Args    : $alias_hash (hashref), $prune_at_nodes (scalar or arrayref)

   util()
        Title   : util
        Usage   :
        Function: Name of the utility producing this result object.
        Returns : scalar string
        Args    :

   som()
        Title   : som
        Usage   :
        Function: get the original SOAP::SOM object
        Returns : a SOAP::SOM object
        Args    : none

   ok()
        Title   : ok
        Usage   :
        Function:
        Returns : true if no SOAP fault
        Args    :

   errstr()
        Title   : errstr
        Usage   :
        Function:
        Returns : fault string of SOAP object
        Args    : none

   accessors()
        Title   : accessors
        Usage   :
        Function: get the list of created accessors for this
                  result
        Returns : array of scalar strings
        Args    : none
        Note    : does not include valid AUTOLOADed accessors; see
                  DESCRIPTION

   webenv()
        Title   : webenv
        Usage   :
        Function: contains WebEnv key referencing this
                  result's session
        Returns : scalar
        Args    : none

   query_key()()
        Title   : query_key()
        Usage   :
        Function: contains the web query key assigned
                  to this result
        Returns : scalar
        Args    :

   fetch_type()
        Title   : fetch_type
        Usage   :
        Function: Get the efetch database name according to WSDL
        Returns : scalar string (db name) or undef if N/A
        Args    : none