1package Config::Std;
2
3use version; $VERSION = qv('0.0.4');
4
5my %global_def_sep;
6
7sub import {
8    my ($package, $opt_ref) = @_;
9    my $caller = caller();
10    $global_def_sep{$caller} = $opt_ref->{def_sep};
11    for my $sub_name (qw( read_config write_config )) {
12        $opt_ref->{$sub_name} ||= $sub_name;
13    }
14    *{$caller.'::'.$opt_ref->{read_config}}  = \&Config::Std::Hash::read_config;
15    *{$caller.'::'.$opt_ref->{write_config}} = \&Config::Std::Hash::write_config;
16}
17
18package Config::Std::Gap;
19use Class::Std;
20### [caller 0]
21{
22    sub serialize { return "\n" }
23    sub update  {}
24    sub extend  {}
25    sub copy_to {}
26}
27
28package Config::Std::Comment;
29use Class::Std;
30{
31    my %text_of : ATTR( :init_arg<text> );
32
33    sub serialize {
34        my ($self) = @_;
35        return $text_of{ident $self};
36    }
37
38    sub append_comment {
39        my ($self, $new_text) = @_;
40        $text_of{ident $self} .= $new_text;
41    }
42
43    sub update  {}
44    sub extend  {}
45    sub copy_to {}
46}
47
48package Config::Std::Keyval;
49use Class::Std;
50{
51    my %key_of      : ATTR( :init_arg<key> :get<key> );
52    my %vals_of     : ATTR;
53    my %deleted_of  : ATTR;
54
55    sub BUILD {
56        my ($self, $ident, $arg_ref) = @_;
57
58        $vals_of{$ident}     = [ { %{$arg_ref} } ];
59    }
60
61    my %SEPARATOR = ( ':' => ': ', '=' => ' = ' );
62
63    use Carp;
64
65    sub serialize {
66        my ($self, $def_sep, $block_name) = @_;
67        my $ident = ident $self;
68
69        return "" if $deleted_of{$ident};
70
71        my ($key, $vals) = ($key_of{$ident}, $vals_of{$ident});
72
73        my $keyspace = q{ } x length($key);
74
75        my $serialization = q{};
76
77        for $n (0..$#{$vals}) {
78            my ($val,$sep,$comm) = @{$vals->[$n]}{qw(val sep comm)};
79
80            my $val_type = ref $val;
81            croak qq{Can't save \L$val_type\E ref as value for key {'$block_name'}{'$key'} (only scalars or array refs)}
82                if $val_type && $val_type ne 'ARRAY';
83
84            $sep = $SEPARATOR{$sep || $def_sep};
85
86            my @vals = $val_type eq 'ARRAY' ? @{$val} : $val;
87            s/ (?!\Z) \n /\n$keyspace$sep/gxms for @vals;
88
89            $serialization .= $comm || q{};
90
91            $serialization .= join q{}, map {"$key$sep$_\n"} @vals;
92        }
93
94        return $serialization;
95    }
96
97    sub update {
98        my ($self, $hash_ref, $updated_ref) = @_;
99        my $ident = ident $self;
100
101        my $key = $key_of{$ident};
102
103        if (!exists $hash_ref->{$key}) {
104            $deleted_of{$ident} = 1;
105        }
106        else {
107            my $val = $hash_ref->{$key};
108            @newvals = ref $val eq 'ARRAY' ? @{$val} : $val;
109            for my $n (0..$#newvals) {
110                $vals_of{$ident}[$n]{val} = $newvals[$n];
111            }
112            splice @{$vals_of{$ident}}, scalar @newvals;
113        }
114
115        $updated_ref->{$key} = 1;
116
117        return 1;
118    }
119
120    sub copy_to {
121        my ($self, $hash_ref)  = @_;
122        my $ident = ident $self;
123        my @vals = map $_->{val}, @{$vals_of{$ident}};
124        $hash_ref->{$key_of{$ident}} = @vals > 1 ? \@vals : $vals[0];
125    }
126
127    sub multivalue {
128        my ($self, $sep, $val, $comm) = @_;
129        push @{$vals_of{ident $self}}, {val=>$val, sep=>$sep, comm=>$comm};
130    }
131}
132
133package Config::Std::Block;
134use Class::Std;
135{
136    my %name_of         : ATTR( :init_arg<name> :get<name> default => '' );
137    my %sep_count_of    : ATTR;
138    my %precomm_of      : ATTR( :init_arg<precomm> default => '' );
139    my %parcomm_of      : ATTR( :init_arg<parcomm> default => '' );
140    my %components_of   : ATTR;
141    my %deleted_of      : ATTR;
142    my %seen            : ATTR;
143    my %is_first        : ATTR( :init_arg<first> default => '' );
144
145    sub BUILD {
146        my ($self, $ident) = @_;
147        @{$sep_count_of{$ident}}{':','='} = (0,0);
148        $components_of{$ident} = [];
149        $seen{$ident} = {};
150    }
151
152    sub copy_to {
153        my ($self, $hash_ref) = @_;
154        my $ident = ident $self;
155
156        my $keyvals = $hash_ref->{$name_of{$ident}} ||= {};
157
158        for my $comp ( @{$components_of{$ident}} ) {
159            $comp->copy_to($keyvals);
160        }
161
162        $hash_ref->{$name_of{$ident}} = $keyvals;
163    }
164
165    sub serialize {
166        my ($self, $first, $caller, $post_gap) = @_;
167        my $ident = ident $self;
168
169        return q{} if $deleted_of{$ident};
170
171        my $is_anon = $first && length($name_of{$ident}) == 0;
172
173        my $serialization = q{};
174        if (!$is_anon) {
175            $serialization = ($precomm_of{$ident} || q{})
176                           . "[$name_of{$ident}]"
177                           . (defined $parcomm_of{$ident}?$parcomm_of{$ident}:q{})
178                           . "\n";
179        }
180
181        my $gds = $global_def_sep{$caller};
182        my $def_sep
183            = defined $gds                                             ? $gds
184            : $sep_count_of{$ident}{':'} >= $sep_count_of{$ident}{'='} ? ':'
185            :                                                            '='
186            ;
187
188        $self->ensure_gap() if !$is_anon;
189
190        for my $comp ( @{$components_of{$ident}} ) {
191            $serialization .= $comp->serialize($def_sep, $name_of{$ident});
192        }
193
194        return $serialization;
195    }
196
197    sub update {
198        my ($self, $hash_ref, $updated_ref) = @_;
199        my $ident = ident $self;
200
201        if (!defined $hash_ref) {
202            $deleted_of{$ident} = 1;
203            return;
204        }
205
206        for my $comp ( @{$components_of{$ident}} ) {
207            $comp->update($hash_ref, $updated_ref) or next;
208        }
209    }
210
211    sub extend {
212        my ($self, $hash_ref, $updated_ref, $post_gap) = @_;
213
214        # Only the first occurrence of a block has new keys added...
215        return unless $is_first{ident $self};
216
217        my $first = 1;
218        for my $key ( grep {!$updated_ref->{$_}} keys %{$hash_ref}) {
219            $self->ensure_gap() if !$first++ || $post_gap;
220            $self->add_keyval($key, undef, $hash_ref->{$key});
221        }
222    }
223
224    sub ensure_gap {
225        my ($self) = @_;
226        my $comp_ref = $components_of{ident $self};
227        return if @{$comp_ref} && $comp_ref->[-1]->isa('Config::Std::Gap');
228        push @{$comp_ref}, Config::Std::Gap->new();
229    }
230
231    sub add_gap {
232        my ($self) = @_;
233        push @{$components_of{ident $self}}, Config::Std::Gap->new();
234    }
235
236    sub add_comment {
237        my ($self, $text) = @_;
238        my $comp_ref = $components_of{ident $self};
239        if ($comp_ref && @{$comp_ref} && $comp_ref->[-1]->isa('Config::Std::Comment') ) {
240            $comp_ref->[-1]->append_comment($text);
241        }
242        else {
243            push @{$comp_ref}, Config::Std::Comment->new({text=>$text});
244        }
245    }
246
247    sub add_keyval {
248        my ($self, $key, $sep, $val, $comm) = @_;
249        my $ident = ident $self;
250
251        $sep_count_of{$ident}{$sep}++ if $sep;
252
253        my $seen = $seen{$ident};
254
255        if ($seen->{$key}) {
256            $seen->{$key}->multivalue($sep, $val, $comm);
257            return;
258        }
259
260        my $keyval
261            = Config::Std::Keyval->new({key=>$key, sep=>$sep, val=>$val, comm=>$comm});
262        push @{$components_of{$ident}}, $keyval;
263        $seen->{$key} = $keyval;
264    }
265}
266
267package Config::Std::Hash;
268use Class::Std;
269{
270    use Carp;
271    use Fcntl ':flock';     # import LOCK_* constants
272
273    my %post_section_gap_for :ATTR;
274    my %array_rep_for        :ATTR;
275    my %filename_for         :ATTR;
276
277    sub write_config (\[%$];$) {
278        my ($hash_ref, $filename) = @_;
279        $hash_ref = ${$hash_ref} if ref $hash_ref eq 'REF';
280
281        $filename = $filename_for{$hash_ref} if @_<2;
282
283        croak "Missing filename for call to write_config()"
284            unless $filename;
285
286        my $post_gap = ($post_section_gap_for{$hash_ref} || 0) >= 0;
287
288        # Update existing keyvals in each block...
289        my %updated;
290        for my $block ( @{$array_rep_for{$hash_ref}} ) {
291            my $block_name = $block->get_name();
292            $block->update($hash_ref->{$block_name}, $updated{$block_name}||={});
293        }
294
295        # Add new keyvals to the first section of block...
296        for my $block ( @{$array_rep_for{$hash_ref}} ) {
297            my $block_name = $block->get_name();
298            $block->extend($hash_ref->{$block_name}, $updated{$block_name}, $post_gap);
299        }
300
301        # Add new blocks at the end...
302        for my $block_name ( sort grep {!$updated{$_}} keys %{$hash_ref} ) {
303            my $block = Config::Std::Block->new({name=>$block_name});
304            my $subhash = $hash_ref->{$block_name};
305            my $first = 1;
306            for my $key ( keys %{$subhash} ) {
307                if (!defined $subhash->{$key}) {
308                    croak "Can't save undefined value for key {'$block_name'}{'$key'} (only scalars or array refs)";
309                }
310                $block->ensure_gap() if !$first++ || $post_gap;
311                $block->add_keyval($key, undef, $subhash->{$key});
312                $block->add_gap();
313            }
314            push @{$array_rep_for{$hash_ref}}, $block;
315        }
316
317        open my $fh, '>', $filename
318            or croak "Can't open config file '$filename' for writing (\L$!\E)";
319
320        flock($fh,LOCK_EX|LOCK_NB)
321            || croak "Can't write to locked config file '$filename'"
322                if ! ref $filename;
323
324        my $first = 1;
325        for my $block ( @{$array_rep_for{$hash_ref}} ) {
326            print {$fh} $block->serialize($first, scalar caller, $post_gap);
327            $first = 0;
328        }
329
330        flock($fh,LOCK_UN) if ! ref $filename;
331
332        return 1;
333    }
334
335    sub read_config ($\[%$]) {
336        my ($filename, $var_ref, $opt_ref) = @_;
337        my $var_type = ref($var_ref) || q{};
338        my $hash_ref;
339        if ($var_type eq 'SCALAR' && !defined ${$var_ref} ) {
340            ${$var_ref} = $hash_ref = {};
341        }
342        elsif ($var_type eq 'HASH') {
343            $hash_ref = $var_ref;
344        }
345        else {
346            croak q{Scalar second argument to 'read_config' must be empty};
347        }
348
349        bless $hash_ref, 'Config::Std::Hash';
350
351        my $blocks = $array_rep_for{$hash_ref}
352                   = _load_config_for($filename, $hash_ref);
353
354        for my $block ( @{$blocks} ) {
355            $block->copy_to($hash_ref);
356        }
357
358        $filename_for{$hash_ref} = $filename;
359
360        # Remove initial empty section if no data...
361        if (!keys %{ $hash_ref->{q{}} }) {
362            delete $hash_ref->{q{}};
363        }
364
365        return 1;
366    }
367
368    sub _load_config_for {
369        my ($filename, $hash_ref) = @_;
370
371        open my $fh, '<', $filename
372            or croak "Can't open config file '$filename' (\L$!\E)";
373        flock($fh,LOCK_SH|LOCK_NB)
374            || croak "Can't read from locked config file '$filename'"
375                if !ref $filename;
376        my $text = do{local $/; <$fh>};
377        flock($fh,LOCK_UN) if !ref $filename;
378
379        my @config_file = Config::Std::Block->new({ name=>q{}, first=>1 });
380        my $comment = q{};
381        my %seen;
382
383        # Start tracking whether section markers have gaps after them...
384        $post_section_gap_for{$hash_ref} = 0;
385
386        for ($text) {
387            pos = 0;
388            while (pos() < length() ) {
389                # Gap...
390                if (m/\G (?: [^\S\n]* (?:\n|\z)+)/gcxms) {
391                    ### Found gap
392                    $config_file[-1]->add_comment($comment) if $comment;
393                    $config_file[-1]->add_gap();
394                    $comment = q{};
395                }
396
397                # Comment...
398                elsif (m/\G (\s* [#] [^\n]* (?:\n|\z) )/gcxms) {
399                    ### Found comment: $1
400                    $comment .= $1;
401                }
402
403                # Block...
404                elsif (m/\G ([^\S\n]*) [[]  ( [^]\n]* ) []] ( ([^\S\n]*) [#] [^\n]* )? (?:\n|\z)/gcxms) {
405                    my ($pre, $name, $parcomm, $ws) = ($1, $2, $3, $4);
406                    ### Found block: $name
407                    if ($parcomm) {
408                        $pre = 2 + length($pre) + length($name) + length($ws);
409                        if (m/\G ( (?: \n? [ ]{$pre,} [#] [^\n]* )+ )/gcxms) {
410                            $parcomm .= "\n$1";
411                        }
412                    }
413                    push @config_file,
414                            Config::Std::Block->new({
415                                name    => $name,
416                                precomm => $comment,
417                                parcomm => $parcomm,
418                                first   => !$seen{$name}++,
419                            });
420                    $comment = q{};
421
422                    # Check for trailing gap...
423                    $post_section_gap_for{$hash_ref}
424                        += m/\G (?= [^\S\n]* (?:\n|\z) )/xms ? +1 : -1;
425                }
426
427                # Key/value...
428                elsif (m/\G [^\S\n]* ([^=:\n]+?) [^\S\n]* ([:=] [^\S\n]*) ([^\n]*) (?:\n|\z)/gcxms) {
429                    my ($key, $sep, $val) = ($1, $2, $3);
430
431                    my $pure_sep = $sep;
432                    $pure_sep =~ s/\s*//g;
433
434                    # Continuation lines...
435                    my $continued = 0;
436                    while (m/\G [^\S\n]* \Q$sep\E ([^\n]*) (?:\n|\z) /gcxms
437                       ||  m/\G [^\S\n]* \Q$pure_sep\E ([^\n]*) (?:\n|\z) /gcxms
438                    ) {
439                        $val .= "\n$1";
440                        $continued = 1;
441                    }
442
443                    $val =~ s/\A \s*|\s* \z//gxms if !$continued;
444
445                    ### Found kv: $key, $val
446
447                    $config_file[-1]->add_keyval($key, $pure_sep, $val, $comment);
448                    $comment = q{};
449                }
450
451                # Mystery...
452                else {
453                    my ($problem) = m/\G ([^\n]{10,40}|.{10}) /gcxms;
454                    die "Error in config file '$filename' near:\n\n\t$problem\n";
455                }
456            }
457        }
458
459        return \@config_file;
460    }
461
462}
463
464
4651; # Magic true value required at end of module
466__END__
467
468=head1 NAME
469
470Config::Std - Load and save configuration files in a standard format
471
472
473=head1 VERSION
474
475This document describes Config::Std version 0.0.4
476
477
478=head1 SYNOPSIS
479
480    use Config::Std;
481
482    # Load named config file into specified hash...
483    read_config 'demo2.cfg' => my %config;
484
485    # Extract the value of a key/value pair from a specified section...
486    $config_value = $config{Section_label}{key};
487
488    # Change (or create) the value of a key/value pair...
489    $config{Other_section_label}{other_key} = $new_val;
490
491    # Update the config file from which this hash was loaded...
492    write_config %config;
493
494    # Write the config information to another file as well...
495    write_config %config, $other_file_name;
496
497
498=head1 DESCRIPTION
499
500This module implements yet another damn configuration-file system.
501
502The configuration language is deliberately simple and limited, and the
503module works hard to preserve as much information (section order,
504comments, etc.) as possible when a configuration file is updated.
505
506See Chapter 19 of "Perl Best Practices" (O'Reilly, 2005) for the
507rationale for this approach.
508
509=head2 Configuration language
510
511The configuration language is a slight extension of the Windows INI format.
512
513=head3 Comments
514
515A comment starts with a C<#> character and runs to the end of the same line:
516
517    # This is a comment
518
519Comments can be placed almost anywhere in a configuration file, except inside
520a section label, or in the key or value of a configuration variable:
521
522    # Valid comment
523    [ # Not a comment, just a weird section label ]
524
525    # Valid comment
526    key: value  # Not a comment, just part of the value
527
528
529=head3 Sections
530
531A configuration file consists of one or more I<sections>, each of which is
532introduced by a label in square brackets:
533
534    [SECTION1]        # Almost anything is a valid section label
535
536    [SECTION 2]       # Internal whitespace is allowed (except newlines)
537
538    [%^$%^&!!!]       # The label doesn't have to be alphanumeric
539
540    [ETC. ETC. AS MANY AS YOU WANT]
541
542The only restriction on section labels is that they must be by
543themselves on a single line (except for any surrounding whitespace or
544trailing comments), and they cannot contain the character C<]>.
545
546Every line after a given section label until the next section label (or
547the end of the config file) belongs to the given section label. If no
548section label is currently in effect, the current section has an empty
549label. In other words, there is an implicit:
550
551    []                # Label is the empty string
552
553at the start of each config file.
554
555=head3 Configuration variables
556
557Each non-empty line within a section must consist of the specification of a
558I<configuration variable>. Each such variable consists of a key and a string
559value. For example:
560
561    name: George
562     age: 47
563
564    his weight! : 185
565
566The key consists of every character (including internal whitespace) from
567the start of the line until the key/value separator. So, the previous
568example declares three keys: C<'name'>, C<'age'>, and C<'his weight!'>.
569
570Note that whitespace before and after the key is removed. This makes it easier
571to format keys cleanly:
572
573           name : George
574            age : 47
575    his weight! : 185
576
577The key/value separator can be either a colon (as above) or an equals sign,
578like so:
579
580           name= George
581            age=  47
582    his weight! = 185
583
584Both types of separators can be used in the same file, but neither can
585be used as part of a key. Newlines are not allowed in keys either.
586
587When writing out a config file, Config::Std tries to preserve whichever
588separator was used in the original data (if that data was read
589in). New data is written back with a colon as its default separator,
590unless you specify otherwise when the module is loaded:
591
592    use Config::Std { def_sep => '=' };
593
594Everything from the first non-whitespace character after the separator,
595up to the end of the line, is treated as the value for the config variable.
596So all of the above examples define the same three values: C<'George'>,
597C<'47'>, and C<'185'>.
598
599In other words, any whitespace immediately surrounding the separator
600character is part of the separator, not part of the key or value.
601
602Note that you can't put a comment on the same line as a configuration
603variable. The C<# etc.> is simply considered part of the value:
604
605    [Delimiters]
606
607    block delims:    { }
608    string delims:   " "
609    comment delims:  # \n
610
611You can comment a config var on the preceding or succeeding line:
612
613    [Delimiters]
614
615    # Use braces to delimit blocks...
616    block delims:    { }
617
618    # Use double quotes to delimit strings
619
620    string delims:   " "
621
622    # Use octothorpe/newline to delimit comments
623    comment delims:  # \n
624
625
626=head3 Multi-line configuration values
627
628A single value can be continued over two or more lines. If the line
629immediately after a configuration variable starts with the separator
630character used in the variable's definition, then the value of the
631variable continues on that line. For example:
632
633    address: 742 Evergreen Terrace
634           : Springfield
635           : USA
636
637The newlines then form part of the value, so the value specified in the
638previous example is: C<S<"742 Evergreen Terrace\nSpringfield\nUSA">>
639
640Note that the second and subsequent lines of a continued value are considered
641to start where the whitespace after the I<original> separator finished, not
642where the whitespace after their own separator finishes. For example, if the
643previous example had been:
644
645    address: 742 Evergreen Terrace
646           :   Springfield
647           :     USA
648
649then the value would be:
650
651    "742 Evergreen Terrace\n  Springfield\n    USA"
652
653If a continuation line has less leading whitespace that the first line:
654
655    address:   742 Evergreen Terrace
656           :  Springfield
657           : USA
658
659it's treated as having no leading whitespace:
660
661    "742 Evergreen Terrace\nSpringfield\nUSA"
662
663
664=head3 Multi-part configuration values
665
666If the particular key appears more than once in the same section, it is
667considered to be part of the same configuration variable. The value of
668that configuration value is then a list, containing all the individual
669values for each instance of the key. For example, given the definition:
670
671    cast: Homer
672    cast: Marge
673    cast: Lisa
674    cast: Bart
675    cast: Maggie
676
677the corresponding value of the C<'cast'> configuration variable is:
678C<S<['Homer', 'Marge', 'Lisa', 'Bart', 'Maggie']>>
679
680Individual values in a multi-part list can also be multi-line (see
681above). For example, given:
682
683    extras: Moe
684          : (the bartender)
685
686    extras: Smithers
687          : (the dogsbody)
688
689the value for the C<'extras'> config variable is:
690C<S<["Moe\n(the bartender)", "Smithers\n(the dogsbody)"]>>
691
692
693=head2 Internal representation
694
695Each section label in a configuration file becomes a top-level hash key whe
696the configuration file is read in. The corresponding value is a nested hash
697reference.
698
699Each configuration variable's key becomes a key in that nested hash reference.
700Each configuration variable's value becomes the corresponding value in that nested hash reference.
701
702Single-line and multi-line values become strings. Multi-part values become
703references to arrays of strings.
704
705For example, the following configuration file:
706
707    # A simple key (just an identifier)...
708    simple : simple value
709
710    # A more complex key (with whitespace)...
711    more complex key : more complex value
712
713    # A new section...
714    [MULTI-WHATEVERS]
715
716    # A value spread over several lines...
717    multi-line : this is line 1
718               : this is line 2
719               : this is line 3
720
721    # Several values for the same key...
722    multi-value: this is value 1
723    multi-value: this is value 2
724    multi-value: this is value 3
725
726would be read into a hash whose internal structure looked like this:
727
728    {
729       # Default section...
730       '' => {
731          'simple'           => 'simple value',
732          'more complex key' => 'more complex value',
733       },
734
735       # Named section...
736       'MULTI-WHATEVERS' => {
737            'multi-line'  => "this is line 1\nthis is line 2\nthis is line 3",
738
739            'multi-value' => [ 'this is value 1',
740                               'this is value 2',
741                               'this is value 3'
742                             ],
743        }
744    }
745
746
747=head1 INTERFACE
748
749The following subroutines are exported automatically whenever the module is
750loaded...
751
752=over
753
754=item C<< read_config($filename => %config_hash) >>
755
756=item C<< read_config($filename => $config_hash_ref) >>
757
758The C<read_config()> subroutine takes two arguments: the filename of a
759configuration file, and a variable into which the contents of that
760configuration file are to be loaded.
761
762If the variable is a hash, then the configuration sections and their
763key/value pairs are loaded into nested subhashes of the hash.
764
765If the variable is a scalar with an undefined value, a reference to an
766anonymous hash is first assigned to that scalar, and that hash is then
767filled as described above.
768
769The subroutine returns true on success, and throws an exception on failure.
770
771
772=item C<< write_config(%config_hash => $filename) >>
773
774=item C<< write_config($config_hash_ref => $filename) >>
775
776=item C<write_config(%config_hash)>
777
778=item C<write_config($config_hash_ref)>
779
780The C<write_config()> subroutine takes two arguments: the hash or hash
781reference containing the configuration data to be written out to disk,
782and an optional filename specifying which file it is to be written to.
783
784The data hash must conform to the two-level structure described earlier:
785with top-level keys naming sections and their values being references to
786second-level hashes that store the keys and values of the configuartion
787variables. If the structure of the hash differs from this, an exception is
788thrown.
789
790If a filename is also specified, the subroutine opens that file
791and writes to it. It no filename is specified, the subroutine uses the
792name of the file from which the hash was originally loaded using
793C<read_config()>. It no filename is specified and the hash I<wasn't>
794originally loaded using C<read_config()>, an exception is thrown.
795
796The subroutine returns true on success and throws and exception on failure.
797
798=back
799
800If necessary (typically to avoid conflicts with other modules), you can
801have the module export its two subroutines with different names by
802loading it with the appropriate options:
803
804    use Config::Std { read_config => 'get_ini', write_config => 'update_ini' };
805
806    # and later...
807
808    get_ini($filename => %config_hash);
809
810    # and later still...
811
812    update_ini(%config_hash);
813
814
815=head1 DIAGNOSTICS
816
817=over
818
819=item Can't open config file '%s' (%s)
820
821You tried to read in a configuration file, but the file you specified
822didn't exist. Perhaps the filepath you specified was wrong. Or maybe
823your application didn't have permission to access the file you specified.
824
825=item Can't read from locked config file '$filename'
826
827You tried to read in a configuration file, but the file you specified
828was being written by someone else (they had a file lock active on it).
829Either try again later, or work out who else is using the file.
830
831=item Scalar second argument to 'read_config' must be empty
832
833You passed a scalar variable as the destination into C<read_config()>
834was supposed to load a configuration file, but that variable already had
835a defined value, so C<read_config()> couldn't autovivify a new hash for
836you. Did you mean to pass the subroutine a hash instead of a scalar?
837
838=item Can't save %s value for key '%s' (only scalars or array refs)
839
840You called C<write_config> and passed it a hash containing a
841configuration variable whose value wasn't a single string, or a list of
842strings. The configuration file format supported by this module only
843supports those two data types as values. If you really need to store
844other kinds of data in a configuration file, you should consider using
845C<Data::Dumper> or C<YAML> instead.
846
847=item Missing filename in call to write_config()
848
849You tried to calll C<write_config()> with only a configuration hash, but that
850hash wasn't originally loaded using C<read_config()>, so C<write_config()> has
851no idea where to write it to. Either make sure the hash you're trying to save
852was originally loaded using C<read_config()>, or else provide an explicit
853filename as the second argument to C<write_config()>.
854
855=item Can't open config file '%s' for writing (%s)
856
857You tried to update or create a configuration file, but the file you
858specified could not be opened for writing (for the reason given in the
859parentheses). This is often caused by incorrect filepaths or lack of
860write permissions on a directory.
861
862=item Can't write to locked config file '%s'
863
864You tried to update or create a configuration file, but the file you
865specified was being written at the time by someone else (they had a file
866lock active on it). Either try again later, or work out who else is
867using the file.
868
869=back
870
871
872=head1 CONFIGURATION AND ENVIRONMENT
873
874Config::Std requires no configuration files or environment variables.
875
876
877=head1 DEPENDENCIES
878
879This module requires the Class::Std module (available from the CPAN)
880
881
882=head1 INCOMPATIBILITIES
883
884None reported.
885
886
887=head1 BUGS AND LIMITATIONS
888
889No bugs have been reported.
890
891Please report any bugs or feature requests to
892C<bug-config-std@rt.cpan.org>, or through the web interface at
893L<http://rt.cpan.org>.
894
895
896=head1 AUTHOR
897
898Damian Conway  C<< <DCONWAY@cpan.org> >>
899
900
901=head1 LICENCE AND COPYRIGHT
902
903Copyright (c) 2005, Damian Conway C<< <DCONWAY@cpan.org> >>. All rights reserved.
904
905This module is free software; you can redistribute it and/or
906modify it under the same terms as Perl itself.
907
908
909=head1 DISCLAIMER OF WARRANTY
910
911BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
912FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
913OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
914PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
915EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
916WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
917ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
918YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
919NECESSARY SERVICING, REPAIR, OR CORRECTION.
920
921IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
922WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
923REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
924LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
925OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
926THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
927RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
928FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
929SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
930SUCH DAMAGES.
931