View of /trunk/webwork2/lib/WeBWorK/CourseEnvironment.pm

    1 ################################################################################
    2 # WeBWorK mod_perl (c) 1995-2002 WeBWorK Team, Univeristy of Rochester
    3 # $Id$
    4 ################################################################################
    5 
    6 package WeBWorK::CourseEnvironment;
    7 
    8 =head1 NAME
    9 
   10 WeBWorK::CourseEnvironment - Read configuration information from global.conf
   11 and course.conf files.
   12 
   13 =cut
   14 
   15 use strict;
   16 use warnings;
   17 use Safe;
   18 use WeBWorK::Utils qw(readFile);
   19 
   20 # new($invocant, $webworkRoot, $courseName)
   21 # $invocant implicitly set by caller
   22 # $webworkRoot  directory that contains the WeBWorK distribution
   23 # $courseName name of the course being used
   24 sub new {
   25   my $invocant = shift;
   26   my $class = ref($invocant) || $invocant;
   27   my $webworkRoot = shift;
   28   my $courseName = shift;
   29   my $safe = Safe->new;
   30 
   31   # set up some defaults that the environment files will need
   32   $safe->reval("\$webworkRoot = '$webworkRoot'");
   33   $safe->reval("\$courseName = '$courseName'");
   34 
   35   # determine location of globalEnvironmentFile
   36   my $globalEnvironmentFile = "$webworkRoot/conf/global.conf";
   37 
   38   # read and evaluate the global environment file
   39   my $globalFileContents = readFile($globalEnvironmentFile);
   40   $safe->reval($globalFileContents);
   41 
   42   # if that evaluation failed, we can't really go on...
   43   # we need a global environment!
   44   $@ and die "Could not evaluate global environment file $globalEnvironmentFile: $@";
   45 
   46   # determine location of courseEnvironmentFile
   47   # pull it out of $safe's symbol table ad hoc
   48   # (we don't want to do the hash conversion yet)
   49   no strict 'refs';
   50   my $courseEnvironmentFile = ${*{${$safe->root."::"}{courseFiles}}}{environment};
   51   use strict 'refs';
   52 
   53   # read and evaluate the course environment file
   54   # if readFile failed, we don't bother trying to reval
   55   my $courseFileContents = eval { readFile($courseEnvironmentFile) }; # catch exceptions
   56   $@ or $safe->reval($courseFileContents);
   57 
   58   # get the safe compartment's namespace as a hash
   59   no strict 'refs';
   60   my %symbolHash = %{$safe->root."::"};
   61   use strict 'refs';
   62 
   63   # convert the symbol hash into a hash of regular variables.
   64   my $self = {};
   65   foreach my $name (keys %symbolHash) {
   66     # weed out internal symbols
   67     next if $name =~ /^(INC|_|__ANON__|main::)$/;
   68     # pull scalar, array, and hash values for this symbol
   69     my $scalar = ${*{$symbolHash{$name}}};
   70     my @array = @{*{$symbolHash{$name}}};
   71     my %hash = %{*{$symbolHash{$name}}};
   72     # for multiple variables sharing a symbol, scalar takes precedence
   73     # over array, which takes precedence over hash.
   74     if (defined $scalar) {
   75       $self->{$name} = $scalar;
   76     } elsif (@array) {
   77       $self->{$name} = \@array;
   78     } elsif (%hash) {
   79       $self->{$name} = \%hash;
   80     }
   81   }
   82 
   83   bless $self, $class;
   84   return $self;
   85 }
   86 
   87 1;
   88 
   89 __END__
   90 
   91 =head1 SYNOPSIS
   92 
   93   use WeBWorK::CourseEnvironment;
   94   $courseEnv = WeBWorK::CourseEnvironment->new($webworkRoot, $courseName);
   95 
   96   $timeout = $courseEnv->{sessionKeyTimeout};
   97   $mode    = $courseEnv->{pg}->{options}->{displayMode};
   98   # etc...
   99 
  100 =head1 DESCRIPTION
  101 
  102 The WeBWorK::CourseEnvironment module reads the system-wide F<global.conf> and
  103 course-specific F<course.conf> files used by WeBWorK to calculate and store
  104 settings needed throughout the system. The F<.conf> files are perl source files
  105 that can contain any code allowed under the default safe compartment opset.
  106 After evaluation of both files, any package variables are copied out of the
  107 safe compartment into a hash. This hash becomes the course environment.
  108 
  109 =head1 CONSTRUCTION
  110 
  111 =over
  112 
  113 =item new (ROOT, COURSE)
  114 
  115 The C<new> method finds the file F<conf/global.conf> relative to the given ROOT
  116 directory. After reading this file, it uses the C<$courseFiles{environment}>
  117 variable, if present, to locate the course environment file. If found, the file
  118 is read and added to the environment.
  119 
  120 =back
  121 
  122 =head1 ACCESS
  123 
  124 There are no formal accessor methods. However, since the course environemnt is
  125 a hash of hashes and arrays, is exists as the self hash of an instance
  126 variable:
  127 
  128   $courseEnvironment->{someKey}->{someOtherKey};
  129 
  130 =head1 AUTHOR
  131 
  132 Written by Sam Hathaway, sh002i (at) math.rochester.edu.
  133 
  134 =cut