NAME

ALPM::Transaction - An object wrapper for transaction functions.

SYNOPSIS

my $t = ALPM->transaction( flags => 'nodeps force',
                           event => sub { ... },
                           conv  => sub { ... },
                           progress => sub { ... },
                          );
$t->sync( $_ ) for qw/ perl perl-alpm /;
eval { $t->commit };
if ( $EVAL_ERROR ) {
    die unless $t->{error}; # re-throw an unknown error
    given ( $t->{error}{type} ) {
        when ( 'fileconflict' ) {
            for my $path ( @{ $t->{error}{list} } ) {
                say "Conflicting Path: $path";
            }
        }
        when ( 'invalid_package' ) {
            say "Corrupt Package: $_" foreach ( @{ $t->{error}{list} } );
        }
    }
}

DESCRIPTION

The transaction object wraps all the alpm_trans_... C functions. When the object goes out of scope and is automatically garbage collected, the transaction is released.

METHODS

sync

1 = $TRANS->sync( $PKGNAME );

Sync adds a package to synchronize via the database repos. The package from the database repository is downloaded and installed.

Parameters

$PKGNAME: The name of a package.

pkgfile

1 = $TRANS->pkgfile( $PKGPATH );

Adds a package file to be installed by the transaction.

Parameters

$PKGPATH: The path to the package file to install.

remove

1 = $TRANS->remove( $PKGNAME );

Adds a package to be removed/uninstalled by the transaction.

Parameters

$PKGNAME: The name of a package.

sync_from_db

1 = $TRANS->sync_from_db( $DBNAME, $PKGNAME );

Sync a package from the specified database.

Parameters

$DBNAME: The name of the database.
$PKGNAME: The name of a package.

sysupgrade

1 = $TRANS->sysupgrade( [$ENABLE_DOWNGRADE] );

Prepares a transaction for the actions it needs to perform a system upgrade. A system upgrade will sync all the packages that are outdated in the local database.

Parameters

$ENABLE_DOWNGRADE

Whether to allow downgrading of packages. If the version installed is greated than the version on the remote database, than the local version installed will still be replaced.

Supply any argument in order to enable downgrading. The value of the argument is not checked. Do not supply an argument if you do not wish to enable downgrading.

get_flags

$FLAGSTR|@FLAGLIST = $TRANS->get_flags();

Returns a list or string representing the flags specified when creating the transaction with "transaction" in ALPM.

Parameters

None

Returns

$FLAGSTR: A string similar to the one used when creating the transaction. The flags may be in a different order than originally passed to the "transaction" in ALPM method. This string is returned in scalar context.
@FLAGLIST: A list of strings with each representing a flag. This list is returned when in list context.

prepare

$TRUE = $TRANS->prepare()

Prepares a transaction. The transaction will be checked for problems and could even throw an error.

"commit" checks if a transaction is prepared. If not it calls this prepare method automatically.

Parameters: None

commit

1 = $TRANS->commit();

Commits the transaction. Actually performs the actions loaded into the transaction.

Parameters: None

get_additions

@PKGS = $TRANS->get_additions();

This method will return a list of packages that are going to be installed by the transaction.

Parameters

None

Returns

@PKGS: A list of ALPM::Package objects.

get_removals

@PKGS = $TRANS->get_removals();

This method will return a list of packages that are going to be uninstalled by the transaction.

Parameters

None

Returns

@PKGS: A list of ALPM::Package objects.

RELEASING A TRANSACTION

You may have noticed there is no release method. A transaction is released as soon as it goes out of scope and is garbage collected. For example:

sub foo
{
    my $t = ALPM->transaction();
    ... do stuffs ...
}

# here, $t is out of scope, garbage collected, and transaction is
# released

In this way, with good coding practices, you should not need to release a transaction because it will go out of scope. But in order to explicitly release a transaction undefine it. For example:

my $t = ALPM->transaction();
$t->sync('perl');
$t->commit;
undef $t;

# or
$t = undef;

# Transaction is released immediately

So be careful you don't keep extra copies of a transaction stored around or else it will not be released. If you need extra copies try using weaken in Scalar::Util.

DOUBLE TRANSACTION PROBLEM

A problem can occur if you are trying to replace a transaction stored in a scalar with a new transaction:

my $t = ALPM->transaction();
$t->sync( 'perl' );
$t->commit();
$t = ALPM->transaction();  # THIS WILL FAIL!

The problem is the $t is not undefined and released until after the <ALPM-transaction()>> call is finished. Unfortunately the method cannot work because the previous transaction in $t is not released yet! Catch 22! You will have to explicitly undef the transaction in this case:

my $t = ALPM->transaction();
$t->sync( 'perl' );
$t->commit;
undef $t; # force release!
$t = ALPM->transaction();

EVENT CALLBACKS

The ALPM::transaction() method takes an optional event key/value pair. The event types and their different values are listed here because there are so many of them.

Events are passed to the callback as a hash reference. Every event type has a name and a status key. The name gives the type of event, and status gives a string representing the status. The different kinds of extra arguments depends on the type of event.

All events can have one of the two statuses, 'start' or 'done' unless noted.

checkdeps
fileconflicts
resolvedeps
integrity
deltaintegrity: All the above events have no special keys.
interconflicts: When status is 'done' there is a key named 'target' which is an ALPM::Package object.
add: Both 'start' and 'done' events also have a key named 'package' which is an ALPM::Package object.
remove: Both 'start' and 'done' events also have a key named 'package' which is an ALPM::Package object.
upgrade: The 'start' event has a key named 'package'. The 'done' event has the keys 'new' and 'old'.
deltapatches: The 'done' event also has keys 'pkgname', and 'patches'.
deltapatch: There is also a fail event with 'status' set to 'failed', in which case there is an 'error' key with an error message as its value.
scriptlet: This always has 'status' set to the empty string. There is also a 'text' key with the scriptlet text I imagine?
printuri: This always has 'status' set to the empty string. There is also a 'name' key with the URI I guess?
retrieve: This always has 'status' set to 'start'. There is also a 'db' key which has the name (ex: "extra") of the database where the package is being retrieved from.

CONVERSATION CALLBACKS

The conversation callback lets ALPM ask questions to the user. The question is passed as a hash reference. The callback returns 1 to answer yes, 0 to answer no. Each key of the hashref is described below.

id

The integer value of the callback type. It is one of these constants, which are exported from ALPM as functions by request:

PM_TRANS_CONV_INSTALL_IGNOREPKG
PM_TRANS_CONV_REPLACE_PKG
PM_TRANS_CONV_CONFLICT_PKG
PM_TRANS_CONV_CORRUPTED_PKG

name

Ids are converted to string names. Each decides what other arguments are provided in the hash reference.

The following table shows what arguments are given for each named conversation event as well as the purpose of each named event. Arguments are simply additional keys in the hash ref.

|------------------+------------------------------------------------|
| Name             | Description                                    |
|------------------+------------------------------------------------|
| install_ignore   | Should the package be installed or ignored?    |
| - package        | The package, an ALPM::Package object.          |
|------------------+------------------------------------------------|
| replace_package  | Should the old package be replaced by another? |
| - old            | The old package, an ALPM::Package object.      |
| - new            | The new package, an ALPM::Package object.      |
| - db             | The name of the database's repository.         |
|------------------+------------------------------------------------|
| package_conflict | Should the conflicting package be removed?     |
| - target         | The name of the package being conflicted.      |
| - local          | The name of the removable local package.       |
| - conflict       | The type/name of the conflict.                 |
|------------------+------------------------------------------------|
| corrupted_file   | Should the corrupted package file be deleted?  |
| - filename       | The name of the corrupted package file.        |
|------------------+------------------------------------------------|

PROGRESS CALLBACKS

Progress of the transaction can be reported to a progress callback. Progress is reported as a hash reference, again. The keys are described in the following table:

|-------------+-----------------------------------------------------|
| Name        | Description                                         |
|-------------+-----------------------------------------------------|
| id          | The numeric ID of the progress type.  Can be:       |
|             | - PM_TRANS_PROGRESS_ADD_START                       |
|             | - PM_TRANS_PROGRESS_UPGRADE_START                   |
|             | - PM_TRANS_PROGRESS_REMOVE_START                    |
|             | - PM_TRANS_PROGRESS_CONFLICTS_START                 |
|-------------+-----------------------------------------------------|
| name        | The string conversion of the numeric ID:            |
|             | - add                                               |
|             | - upgrade                                           |
|             | - remove                                            |
|             | - conflicts                                         |
|-------------+-----------------------------------------------------|
| desc        | A string for extra description of the callback.     |
|             | For example, the name of the package being added.   |
|-------------+-----------------------------------------------------|
| item        | The percentage of progress for the individual item. |
|             | Like a package, for example.                        |
|-------------+-----------------------------------------------------|
| total_count | The number of items being processed in total.       |
|-------------+-----------------------------------------------------|
| total_pos   | The item's position in the total count above.       |
|-------------+-----------------------------------------------------|

ERRORS

Transaction errors are croaked and can be examined with the $@ or $EVAL_ERROR variable like other ALPM errors. They are prefixed with ALPM Transaction Error:. Errors can happen when preparing or commiting.

Extra information is available for ALPM transaction errors. When an error occurs the transaction object that was used will have a new hash key called error, containing a hash reference.

The error hash reference has the keys msg, list, and type. msg is the same as the string in $@, without the ALPM Transaction Error: prefix. The array ref in list is different depending on each type. Each type and its associated msg and list are described in the following table.

|-----------------+--------------------------------------------------|
| Type            | Description                                      |
|-----------------+--------------------------------------------------|
| fileconflict    | Two packages share a file with the same path.    |
| - msg           | 'conflicting files'                              |
| - list          | An arrayref of hashes representing the conflict: |
| -- target       | The package which caused the conflict.           |
| -- type         | 'filesystem' or 'target'                         |
| -- file         | The path of the conflicting file.                |
| -- ctarget      | Empty string ('') ?                              |
|-----------------+--------------------------------------------------|
| depmissing      | A dependency could not be satisfied (missing?).  |
| - msg           | 'could not satisfy dependencies'                 |
| - list          | An arrayref of hashes represending the dep:      |
| -- target       | The depended on package name.                    |
| -- cause        | The package name of who depends on target.       |
| -- depend       | A hashref, same as dependencies of packages.     |
|-----------------+--------------------------------------------------|
| depconflict     | A package which explicitly conflicts with        |
|                 | another (in the PKGBUILD) cannot be installed.   |
| - msg           | 'conflicting dependencies'                       |
| - list          | An arrayref of hashrefs showing the conflict:    |
| -- reason       | A reason message.                                |
| -- packages     | An arrayref of two packages who conflict.        |
|-----------------+--------------------------------------------------|
| invalid_delta   | (UNTESTED) A delta is corrupted?                 |
| - msg           | ?                                                |
| - list          | An arrayref of corrupted delta names.            |
|-----------------+--------------------------------------------------|
| invalid_package | A package is corrupted (or invalid?).            |
| - msg           | 'invalid or corrupted package'                   |
| - list          | An arrayref of package filenames.                |
|-----------------+--------------------------------------------------|

AUTHOR

Justin Davis, <juster at cpan dot org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

To install ALPM, copy and paste the appropriate command in to your terminal.

cpanm

cpanm ALPM

CPAN shell

perl -MCPAN -e shell
install ALPM

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

sync

pkgfile

remove

sync_from_db

sysupgrade

get_flags

prepare

commit

get_additions

get_removals

RELEASING A TRANSACTION

DOUBLE TRANSACTION PROBLEM

EVENT CALLBACKS

CONVERSATION CALLBACKS

PROGRESS CALLBACKS

ERRORS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions