1Prima::IniFile(3)     User Contributed Perl Documentation    Prima::IniFile(3)
2
3
4

NAME

6       Prima::IniFile - support of Windows-like initialization files
7

DESCRIPTION

9       The module contains a class, that provides mapping of text
10       initialization file to a two-level hash structure. The first level is
11       called sections, which groups the second level hashes, called items.
12       Sections must have unique keys. The items hashes values are arrays of
13       text strings. The methods, operated on these arrays are get_values,
14       set_values, add_values and replace_values.
15

SYNOPSIS

17               use Prima::IniFile;
18
19               my $ini = create Prima::IniFile;
20               my $ini = create Prima::IniFile FILENAME;
21               my $ini = create Prima::IniFile FILENAME,
22                                               default => HASHREF_OR_ARRAYREF;
23               my $ini = create Prima::IniFile file => FILENAME,
24                                               default => HASHREF_OR_ARRAYREF;
25
26               my @sections = $ini->sections;
27               my @items = $ini->items(SECTION);
28               my @items = $ini->items(SECTION, 1);
29               my @items = $ini->items(SECTION, all => 1);
30
31               my $value = $ini-> get_values(SECTION, ITEM);
32               my @vals = $ini-> get_values(SECTION, ITEM);
33               my $nvals = $ini-> nvalues(SECTION, ITEM);
34
35               $ini-> set_values(SECTION, ITEM, LIST);
36               $ini-> add_values(SECTION, ITEM, LIST);
37               $ini-> replace_values(SECTION, ITEM, LIST);
38
39               $ini-> write;
40               $ini-> clean;
41               $ini-> read( FILENAME);
42               $ini-> read( FILENAME, default => HASHREF_OR_ARRAYREF);
43
44               my $sec = $ini->section(SECTION);
45               $sec->{ITEM} = VALUE;
46               my $val = $sec->{ITEM};
47               delete $sec->{ITEM};
48               my %everything = %$sec;
49               %$sec = ();
50               for ( keys %$sec) { ... }
51               while ( my ($k,$v) = each %$sec) { ... }
52

METHODS

54       add_values SECTION, ITEM, @LIST
55           Adds LIST of string values to the ITEM in SECTION.
56
57       clean
58           Cleans all internal data in the object, including the name of the
59           file.
60
61       create PROFILE
62           Creates an instance of the class. The PROFILE is treated partly as
63           an array, partly as a hash. If PROFILE consists of a single item,
64           the item is treated as a filename. Otherwise, PROFILE is treated as
65           a hash, where the following keys are allowed:
66
67           file FILENAME
68               Selects name of file.
69
70           default %VALUES
71               Selects the initial values for the file, where VALUES is a two-
72               level hash of sections and items. It is passed to read, where
73               it is merged with the file data.
74
75       get_values SECTION, ITEM
76           Returns array of values for ITEM in SECTION. If called in scalar
77           context, and there is more than one value, the first value in list
78           is returned.
79
80       items SECTION [ HINTS ]
81           Returns items in SECTION. HINTS parameters is used to tell if a
82           multiple-valued item must be returned as several items of the same
83           name; HINTS can be supplied in the following forms:
84
85           items( $section, 1 ) items( $section, all => 1);
86
87       new PROFILE
88           Same as create.
89
90       nvalues SECTION, ITEM
91           Returns number of values in ITEM in SECTION.
92
93       read FILENAME, %PROFILE
94           Flushes the old content and opens new file. FILENAME is a text
95           string, PROFILE is a two-level hash of default values for the new
96           file. PROFILE is merged with the data from file, and the latter
97           keep the precedence.  Does not return any success values but, warns
98           if any error is occurred.
99
100       replace_values SECTION, ITEM, @VALUES
101           Removes all values form ITEM in SECTION and assigns it to the new
102           list of VALUES.
103
104       section SECTION
105           Returns a tied hash for SECTION. All its read and write operations
106           are reflected in the caller object, which allows the following
107           syntax:
108
109                   my $section = $inifile-> section( 'Sample section');
110                   $section-> {Item1} = 'Value1';
111
112           which is identical to
113
114                   $inifile-> set_items( 'Sample section', 'Item1', 'Value1');
115
116       sections
117           Returns array of section names.
118
119       set_values SECTION, ITEM, @VALUES
120           Assigns VALUES to ITEM in SECTION. If number of new values are
121           equal or greater than the number of the old, the method is same as
122           replace_values. Otherwise, the values with indices higher than the
123           number of new values are not touched.
124
125       write
126           Rewrites the file with the object content. The object keeps an
127           internal modification flag under name "{changed}"; in case it is
128           "undef", no actual write is performed.
129

AUTHORS

131       Anton Berezin, <tobez@plab.ku.dk>
132
133       Dmitry Karasik <dmitry@karasik.eu.org>
134
135
136
137perl v5.34.0                      2021-07-22                 Prima::IniFile(3)