=begin pod

=head1 NAME

AWS::Credentials::Provider::SharedCredentials - load credentials from file

=head1 SYNOPSIS

    use AWS::Credentials;

    my $credentials = load-credentials();

=head1 DESCRIPTION

This credentials provider will load credentials from the credentials
configuration file. This depends on the L<AWS::Session> object to locate and
read the credentials file (usually F<~/.aws/credentials>).

=head1 ATTRIBUTES

If you have a need to store credentials in a different file than the usual one,
there are some tweaks you can use in the attributes to this object to modify how
this happens.

See the attribute descriptions below for the particulars, but here's an example that will prefer the C<aws_access_key> and C<aws_secret_key> parameters found in the C<staging> profile of the credentials file named F</etc/aws-credentials>.

    # Handy alias to make the next part easier to read
    constant SharedCredentials = AWS::Credentials::Provider::SharedCredentials;

    # Insert our new provider before the other SharedCredentials
    my $resolver = AWS::Credentials::Provider::Resolver.DEFAULT;
    $resolver.providers.splice(
        $resolver.providers.first(SharedCredentials, :k), 0,
        SharedCredentials.new(
            access-key           => 'aws_access_key',
            secret-key           => 'aws_secret_key',
            credentials-filename => '/etc/aws-credentials'.IO,
            profile              => 'staging',
        ),
    );

You can specify an alternate credentials filename using the C<credentials-filesname>

=head2 access-key

This is a list of configuration variable names to use from the configuration
file for the access key. Defaults to C<aws_access_key_id>.

=head2 secret-key

This is the list of configuraiton variable names to use from the configuration
file for the secret key. Defaults to C<aws_secret_access_key>.

=head2 token

This is the list of configuraiton variable names to use from the configuration
file for the session token. Defaults to trying C<aws_security_token> first and
then trying C<aws_session_token>.

=head2 credentials-filename

This is the L<IO::Path> of a specific filename to use for loading credentials.
If not set, it will use either the credentials filename or configuration
filename determined by the L<AWS::Session>.

=head2 profile

This is the section of configuration within the configuraiton file to use when loading credentials. If not set, the C<load> method will use the profile determined by the L<AWS::Session>.

=head2 configuration-file-key

This is mostly used internally. This must be set to one of the values defined in C<AWS::Credentials::Provider::SharedCredentials::ConfigFileKey>.

=item AWS::Credentials::Provider::SharedCredentials::ConfigFileKey::LoadFromCredentials

This is the default value and tells the provider to use the credentials from determined by the L<AWS::Session> when an explicit C<credentials-filename> has not been set.

=item AWS::Credentials::Provider::SharedCredentials::ConfigFileKey::LoadFromCredentials

This tells the provider to load from the configuration file as determined by the L<AWS::Session> when an explicit C<credentials-filename> has not been set.

This is not ideal, but sometime older setups will have the credentials kept in the configuration file, so it is sometimes convenient.

=end pod
