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

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