- NAME
- SYNOPSIS
- DESCRIPTION
- BUGS

# NAME

ActivePerl::PPM::Client - Client class

# SYNOPSIS

      my $ppm = ActivePerl::PPM::Client->new;

# DESCRIPTION

The `ActivePerl::PPM::Client` object ties together a set of install areas and repositories and allow the installed packages to be managed. The install areas are deducted from the values of `@INC` when the object is constructed.

The following methods are provided:

$client = ActivePerl::PPM::Client->new
$client = ActivePerl::PPM::Client->new( $home_dir )
$client = ActivePerl::PPM::Client->new( %opt )

  The constructor creates a new client based on the configuration found in $home_dir which defaults to $ENV{HOME}/.ActivePerl directory of the current user. If no such directory is found it is created.

  Alternatively, key/value pairs to configure the client is passed in. The following options are recognized:

  home => $home_dir

    Directory where the client configuration database lives.

  inc => \@array

    Override the list of locations to initialize install areas from.

  arch => $arch

    Allow to override the architecture identification string used. Mainly userful for debugging.

$client->arch

  A string that identifies the architecture for the current perl. This must match the ARCHITECTURE/NAME attribute of PPDs for them to match.

$client->area( $name )

  Returns an object representing the given named install area. The method will croak if no install area with the given $name is known. The `perl` and `site` areas will always be available. See ActivePerl::PPM::InstallArea for methods available on the returned object.

$client->areas

  Return list of available install area names. The list is ordered to match the corresponding entries in `@INC`.

$client->default_install_area

  Return the name of the area where installations should normally go. Might return `undef` if there is no appropriate default.

$value = $client->config_get( $key )
($value1, $value2, ...) = $client->config_get( $key1, $key2, ...)

  Read back one or more configuration values previosly saved.

($key, $value, ...) = $client->config_list
($key, $value, ...) = $client->config_list( $glob_pattern )

  Return all key/value pairs where $key match the given $glob_pattern. If $glob_pattern is missing return all key/value pairs.

$client->config_save( $key => $value )
$client->config_save( %pairs )

  Will persistently store the given key/value pairs. The values can be extracted again with $client->config_get().

$client->repo( $repo_id )

  Returns a reference to a hash describing the repo with the given identifier. The interesting fields of this hash are:

  name

    The full (user friendly) name of the repository. Can be modified by $repo->repo_set_name().

  enabled

    A boolean that indicated if the repo is enabled or not. Can be modified by $repo->repo_enable().

  pkgs

    The number of packages provided by this repository.

  packlist_uri

    The URI that the PPM client will monitor for changes to the repository. This URI can denote a packlist.xml, packlist.lst file or an HTML document with links to PPD files (typically a server generated directory listing). The URI can use any scheme that LWP supports and can embed a username and password for HTTP using this syntax: `http://user:pass@ppm.example.com/`.

  packlist_last_status

    The HTTP status code reported last time the PPM client tried to access `packlist_uri` document.

  packlist_last_access

    When did we last try to to access the `packlist_uri` document. The value is seconds from epoch as for perl's time() function.

  packlist_fresh_until

    When do we need to refetch the `packlist_uri` document. The value is seconds from epoch as for perl's time() function.

$client->repos

  Returns list of available repo identifiers.

$client->repo_add( name => $name, packlist_uri => $uri )

  Will add a new repository with the given attributes. The method will croak if a repository with the same `packlist_uri` already exists. The return value is the $repo_id of the new repository.

$client->repo_delete( $repo_id )

  Will make the client forget about the given repository.

$client->repo_enable( $repo_id )
$client->repo_enable( $repo_id, $bool )

  Makes it possible to enable and disable the given reposiory. If $bool is provided and is FALSE, then the repository is disabled. The return value is TRUE if the given repository was enabled.

$client->repo_set_name( $repo_id, $name )

  Will update the name by which the given repo is known.

$client->repo_set_packlist_uri( $repo_id, $uri )

  Will update the address of the packlist to monitor for the given repository. Will croak if the $uri is already used by some other repo.

  Updating the URI will loose all cached information about the repo. A new 'repo_sync' is needed to update this information.

$client->repo_sync( %args )

  Will sync the local cache of packages from the enabled repositories. Remote repositories are not contacted if the cache is not considered stale yet. The following options are recognized:

  force => $bool

    If TRUE force state to be transfered again from remote repositories. Make requests unconditional.

  validate => $bool

    If TRUE validate state from remote repositories even if state still believed to be fresh. Will still send conditional requests.

  max_ppd => $num

    If repository is an HTML document set limit for how many PPD links it might contain. The default is 100.

  repo => $repo_id

    Pass `repo` with an identifier to only sync the given repo.

$client->search( $pattern )
$client->search( $pattern, $field,... )

  Will search for packages matching the given glob style $pattern. Without further arguments this will return a list of package names. With $field arguments it will return a list of array references, each one filled in with the corresponding values for maching packages.

  The supported field names are:

          id
          name
          version
          release_date
          author
          abstract
          ppd_uri
          ppd_etag
          ppd_fresh_until
          codebase
          repo_id
          cannot_install

  See ActivePerl::PPM::RepoPackage (and ActivePerl::PPM::Package) for a description of these fields. The `cannot_install` field is a boolean that is TRUE for packages that can't be installed for some reason.

$client->search_lookup( $num )

  Will look up the given package from the last search() result, where $num matches the 1-based index into the list returned by the last search. This will return an ActivePerl::PPM::RepoPackage object.

$client->packages
$client->packages( $field,... )

  Without arguments returns the ids of packages available. In scalar context returns the number of packages.

  With arguments return a list of array references each one representing one package. The elements of each array are the fields requested. For the list of field names that can be used see the description of the "search" method above.

$client->package( $id )
$client->package( $name, $version )

  Returns the ActivePerl::PPM::RepoPackage object matching the arguments or `undef` if none match. If $version is passed as `undef`, the package needs to be versionless to be returned.

$client->feature_best( $feature )

  Returns the highest version number provided for the given feature by the packages found in all enabled repositories. The method return `undef` if no package provide this feature.

$client->package_best( $feature, $version )

  Returns the best package of all enabled repositories that provide the given feature at or better than the given version.

$client->feature_have( $feature )
$client->feature_have( $feature, @areas )

  Returns the installed version number of the given feature. Returns `undef` if none of the installed packages provide this feature.

  If one or more @areas are provided, only look in the areas given by these names.

$client->packages_depending_on( $pkg, $area )

  Returns the packages (as `ActivePerl::PPM::Package` objects) that would "break" if the given package was uninstalled. This means that the returned packages are those that depend on features that the given package provide. In scalar context return number of packages.

  The $pkg argument can be either a package name or a package object.

$client->packages_missing( %args )

  Returns the list of packages to install in order to obtain the requested features. The returned list consist of ActivePerl::PPM::RepoPackage objects. The attribute `_wanted` will be TRUE if a package was requested directly. The attribute `_needed_by` will be an array reference of package names listing packages having resolved dependencies on this package. These attributes do not exclude each other.

  The returned list will be empty if all the requested features are already installed.

  The method will croak if nothing provides the requested features, if dependencies can't be resolved or if the packages selected have conflicting dependencies.

  The arguments to the function are passed as key/value pairs:

  want => \@features

    This is the list of features to resolve. The elements can be plain strings denoting feature names, or references to arrays containing a $name, $version pair. If $version is provided as `undef` then this is taken as an upgrade request and the function will try to find the packages that provide the best possible version of this feature.

  have => \@pkgs

    List of packages you already have decided to install. The function will check if any of these packages provide needed features before looking anywhere else.

  want_deps => \@pkgs

    Resolve any dependencies for the given packages.

  area => \@areas

    List of names of install areas to consider when determining if requested features or dependencies are already installed or not.

  force => $bool

    If TRUE then return packages that provide the given features even if they are already installed. Will also disable check for downgrades.

  follow_deps => $str

    In what way should packages dependencies be resolved. The provided $str can take the values `all`, `missing`, or `none`. The default is `missing`. If $str is `all` then dependent packages are returned even if they are already installed. If $str is `missing` then only missing dependencies are returned. If $str is `none` then dependencies are ignored.

  error_handler => \&callback

    Call the given error handler instead of croaking in the case of trouble. Error messages are provided as argument. There can be more than one.

    Providing an error_handler allow the function to return missing packages for working dependencies even if not all dependencies worked out.

$client->install( %args )

  Will download, unpack and install the given packages. The function will raise an exception of it gets into trouble, otherwise it will return

  The arguments to the function are passed as key/value pairs:

  packages => \@pkgs

    Mandatory argument that provide the packages to install. The array passed should contain `ActivePerl::PPM::Package` objects.

  area => $area

    What install area to install into. If not provided, then $client->default_install_area is used.

  run_cb => \&func

    A callback function that should behave like &ActivePerl::Run::run which will be called to execute the commands of the post install script. If not provided, then &ActivePerl::Run::run will be used.

$client->profile_xml

  Returns an XML document that describes the configured repositories and the installed packages.

$client->profile_xml_restore( $profile_xml, %opt )

  Will try to restore the repositories and packages described by the passed in XML document. The document should be one generated by the profile_xml method. The following options are recognized:

  restore_repo => $bool

    Pass a FALSE value to suppress adding the repositories found in the profile document.

  restore_pkgs => $bool

    Pass a FALSE value to suppress installation of the packages listed in the profile document that are missing.

  verbose => $bool

    Log extra information about the steps taken when TRUE.

  area => $area_name

    Which install area to install into. If not provided, then $client->default_install_area is used.

# BUGS

none.