/ 
Bio-EnsEMBL-113.0.0
River stage zero No dependents
/ Bio::EnsEMBL::Utils::URI

LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::Utils::URI

SYNOPSIS

use Bio::EnsEMBL::Utils::URI qw/parse_uri is_uri/;
# or use Bio::EnsEMBL::Utils::URI qw/:all/; # to bring everything in

my $db_uri = parse_uri('mysql://user@host:3157/db');
my $http_uri = parse_uri('http://www.google.co.uk:80/search?q=t');

is_uri('mysql://user@host'); # returns 1
is_uri('file:///my/path'); # returns 1
is_uri('/my/path'); # returns 0

DESCRIPTION

This object is a generic URI parser which is primarily used in the parsing of database URIs into a more managable data structure. We also provide the resulting URI object

DEPENDENCIES

URI::Escape is an optional dependency but if available the code will attempt to perform URI encoding/decoding on parameters. If you do not want this functionality then modify the global $Bio::EnsEMBL::Utils::URI::URI_ESCAPE to false;

METHODS

is_uri

Arg[1]      : Scalar; URI to parse
Example     : is_uri('mysql://user:pass@host:415/db');
Description : Looks for the existence of a URI scheme to decide if this
              is a classical URI. Whilst non-scheme based URIs can still be
              interprited it is useful to use when you need to know if
              you are going to work with a URI or not
Returntype  : Boolean
Caller      : General
Status      : Beta

parse_uri

Arg[1]      : Scalar; URI to parse
Example     : my $uri = parse_uri('mysql://user:pass@host:415/db');
Description : A URL parser which attempts to convert many different types
              of URL into a common data structure.
Returntype  : Bio::EnsEMBL::Utils::URI
Caller      : General
Status      : Beta

new()

Arg[1]      : String; scheme the URI will confrom to
Description : New object call
Returntype  : Bio::EnsEMBL::Utils::URIParser::URI
Exceptions  : Thrown if scheme is undefined.
Status      : Stable

db_schemes()

Description: Returns a hash of scheme names known to be databases
Returntype : HashRef
Exceptions : None
Status     : Stable

is_db_scheme()

Description: Returns true if the code believes the scheme to be a Database
Returntype : Boolean
Exceptions : None
Status     : Stable

scheme()

Description : Getter for the scheme attribute
Returntype  : String
Exceptions  : None
Status      : Stable

path()

Arg[1]      : Setter argument
Description : Getter/setter for the path attribute
Returntype  : String
Exceptions  : None
Status      : Stable

user()

Arg[1]      : Setter argument
Description : Getter/setter for the user attribute
Returntype  : String
Exceptions  : None
Status      : Stable

pass()

Arg[1]      : Setter argument
Description : Getter/setter for the password attribute
Returntype  : String
Exceptions  : None
Status      : Stable

host()

Arg[1]      : Setter argument
Description : Getter/setter for the host attribute
Returntype  : String
Exceptions  : None
Status      : Stable

port()

Arg[1]      : Setter argument
Description : Getter/setter for the port attribute
Returntype  : Integer
Exceptions  : If port is not a number, less than 1 or not a whole integer
Status      : Stable

param_keys()

Description : Getter for the paramater map keys in the order they were first
              seen. Keys should only appear once in this array
Returntype  : ArrayRef
Exceptions  : None
Status      : Stable

param_exists_ci()

Arg[1]      : String; Key
Description : Performs a case-insensitive search for the given key
Returntype  : Boolean; returns true if your given key was seen
Exceptions  : None
Status      : Stable

add_param()

Arg[1]      : String; key
Arg[1]      : Scalar; value
Description : Add a key/value to the params map. Multiple inserts of the same
              key is allowed
Returntype  : None
Exceptions  : None
Status      : Stable

get_params()

Arg[1]      : String; key
Description : Returns the values which were found to be linked to the given
              key. Arrays are returned because one key can have many
              values in a URI
Returntype  : ArrayRef[Scalar]
Exceptions  : None
Status      : Stable

db_params()

Description : Storage of parameters used only for database URIs since
              they require
Returntype  : HashRef; Database name is keyed under C<dbname> and the
              table is keyed under C<table>
Exceptions  : None
Status      : Stable

generate_dbsql_params()

Arg[1]      : boolean $no_table alows you to avoid pushing -TABLE as an 
              output value
Description : Generates a Hash of Ensembl compatible parameters to be used
              to construct a DB object. We combine those parameters
              which are deemed to be part of the C<db_params()> method
              under C<-DBNAME> and C<-TABLE>. We also search for a number
              of optional parameters which are lowercased equivalents
              of the construction parameters available from a
              L<Bio::EnsEMBL::DBSQL::DBAdaptor>,
              L<Bio::EnsEMBL::DBSQL::DBConnection> as well as C<verbose>
              being supported.

              We also convert the scheme type into the driver attribute

Returntype  : Hash (not a reference). Output can be put into a C<DBConnection>
              constructor.
Exceptions  : None
Status      : Stable

_decode_sqlite

Description : Performs path gymnastics to decode into a number of possible
              options. The issue with SQLite is that the normal URI scheme
              looks like sqlite:///my/path.sqlite/table but how do we know
              that the DB name is C</my/path.sqlite> and the table is 
              C<table>?
              
              The code takes a path, looks for the full path & if it cannot
              be found looks for the file a directory back. In the above
              example it would have looked for C</my/path.sqlite/table>,
              found it to be non-existant, looked for C</my/path.sqlite>
              and found it. 
              
              If the path splitting procdure resulted in just 1 file after
              the first existence check e.g. C<sqlite://db.sqlite> it assumes
              that should be the name. If no file can be found we default to
              the full length path.
Caller      : internal

generate_uri()

Description : Generates a URI string from the paramaters in this object
Returntype  : String
Exceptions  : None
Status      : Stable