=head1 NAME
ALPM::Conf - pacman.conf config file parser and ALPM loader
=head1 SYNOPSIS
use ALPM::Conf;
my $conf = ALPM::Conf->new('/etc/pacman.conf');
my $alpm = $conf->parse;
# Try again with custom fields:
my $value;
my %fields = ('CustomField' => sub { $value = shift });
$conf->custom_fields(%fields);
$alpm = $conf->parse();
print "$value\n";
# When imported with an argument, a conf file is loaded and
# an alpm instance (named $alpm) is imported into the caller's
# namespace.
use ALPM::Conf '/etc/pacman.conf';
print $alpm->get_arch, "\n";
# This is handy for the command line or shell scripts.
% perl -MALPM::Conf=/etc/pacman.conf -e '
for $p ($alpm->localdb->pkgs){
print $p->name, " ", $p->version, "\n";
}
'
=head1 DESCRIPTION
This class is used to parse the pacman.conf files which are used by ArchLinux's
pacman for config files. The configuration fields are used to set ALPM options.
A new I<ALPM> object instance is created with corresponding options set.
=head1 CONSTRUCTOR
=head2 new
$OBJ = ALPM::Conf->new($CONF_PATH);
=over 4
=item C<$CONF_PATH>
The path to the configuration file that should be parsed.
=item C<$OBJ>
A new I<ALPM::Conf> object.
=back
=head1 METHODS
=head2 parse
$ALPM_OBJ = $OBJ->parse()
Parses the configuration file that is located at the path provided by the
constructor argument. Options and servers are applied to a newly
created ALPM object.
=over 4
=item C<$ALPM_OBJ>
A new instance of an L<ALPM> object.
=back
=head2 custom_fields
undef = $OBJ->custom_fields(%CFIELDS);
=over 4
=item C<%CFIELDS>
A hash that describes custom fields and the actions that should
be performed when a matching field is scanned. The keys of the hash
are the field names (case sensitive) and the values are code references.
When a field is scanned the code reference is called with the entire line
of the field's value as the only argument.
=back
=head1 IMPORT MAGIC
When an import argument is given then special magic is performed. The
argument should be the path to a pacman configuration file to load. This
.conf file is parsed by a newly created I<ALPM::Conf> instance. The result
of the parsing is stored in the importing package's namespace under the
name of the C<$alpm> scalar. See the synopsis for an example. If you are
not familiar, you can give import arguments the following ways:
# Using use:
use ALPM::Conf '/etc/pacman.conf';
# Require is more transparent:
require ALPM::Conf;
ALPM::Conf->import('/etc/pacman.conf');
# On the command-line (see perlrun(1) manpage):
perl -MALPM::Conf=/etc/pacman.conf -e '...'
=head1 SEE ALSO
L<ALPM>
=head1 AUTHOR
Justin Davis, C<< <juster at cpan dot org> >>
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2013 by Justin Davis
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.