This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: UDDI, Next: UDDI/Lite, Prev: Tree/Trie, Up: Module List UDDI client interface ********************* NAME ==== UDDI - UDDI client interface SYNOPSIS ======== use UDDI; my $list = UDDI::find_business(name => "a"); my $bis = $list->businessInfos; for my $b ($bis->businessInfo) { print $b->name, "\n"; } DESCRIPTION =========== This module provide functions to interact with UDDI registry servers. UDDI (*Universal Description, Discovery and Integration*) is the name of a group of web-based registries that expose information about businesses and their technical interfaces (APIs). Learn more about UDDI at *www.uddi.org*. The interface exposed comply with the "UDDI Programmer's API Specification". Currently only the UDDI inquiry interface is provided. FUNCTIONS ========= The following functions are provided. None of them are exported by default. A successful invocation will return some UDDI object. On error undef is returned and the global variable %UDDI::err is set. All the find_xxx() functions take key/value pairs as arguments. All they get_xxx() functions simply take one or more keys as argument. find_binding( serviceKey => $key, ... ) This function will find binding details for a specific service. On success a UDDI::bindingDetails object is returned. Optional arguments are `maxRows', `findQualifiers' and `tModelBag'. find_business( ... ) This function will return businesses that fullfil the search criteria given. On success a UDDI::businessList object is returned. The returned businessList might be empty. Arguments are `maxRows', `findQualifiers', name, `identiferBag', `categoryBag', `tModelBag' are `discoveryURLs'. find_service( businessKey => $key, ... ) This function will find services for a specific business. On success a UDDI::serviceList object is returned. Optional arguments are `maxRows', `findQualifiers', name, `categoryBag' and `tModelBag'. find_tModel( ... ) This function will return tModels that fullfil the search criteria given. On success a UDDI::tModelList object is returned. The returned tModelList might be empty. Arguments are `maxRows', `findQualifiers', name, `identiferBag' and `categoryBag'. get_bindingDetail( $bindingKey, ... ) This function will return a UDDI::bindingDetail object containing a UDDI::bindingTemplate for each binding key given as argument. get_businessDetail( $businessKey, ... ) This function will return a UDDI::businessDetail object containing a UDDI::businessEntity for each business key given as argument. get_businessDetailExt( $businessKey, ... ) This function will return a UDDI::businessDetailExt object containing a UDDI::businessEntityExt for each business key given as argument. get_serviceDetail( $serviceKey, ... ) This function will return a UDDI::serviceDetail object containing a UDDI::businessService for each service key given as argument. get_tModelDetail( $tModelKey, ... ) This function will return a UDDI::tModelDetail object containing a UDDI::tModel for each tModel key given as argument. GLOBALS ======= %UDDI::err ---------- In case of errors the functions above will return undef and the %UDDI::err hash will be filled with the following values: type A short string giving the overall type of the failure. It can be either "HTTP" or "SOAP". code Error code. For HTTP it is a 3 digit number. For UDDI failures it is some string prefixed with "E_". For general SOAP failures it is a short string like "VersionMismatch", "MustUnderstand", "Client", "Server" (defined in section 4.4.1 in the SOAP spec.) message A short human readable (English) message describing the error. detail A reference to the corresponing error object. The hash will be empty after a successful function call. $UDDI::registry --------------- The $UDDI::registry variable contains the URL to the registry server to use for the calls. Currently it defaults to Microsoft's test server. $UDDI::TRACE ------------ For debugging you might assign a file handle to the $UDDI::TRACE variable. Trace logs of the SOAP messages are then written to this file. SEE ALSO ======== http://www.uddi.org, *Note SOAP: SOAP,, *Note SOAP/Lite: SOAP/Lite, AUTHOR ====== Gisle Aas Copyright 2000 ActiveState Tool Corp. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: UDDI/Lite, Next: UNIVERSAL, Prev: UDDI, Up: Module List Library for UDDI clients in Perl ******************************** NAME ==== UDDI::Lite - Library for UDDI clients in Perl SYNOPSIS ======== use UDDI::Lite; print UDDI::Lite -> proxy('http://uddi.microsoft.com/inquire') -> find_business(name => 'old') -> result -> businessInfos->businessInfo->serviceInfos->serviceInfo->name; The same code with autodispatch: use UDDI::Lite +autodispatch => proxy => 'http://uddi.microsoft.com/inquire' ; print find_business(name => 'old') -> businessInfos->businessInfo->serviceInfos->serviceInfo->name; Or with importing: use UDDI::Lite 'UDDI::Lite' => [':inquire'], proxy => 'http://uddi.microsoft.com/inquire' ; print find_business(name => 'old') -> businessInfos->businessInfo->serviceInfos->serviceInfo->name; Publishing API: use UDDI::Lite import => ['UDDI::Data'], import => ['UDDI::Lite'], proxy => "https://some.server.com/endpoint_fot_publishing_API"; my $auth = get_authToken({userID => 'USERID', cred => 'CRED'})->authInfo; my $busent = with businessEntity => name("Contoso Manufacturing"), description("We make components for business"), businessKey(''), businessServices with businessService => name("Buy components"), description("Bindings for buying our components"), serviceKey(''), bindingTemplates with bindingTemplate => description("BASDA invoices over HTTP post"), accessPoint('http://www.contoso.com/buy.asp'), bindingKey(''), tModelInstanceDetails with tModelInstanceInfo => description('some tModel'), tModelKey('UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4') ; print save_business($auth, $busent)->businessEntity->businessKey; DESCRIPTION =========== UDDI::Lite for Perl is a collection of Perl modules which provides a simple and lightweight interface to the Universal Description, Discovery and Integration (UDDI) server. To learn more about UDDI, visit http://www.uddi.org/. The main features of the library are: * Supports both inquiry and publishing API * Builded on top of SOAP::Lite module, hence inherited syntax and features * Supports easy-to-use interface with convinient access to (sub)elements and attributes * Supports HTTPS protocol * Supports SMTP protocol * Supports Basic/Digest server authentication OVERVIEW OF CLASSES AND PACKAGES ================================ This table should give you a quick overview of the classes provided by the library. UDDI::Lite.pm -- UDDI::Lite -- Main class provides all logic -- UDDI::Data -- Provides extensions for serialization architecture -- UDDI::Serializer -- Serializes data structures to UDDI/SOAP package -- UDDI::Deserializer -- Deserializes result into objects -- UDDI::SOM -- Provides access to deserialized object tree UDDI::Lite ---------- All methods that UDDI::Lite gives you access to can be used for both setting and retrieving values. If you provide no parameters, you'll get current value, and if you'll provide parameter(s), new value will be assigned and method will return object (if not stated something else). This is suitable for stacking these calls like: $uddi = UDDI::Lite -> on_debug(sub{print@_}) -> proxy('http://uddi.microsoft.com/inquire') ; Order is insignificant and you may call new() method first. If you don't do it, UDDI::Lite will do it for you. However, new() method gives you additional syntax: $uddi = new UDDI::Lite on_debug => sub {print@_}, proxy => 'http://uddi.microsoft.com/inquire' ; new() accepts hash with method names and values, and will call appropriate method with passed value. Since new() is optional it won't be mentioned anymore. Other available methods inherited from SOAP::Lite and most usable are: proxy() Shortcut for `transport->proxy()'. This lets you specify an endpoint and also loads the required module at the same time. It is required for dispatching SOAP calls. The name of the module will be defined depending on the protocol specific for the endpoint. SOAP::Lite will do the rest work. namespace() Shortcut for `serializer->namespace()'. Lets you specify default namespace for generated envelope. 'SOAP-ENV' by default. on_fault() Lets you specify handler for on_fault event. Default behavior is die on transport error and does nothing on others. You can change this behavior globally or locally, for particular object. on_debug() Lets you specify handler for on_debug event. Default behavior is do nothing. Use +trace/+debug option for UDDI::Lite instead. UDDI::Data ---------- You can use this class if you want to specify value and name for UDDI elements. For example, `UDDI::Data->name('businessInfo')->value(123)' will be serialized to `123', as well as `UDDI::Data-'name(businessInfo => 123)>. If you want to provide names for your parameters you can either specify find_business(name => 'old') or do it with UDDI::Data: find_business(UDDI::Data->name(name => 'old')) Later has some advantages: it'll work on any level, so you can do: find_business(UDDI::Data->name(name => UDDI::Data->name(subname => 'old'))) and also you can create arrays with this syntax: find_business(UDDI::Data->name(name => [UDDI::Data->name(subname1 => 'name1'), UDDI::Data->name(subname2 => 'name2')])) will be serialized into: name1 name2 For standard elements more convinient syntax is available: find_business( findQualifiers(findQualifier('sortByNameAsc', 'caseSensitiveMatch')), name('M') ) and find_business( findQualifiers([findQualifier('sortByNameAsc'), findQualifier('caseSensitiveMatch')]), name('M') ) both will generate: sortByNameAsc caseSensitiveMatch M You can use ANY valid combinations (according to "UDDI Programmer's API Specification"). If you try to generate something unusual, like `name(name('myname'))', you'll get: Don't know what to do with 'name' and 'name' elements .... If you REALLY need to do it, use UDDI::Data syntax described above. As special case you can pass hash as the first parameter of method call and values of this hash will be added as attributes to top element: find_business({maxRows => 10}, UDDI::Data->name(name => old)) gives you .... You can also pass back parameters exactly as you get it from method call (like you probably want to do with authInfo). You can get access to attributes and elements through the same interface: my $list = find_business(name => old); my $bis = $list->businessInfos; for ($bis->businessInfo) { my $s = $_->serviceInfos->serviceInfo; print $s->name, # element $s->businessKey, # attribute "\n"; } To match advantages provided by with operator available in other languages (like VB) we provide similar functionality that adds you flexibility: with findQualifiers => findQualifier => 'sortByNameAsc', findQualifier => 'caseSensitiveMatch' is the same as: with(findQualifiers => findQualifier('sortByNameAsc'), findQualifier('caseSensitiveMatch'), ) and: findQualifiers->with( findQualifier('sortByNameAsc'), findQualifier('caseSensitiveMatch'), ) will all generate the same code as mentioned above: findQualifiers(findQualifier('sortByNameAsc', 'caseSensitiveMatch')), Advantage of with syntax is the you can specify both attributes and elements through the same interface. First argument is element where all other elements and attributes will be attached. Provided examples and tests cover different syntaxes. AUTODISPATCHING --------------- UDDI::Lite provides autodispatching feature that lets you create code that looks similar for local and remote access. For example: use UDDI::Lite +autodispatch => proxy => 'http://uddi.microsoft.com/inquire'; tells autodispatch all UDDI calls to 'http://uddi.microsoft.com/inquire'. All subsequent calls can look like: find_business(name => 'old'); find_business(UDDI::Data->name(name => 'old')); find_business(name('old')); BUGS AND LIMITATIONS ==================== * Interface is still subject to change. * Though HTTPS/SSL is supported you should specify it yourself (with proxy or `endpoint') for publishing API calls. AVAILABILITY ============ For now UDDI::Lite is distributed as part of SOAP::Lite package. You can download it from ( http://soaplite.com/ ) or from CPAN ( http://search.cpan.org/search?dist=SOAP-Lite ). SEE ALSO ======== *Note SOAP/Lite: SOAP/Lite, ( http://search.cpan.org/search?dist=SOAP-Lite ) *Note UDDI: UDDI, ( http://search.cpan.org/search?dist=UDDI ) COPYRIGHT ========= Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Paul Kulchenko (paulclinger@yahoo.com)  File: pm.info, Node: UNIVERSAL, Next: UNIVERSAL/exports, Prev: UDDI/Lite, Up: Module List base class for ALL classes (blessed references) *********************************************** NAME ==== UNIVERSAL - base class for ALL classes (blessed references) SYNOPSIS ======== $io = $fd->isa("IO::Handle"); $sub = $obj->can('print'); $yes = UNIVERSAL::isa($ref, "HASH"); DESCRIPTION =========== UNIVERSAL is the base class which all bless references will inherit from, see *Note Perlobj: (perl.info)perlobj, UNIVERSAL provides the following methods isa ( TYPE ) isa returns *true* if `REF' is blessed into package TYPE or inherits from package TYPE. isa can be called as either a static or object method call. can ( METHOD ) can checks if the object has a method called METHOD. If it does then a reference to the sub is returned. If it does not then undef is returned. can can be called as either a static or object method call. VERSION ( [ REQUIRE ] ) VERSION will return the value of the variable $VERSION in the package the object is blessed into. If REQUIRE is given then it will do a comparison and die if the package version is not greater than or equal to REQUIRE. VERSION can be called as either a static or object method call. The isa and can methods can also be called as subroutines UNIVERSAL::isa ( VAL, TYPE ) isa returns *true* if one of the following statements is true. * `VAL' is a reference blessed into either package TYPE or a package which inherits from package TYPE. * `VAL' is a reference to a TYPE of Perl variable (e.g. 'HASH'). * `VAL' is the name of a package that inherits from (or is itself) package TYPE. UNIVERSAL::can ( VAL, METHOD ) If `VAL' is a blessed reference which has a method called METHOD, can returns a reference to the subroutine. If `VAL' is not a blessed reference, or if it does not have a method METHOD, undef is returned. These subroutines should not be imported via `use UNIVERSAL qw(...)'. If you want simple local access to them you can do *isa = \&UNIVERSAL::isa; to import isa into your package.  File: pm.info, Node: UNIVERSAL/exports, Next: UNIVERSAL/require, Prev: UNIVERSAL, Up: Module List Lightweight, universal exporting of variables ********************************************* NAME ==== UNIVERSAL::exports - Lightweight, universal exporting of variables SYNOPSIS ======== package Foo; use UNIVERSAL::exports; # Just like Exporter. @EXPORT = qw($This &That); @EXPORT_OK = qw(@Left %Right); # Meanwhile, in another piece of code! package Bar; use Foo; # exports $This and &That. DESCRIPTION =========== This is an alternative to Exporter intended to provide a universal, lightweight subset of its functionality. It supports import, `@EXPORT' and `@EXPORT_OK' and not a whole lot else. Additionally, `exports()' is provided to find out what symbols a module exports. UNIVERSAL::exports places its methods in the UNIVERSAL namespace, so there is no need to subclass from it. Methods ======= UNIVERSAL::exports has two public methods... import Some::Module->import; Some::Module->import(@symbols); Works just like `Exporter::import()' excepting it only honors @Some::Module::EXPORT and @Some::Module::EXPORT_OK. The given @symbols are exported to the current package provided they are in @Some::Module::EXPORT or @Some::Module::EXPORT_OK. Otherwise an exception is thrown (ie. the program dies). If @symbols is not given, everything in @Some::Module::EXPORT is exported. exports @exported_symbols = Some::Module->exports; Some::Module->exports($symbol); Reports what symbols are exported by Some::Module. With no arguments, it simply returns a list of all exportable symbols. Otherwise, it reports if it will export a given $symbol. DIAGNOSTICS =========== '"%s" is not exported by the %s module' Attempted to import a symbol which is not in @EXPORT or @EXPORT_OK. 'Can\'t export symbol: %s' Attempted to import a symbol of an unknown type (ie. the leading $@% salad wasn't recognized). AUTHORS ======= Michael G Schwern SEE ALSO ======== *Note Exporter: Exporter,, *Note UNIVERSAL/require: UNIVERSAL/require,, http://dev.perl.org/rfc/257.pod  File: pm.info, Node: UNIVERSAL/require, Next: URI, Prev: UNIVERSAL/exports, Up: Module List require() modules from a variable ********************************* NAME ==== UNIVERSAL::require - require() modules from a variable SYNOPSIS ======== # This only needs to be said once in your program. require UNIVERSAL::require; # Same as "require Some::Module;" Some::Module->require; # Ditto my $module = 'Some::Module'; $module->require; DESCRIPTION =========== If you've ever had to do this... eval "require $module"; to get around the bareword caveats on require(), this module is for you. It creates a universal require() class method that will work with every Perl module. So instead of doing some arcane eval() work, you can do this: $module->require; And `use Some::Module' can be done dynamically like so: BEGIN { $module->require; $module->import; } It doesn't save you much typing, but it'll make alot more sense to someone who's not a ninth level Perl acolyte. Methods ======= require $module->require; $module->require($version); This works exactly like Perl's require, except without the bareword restriction. Since require() is placed in the UNIVERSAL namespace, it will work on any module. You just have to use UNIVERSAL::require somewhere in your code. AUTHOR ====== Michael G Schwern SEE ALSO ======== *Note UNIVERSAL/exports: UNIVERSAL/exports,, `require', *Note Perlfunc: (perl.info)perlfunc,, http://dev.perl.org/rfc/253.pod  File: pm.info, Node: URI, Next: URI2/Heuristic, Prev: UNIVERSAL/require, Up: Module List Uniform Resource Identifiers (absolute and relative) **************************************************** NAME ==== URI - Uniform Resource Identifiers (absolute and relative) SYNOPSIS ======== $u1 = URI->new("http://www.perl.com"); $u2 = URI->new("foo", "http"); $u3 = $u2->abs($u1); $u4 = $u3->clone; $u5 = URI->new("HTTP://WWW.perl.com:80")->canonical; $str = $u->as_string; $str = "$u"; $scheme = $u->scheme; $opaque = $u->opaque; $path = $u->path; $frag = $u->fragment; $u->scheme("ftp"); $u->host("ftp.perl.com"); $u->path("cpan/"); DESCRIPTION =========== This module implements the `URI' class. Objects of this class represent "Uniform Resource Identifier references" as specified in RFC 2396. A Uniform Resource Identifier is a compact string of characters for identifying an abstract or physical resource. A Uniform Resource Identifier can be further classified either a Uniform Resource Locator (URL) or a Uniform Resource Name (URN). The distinction between URL and URN does not matter to the `URI' class interface. A "URI-reference" is a URI that may have additional information attached in the form of a fragment identifier. An absolute URI reference consists of three parts. A scheme, a *scheme specific part* and a fragment identifier. A subset of URI references share a common syntax for hierarchical namespaces. For these the scheme specific part is further broken down into *authority*, path and query components. These URI can also take the form of relative URI references, where the scheme (and usually also the authority) component is missing, but implied by the context of the URI reference. The three forms of URI reference syntax are summarized as follows: :# ://?# ?# The components that a URI reference can be divided into depend on the scheme. The `URI' class provides methods to get and set the individual components. The methods available for a specific `URI' object depend on the scheme. CONSTRUCTORS ============ The following methods construct new `URI' objects: $uri = URI->new( $str, [$scheme] ) This class method constructs a new URI object. The string representation of a URI is given as argument together with an optional scheme specification. Common URI wrappers like "" and <>, as well as leading and trailing white space, are automatically removed from the $str argument before it is processed further. The constructor determines the scheme, maps this to an appropriate URI subclass, constructs a new object of that class and returns it. The $scheme argument is only used when $str is a relative URI. It can either be a simple string that denotes the scheme, a string containing an absolute URI reference or an absolute `URI' object. If no $scheme is specified for a relative URI $str, then $str is simply treated as a generic URI (no scheme specific methods available). The set of characters available for building URI references is restricted (see *Note URI/Escape: URI/Escape,). Characters outside this set are automatically escaped by the URI constructor. $uri = URI->new_abs( $str, $base_uri ) This constructs a new absolute URI object. The $str argument can denote a relative or absolute URI. If relative, then it will be absolutized using $base_uri as base. The $base_uri must be an absolute URI. $uri = URI::file->new( $filename, [$os] ) This constructs a new file URI from a file name. See *Note URI/file: URI/file,. $uri = URI::file->new_abs( $filename, [$os] ) This constructs a new absolute file URI from a file name. See *Note URI/file: URI/file,. $uri = URI::file->cwd This returns the current working directory as a file URI. See *Note URI/file: URI/file,. $uri->clone This method returns a copy of the $uri. COMMON METHODS ============== The methods described in this section are available for all `URI' objects. Methods that give access to components of a URI will always return the old value of the component. The value returned will be undef if the component was not present. There is generally a difference between a component that is empty (represented as "") and a component that is missing (represented as undef). If an accessor method is given an argument it will update the corresponding component in addition to returning the old value of the component. Passing an undefined argument will remove the component (if possible). The description of the various accessor methods will tell if the component is passed as an escaped or an unescaped string. Components that can be futher divided into sub-parts are usually passed escaped, as unescaping might change its semantics. The common methods available for all URI are: $uri->scheme( [$new_scheme] ) This method sets and returns the scheme part of the $uri. If the $uri is relative, then $uri->scheme returns undef. If called with an argument, it will update the scheme of $uri, possibly changing the class of $uri, and return the old scheme value. The method croaks if the new scheme name is illegal; scheme names must begin with a letter and must consist of only US-ASCII letters, numbers, and a few special marks: ".", "+", "-". This restriction effectively means that scheme have to be passed unescaped. Passing an undefined argument to the scheme method will make the URI relative (if possible). Letter case does not matter for scheme names. The string returned by $uri->scheme is always lowercase. If you want the scheme just as it was written in the URI in its original case, you can use the $uri->_scheme method instead. $uri->opaque( [$new_opaque] ) This method sets and returns the scheme specific part of the $uri (everything between the scheme and the fragment) as an escaped string. $uri->path( [$new_path] ) This method sets and returns the same value as $uri->opaque unless the URI supports the generic syntax for hierarchical namespaces. In that case the generic method is overridden to set and return the part of the URI between the *host name* and the fragment. $uri->fragment( [$new_frag] ) This method returns the fragment identifier of a URI reference as an escaped string. $uri->as_string This method returns a URI object to a plain string. URI objects are also converted to plain strings automatically by overloading. This means that $uri objects can be used as plain strings in most Perl constructs. $uri->canonical This method will return a normalized version of the URI. The rules for normalization are scheme dependent. It usually involves lowercasing of the scheme and the Internet host name components, removing the explicit port specification if it matches the default port, uppercasing all escape sequences, and unescaping octets that can be better represented as plain characters. For efficiency reasons, if the $uri already was in normalized form, then a reference to it is returned instead of a copy. $uri->eq( $other_uri ) URI::eq( $first_uri, $other_uri ) This method tests whether two URI references are equal. URI references that normalize to the same string are considered equal. The method can also be used as a plain function which can also test two string arguments. If you need to test whether two `URI' object references denote the same object, use the '==' operator. $uri->abs( $base_uri ) This method returns an absolute URI reference. If $uri already is absolute, then a reference to it is simply returned. If the $uri is relative, then a new absolute URI is constructed by combining the $uri and the $base_uri, and returned. $uri->rel( $base_uri ) This method returns a relative URI reference if it is possible to make one that denotes the same resource relative to $base_uri. If not, then $uri is simply returned. GENERIC METHODS =============== The following methods are available to schemes that use the common/generic syntax for hierarchical namespaces. The description of schemes below will tell which one these are. Unknown schemes are assumed to support the generic syntax, and therefore the following methods: $uri->authority( [$new_authority] ) This method sets and returns the escaped authority component of the $uri. $uri->path( [$new_path] ) This method sets and returns the escaped path component of the $uri (the part between the host name and the query or fragment). The path will never be undefined, but it can be the empty string. $uri->path_query( [$new_path_query] ) This method sets and returns the escaped path and query components as a single entity. The path and the query are separated by a "?" character, but the query can itself contain "?". $uri->path_segments( [$segment,...] ) This method sets and returns the path. In scalar context it returns the same value as $uri->path. In list context it will return the unescaped path segments that make up the path. Path segments that have parameters are returned as an anonymous array. The first element is the unescaped path segment proper. Subsequent elements are escaped parameter strings. Such an anonymous array uses overloading so it can be treated as a string too, but this string does not include the parameters. $uri->query( [$new_query] ) This method sets and returns the escaped query component of the $uri. $uri->query_form( [$key => $value,...] ) This method sets and returns query components that use the *application/x-www-form-urlencoded* format. Key/value pairs are separated by "&" and the key is separated from the value with a "=" character. $uri->query_keywords( [$keywords,...] ) This method sets and returns query components that use the keywords separated by "+" format. SERVER METHODS ============== Schemes where the *authority* component denotes a Internet host will have the following methods available in addition to the generic methods. $uri->userinfo( [$new_userinfo] ) This method sets and returns the escaped userinfo part of the authority componenent. For some schemes this will be a user name and a password separated by a colon. This practice is not recommended. Embedding passwords in clear text (such as URI) has proven to be a security risk in almost every case where it has been used. $uri->host( [$new_host] ) This method sets and returns the unescaped hostname. If the $new_host string ends with a colon and a number, then this number will also set the port. $uri->port( [ $new_port] ) This method sets and returns the port. The port is simple integer that should be greater than 0. If no explicit port is specified in the URI, then the default port of the URI scheme is returned. If you don't want the default port substituted, then you can use the $uri->_port method instead. $uri->host_port( [ $new_host_port ] ) This method sets and returns the host and port as a single unit. The returned value will include a port, even if it matches the default port. The host part and the port part is separated with a colon; ":". $uri->default_port This method returns the default port of the URI scheme that $uri belongs to. For http this will be the number 80, for ftp this will be the number 21, etc. The default port for a scheme can not be changed. SCHEME SPECIFIC SUPPORT ======================= The following URI schemes are specifically supported. For `URI' objects not belonging to one of these you can only use the common and generic methods. data: The data URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally. `URI' objects belonging to the data scheme support the common methods and two new methods to access their scheme specific components; $uri->media_type and $uri->data. See *Note URI/data: URI/data, for details. file: An old specification of the file URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but file URI references are in common use. `URI' objects belonging to the file scheme support the common and generic methods. In addition they provide two methods to map file URI back to local file names; $uri->file and $uri->dir. See *Note URI/file: URI/file, for details. ftp: An old specification of the ftp URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but ftp URI references are in common use. `URI' objects belonging to the ftp scheme support the common, generic and server methods. In addition they provide two methods to access the userinfo sub-components: $uri->user and $uri->password. *gopher*: The *gopher* URI scheme is specified in and will hopefully be available as a RFC 2396 based specification. `URI' objects belonging to the gopher scheme support the common, generic and server methods. In addition they support some methods to access gopher specific path components: $uri->gopher_type, $uri->selector, $uri->search, $uri->string. http: The http URI scheme is specified in (which will become an RFC soon). The scheme is used to reference resources hosted by HTTP servers. `URI' objects belonging to the http scheme support the common, generic and server methods. *https*: The *https* URI scheme is a Netscape invention which is commonly implemented. The scheme is used to reference HTTP servers through SSL connections. It's syntax is the same as http, but the default port is different. *ldap*: The *ldap* URI scheme is specified in RFC 2255. LDAP is the Lightweight Directory Access Protocol. A ldap URI describes an LDAP search operation to perform to retrieve information from an LDAP directory. `URI' objects belonging to the ldap scheme support the common, generic and server methods as well as specific ldap methods; $uri->dn, $uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See *Note URI/ldap: URI/ldap, for details. mailto: The mailto URI scheme is specified in RFC 2368. The scheme was originally used to designate the Internet mailing address of an individual or service. It has (in RFC 2368) been extended to allow setting of other mail header fields and the message body. `URI' objects belonging to the mailto scheme support the common methods and the generic query methods. In addition they support the following mailto specific methods: $uri->to, $uri->headers. news: The news, *nntp* and *snews* URI schemes are specified in and will hopefully be available as a RFC 2396 based specification soon. `URI' objects belonging to the news scheme support the common, generic and server methods. In addition they provide some methods to access the path: $uri->group and $uri->message. *nntp*: See news scheme. pop: The pop URI scheme is specified in RFC 2384. The scheme is used to reference a POP3 mailbox. `URI' objects belonging to the pop scheme support the common, generic and server methods. In addition they provide two methods to access the userinfo components: $uri->user and $uri->auth *rlogin*: An old speficication of the *rlogin* URI scheme is found in RFC 1738. `URI' objects belonging to the rlogin scheme support the common, generic and server methods. *rsync*: Information about rsync is available from http://rsync.samba.org. `URI' objects belonging to the rsync scheme support the common, generic and server methods. In addition they provide methods to access the userinfo sub-components: $uri->user and $uri->password. *snews*: See news scheme. It's syntax is the same as news, but the default port is different. *telnet*: An old speficication of the *telnet* URI scheme is found in RFC 1738. `URI' objects belonging to the telnet scheme support the common, generic and server methods. CONFIGURATION VARIABLES ======================= The following configuration variables influence how the class and it's methods behave: $URI::ABS_ALLOW_RELATIVE_SCHEME Some older parsers used to allow the scheme name to be present in the relative URL if it was the same as the base URL scheme. RFC 2396 says that this should be avoided, but you can enable this old behaviour by setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value. The difference is demonstrated by the following examples: URI->new("http:foo")->abs("http://host/a/b") ==> "http:foo" local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1; URI->new("http:foo")->abs("http://host/a/b") ==> "http:/host/a/foo" $URI::ABS_REMOTE_LEADING_DOTS You can also have the abs() method ignore excess ".." segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS to a TRUE value. The difference is demonstrated by the following examples: URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/../../foo" local $URI::URL::ABS_REMOTE_LEADING_DOTS = 1; URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/foo" BUGS ==== Using regexp variables like $1 directly as argument to the URI methods do not work too well with current perl implementations. I would argue that this is actually a bug in perl. The workaround is to quote them. E.g.: /(...)/ || die; $u->query("$1"); SEE ALSO ======== *Note URI/file: URI/file,, *Note URI/WithBase: URI/WithBase,, *Note URI/Escape: URI/Escape,, *Note URI/Heuristic: URI/Heuristic, RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax", Berners-Lee, Fielding, Masinter, August 1998. COPYRIGHT ========= Copyright 1995-2001 Gisle Aas. Copyright 1995 Martijn Koster. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS / ACKNOWLEDGMENTS ========================= This module is based on the URI::URL module, which in turn was (distantly) based on the `wwwurl.pl' code in the libwww-perl for perl4 developed by Roy Fielding, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter. URI::URL was developed by Gisle Aas, Tim Bunce, Roy Fielding and Martijn Koster with input from other people on the libwww-perl mailing list. `URI' and related subclasses was developed by Gisle Aas.  File: pm.info, Node: URI2/Heuristic, Next: URI/Attr, Prev: URI, Up: Module List Expand URL using heuristics *************************** NAME ==== uf_urlstr - Expand URL using heuristics SYNOPSIS ======== use URI2::Heuristic qw(uf_urlstr); $url = uf_urlstr("perl"); # http://www.perl.com $url = uf_urlstr("www.sol.no/sol"); # http://www.sol.no/sol $url = uf_urlstr("aas"); # http://www.aas.no $url = uf_urlstr("ftp.funet.fi"); # ftp://ftp.funet.fi $url = uf_urlstr("/etc/passwd"); # file:/etc/passwd DESCRIPTION =========== This module provide functions that expand strings into real absolute URLs using some builtin heuristics. Strings that already represent absolute URLs (i.e. start with a `scheme:' part) are never modified and are returned unchanged. The main use of these functions are to allow abbreviated URLs similar to what many web browsers allow for URLs typed in by the user. The following functions are provided: uf_urlstr($str) The uf_urlstr() function will try to make the string passed as argument into a proper absolute URL string. The "uf_" prefix stands for "User Friendly". uf_url($str) This functions work the same way as uf_urlstr() but it will return a `URI2::URL' object. ENVIRONMENT =========== If the hostname portion of a URL does not contain any dots, then certain qualified guesses will be made. These guesses are governed be the following two environment variables. COUNTRY This is the two letter country code (ISO 3166) for your location. If the domain name of your host ends with two letters, then it is taken to be the default country. See also *Note Locale/Country: Locale/Country,. URL_GUESS_PATTERN Contain a space separated list of URL patterns to try. The string "ACME" is for some reason used as a placeholder for the host name in the URL provided. Example: URL_GUESS_PATTERN="www.ACME.no www.ACME.se www.ACME.com" export URL_GUESS_PATTERN Specifying URL_GUESS_PATTERN disables any guessing rules based on country. An empty URL_GUESS_PATTERN disables any guessing that involves host name lookups. COPYRIGHT ========= Copyright 1997-1998, Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: URI/Attr, Next: URI/Bookmark, Prev: URI2/Heuristic, Up: Module List associate attributes with the URI name space ******************************************** NAME ==== URI::Attr - associate attributes with the URI name space SYNOPSIS ======== use URI::Attr; $attr = URI::Attr->new; $attr->attr_update(SERVER => "http://www.perl.com")->{visit} = "yes"; if ($attr->attr_plain($url, "visit")) { #... } DESCRIPTION =========== Instances of the *URI::Attr* class is able to associate attributes with "places" in the URI name space. The main idea is to be able to look up all attributes that are relevant to a specific absolute URI efficiently and to be able to override attributes at different hierarchal levels of the URI namespace. The levels of the URI namespace is given the following names: GLOBAL - affect all URIs SCHEME - affect all URIs of the given scheme DOMAIN - affect all URIs within the given domain (domains nest) HOST - a given host SERVER - a specific server (port) on the host DIR - a directory component (nestable) PATH - the final path component GLOBAL and SCHEME are the only levels available for all URIs. The other levels only make sense for URIs that follow the generic URL pattern (like http: and ftp: schemes). Other level names can be used for specific schemes. Lets take a look at an example. Consider the following URL: http://www.perl.com/cgi-bin/cpan_mod?module=LWP This URL can be broken up into the following hierarchal levels: SCHEME http DOMAIN .com DOMAIN .perl HOST www SERVER 80 (implicit port) DIR cgi-bin PATH cpan-mod METHODS ======= The following methods are provided by this class: $db = URI::Attr->new The constructor takes now arguments. It returns a newly allocated *URI::Attr* object. $db->attr($uri, [$attr_name]) Look up all attributes that are relevant to the given $uri. In scalar context only the most specific attribute is returned. In list context all attributes are returned, with the most specific first. Each attribute is represented by a reference to a 2 element array. The first element is the name of the level. The second element is the attribute(s). If the optional $attr_name is given, only the attribute with the given name is considered. If no $attr_name is given, then the attributes are returned as a hash reference. $db->attr_plain($uri, [$attr_name]) Same as attr() but only return the attribute(s), not the associated level names. $db->attr_update($level, $uri) Returns a hash reference associated with $uri at the given $level. If the given $level name does not make sense for the given $uri return . If the $level is nestable, then the most specific instance related to the $uri is used. The hash returned can then be updated in order to assign attributes to the given place in the URI name space. $db->as_string Dump the content of the *URI::Attr* object. Mainly useful for debugging. BUGS ==== There ought to be a way to associate attributes with domains/hosts without regard to scheme (and for several schemes and several domain/hosts). Think, think,... Perhaps there should be defined relationships between schemes, so that for instace everything that is valid for http is also valid for *https*, but not the other way around. Same goes for *nntp* and news which should be treated as the same thing and their relation to *snews*. A similar concept is present in w3c-libwww under the name *URL Tree*. The scheme is simply ignored here and the root of the tree is the hostname part of the URL. A totally different approach would be associate attributes with regular expressions that are matched against URLs. Perhaps this would have been a better way? SEE ALSO ======== *Note URI: URI, COPYRIGHT ========= Copyright 1998, Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: URI/Bookmark, Next: URI/Bookmark/Netscape, Prev: URI/Attr, Up: Module List Perl module class encapsulating an entry in a typical bookmark file. ******************************************************************** NAME ==== URI::Bookmark - Perl module class encapsulating an entry in a typical bookmark file. SYNOPSIS ======== See *Note URI/Bookmarks: URI/Bookmarks,. DESCRIPTION =========== URI::Bookmark is a subclass of Tree::DAG_Node, so that each entry in the bookmark collection is a node in a directed acyclic graph. All methods from Tree::DAG_Node are available. Each instance has a type, which can be: `root' -- the root of the bookmark tree (this is also a folder) `folder' -- a folder containing more entries `bookmark' -- a bookmark (duh) `rule' -- a horizontal rule separating entries METHODS ------- * *set_attribs* $bookmark->set_attribs(name => 'Slashdot', type => bookmark, HREF => 'http://slashdot.org'); This method should be self-explanatory. The allowed attributes are: `name', `type', `HREF', `ADD_DATE', `LAST_MODIFIED', `LAST_VISIT', `ALIASOF', `ALIASID', `description'. Attempts to set any others will be ignored and generate a warning. * *dump_attribs* $bookmark->dump_attribs(); Dumps all attribute (key, value) pairs for this node, one per line. This is only really for debugging. * type my $type = $bookmark->type(); $bookmark->type($new_type); If a parameter is specified, sets the bookmark to the type given by it. Generates a warning if the type given isn't valid. Returns the current type of the bookmark. AUTHOR ====== Adam Spiers SEE ALSO ======== *Note URI/Bookmarks: URI/Bookmarks,, `URI::Bookmarks::*' in this node, `URI::Bookmark::*' in this node, `perl(1)' in this node.  File: pm.info, Node: URI/Bookmark/Netscape, Next: URI/Bookmarks, Prev: URI/Bookmark, Up: Module List Perl module containing routines for individual Netscape bookmarks ***************************************************************** NAME ==== URI::Bookmarks::Netscape - Perl module containing routines for individual Netscape bookmarks SYNOPSIS ======== See *Note URI/Bookmarks: URI/Bookmarks,. DESCRIPTION =========== URI::Bookmark::Netscape contains some helper routines specifically for URI::Bookmark objects which were originally from Netscape bookmark files. AUTHOR ====== Adam Spiers SEE ALSO ======== *Note URI/Bookmarks: URI/Bookmarks,, `URI::Bookmarks::*' in this node, *Note URI/Bookmark: URI/Bookmark,, `perl(1)' in this node.  File: pm.info, Node: URI/Bookmarks, Next: URI/Bookmarks/Netscape, Prev: URI/Bookmark/Netscape, Up: Module List Perl module class encapsulating bookmark files ********************************************** NAME ==== URI::Bookmarks - Perl module class encapsulating bookmark files SYNOPSIS ======== use URI::Bookmarks; # URI::Bookmarks automagically detects that we're dealing with a # collection of Netscape bookmarks my $bookmarks = new URI::Bookmarks(file => "$ENV{HOME}/.netscape/bookmarks.html"); my $bookmarks = new URI::Bookmarks(handle => $fh); my $bookmarks = new URI::Bookmarks(array => \@lines); # Manipulate $bookmarks using nice tree methods from Tree::DAG_Node, # e.g. delete all bookmarks under $folder: ($bookmarks->name_to_nodes($folder))[0]->unlink_from_mother(); # Then output the new file. print $bookmarks->export('Netscape array'); DESCRIPTION =========== URI::Bookmarks provides a class for manipulating hierarchical collections of bookmarks. Each entry in the collection is an object of type URI::Bookmark, which is in turn a subclass of Tree::DAG_Node, and hence all standard tree manipulation methods are available (see the documentation for Tree::DAG_Node). * *build_name_lookup* $bookmarks->build_name_lookup(); This method builds an internal hash which maps node names to arrays of nodes which have the corresponding key as their name. It only needs to be called if you want to rebuild the hash after modifying the bookmark collection in some way; if the hash is needed and has not been built, it will be built automatically. * *tree_root* my $tree_root_node = $bookmarks->tree_root(); $bookmarks->tree_root($new_root); Returns the current root node of the tree of bookmarks. If the optional parameter is provided, the root node is changed to it. * *name_to_nodes* my @nodes = $bookmarks->name_to_nodes('Cinemas'); Returns an array of all nodes matching the given name. * title my $title = $bookmarks->title(); $bookmarks->title($new_title); Returns the current title of the collection of bookmarks. If the optional parameter is provided, the title is changed to it. * origin my $origin = $bookmarks->origin(); my $origin_type = $origin{type}; Returns a hash containing information about the origin of the collection of bookmarks. * export my @lines = $bookmarks->export('Netscape array'); The interface to the export routines. The examples above show the currently available export types. * *all_URLs* $bookmarks->all_URLs(); This method simply returns an array of all the URLs in the collection of bookmarks. BUGS ==== The file key of new() might not be safe. AUTHOR ====== Adam Spiers SEE ALSO ======== `URI::Bookmarks::*' in this node, *Note URI/Bookmark: URI/Bookmark,, `URI::Bookmark::*' in this node, `perl(1)' in this node.