• NAME
• SYNOPSIS
• DESCRIPTION
• METHODS
• new
• file
• filename
• dir
• subdir
• home
• name
• uid
• SEE ALSO
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

WWW::Yahoo::Credentials::File - object specifying location of credentials file

SYNOPSIS

  require WWW::Yahoo::Credentials::File;
  my $file = new WWW::Yahoo::Credentials::File; # use default location
  my $file = WWW::Yahoo::Credentials::File->new( $newfile );

DESCRIPTION

This class provides different ways of specifying the location of a credentials file, with acceptable defaults.

Errors are thrown using the Exception::Class module for problems determining the home directory or for invalid or incorrect usage of method parameters.

METHODS

new

This creates a new object representing the location of the credentials file. The default location of this file is ``~/.yahoo/credentials.xml'', but the location can be specified using the various options described below.

file

This specifies the full path to the credentials file. If set, no other option is considered. For example,

  my $file =
    WWW::Yahoo::Credentials::File->new( file =>
                                        '/home/user/.yahoo/credentials.xml' );

It is not necessary to name this option when it is the only option used:

  my $file =
    WWW::Yahoo::Credentials::File->new( '/home/user/.yahoo/credentials.xml' );

filename

This specifies the filename. The default is 'credentials.xml'. The directory location of this file can be specified with the following options.

dir

This specifies the full path to the directory containing the credentials file. If set, none of the remaining options are considered. For example,

  my $file =
    WWW::Yahoo::Credentials::File->new( dir => '/home/user/.yahoo',
                                        filename => 'credentials.xml' );

subdir

This specifies the subdirectory under the home directory that will be used. The default is '.yahoo'. The home directory can be specified with the following options.

home

This specifies the home directory to use. For example,

  my $file =
    WWW::Yahoo::Credentials::File->new( home => '/home/user',
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );

name

This specifies the uid to use when looking up the home directory via the perl function getpwnam. For example,

  my $file =
    WWW::Yahoo::Credentials::File->new( name => 'user',
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( name => 'user',
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );

uid

This specifies the uid to use when looking up the home directory via the perl function getpwuid. For example,

  my $file =
    WWW::Yahoo::Credentials::File->new( uid => 1000,
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( uid => $<,
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );

If the directory of the file is not specified using the above options, then the default home directory will be used. The environment variables HOME and LOGDIR are checked in turn for the home directory. If neither of these are defined, then getpwuid($<) is used to look up the home directory. If you would like to skip over the checking of HOME and LOGDIR and move straight to getpwuid($<) for the home directory, then specify $< as the uid, for example,

  my $file = WWW::Yahoo::Credentials::File->new( uid => $< );

The tilde character can be used in the conventional manner to specify a home directory, for example,

  my $file =
    WWW::Yahoo::Credentials::File->new( file => '~/.yahoo/credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( '~user/.yahoo/credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( dir => '~/.yahoo',
                                        filename => 'credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( home => '~user',
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( dir => '~/.yahoo',
                                        filename => 'credentials.xml' );
  my $file =
    WWW::Yahoo::Credentials::File->new( home => '~user',
                                        subdir => '.yahoo',
                                        filename => 'credentials.xml' );

The value for each option can be later retrieved via an accessor method, for example:

  my $dir = $file->dir;
  my $filename = $file->filename;

To get the full filename including path, simply use the object in a string context or use the ``file'' accessor method:

  my $path = "$file";
  my $path = $file->file;

If a tilde character was specified for an option, then all the options are rewritten to make use of the ``name'' option to hold the username (if one was supplied). In this case, the accessor methods will return the rewritten values instead of the originally supplied values.

Here is a summary, in order of priority, of how the location of the credentials file is determined from the given options and/or the defaults:

  1. file
  2. dir / filename
  3. home(name) / subdir / filename
  4. home(uid)  / subdir / filename
  5. home       / subdir / filename

file

  my $fullname = $file->file;
  my $fullname = "$file";

filename

  my $filename = $file->filename;

dir

  my $dir = $file->dir;

subdir

  my $dir = $file->subdir;

home

  my $home = $file->home;

name

  my $name = $file->name;

uid

  my $uid = $file->uid;

SEE ALSO

WWW::Yahoo::Credentials::File, Exception::Class

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright 2003 by Ken Neighbors

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