程式執行參數處理函式庫：Boost Program Options（1/N）

原帖：http://viml.nchc.org.tw/blog/paper_info.php?CLASS_ID=1&SUB_ID=1&PAPER_ID=361

一般程式寫得大一點、或是需要比較有彈性，通常都需要在程式執行的時候，從外部讀取一些參數，來做為內部的設定值。一般來說，比較常見的方法，大概就是直接透過命令提示字元（command line）來下參數，或是透過讀取設定檔（例如 ini 檔）來讀取設定值。

以前者來說，雖然 C++ 的主函式、main() 本來就有 argc 和 argv 兩個參數，可以用來處理命令提示字元輸入的參數，但是實際上要去自己根據需求，一個一個來處理，其實當參數多的時候，還是滿麻的。而 Boost C++ Libraries 所提供的 program options 這個函式庫（官方文件），基本上就是一個可以用更結構化、更有系統地來處理這些參數的函式庫。

要使用 Boost Program Options 時，需要 include 他的 header 檔：

#include 

而所有的相關函式、物件，也都在 boost::program_options 這個 namespace 下。他基本的使用，大致上就是：

#include 
#include 
using namespace std;

#include namespace BPO = boost::program_options;

int main( int argc , char ** argv ) { int iValInt;

// setup program options description BPO:: options_description bOptions( "Test Options" ); bOptions.add_options() ( "help" , "Produce help message" ) ( "vint" , BPO::value< int >(), "int value" ) ;

// parse program options BPO:: variables_map mVMap; BPO::store( BPO::parse_command_line( argc , argv , bOptions ), mVMap ); BPO::notify( mVMap );

// output help message if required if ( mVMap.count( "help" ) ) { cout << bOptions << endl; return 1; } // process other option if ( mVMap.count( "vint" ) ) { iValInt = mVMap[ "vint" ].as< int >(); cout << "Int: " << iValInt << endl; }

}

在這個範例程式，執行時可以接受「--help」、「--vint」這兩個參數，其中，「--vint」後面需要給一個整數值；下面就是一個執行的範例：

C:\test.exe --vint 10
Int: 10

而「--help」則會把 Boost Program Options 產生的參數說明列印出來，下面就是執行 test.exe --help 後所輸出的說明：

Test Options:
  --help                Produce help message
  --vint arg            int value

---

接下來，來看程式碼的部分。

在上面的程式碼裡，可以看到有四個區段有加上底色強化。其中最前面的黃底的部分，算是使用 Boost Program Options 的前置步驟，基本上就是 include 必要的 header 檔、boost/program_options.hpp 這個檔案。

不過，由於他的相關功能都在 boost::program_options 這個很長的 namespace 下，所以為了簡化之後的程式，所以這邊是透過 namespace alias 的方法（MSDN），把它簡化成 BPO；如果完全不想加 namespace 的話，也可以使用「using namespace boost::program_options;」來做處理。

而接下來三個區段，則是 Boost Program Options 在使用上的三個主要步驟：

1. 設定選項的描述（options decription）、定義有哪些參數
2. 根據來源（這邊是根據 command line 的參數，argc 和 argv）來做分析，並把分析結果儲存在 map 裡
3. 處理分析完成、儲存在 map 裡的資料

下面就大概來說明一下這幾的部分：

---

設定選項的描述

Boost Program Options 用來定義有哪些參數，主要是 options_description 這個類別（官方文件）。

options_description 的物件可以透過 ostream 做輸出，他會把設定好的選項描述、做適當的排版後輸出，這也是使用 Boost Program Options 的一大好處！也因此，在建立 options_description 的物件的時候（這邊是 bOptions），有需要的話可以加上一個字串，作為這個選項描述的最基本的說明，在這邊 Heresy 是給他「Test Options」。

而要加入新的選項定義的時候，基本上是使用 add_options() 這個函式、產生一個 options_description_easy_init 的 callable object（官方文件），它的目的就是用來快速地設定參數的描述用的；透過這個物件，可以透過類似呼叫函式的方法（operator()），來做快速的處理。

在這邊的範例裡，Heresy 是在呼叫 add_options() 後，用了兩行、以兩種不同的設定方法，加入了兩個選項定義，分別是 help 以及 vint；不過要注意的是，這其實算是同一行指令，中間都沒有結束的分號（;），是等到所有參數定義都設定完，才算完成整的指令的。

bOptions.add_options()
  ( "help",    "Produce help message" )
  ( "vint",    BPO::value<int>(), "int value" );

首先，help 這個選項的部分，可以看到很簡單，就是兩個字串；第一個字串就是選項的名字、也就是下命令的時候，要給的字串（前面要加上「--」）；而第二個字串，則就是這個參數的說明，他會在把 options_description 輸出時，作為選項的說明文字來顯示，所以如果要讓使用者了解這個參數的意義、使用方法的話，就需要在這邊做說明。

而第二個 vint 的選設定項，可以看到和 help 相比，中間多了一個「BPO::value<int>()」，value<>() 這個 template function 是用來指定 --vint 這個選項所需要的值的型別，在這邊是指定為 int，也就是說 --vint 後面要跟著指定一個整數的值。而指定的方法，可以空一個空白後，直接給值，也可以用「=」來做指定；也就是下面兩種方法，都是可以的：

--vint 10
--vint=10

不過要注意的是，如果給的值的形式不對（例如給他一個字串）、或是沒有給值的話，Boost Program Options 是會丟出 exception，在沒有特別處理的情況下，是會讓程式執行錯誤的。

這邊基本上算是寫了兩種不同的選項的設定方法。而實際上，如果有使用 value<> 來做型別的指定的話，其實是還有更多、更方便的功能的！不過這部分就等下一篇文章再寫吧～

---

分析、儲存選項

在設定完所有的選項的描述後，接下來就是要根據參數的來源，來進行分析了～這段程式碼如下：

BPO::variables_map mVMap;
BPO::store( BPO::parse_command_line( argc, argv, bOptions ), mVMap );
BPO::notify( mVMap );

Boost Program Options 有提供幾種不同的解析器（parser），可以根據不同的資料來源，進行分析；而在這邊 Heresy 所使用的，是 command line 的參數，所以就先使用最簡單的，parse_command_line() 這個函式了。它的使用方法很簡單，只要把 main() 的 argc 和 argv，以及前面所定義好的選項描述、bOptions 當作引數傳給這個函式就可以了～而分析完成後，他會回傳一個型別是 basic_parsed_options 的物件，裡面就是分析完後的結果。

不過在這邊，並不是要直接去使用這個物件，而是要先透過 store() 這個函式，把分析完的結果，儲存到型別為 variables_map 的物件（mVMap），然後再來做操作。

最後，則要記得再透過 notify() 這個函式，來讓 mVMap 裡的選項做最後的處理。

---

處理分析完成資料

當分析完成後，解下來就是要處理這些分析好的結果了。而這邊用來存取的，都是前面處理好的、型別為 variables_map 的物件（mVMap）（官方文件）。他基本上是繼承自 STL map 的一個類別，所以架構上就是一個 key、對應到一個 value 的形式，而本來 std::map 有的功能，他也都可以使用。

而一般的使用的話，基本上都是先透過 count() 這個函式，來確認這個選項的值是否存在；以上面的範例裡的 help 來說，就是下面的寫法：

if( mVMap.count( "help" ) )
{
  cout << bOptions << endl;
  return 1;
}

這樣的寫法，實際上就是去判斷，當 mVMap 裡面 help 這個 key 的數量不等於 0 的時候（也就是至少有一個），就去把 bOptions 透過 cout 輸出，顯示使用說明給使用者看。

而如果是要取得值呢？則可以看 vint 的部分：

if( mVMap.count( "vint" ) )
{
  iValInt = mVMap["vint"].as<int>();
  cout << "Int: " << iValInt << endl;
}

一樣，先透過 count() 來確認有指定 vint 這個選項的值，然後再透過 operator[] 來把它拿出來；不過取出來的物件是一種型別是 variable_value 的物件（官方文件），所以還需要透過 as<> 這個 template 函式，來把它做轉換成我們需要的型別來使用，像這邊因為是整數，所以就是 as() 了～

---

Boost Program Options 的基本使用大概就先到這裡了。實際上，他還有很多更方便的功能可以用的！像是每個選項實際上都可以設定成允許多次設定、甚至有預設值，而選項的描述也可以用分類來處理…不過礙於篇幅問題，就拆到之後再寫吧～