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



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
 WWW::Yahoo::Credentials::File - object specifying location of credentials file