a43ac53e0f96196a68da6953c485fdfacb3ed30c
[p5sagit/Config-Any.git] / lib / Config / Any / INI.pm
1 package Config::Any::INI;
2
3 use strict;
4 use warnings;
5
6 use base 'Config::Any::Base';
7
8 our $MAP_SECTION_SPACE_TO_NESTED_KEY = 1;
9
10 =head1 NAME
11
12 Config::Any::INI - Load INI config files
13
14 =head1 DESCRIPTION
15
16 Loads INI files. Example:
17
18     name=TestApp
19     
20     [Controller::Foo]
21     foo=bar
22     
23     [Model::Baz]
24     qux=xyzzy
25
26 =head1 METHODS
27
28 =head2 extensions( )
29
30 return an array of valid extensions (C<ini>).
31
32 =cut
33
34 sub extensions {
35     return qw( ini );
36 }
37
38 =head2 load( $file )
39
40 Attempts to load C<$file> as an INI file.
41
42 =cut
43
44 sub load {
45     my $class = shift;
46     my $file  = shift;
47
48     require Config::Tiny;
49     my $config = Config::Tiny->read( $file );
50
51     die $Config::Tiny::errstr if not defined $config;
52
53     my $out = delete $config->{ _ } || {};
54
55     for my $k ( keys %$config ) {
56         my @keys = split /\s+/, $k;
57         my $ref = $config->{ $k };
58
59         if ( $MAP_SECTION_SPACE_TO_NESTED_KEY && @keys > 1 ) {
60             my ( $a, $b ) = @keys[ 0, 1 ];
61             $out->{ $a }->{ $b } = $ref;
62         }
63         else {
64             $out->{ $k } = { %{ $out->{ $k } || {} }, %$ref };
65         }
66     }
67
68     return $out;
69 }
70
71 =head2 requires_all_of( )
72
73 Specifies that this module requires L<Config::Tiny> in order to work.
74
75 =cut
76
77 sub requires_all_of { 'Config::Tiny' }
78
79 =head1 PACKAGE VARIABLES
80
81 =over 4
82
83 =item $MAP_SECTION_SPACE_TO_NESTED_KEY (boolean)
84
85 This variable controls whether spaces in INI section headings will be expanded into nested hash keys.
86 e.g. it controls whether [Full Power] maps to $config->{'Full Power'} or $config->{'Full'}->{'Power'}
87
88 By default it is set to 1 (i.e. true). 
89
90 Set it to 0 to preserve literal spaces in section headings:
91
92     use Config::Any;
93     use Config::Any::INI;
94     $Config::Any::INI::MAP_SECTION_SPACE_TO_NESTED_KEY = 0;
95
96 =back
97
98 =head1 AUTHORS
99
100 Brian Cassidy E<lt>bricas@cpan.orgE<gt>
101
102 Joel Bernstein E<lt>rataxis@cpan.orgE<gt>
103
104 =head1 COPYRIGHT AND LICENSE
105
106 Copyright 2006-2009 by Brian Cassidy, portions copyright 2006, 2007 by Joel Bernstein
107
108 This library is free software; you can redistribute it and/or modify
109 it under the same terms as Perl itself. 
110
111 =head1 SEE ALSO
112
113 =over 4 
114
115 =item * L<Catalyst>
116
117 =item * L<Config::Any>
118
119 =item * L<Config::Tiny>
120
121 =back
122
123 =cut
124
125 1;