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