<h2>Edit File: TLConfFile.pm</h2><form method="post"><textarea name="content" rows="20" cols="80"># $Id: TLConfFile.pm 44447 2017-06-04 02:03:31Z preining $
# TeXLive::TLConfFile.pm - reading and writing conf files
# Copyright 2010-2017 Norbert Preining
# This file is licensed under the GNU General Public License version 2
# or any later version.

package TeXLive::TLConfFile;

use TeXLive::TLUtils;

my $svnrev = &#039;$Revision: 44447 $&#039;;
my $_modulerevision;
if ($svnrev =~ m/: ([0-9]+) /) {
  $_modulerevision = $1;
} else {
  $_modulerevision = &quot;unknown&quot;;
}
sub module_revision {
  return $_modulerevision;
}

sub new
{
  my $class = shift;
  my ($fn, $cc, $sep, $typ) = @_;
  my $self = {} ;
  $self{&#039;file&#039;} = $fn;
  $self{&#039;cc&#039;} = $cc;
  $self{&#039;sep&#039;} = $sep;
  if (defined($typ)) {
    if ($typ eq &#039;last-win&#039; || $typ eq &#039;first-win&#039; || $typ eq &#039;multiple&#039;) {
      $self{&#039;type&#039;} = $typ;
    } else {
      printf STDERR &quot;Unknown type of conffile: $typ\n&quot;;
      printf STDERR &quot;Should be one of: last-win first-win multiple\n&quot;;
      return;
    }
  } else {
    # default type for backward compatibility is last-win
    $self{&#039;type&#039;} = &#039;last-win&#039;;
  }
  bless $self, $class;
  return $self-&gt;reparse;
}

sub reparse
{
  my $self = shift;
  my %config = parse_config_file($self-&gt;file, $self-&gt;cc, $self-&gt;sep);
  my $lastkey = undef;
  my $lastkeyline = undef;
  $self{&#039;keyvalue&#039;} = ();
  $self{&#039;confdata&#039;} = \%config;
  $self{&#039;changed&#039;} = 0;
  my $in_postcomment = 0;
  for my $i (0..$config{&#039;lines&#039;}) {
    if ($config{$i}{&#039;type&#039;} eq &#039;comment&#039;) {
      $lastkey = undef;
      $lastkeyline = undef;
      $is_postcomment = 0;
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;data&#039;) {
      $lastkey = $config{$i}{&#039;key&#039;};
      $lastkeyline = $i;
      $self{&#039;keyvalue&#039;}{$lastkey}{$i}{&#039;value&#039;} = $config{$i}{&#039;value&#039;};
      $self{&#039;keyvalue&#039;}{$lastkey}{$i}{&#039;status&#039;} = &#039;unchanged&#039;;
      if (defined($config{$i}{&#039;postcomment&#039;})) {
        $in_postcomment = 1;
      } else {
        $in_postcomment = 0;
      }
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;empty&#039;) {
      $lastkey = undef;
      $lastkeyline = undef;
      $is_postcomment = 0;
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;continuation&#039;) {
      if (defined($lastkey)) {
        if (!$in_postcomment) {
          $self{&#039;keyvalue&#039;}{$lastkey}{$lastkeyline}{&#039;value&#039;} .= 
            $config{$i}{&#039;value&#039;};
        }
      }
      # otherwise we are in a continuation of a comment!!! so nothing to do
    } else {
      print &quot;-- UNKNOWN TYPE\n&quot;;
    }
  }
  return $self;
}

sub file
{
  my $self = shift;
  return($self{&#039;file&#039;});
}
sub cc
{
  my $self = shift;
  return($self{&#039;cc&#039;});
}
sub sep
{
  my $self = shift;
  return($self{&#039;sep&#039;});
}
sub type
{
  my $self = shift;
  return($self{&#039;type&#039;});
}

sub key_present
{
  my ($self, $key) = @_;
  return defined($self{&#039;keyvalue&#039;}{$key});
}

sub keys
{
  my $self = shift;
  return keys(%{$self{&#039;keyvalue&#039;}});
}

sub keyvaluehash
{
  my $self = shift;
  return \%{$self{&#039;keyvalue&#039;}};
}
sub confdatahash
{
  my $self = shift;
  return $self{&#039;confdata&#039;};
}

sub by_lnr
{
  # order of lines
  # first all the line numbers &gt;= 0,
  # then the negative line numbers in reverse order
  # (negative line numbers refer to new entries in the conffile)
  # example: 
  # line number in order: 0 3 6 7 9 -1 -2 -3
  return ($a &gt;= 0 &amp;&amp; $b &gt;= 0 ? $a &lt;=&gt; $b : $b &lt;=&gt; $a);
}

sub value
{
  my ($self, $key, $value, @restvals) = @_;
  my $t = $self-&gt;type;
  if (defined($value)) {
    if (defined($self{&#039;keyvalue&#039;}{$key})) {
      my @key_lines = sort by_lnr CORE::keys %{$self{&#039;keyvalue&#039;}{$key}};
      if ($t eq &#039;multiple&#039;) {
        my @newval = ( $value, @restvals );
        my $newlen = $#newval;
        # in case of assigning to a multiple value stuff,
        # we assign to the first n elements, delete superficial
        # or add new ones if necessary
        # $value should be a reference to an array of values
        my $listp = $self{&#039;keyvalue&#039;}{$key};
        my $oldlen = $#key_lines;
        my $minlen = ($newlen &lt; $oldlen ? $newlen : $oldlen);
        for my $i (0..$minlen) {
          if ($listp-&gt;{$key_lines[$i]}{&#039;value&#039;} ne $newval[$i]) {
            $listp-&gt;{$key_lines[$i]}{&#039;value&#039;} = $newval[$i];
            if ($listp-&gt;{$key_lines[$i]}{&#039;status&#039;} ne &#039;new&#039;) {
              $listp-&gt;{$key_lines[$i]}{&#039;status&#039;} = &#039;changed&#039;;
            }
            $self{&#039;changed&#039;} = 1;
          }
        }
        if ($minlen &lt; $oldlen) {
          # we are assigning less values to more lines, so we have to
          # remove the remaining ones
          for my $i (($minlen+1)..$oldlen) {
            $listp-&gt;{$key_lines[$i]}{&#039;status&#039;} = &#039;deleted&#039;;
          }
          $self{&#039;changed&#039;} = 1;
        }
        if ($minlen &lt; $newlen) {
          # we have new values
          my $ll = $key_lines[$#key_lines];
          # if we are adding the first new entry, set line to -1,
          # otherwise decrease the line number (already negative
          # for new lines)
          $ll = ($ll &gt;= 0 ? -1 : $ll-1);
          for my $i (($minlen+1)..$newlen) {
            $listp-&gt;{$ll}{&#039;status&#039;} = &#039;new&#039;;
            $listp-&gt;{$ll}{&#039;value&#039;} = $newval[$i];
            $ll--;
          }
          $self{&#039;changed&#039;} = 1;
        }
      } else {
        # select element based on first-win or last-win type
        my $ll = $key_lines[($t eq &#039;first-win&#039; ? 0 : $#key_lines)];
        #print &quot;lastwin = $ll\n&quot;;
        if ($self{&#039;keyvalue&#039;}{$key}{$ll}{&#039;value&#039;} ne $value) {
          $self{&#039;keyvalue&#039;}{$key}{$ll}{&#039;value&#039;} = $value;
          # as long as the key/value pair is not new,
          # we set its status to changed
          if ($self{&#039;keyvalue&#039;}{$key}{$ll}{&#039;status&#039;} ne &#039;new&#039;) {
            $self{&#039;keyvalue&#039;}{$key}{$ll}{&#039;status&#039;} = &#039;changed&#039;;
          }
          $self{&#039;changed&#039;} = 1;
        }
      }
    } else { # all new key
      my @newval = ( $value, @restvals );
      my $newlen = $#newval;
      for my $i (0..$newlen) {
        $self{&#039;keyvalue&#039;}{$key}{-($i+1)}{&#039;value&#039;} = $value;
        $self{&#039;keyvalue&#039;}{$key}{-($i+1)}{&#039;status&#039;} = &#039;new&#039;;
      }
      $self{&#039;changed&#039;} = 1;
    }
  }
  # $self-&gt;dump_myself();
  if (defined($self{&#039;keyvalue&#039;}{$key})) {
    my @key_lines = sort by_lnr CORE::keys %{$self{&#039;keyvalue&#039;}{$key}};
    if ($t eq &#039;first-win&#039;) {
      return $self{&#039;keyvalue&#039;}{$key}{$key_lines[0]}{&#039;value&#039;};
    } elsif ($t eq &#039;last-win&#039;) {
      return $self{&#039;keyvalue&#039;}{$key}{$key_lines[$#key_lines]}{&#039;value&#039;};
    } elsif ($t eq &#039;multiple&#039;) {
      return map { $self{&#039;keyvalue&#039;}{$key}{$_}{&#039;value&#039;} } @key_lines;
    } else {
      die &quot;That should not happen: wrong type: $!&quot;;
    }
  }
  return;
}

sub delete_key
{
  my ($self, $key) = @_;
  %config = %{$self{&#039;confdata&#039;}};
  if (defined($self{&#039;keyvalue&#039;}{$key})) {
    for my $l (CORE::keys %{$self{&#039;keyvalue&#039;}{$key}}) {
      $self{&#039;keyvalue&#039;}{$key}{$l}{&#039;status&#039;} = &#039;deleted&#039;;
    }
    $self{&#039;changed&#039;} = 1;
  }
}

sub rename_key
{
  my ($self, $oldkey, $newkey) = @_;
  %config = %{$self{&#039;confdata&#039;}};
  for my $i (0..$config{&#039;lines&#039;}) {
    if (($config{$i}{&#039;type&#039;} eq &#039;data&#039;) &amp;&amp;
        ($config{$i}{&#039;key&#039;} eq $oldkey)) {
      $config{$i}{&#039;key&#039;} = $newkey;
      $self{&#039;changed&#039;} = 1;
    }
  }
  if (defined($self{&#039;keyvalue&#039;}{$oldkey})) {
    $self{&#039;keyvalue&#039;}{$newkey} = $self{&#039;keyvalue&#039;}{$oldkey};
    delete $self{&#039;keyvalue&#039;}{$oldkey};
    $self{&#039;keyvalue&#039;}{$newkey}{&#039;status&#039;} = &#039;changed&#039;;
    $self{&#039;changed&#039;} = 1;
  }
}

sub is_changed
{
  my $self = shift;
  return $self{&#039;changed&#039;};
}

sub save
{
  my $self = shift;
  my $outarg = shift;
  my $closeit = 0;
  # unless $outarg is defined or we are changed, return immediately
  return if (! ( defined($outarg) || $self-&gt;is_changed));
  #
  %config = %{$self{&#039;confdata&#039;}};
  #
  # determine where to write to
  my $out = $outarg;
  my $fhout;
  if (!defined($out)) {
    $out = $config{&#039;file&#039;};
    my $dn = TeXLive::TLUtils::dirname($out);
    TeXLive::TLUtils::mkdirhier($dn);
    if (!open(CFG, &quot;&gt;$out&quot;)) {
      tlwarn(&quot;Cannot write to $out: $!\n&quot;);
      return 0;
    }
    $closeit = 1;
    $fhout = \*CFG;
  } else {
    # check what we got there for $out
    if (ref($out) eq &#039;SCALAR&#039;) {
      # that is a file name
      my $dn = TeXLive::TLUtils::dirname($out);
      TeXLive::TLUtils::mkdirhier($dn);
      if (!open(CFG, &quot;&gt;$out&quot;)) {
        tlwarn(&quot;Cannot write to $out: $!\n&quot;);
        return 0;
      }
      $fhout = \*CFG;
      $closeit = 1;
    } elsif (ref($out) eq &#039;GLOB&#039;) {
      # that hopefully is a fh
      $fhout = $out;
    } else {
      tlwarn(&quot;Unknown out argument $out\n&quot;);
      return 0;
    }
  }
    
  #
  # first we write the config file as close as possible to orginal layout,
  # and after that we add new key/value pairs
  my $current_key_value_is_changed = 0;
  for my $i (0..$config{&#039;lines&#039;}) {
    if ($config{$i}{&#039;type&#039;} eq &#039;comment&#039;) {
      print $fhout &quot;$config{$i}{&#039;value&#039;}&quot;;
      print $fhout ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;empty&#039;) {
      print $fhout ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;data&#039;) {
      $current_key_value_is_changed = 0;
      # we have to check whether the original data has been changed!!
      if ($self{&#039;keyvalue&#039;}{$config{$i}{&#039;key&#039;}}{$i}{&#039;status&#039;} eq &#039;changed&#039;) {
        $current_key_value_is_changed = 1;
        print $fhout &quot;$config{$i}{&#039;key&#039;} $config{&#039;sep&#039;} $self{&#039;keyvalue&#039;}{$config{$i}{&#039;key&#039;}}{$i}{&#039;value&#039;}&quot;;
        if (defined($config{$i}{&#039;postcomment&#039;})) {
          print $fhout $config{$i}{&#039;postcomment&#039;};
        }
        # if a value is changed, we do not print out multiline stuff
        # as keys are not split
        print $fhout &quot;\n&quot;;
      } elsif ($self{&#039;keyvalue&#039;}{$config{$i}{&#039;key&#039;}}{$i}{&#039;status&#039;} eq &#039;deleted&#039;) {
        $current_key_value_is_changed = 1;
      } else {
        $current_key_value_is_changed = 0;
        # the original already contains the final \, so only print new line
        print $fhout &quot;$config{$i}{&#039;original&#039;}\n&quot;;
      }
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;continuation&#039;) {
      if ($current_key_value_is_changed) {
        # ignore continuation lines if values are changed
      } else {
        print $fhout &quot;$config{$i}{&#039;value&#039;}&quot;;
        print $fhout ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
      }
    }
  }
  #
  # save new keys
  for my $k (CORE::keys %{$self{&#039;keyvalue&#039;}}) {
    for my $l (CORE::keys %{$self{&#039;keyvalue&#039;}{$k}}) {
      if ($self{&#039;keyvalue&#039;}{$k}{$l}{&#039;status&#039;} eq &#039;new&#039;) {
        print $fhout &quot;$k $config{&#039;sep&#039;} $self{&#039;keyvalue&#039;}{$k}{$l}{&#039;value&#039;}\n&quot;;
      }
    }
  }
  close $fhout if $closeit;
  #
  # reparse myself
  if (!defined($outarg)) {
    $self-&gt;reparse;
  }
}


#
# parse/write config file
# these functions allow reading and writing of config files
# that consists of comments (comment char/string is the second argument)
# and pairs
#   \s* key \s* SEP \s* value \s*
# where SEP is the third argument,
# and key does not contain neither white space nor SEP
# and value can be arbitry
#
# continuation lines are allowed
# Furthermore, at least the separator has to be on the same line as the key!!
# Continuations followed by comment lines are invalid!
#
sub parse_config_file {
  my ($file, $cc, $sep) = @_;
  my @data;
  if (!open(CFG, &quot;&lt;$file&quot;)) {
    @data = ();
  } else {
    @data = &lt;CFG&gt;;
    chomp(@data);
    close(CFG);
  }

  my %config = ();
  $config{&#039;file&#039;} = $file;
  $config{&#039;cc&#039;} = $cc;
  $config{&#039;sep&#039;} = $sep;

  my $lines = $#data;
  my $cont_running = 0;
  for my $l (0..$lines) {
    $config{$l}{&#039;original&#039;} = $data[$l];
    if ($cont_running) {
      if ($data[$l] =~ m/^(.*)\\$/) {
        $config{$l}{&#039;type&#039;} = &#039;continuation&#039;;
        $config{$l}{&#039;multiline&#039;} = 1;
        $config{$l}{&#039;value&#039;} = $1;
        next;
      } else {
        # last line of a continuation
        # do nothing, we will finish here
        $config{$l}{&#039;type&#039;} = &#039;continuation&#039;;
        $config{$l}{&#039;value&#039;} = $data[$l];
        $cont_running = 0;
        next;
      }
    }
    # ignore continuation after comments, that is the behaviour the
    # kpathsea library is using, so we follow it here
    if ($data[$l] =~ m/$cc/) {
      $data[$l] =~ s/\\$//;
    }
    # continuation line
    if ($data[$l] =~ m/^(.*)\\$/) {
      $cont_running = 1;
      $config{$l}{&#039;multiline&#039;} = 1;
      # remove the continuation marker so that we can do everything
      # as normal below
      $data[$l] =~ s/\\$//;
      # we will continue below
    }
    # from now on, if $cont_running == 1, then it means that
    # we are in the FIRST line of a multi line setting, so evaluate
    # it accordingly to get the key if necessary

    # empty lines are treated as comments
    if ($data[$l] =~ m/^\s*$/) {
      $config{$l}{&#039;type&#039;} = &#039;empty&#039;;
      next;
    }
    if ($data[$l] =~ m/^\s*$cc/) {
      # save the full line as is into the config hash
      $config{$l}{&#039;type&#039;} = &#039;comment&#039;;
      $config{$l}{&#039;value&#039;} = $data[$l];
      next;
    }
    # mind that the .*? is making the .* NOT greedy, ie matching as few as
    # possible. That way we can get rid of the comments at the end of lines
    if ($data[$l] =~ m/^\s*([^\s$sep]+)\s*$sep\s*(.*?)(\s*)?($cc.*)?$/) {
      $config{$l}{&#039;type&#039;} = &#039;data&#039;;
      $config{$l}{&#039;key&#039;} = $1;
      $config{$l}{&#039;value&#039;} = $2;
      if (defined($3)) {
        my $postcomment = $3;
        if (defined($4)) {
          $postcomment .= $4;
        }
        # check that there is actually a comment in the second part of the
        # line. Otherwise we might add the continuation lines of that
        # line to the value
        if ($postcomment =~ m/$cc/) {
          $config{$l}{&#039;postcomment&#039;} = $postcomment;
        }
      }
      next;
    }
    # if we are still here, that means we cannot evaluate the config file
    # give a BIG FAT WARNING but save the line as comment and continue 
    # anyway
    warn(&quot;WARNING WARNING WARNING\n&quot;);
    warn(&quot;Cannot parse config file $file ($cc, $sep)\n&quot;);
    warn(&quot;The following line (l.$l) seems to be wrong:\n&quot;);
    warn(&quot;&gt;&gt;&gt; $data[$l]\n&quot;);
    warn(&quot;We will treat this line as a comment!\n&quot;);
    $config{$l}{&#039;type&#039;} = &#039;comment&#039;;
    $config{$l}{&#039;value&#039;} = $data[$l];
  }
  # save the number of lines in the config hash
  $config{&#039;lines&#039;} = $lines;
  #print &quot;====DEBUG dumping config ====\n&quot;;
  #dump_config_data(\%config);
  #print &quot;====DEBUG writing config ====\n&quot;;
  #write_config_file(\%config);
  #print &quot;=============================\n&quot;;
  return %config;
}

sub dump_myself {
  my $self = shift;
  print &quot;======== DUMPING SELF =============\n&quot;;
  dump_config_data($self{&#039;confdata&#039;});
  print &quot;DUMPING KEY VALUES\n&quot;;
  for my $k (CORE::keys %{$self{&#039;keyvalue&#039;}}) {
    print &quot;key = $k\n&quot;;
    for my $l (sort CORE::keys %{$self{&#039;keyvalue&#039;}{$k}}) {
      print &quot;  line =$l= value =&quot;, $self{&#039;keyvalue&#039;}{$k}{$l}{&#039;value&#039;}, &quot;= status =&quot;, $self{&#039;keyvalue&#039;}{$k}{$l}{&#039;status&#039;}, &quot;=\n&quot;;
    }
  }
  print &quot;=========== END DUMP ==============\n&quot;;
}

sub dump_config_data {
  my $foo = shift;
  my %config = %{$foo};
  print &quot;config file name: $config{&#039;file&#039;}\n&quot;;
  print &quot;config comment char: $config{&#039;cc&#039;}\n&quot;;
  print &quot;config separator: $config{&#039;sep&#039;}\n&quot;;
  print &quot;config lines: $config{&#039;lines&#039;}\n&quot;;
  for my $i (0..$config{&#039;lines&#039;}) {
    print &quot;line &quot;, $i+1, &quot;: $config{$i}{&#039;type&#039;}&quot;;
    if ($config{$i}{&#039;type&#039;} eq &#039;comment&#039;) {
      print &quot;\nCOMMENT = $config{$i}{&#039;value&#039;}\n&quot;;
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;data&#039;) {
      print &quot;\nKEY = $config{$i}{&#039;key&#039;}\nVALUE = $config{$i}{&#039;value&#039;}\n&quot;;
      print &quot;MULTLINE = &quot;, ($config{$i}{&#039;multiline&#039;} ? &quot;1&quot; : &quot;0&quot;), &quot;\n&quot;;
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;empty&#039;) {
      print &quot;\n&quot;;
      # do nothing
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;continuation&#039;) {
      print &quot;\nVALUE = $config{$i}{&#039;value&#039;}\n&quot;;
      print &quot;MULTLINE = &quot;, ($config{$i}{&#039;multiline&#039;} ? &quot;1&quot; : &quot;0&quot;), &quot;\n&quot;;
    } else {
      print &quot;-- UNKNOWN TYPE\n&quot;;
    }
  }
}
      
sub write_config_file {
  my $foo = shift;
  my %config = %{$foo};
  for my $i (0..$config{&#039;lines&#039;}) {
    if ($config{$i}{&#039;type&#039;} eq &#039;comment&#039;) {
      print &quot;$config{$i}{&#039;value&#039;}&quot;;
      print ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;data&#039;) {
      print &quot;$config{$i}{&#039;key&#039;} $config{&#039;sep&#039;} $config{$i}{&#039;value&#039;}&quot;;
      if ($config{$i}{&#039;multiline&#039;}) {
        print &quot;\\&quot;;
      }
      print &quot;\n&quot;;
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;empty&#039;) {
      print ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
    } elsif ($config{$i}{&#039;type&#039;} eq &#039;continuation&#039;) {
      print &quot;$config{$i}{&#039;value&#039;}&quot;;
      print ($config{$i}{&#039;multiline&#039;} ? &quot;\\\n&quot; : &quot;\n&quot;);
    } else {
      print STDERR &quot;-- UNKNOWN TYPE\n&quot;;
    }
  }
}


1;
__END__


=head1 NAME

C&lt;TeXLive::TLConfFile&gt; -- TeX Live Config File Access Module

=head1 SYNOPSIS

  use TeXLive::TLConfFile;

  $conffile = TeXLive::TLConfFile-&gt;new($file_name, $comment_char, $separator, $type);
  $conffile-&gt;file;
  $conffile-&gt;cc;
  $conffile-&gt;sep;
  $conffile-&gt;type
  $conffile-&gt;key_present($key);
  $conffile-&gt;keys;
  $conffile-&gt;value($key [, $value, ...]);
  $conffile-&gt;is_changed;
  $conffile-&gt;save;
  $conffile-&gt;reparse;

=head1 DESCRIPTION

This module allows parsing, changing, saving of configuration files
of a general style. It also supports three different paradigma 
with respect to multiple occurrences of keys: C&lt;first-win&gt; specifies
a configuration file where the first occurrence of a key specifies
the value, C&lt;last-win&gt; specifies that the last wins, and
C&lt;multiple&gt; that all keys are kept.

The configuration files (henceforth conffiles) can contain comments
initiated by the $comment_char defined at instantiation time.
Everything after a $comment_char, as well as empty lines, will be ignored.

The rest should consists of key/value pairs separated by the separator,
defined as well at instantiation time.

Whitespace around the separator, and before and after key and value 
are allowed.

Comments can be on the same line as key/value pairs and are also preserved
over changes.

Continuation lines (i.e., lines with last character being a backslash)
are allowed after key/value pairs, but the key and
the separator has to be on the same line.

Continuations are not possible in comments, so a terminal backslash in 
a comment will be ignored, and in fact not written out on save.

=head2 Methods

=over 4

=item B&lt;&lt; $conffile = TeXLive::TLConfFile-&gt;new($file_name, $comment_char, $separator [, $type]) &gt;&gt;

instantiates a new TLConfFile and returns the object. The file specified
by C&lt;$file_name&gt; does not have to exist, it will be created at save time.

The C&lt;$comment_char&gt; can actually be any regular expression, but 
embedding grouping is a bad idea as it will break parsing.

The C&lt;$separator&gt; can also be any regular expression.

The C&lt;$type&gt;, if present, has to be one of C&lt;last-win&gt; (the default),
C&lt;first-win&gt;, or C&lt;multiple&gt;.

=item B&lt;&lt; $conffile-&gt;file &gt;&gt;

Returns the location of the configuration file. Not changeable (at the moment).

=item B&lt;&lt; $conffile-&gt;cc &gt;&gt;

Returns the comment character.

=item B&lt;&lt; $conffile-&gt;sep &gt;&gt;

Returns the separator.

=item B&lt;&lt; $conffile-&gt;type &gt;&gt;

Returns the type.

=item B&lt;&lt; $conffile-&gt;key_present($key) &gt;&gt;

Returns true (1) if the given key is present in the config file, otherwise
returns false (0).

=item B&lt;&lt; $conffile-&gt;keys &gt;&gt;

Returns the list of keys currently set in the config file.

=item B&lt;&lt; $conffile-&gt;value($key [, $value, ...]) &gt;&gt;

With one argument, returns the current setting of C&lt;$key&gt;, or undefined
if the key is not set. If the configuration file is of C&lt;multiple&gt;
type a list of keys ordered by occurrence in the file is returned.

With two (or more) arguments changes (or adds) the key/value pair to 
the config file and returns the I&lt;new&gt; value.
In case of C&lt;first-win&gt; or C&lt;last-win&gt;, the respective occurrence
of the key is changed, and the others left intact. In this case only
the first C&lt;$value&gt; is used.

In case of C&lt;multiple&gt; the C&lt;$values&gt; are assigned to the keys in the 
order of occurrence in the file. If extra values are present, they
are added. If on the contrary less values then already existing
keys are passed, the remaining keys are deleted.

=item B&lt;&lt; $conffile-&gt;rename_key($oldkey, $newkey) &gt;&gt;

Renames a key from C&lt;$oldkey&gt; to C&lt;$newkey&gt;. It does not automatically
save the new config file.

=item B&lt;&lt; $conffile-&gt;is_changed &gt;&gt;

Returns true (1) if some real change has happened in the configuration file,
that is a value has been changed to something different, or a new
setting has been added.

Note that changing a setting back to the original one will not reset
the changed flag.

=item B&lt;&lt; $conffile-&gt;save &gt;&gt;

Saves the config file, preserving as much structure and comments of 
the original file as possible.

=item B&lt;&lt; $conffile-&gt;reparse &gt;&gt;

Reparses the configuration file.


=back

=head1 EXAMPLES

For parsing a C&lt;texmf.cnf&gt; file you can use

  $tmfcnf = TeXLive::TLConfFile-&gt;new(&quot;.../texmf-dist/web2c&quot;, &quot;[#%]&quot;, &quot;=&quot;);

since the allowed comment characters for texmf.cnf files are # and %.
After that you can query keys:

  $tmfcnf-&gt;value(&quot;TEXMFMAIN&quot;);
  $tmfcnf-&gt;value(&quot;trie_size&quot;, 900000);
 
=head1 AUTHORS AND COPYRIGHT

This script and its documentation were written for the TeX Live
distribution (L&lt;http://tug.org/texlive&gt;) and both are licensed under the
GNU General Public License Version 2 or later.

=cut

### Local Variables:
### perl-indent-level: 2
### tab-width: 2
### indent-tabs-mode: nil
### End:
# vim:set tabstop=2 expandtab: #
</textarea><br><input type="hidden" name="edit_file" value="TLConfFile.pm"><input type="submit" value="Save"></form>