NAME

WWW::Yahoo::Credentials - personal storage of userid/password/security_key

SYNOPSIS

  require WWW::Yahoo::Credentials;
  my $credentials = new WWW::Yahoo::Credentials;
  my $password = $credentials->password( $userid );
  my( $userid, $password ) = $credentials->tuple;

DESCRIPTION

This module provides access methods to credentials stored in an XML file. The format of this file is as shown in this example:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <credentials>
    <account userid="userid1" password="password1"/>
    <account userid="userid2" password="password2"/>
    <account userid="userid3" password="password3" security-key="key3"/>
  </credential>

Note that this module does not perform an actual XML parse of the credentials file. Instead, it simply performs a regular expression pattern match for the 'account' tag, and searches for the three attributes listed above.

When used in a string context, this object will return the filename, for example,

  print "Loaded credentials file '$credentials'\n";

Errors may be caught using ``eval'', for example,

  my( $credentials, $userid, $password );
  eval {
      $credentials = new WWW::Yahoo::Credentials;
      ( $userid, $password ) = $credentials->tuple;
  };
  if ( $@ ) {
      die ucfirst( $@->description ) . ": $@";
  }
  elsif ( not defined $userid ) {
      die "File error: userid not found in credentials file: $credentials\n";
  }

See WWW::Yahoo::Credentials::Exceptions for a list of exceptions (they are thrown using the Exception::Class module).

METHODS

new

  my $credentials = new WWW::Yahoo::Credentials;
  my $credentials = WWW::Yahoo::Credentials->new( '~/.yahoo/credentials.xml' );
  my $credentials = WWW::Yahoo::Credentials->new( %options );

This creates a new object representing the credentials stored in an XML file. The default location of this file is ``~/.yahoo/credentials.xml'', but the location can be specified using the various options described in the new method of WWW::Yahoo::Credentials::File.

file

  my $file = $credentials->file;
  my $oldfile = $credentials->file( $newfile );
  my $oldfile = $credentials->file( undef ); # use default location
  my $oldfile = $credentials->file( %options );

Returns current file object (WWW::Yahoo::Credentials::File) or reads a new credentials file. The location of the new file can be specified using the various options described in the new method of WWW::Yahoo::Credentials::File.

userids

  my @userids = $credentials->userids;

Returns a list of all userids defined in the credentials file.

password

  my $password = $credentials->password( $userid );

Returns the password for the given userid. The userid is looked up in a case-insensitive manner.

Note: do not confuse the Yahoo userid with your local username.

security_key

  my $security_key = $credentials->security_key( $userid );

Returns the security_key for the given userid. The userid is looked up in a case-insensitive manner.

Note: do not confuse the Yahoo userid with your local username.

tuple

  my( $userid, $password, $security_key ) = $credentials->tuple;
  my( $userid, $password, $security_key ) = $credentials->tuple( $userid );

Returns the userid, password, and security_key for a given userid (or for the first userid if none is defined). The userid is looked up in a case-insensitive manner.

refresh

  my $refreshed = $credentials->refresh;

Checks to see if the date of the credentials file has changed since it was last read. If so, re-reads it. This method is automatically called by the other methods.

AUTHOR

Ken Neighbors, Ph.D. ken@nsds.com

COPYRIGHT AND LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.000 or (at your option) any later version of Perl. That is, you can redistribute this module and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free Software
     Foundation; either version 1, or (at your option) any later version,
     or

  b) the "Artistic License" which comes with Perl, or

  c) the license terms of Perl versions later than 5.000

WWW::Yahoo::Credentials - personal storage of userid/password/security_key