tutorial~

一个Linux下读写文件的代码

Tutorial


This is a quick tutorial on how to get started with ConfigLib.  The latest version is available at http://configlib.wiki.sourceforge.net/tutorial

----

ConfigLib is designed to offer a simple class structure for accessing configuration files while offering flexibility and ensuring that all configuration file functions work without any work beyond the initial variable declaration.

The project is designed to work as a static library and has an associated make file and vcproj for inclusion in your project. It is also possible to just add the files to any C++ project.

The next step is, of course, to declare the configuration file object. Each configuration file should have it's own object, and it should be a static variable to avoid rereading the file each time it is accessed. You can add it to an object and use the singleton pattern if you wish, but in this tutorial it's easier to just make it global.

[[code]]
#include "configfile.h"

using namespace configlib;
configfile configuration("filename.conf");
[[code]]

Note that the constructor takes a file name. If the file name must be computed at runtime then use the singleton pattern and create the configfile object when it is needed.

Now we need to read the configuration file and, while we are at it, parse the command line too.

[[code]]
int main(int argc, char* argv[])
{
    configuration.read();
    configuration.parse(argc, argv);
}
[[code]]

----

Now that the configuration file is read it is time to add some configuration variables. Consider the configuration file

[[code]]
[main]
int value=7
string value=This is a string

# A list of defined colors
[colors]
red=255 0 0
green=0x00 0xFF 0x00
blue=#0000FF

[other stuff]
int value=12
bob=12.35.63.17:45
local network=192.168.10.0/24
[[code]]

This has three sections, main, colors and other stuff. Each section has it's own configuration settings, comments begin with the # character. The examples below are all going to read this file.

----

Let's start by reading the two values in the main section.

[[code]]
#include "configfile.h"
#include "configitem.h"

using namespace configlib;
configfile configuration("filename.conf");

configitem<int> int_value(configuration, "main" "int value", "", 0);
configitem<std::string>> string_item(configuration, "main", "string value", "", "Default");
[[code]]

The first thing to note is that the configitem is a C++ template. This allows it to duplicate any type we want, or even create our own objects for handling configuration items.

The constructor for the configitem takes five parameters:

1. The configfile object to associate it with.
2. The name of the section to use. this can be blank to mean there is no section header, or * to mean any section header is valid.
3. The setting name.
4. The command line options -- more on this later.
5. The default value, used if the configuration file has not yet been read, or the option is not in the file.

We can now modify the function to read and write these settings by typecasting the to the variables they represent.

[[code]]
int main(int argc, char* argv[])
{
    configuration.read();
    configuration.parse(argc, argv);

    std::cout << (int)int_value << std::endl;
    string_value = "New string";
}
[[code]]

----

Of course, there is no reason we have to use the preexisting C++ types for a configuration item. Any object with a default constructor that can serialize to a string is able to work. There are two objects included with the library that handle the common configuration options color and ipaddress.

Lets add the configuration setting for the IP address bob:

[[code]]
#include "configfile.h"
#include "configitem.h"
#include "ipaddress.h"

using namespace configlib;
configfile configuration("filename.conf");

configitem<int> int_value(configuration, "main" "int value", "", 0);
configitem<std::string> string_item(configuration, "main", "string value", "", "Default");
configitem<ipaddress> bob(configuration, "other stuff", "bob", "", LOOPBACK);
[[code]]

This works just like the other settings. LOOPBACK is a special predefined ipaddress object useful for default values.

But we don't need to have a global variable. Using a global saves processing time when a variable is reused often, but if you are reading a value just once, or if the routine is not time critical feel free to use a local variable.

[[code]]
    std::cout << (int)int_value << std::endl;
    string_value = "New string";

    ipaddress default("192.168.0.0/24");
    configitem<ipaddress> localnet(configuration, "other stuff", "local network", "", default);
    assign_local_network(localnet.get_address(), localnet.get_mask());
}
[[code]]

There are two important things to remember when using local variables:

1. Note that any changes made to the local variable will still affect the configfile object, so the next time the setting is read it will have the new value.
2. Command line settings are not written to the configfile object, so if the parse() function is called before the local variable is created the command line switches will not affect its value.

----

So reading the configuration file is useful, but what if we want to write out the changes? For that we use the write function.

All changes to configitem objects are stored immediately in the configfile object. Comments are kept and changes are placed on the same line as the original setting. New configuration settings are placed at the end of the section they appear in, new sections are added to the end of the file.

[[code]]
    configitem<ipaddress> localnet(configuration, "other stuff", "local network", "", default);
    assign_local_network(localnet.get_address(), localnet.get_mask());

    configuration.write();
}
[[code]]

----

To read an entire section, use the configmap or configvector templates. These are only appropriate if the section contains all the same setting types. If you need to read mixed types you can use a std::string object and parse the values yourself.

[[code]]
#include "configfile.h"
#include "configitem.h"
#include "configmap.h"

using namespace configlib;
configfile configuration("filename.conf");

configitem<int> int_value(configuration, "main" "int value", "", 0);
configitem<std::string> string_item(configuration, "main", "string value", "", "Default");
configitem<ipaddress> bob(configuration, "other stuff", "bob", "", LOOPBACK);
configmap<color> color_list(configuration, "colors");
[[code]]

Since everything in a section is read, there is no name parameter and no default value.

A configmap can be iterated just like a std::map. New values can be added and old ones removed just as easily.

[[code]]
    configitem<ipaddress> localnet(configuration, "other stuff", "local network", "", default);
    assign_local_network(localnet.get_address(), localnet.get_mask());

    for (configmap<color>::iterator it = color_list.begin();color_list.end() != it;it++)
        std::cout << "Color " << it->first << " is " << it->second << std::endl;

    set_background(color_list["blue"]);
    color yellow(255, 255, 0);
    color_list.set("yellow", yellow);

    configuration.write();
}
[[code]]

----

Now would be a good time to actually parse the command line itself. The command line is being passed top the configfile object, but no parameters have been defined, so nothing happens except storing the name of the program running.

The fourth parameter defines what command line options are read for what configuration settings. Let's add a command line switch as a boolean.

[[code]]
configitem<ipaddress> bob(configuration, "other stuff", "bob", "", LOOPBACK);
configmap<color> color_list(configuration, "colors");
configitem<bool> verbose(configuration, "", "", "v", false);
[[code]]

By using the "v" character we mark that the item should be incremented when that character appears as a command line switch like -v (or in a group of switched characters. Note that each appearance increments the value, but a bool has only two values so it is toggled. that means the switch -vv will reset verbose to the off position.

To keep track of a count use an int. Let's do that with the int_value configuration setting:

[[code]]
configitem<int> int_value(configuration, "main" "int value", "-i", 0);
[[code]]

Now if the command line has -i the int_value will be set to one more than the value set in the configuration file and -ii will set it two larger and so on.

Note that there is also a - in the string. This allows the command line to use Unix style long names. In this case -int-value will act just like the -i switch.

This doesn't work for the string, though. For the string we need to specify that the command line switch has a parameter. Use = for that.

[[code]]
configitem<std::string> string_item(configuration, "main", "string value", "-s=", "Default");
[[code]]

The command switch indicates that the next parameter is the string_item: -s new-value will store "new-value" in string_item. Long name style is also allowed, which means -string-value=new-value will also work.

Finally, the IP address for bob should be the first command line parameter that isn't a switch. To do that we use a the index of the command line item. The first index is 0, so put 0 in the bob item.

[[code]]
configitem<ipaddress> bob(configuration, "other stuff", "bob", "0", LOOPBACK);
[[code]]

If bob is not present on teh command line the configuration file setting or the default value will be used instead. To detect a missing required parameter just leave the configuration file names blank and use an invalid default value.

----

And that covers using the ConfigLib. if you have any more questions post them in the [[http://sourceforge.net/forum/forum.php?forum_id=798261|help forum]].