# Command line arguments interpretation {#tutorial_dc_args}

@ja

gtool5 には実行プログラムのコマンドライン引数を解析する
サブルーチンを提供するモジュール dc_args が用意されています.
これを用いるとプログラム実行時のオプション指定,
ヘルプメッセージの表示などが可能になります.

例として,
@ref tutorial_dc_types "Fortran 90/95 汎用モジュール: 種別型パラメタの提供"
で用いたサンプルプログラムに
コマンドライン引数を与えるように修正したプログラムを示します
(ソースコードは dc_args/diffusion_7.f90).
**太字** が dc_args に関係している箇所です.
関連して必要となる
dc_types,
dc_string,
dc_message
モジュールで提供されているデータ型とサブルーチンも use 文で参照しています.

@endja
@en

dc_args module of gtool5
provides subroutines for interpretation of command line arguments.
By using dc_args, run time options and help message can be specified
to user's program.

For example, a sample program using the dc_args module
(dc_args/diffusion_7.f90) is shown here, which is
modified from diffusion_3.f90 in
@ref tutorial_dc_types "Fortran 90/95 general-purpose modules: Type parameter specification".
Statements with **bold font** are associated with the dc_args module.

@enden

@ja
## プログラム全体
@endja
@en
## Complete program
@enden

@include dc_args/diffusion_7.f90

@ja
## dc_args の使用箇所

### モジュールの読み込み
@endja
@en
## dc_args related code

### Module imports
@enden

@snippet dc_args/diffusion_7.f90 dc_args_use

@ja
### 変数宣言
@endja
@en
### Variable declarations
@enden

@snippet dc_args/diffusion_7.f90 dc_args_vars

@ja
### 初期化・オプション設定・終了処理
@endja
@en
### Initialization, option setting, and finalization
@enden

@snippet dc_args/diffusion_7.f90 dc_args_calls

@ja
## 実行方法

このプログラムではコマンドラインオプションで計算ステップ数を指定できる
ようにしています. また, デバッグモードでの実行
(@ref tutorial_dc_trace "Fortran90 汎用ライブラリ: デバッグ補助" 参照),
ヘルプメッセージの出力もオプションで指定できます.

計算ステップ数の指定はプログラム実行時に

    $ ./a.out -S=<計算ステップ数>

または

    $ ./a.out --step=<計算ステップ数>

とします.

デバッグモードで実行する場合

    $ ./a.out -D

とします. デバッグメッセージはデフォルトでは標準出力に出力されます.

ヘルプメッセージの出力は

    $ ./a.out -H

とします. このときプログラムは以下のようなヘルプメッセージを表示
して終了します.

    Options::
     -S=VAL, --step=VAL
         Specify time step (nt) [default value is 200].

     -D=VAL, --debug=VAL
         call dc_trace#SetDebug (display a lot of messages for debug).
         VAL is unit number (default is standard output)

     -h=VAL, -H=VAL, --help=VAL
         display this help and exit. VAL is unit number (default is
         standard output)

@endja
@en
## Execution

In this program, the time step number can be specified by command
line argument.
Execution in debug mode
(@ref tutorial_dc_trace "Fortran 90/95 general-purpose modules: Debug support"),
and help message can be also specified.

The time step number is specified as follows

    $ ./a.out -S=<time step number>

or,

    $ ./a.out --step=<time step number>

Debug option is specified as follows.

    $ ./a.out -D

Debug messages are dumped to standard out.

Help message can be displayed as follows.

    $ ./a.out -H

If the '-H' is given, following messages are displayed.

    Options::
     -S=VAL, --step=VAL
         Specify time step (nt) [default value is 200].

     -D=VAL, --debug=VAL
         call dc_trace#SetDebug (display a lot of messages for debug).
         VAL is unit number (default is standard output)

     -h=VAL, -H=VAL, --help=VAL
         display this help and exit. VAL is unit number (default is
         standard output)

@enden

@ja
## サブルーチンの説明

以下では dc_args モジュールのサブルーチンが行っていることを大まかに説明します.
ここで扱っていないサブルーチンの機能を含むより詳しい説明は
dc_args のリファレンスマニュアルを参照してください.

**use dc_args**

モジュールの使用を宣言します. Fortran90 メインプログラムの先頭にいれ
ましょう. ここでは only 文を用いて必要なデータ型とサブルーチンだけを参照します.

**type(ARGS)**

構造型 ARGS 変数の宣言文です. 引数情報は構造型 ARGS 変数に格納されます.

**character(STRING)**

種別型パラメタ STRING を用いた文字変数の宣言文です. 引数の値を格納する
文字型変数の種別型パラメタは, STRING にする必要があります.
種別型パラメタ STRING は dc_types モジュールで提供されているので,
メインプログラムの先頭部分で, use 文を用いて参照します.

**DCArgsOpen(arg)**

構造型 ARGS 変数 arg の初期化を行います.

**DCArgsOption(arg, options, flag, [value], [help])**

オプション情報の登録と取得を行います. 引数の意味は以下の通りです.

- **arg** は第二引数以下のオプション情報を格納する構造型 ARGS
  変数を指定する引数です.
- **options** はオプション文字列を指定する引数です.
  上記の例では '-S' と '--step' の二通りで与えられるようにしています
  (StoA は dc_string モジュールで用意されている型変換関数です).
- **flag** はオプションが与えられているか否かを判定するための
  論理型変数を指定する引数です.
  **options** がコマンドライン引数に与えられると .true. を返し,
  そうでない場合は .false. を返します.
- **[value]** はオプションに値が指定されていた場合にその値を格納する
  変数を指定する引数です.
- **[help]** はオプションに関するヘルプメッセージを指定する引数です.
  サブルーチン Help を用いた際にこのメッセージが出力されます.

**DCArgsDebug(arg)**

デバッグオプション -D および --debug を自動設定します.

**DCArgsHelp(arg)**

ヘルプオプション -H および --help を自動設定します.
このサブルーチンを使う場合は事前に Option, Debug サブルーチンを呼ぶ
必要があります.

**DCArgsStrict(arg, [severe])**

オプションに与えられた文字列が Option サブルーチンで設定されていない
場合に警告を返します. 引数 **[severe]** を .true. にしておくと
エラーを返しプログラムを強制終了します.
このサブルーチンを使う場合は事前に Option, Debug, Help サブルーチンを
呼ぶ必要があります.

**DCArgsClose(arg)**

構造型 ARGS 変数 arg の使用を終了します.

@endja
@en
## Subroutine descriptions

Summary of dc_args module and its subroutines used in the sample
program are as follows. In detail, please see the dc_args
reference manual.

**use dc_args**

Access dc_args module. This statement is located at the beginning
of main program. In this case, ONLY option is used.

**type(ARGS)**

Definition of ARGS derived data type variable.
Information of command line arguments is stored this type variable.

**character(STRING)**

Definition of character literal constant with STRING type parameter.
The type parameter of character literal constant which store
the value of command line arguments must be STRING.
The type parameter STRING is provided by dc_types module.
This module is accessed at the beginning of main program.

**DCArgsOpen(arg)**

Initialize ARGS derived data type variable 'arg'.

**DCArgsOption(arg, options, flag, [value], [help])**

Define command line options. Descriptions of each argument are as follows.

- **arg** specifies ARGS derived data type variable which store
  information of command line arguments.
- **options** specifies string of command line option.
  In this case, '-S' and '--step' are specified
  (StoA is type translation function provided by dc_string module).
- **flag** is logical argument for judgement whether command line option
  is specified or not.
  If **options** is specified as command line option,
  return value of **flag** is '.true.', If not, return value
  **flag** is '.false.'
- **[value]** is optional argument which store the value of
  command line option.
- **[help]** is optional argument which specifies help message.
  This message is displayed when -H or --help options are specified.

**DCArgsDebug(arg)**

Set debug option (-D/--debug) automatically.

**DCArgsHelp(arg)**

Set help option (-H/--help) automatically.
To call this subroutine, Option and Debug subroutine must be
called previously.

**DCArgsStrict(arg, [severe])**

Show warning message if specified command line argument is not defined
by Option subroutine.
If the argument **[severe]** is '.true.' program is terminated.
To call this subroutine, Option, Debug and Help subroutine must be
called previously.

**DCArgsClose(arg)**

Finalize ARGS derived data type variable 'arg'.

@enden