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