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