Boost.Program_options – Introduction and Tutorial

最近因為需要一些自動化的程式看了 Boost.Program_options 這個 library ，這系列文章主要內容都是翻譯自 Boost 1.39.0 Doc 裡頭，希望還有點時間可以加上一些 trace 的心得和紀錄，希望沒有誤人子弟、教壞囝仔大小、對大家有幫助～

Vocabulary

1. Program options, options
2. Config file
3. Command line
4. pair. (name, value)

Introduction

Boost.Program_options 是個可以讓程式設計師獲得 program options 的函式庫，什麼是 program options 呢？就是那種由使用者提供，可能是 command line 或是 config file 的 (name, value) 組合（pairs）。

那為什麼需要使用 Boost.Program_options 呢？為什麼說它比我們依靠直覺寫出來的程式碼還好呢？

• 簡單。Boost.Program_options 很小、提供的新增 options 的語法也簡單。像是自動化的 option value 的型別轉換（type conversion）、變數存放。
• 比較好的錯誤回報。 當分析（parsing）command line input 出錯時，Boost.Program_options 會回報所有的錯誤，但 hand-written code 可能會誤判。
• Options 可以來自任何地方。當使用者可能對你的程式只能藉由 command line 輸入感到不滿，妳/你很快就會用到 config file 或是 environment variables 了。這些都可以幾乎無痛得透過 Boost.Program_options 來擴充。

Tutorial

在這個 section ，我們將從最簡單的地方開始，之後逐漸知道大部分 Boost.Program_options 的 usage scenarios 。這部份的文件都只有部份的、重要的程式碼，完整的範例可以在：

BOOST_ROOT/libs/program_options/example

資料夾找到。此外整個範例，都假設下面的 namesapce alias 是有效的！

namespace po = boost::program_options

Getting Started

第一個也可能是最簡單的一個範例是：

處理兩個 options

下面是程式碼部份（完整程式可以在 example/first.cpp 找到）

// Declare the supported options.
po::options_description desc("Allowed options");
desc.add_options()
    ("help", "produce help message")
    ("compression", po::value<int>(), "set compression level")
;

一開始的地方宣告了一個 options_descriptions 來存放允許的 options。呼叫 options_description class 的 add_options method 會回傳一個提供了 operator() 操作的 proxy object 。呼叫 operator() 就是宣告了 options 。參數分別是：

(option name, information about value, option description)

這個範例裡頭，第一個 option 沒有 value，第二個 options 有一個型別是 int 的 value 。

po::variables_map vm;
po::store(po::parse_command_line(ac, av, desc), vm);
po::notify(vm);    

之後，宣告一個型別為 variables_map 的 object -- vm。variables_map 是用來存放任意型別的 value 。接著呼叫：

1. store
2. parse_command_line
3. notify

去讓 vm 獲得所有 command line 來的 value。

if (vm.count("help")) {
    cout << desc << "\n";
    return 1;
}

if (vm.count("compression")) {
    cout << "Compression level was set to " 
 << vm["compression"].as<int>() << ".\n";
} else {
    cout << "Compression level was not set.\n";
}

最後我們可以任意地使用 options 了，variable_map 提供了像是 std::map 的操作，除了取得 value 時，必須使用 as method外。（要是你不小心誤用了 as 中的型別參數，使得 as 參數想取出的型別和實際不合時，會出一個 exception）

試著 compile 你的程式吧，下面是個範例：

$bin/gcc/debug/first
Compression level was not set.
$bin/gcc/debug/first --help
Allowed options:
  --help                 : produce help message
  --compression arg      : set compression level
$bin/gcc/debug/first --compression 10
Compression level was set to 10.

Reference

1. Boost 1.39.0 Doc: Chapter 13. Boost.Program_options

See Also

1. Boost.Program_options – Option Details and Multiple Sources