NAME

    Net::WoRMS bundles functionalities for the tool query-worms.

VERSION

    version 1.5

SYNOPSIS

    Net::WoRMS bundles WEB access, parsing and formatting capabilities for
    the tool query-worms <https://metacpan.org>, to harvest information
    form the "World Register of Marine Species" --
    http://www.marinespecies.org. The module was built around the module
    SOAP::Lite and is implemented by a Moo object.

MODULE DEPENDENCIES

    The module uses the packages:

    Data::Dumper

      Debugging purposes

    Moo

      Object oriented extension for the module

    MooX::Types::MooseLike::Base

      Minimal type system for Moo

    SOAP::Lite

      is used for the WEB access and parsing capabilities to retrieve data
      from http://www.marinespecies.org.

    Syntax::Keyword::Match, to end the switch-case/while-given madness

GLOBAL VARIABLES and CONSTANTS

    $END_POINT = 'http://www.marinespecies.org/aphia.php?p=soap'

      The access point to retrieve data via the Simple Object Access
      Protocol.

    $APHIA_NS = 'http://aphia/v1.0'

      Namespace and corresponding URI. In the development context these
      variables are considered as a constants. There are methods to change
      these values but never tested.

    $FORMAT ='TEXT'

      FORMAT defines the default output format.

    @ORDER_SCORE = qw/APHIA_ID ... /

      The array holds field names for SQL related output.

    @ORDER_DOT = qw/APHIA.ID ... /

      The array holds field names for TEXT and CSV related output.

    %FORMATS = ( TEXT = 1, SQL => 2, CSV => 3)>

      The format hash mostly for validation.

    %ORDER_HASH

      Dictionary to sort and translate the retrieved field names from the
      WoRMS database and bring them into a consistent form.

    @TYPE

      Type array corresponding to @ORDER_SCORE/@ORDER_DOT and the
      %ORDER_HASH to handle quotes and NULL values.

FIELDS

    Debug: BOOL

      Flag to switch to the debugging mode.

    Format: STR

      Field holds the current output format. The tags "TEXT|SQL|CSV" are
      allowed.

    EndPoint: STR (URI)

      The current SOAP endpoint defaults to $END_POINT.

    AphiaNS and AphiaURI: STR (URI)

      The current namespace and corresponding URI, defaulting to $APHIA_NS.

    Soap

      The SOAP access client instance generate by SOAP::Lite.

METHODS

    init()

      Initializes the SOAP client.

      Note: All change*(...) functions must be used before the
      initialization phase.

 CHANGE METHODS

    changeEndPoint($uri)

      Change the end point for the soap client (don't change).

    changeAphiaURI($uri)

      Change the namespace URI for the soap client (don't change).

    changeAphiaNS($uri)

      Change the namespace soap soap client (don't change).

    changeDebug($flag)

      Demand debugging capabilities.

    changeFormat($format)

      Changes the output format. Valid formats are TEXT|CSV|SQL.

    getFormats()

      Get the format dictionary for validation.

 QUERY METHODS

    checkSoap()

      Check if the soap client is running. The function stops the calling
      program (die ...) in case of an error.

    checkError($soapResponse)

      Checks the SOAP query result. The function stops the calling program
      in case of an communication error.

    checkDebug($queryResult)

      Prints the query result (dictionary) via Data::Dumper to STDERR if
      the debug flag is set.

    searchSpeciesID($name, $print)

      Function to find a species by a certain name. The if the flag $print
      is set. The result will be written to STDOUT on the given format.

    getRecordByID($aphiaID)

      Retrieves a record for a given AphiaID and returns a dictionary or
      'dies' with an error.

    getBlockChildrenByID($AphiaID, $offs)

      Retrieve a set of taxon records under an given AphiaID for a defined
      offset in the query ensemble. The offset addresses a paging pattern.

    getChildrenByID($aphiaID)

      Retrieves all children under a given AphiaID using the method
      getBlockChildrenID(...) and prints the result to STDOUT using the
      method printRecord(...).

    printRecord($record, $first, $last, $spc)

      Prints a record to STDOUT and handles indentation by $spc as well as
      header and trailing aspects by using the flags $first and $last.

AUTHOR

    Alexander Weidauer <alex.weidauer@huckfinn.de>

COPYRIGHT AND LICENSE

    Copyright (C) 2012 by Alexander Weidauer

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or any later
    version.

    This program 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
    General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see <http://www.gnu.org/licenses/>.

