The CONFIG:: Guide
2. Simple usage of CONFIG::Plain
The first steps to use the CONFIG::Plain package are very simple:
1: #! /usr/local/bin/perl -w
2:
3: use strict;
4: use CONFIG::Plain;
5:
6: my $configuration;
7:
8: $configuration = CONFIG::Plain->new('sample.rc');
9:
10: print $configuration->getfile();
11:
12: $config->close;
|
| src/list_2_1.pl |
This program reads the file sample.rc and prints it.
The first intresting function is the new method of the CONFIG::Plain module, which (suprise) creates an new object, reads the file and preparses the content of the file. The new method takes the filename as argument and returns a CONFIG::Plain object.
The following getfile() method call returns the whole file as a scalar.
Strange enough, if you run this program on a existing smaple.rc file it works. If you miss something of your file (e.g. empty lines) be patient, the default behaviour of the module and how to change it will be described in the next chapter.
Another way to read the file is line by line:
1: #! /usr/bin/perl -w
2:
3: use strict;
4: use CONFIG::Plain;
5:
6: my $config;
7: my $line;
8:
9: $config = CONFIG::Plain->new('sample.rc');
10:
11: while (defined ($line = $config->getline())) {
12: printf("%s:%d> %s\n", $config->getline_file,
13: $config->getline_number,
14: $line);
15: }
16:
17: $config->close;
|
| src/list_2_2.pl |
which will also work as expected.
You noticed the two new methods used in this program: getline_file and
getline_number. getline_file returns the full path to the file
read by the module. The path returned by this method is also the internal
key to find an already opend instance of this file. So if you have two scripts
running in two directories using the same file, will use the same cached
instance of this file.
The getline_number method returns the input line number like the
$. (or $NR, $INPUT_LINE_NUMBER if you use the English module, which is not recommended) perl variable does.
Well, i guess you already tested this program without the sample.rc file.
If you don't run into a Use of uninitialized value error you should
enable the perl warnings with the -w tag.
You may expect the $configuration variable to be uninizialized as you
would get an uninizialized value if you try to open a non-existing file with
the FileHandle package.
But you are wrong, the error handling of this module is a litte bit different.
Since the new() method never fails there is a other way to check for errors:
The getline_error() method returns the errors occured in the line returned from
the last call of getline(). If you call the getline_error() method before
calling getline() you will receive the global error messages such as
"file not found".
In later chapers you'll see situation in which a single line causes more the one error. For such situations it is possible to to call the getline_error method often in order to receive all error messages. The list is terminated by an undefined value. So we can write a program with full error reporting:
1: #! /usr/bin/perl -w
2:
3: use strict;
4: use CONFIG::Plain;
5:
6: my $config;
7: my $line;
8: my $error;
9:
10: $config = CONFIG::Plain->new('sample.rc');
11:
12: #####################################################################
13: # GLOBAL ERROR HANDLING
14: while (defined ($error = $config->getline_error)) {
15: print("GLOBAL ERROR: ". $error ."\n");
16: }
17:
18: #####################################################################
19: # LINE BASED ERROR HANDLING
20: while (defined ($line = $config->getline())) {
21: $error = $config->getline_error;
22: if (defined $error) {
23: ### line has error(s)
24: printf("ERROR in %s:%d\n",
25: $config->getline_file, $config->getline_number);
26: do { ### report all errors
27: printf(" %s\n", $error);
28: } while (defined ($error = $config->getline_error));
29: } else {
30: ### line has no errors
31: printf("%s:%d> %s\n", $config->getline_file,
32: $config->getline_number,
33: $line);
34: }
35: }
36:
37: $config->close;
|
| src/list_2_3.pl |
Please notice every getline_error call is used in a loop to report multiple errors (even the global error reporting).
Since this error reporting code is very nice, I sticked it into a method: get_errors returns a scalar holding all errors occured in this file in a preformated manner. The get_erorrs method returns an empty scalar (not an undef!) if no error occured.
Now we can finalize our program to do error reporting using the get_errors method:
1: #! /usr/bin/perl -w
2:
3: use strict;
4: use CONFIG::Plain;
5:
6: my $config;
7: my $line;
8: my $errors;
9:
10: $config = CONFIG::Plain->new('sample.rc');
11:
12: if (($errors = $config->get_errors) eq '') {
13: while (defined ($line = $config->getline())) {
14: printf("%s:%d> %s\n", $config->getline_file,
15: $config->getline_number,
16: $line);
17: }
18: } else {
19: print($errors);
20: }
21:
22: $config->close();
|
| src/list_2_4.pl |
This is the recommended way to start every file reading: Check for all errors using the get_errors method, go on with your script on no error or print the erros and exit on errors.
You can still use the getline_error method to distinguish between global errors, line based errors or handle different errors in a different way.
Please Notice:The get_errors method was designed to be used in the way shown above. A call to this method resets the cursor, so any later call to getline will start again with the first line of the file. If you want to read the file twice you can reset the cursor with the getline_reset method. The usual way to read the file twice is to close it with the close method and just open it again.
