程式執行參數處理函式庫:Boost Program Options(1/N)

| | 0 Comments| 13:56
Categories:

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

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

要使用 Boost Program Options 時,需要 include 他的 header 檔:

#include <boost/program_options.hpp>

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

#include <iostream>
#include <string>
using namespace std;

#include <boost/program_options.hpp>
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()argcargv,以及前面所定義好的選項描述、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<int>() 了~


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

Leave a Reply

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *