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