Boost Program Options Add Options Syntax

Question

I am writing a program that uses Boost's Program Options library and I noticed the following syntax that has haunted me since I saw it:

desc.add_options()
        ("help","produce help message")
        ( /* other flag, value, description pairs here */)
;

I see that in the header, operator() is overridden, but I'm not sure how that allows this to be syntactically correct.

Secondly, is there any advantage to this syntax, compared with just calling add_options() multiple times (besides showing off the fact that you can manipulate syntax like this)?

Answer 1

The add_options member function returns an object of type options_description_easy_init. The latter has operator() overloaded to return a reference to itself. This allows you to chain the calls as you've shown in the snippet.

The difference between chaining the calls and calling add_options several times is that in the former case a single instance of options_description_easy_init is created and each time you invoke operator() on it, it adds the options to the owner (options_description). If you were to call add_options multiple times each call would create a new instance of options_description_easy_init.

Answer 2

The advantage question is subjective, but in this case it's brevity.

Compare this from one of my home projects:

("help,h", "Generate this help message")
("output-file,o", po::value<std::string>(), "Output filename. Required.")
("tangent,t", "Generate/load tangent-space basis.")
("collada-output,c", "Write a Collada file, rather than our mesh XML format.")
("arrays,a", "Write arrays instead of indexed verts. Cannot combine with Collada writing.")
("flip-tangent,f", "Change the tangent-space basis matrix's handedness. Negates bitangent.")
("map", po::value<std::string>(), "Map filename. Defaults to the ColladaConv directory's 'stdmap.txt' file.")
("vao", po::value<std::vector<std::string> >(), "Sequence of mappings, of the form:\n"
        "Name # # # #\n"
        "\n"
        "Each # is an attribute index to use for this VAO.\n"
        "Each VAO name must be unique; you cannot use the same VAO in the same place.")

to this:

visible.add_options()("help,h", "Generate this help message")
visible.add_options()("output-file,o", po::value<std::string>(), "Output filename. Required.")
visible.add_options()("tangent,t", "Generate/load tangent-space basis.");
visible.add_options()("collada-output,c", "Write a Collada file, rather than our mesh XML format.");
visible.add_options()("arrays,a", "Write arrays instead of indexed verts. Cannot combine with Collada writing.");
visible.add_options()("flip-tangent,f", "Change the tangent-space basis matrix's handedness. Negates bitangent.");
visible.add_options()("map", po::value<std::string>(), "Map filename. Defaults to the ColladaConv directory's 'stdmap.txt' file.");
visible.add_options()("vao", po::value<std::vector<std::string> >(), "Sequence of mappings, of the form:\n"
        "Name # # # #\n"
        "\n"
        "Each # is an attribute index to use for this VAO.\n"
        "Each VAO name must be unique; you cannot use the same VAO in the same place.");

Line length matters. And not having to have visible.add_options() in front of everything makes it easier to read.