
sub valid_preference_file {
  if ($trace) { print "Entering valid_preference_file \n" };
  
  ## IN : @_[0] = $file = full path to symlink file.
  ## OUT: "yes" if valid, "no" if not valid
  ## DESCRIPTION: check the validity of a symlink file.
  ## CALLED BY: join_symlink_files(), ...
 
  $file = @_[0];

  ## A valid symlink file can contain:
  ## zero or more blank lines, 
  ## zero or more lines starting with a "#", aka., commented lines,
  ## zero or more lines starting with "enable" followed by one file name,
  ## zero or more lines starting with "ignore" followed by one file name,
  ## zero or more lines starting with "override" followed by two file names separated by a space.
  ## exactly one line starting with the string "searchpath" followed by
  ## zero or more comma separated directories.
  ## exactly one line starting with the string "sharsearchpath" followed by
  ## zero or more comma separated directories.
  ## and nothing else!

  $valid = 1;
  if (-f $file) {
    open IN, "+<$file" or die "Can't open $file: $!\n";
    undef $/;
    my $s = <IN>;
    close IN;
    @lines = split /\n/, $s;
    foreach $line (@lines) {
      $linenum++;
      $_ = $line;
      if (/^ *\n*$/) {
        #print "=>BLANK<=\n";       
      }
      elsif (/^#/) {
        #print "=>COMMENT<=\n";
      }
      elsif (/^enable [a-zA-Z_0-9\.\-\+]+ *$/) {
        #print "=>ENABLE<=\n";
        ## not checking the one string is a file
      }
      elsif (/^ignore [a-zA-Z_0-9\.\-\+]+ *$/) {
        #print "=>IGNORE<=\n";
        ## not checking the one string is a file
      }
      elsif (/^override [a-zA-Z_0-9\.\-\+]+ [a-zA-Z_0-9\.\-\+]+ *$/) {
        #print "=>OVERRIDE<=\n";
        ## not checking the two strings are files
      }
      elsif (/^searchpath /) {
        #print "=>SEARCHPATH<=\n";
        ## not checking the comma separated string(s) is/are file(s)
        $sp++;
        if ($sp > 1) {
          print "ERROR: invalid lines in $file:\n";
          print "       more than one searchpath directive.\n";
          $valid = 0;
        };
        $sp = 0;
      }
      elsif (/^sharsearchpath /) {
        #print "=>SHARSEARCHPATH<=\n";
        ## not checking the comma separated string(s) is/are file(s)
        $ssp++;
        if ($ssp > 1) {
          print "ERROR: invalid lines in $file:\n";
          print "       more than one sharsearchpath directive.\n";
          $valid = 0;
        };
        $ssp = 0;
      }
      else {
        print "ERROR: invalid line in $file:\n";
        print "       line number $linenum: $line\n";
        $valid = 0;
      };
    };
  }
  else {
    print "ERROR: invalid symlink file!\n";
    print "       File $file does not exist!\n";
    return ("no");
  };

  $/ = "\n";

  if ($valid == 1) {
    if ($trace) { print "Leaving valid_preference_file \n" };
    return ("yes");
  }
  else {
    if ($trace) { print "Leaving valid_preference_file \n" };
    return ("no");
  };

};

################################################################################
