+--------------------------------------------------------------------+
|                                                                    |
|       ctlParameter                                                 |
|               A library for getting parameter value from           |
|                                          configuration information |
|                                                                    |
|               Copyright (C) 2009  Madoka Nakakusa                  |
|                                                                    |
+--------------------------------------------------------------------+



■概要
  本ライブラリは、設定ファイル、環境変数、char[]に記述した設定情報を、容易に
  アクセスするための機能を提供するC言語用関数群になります。



■特徴
  ・設定項目名（パラメータ名）と設定値が1対1で定義されている単純な設定情報から
    設定値を取得する
  ・パラグラム概念（スタンザ）を利用することが可能
  ・取得した設定値を編集する機能を利用可能（トリム処理、コメント除去）
  ・設定ファイルから定義された設定情報から取得することが可能
  ・char[]にハードコーディングした文字列から取得することが可能
  ・環境変数を使用し、設定値を定義ならびに上書き定義することが可能
  ・また、その設定値を取得することが可能



■ライブラリの使い方
  - コンパイルおよびヘッダファイル
    "libgetparameter.a"と"getparameter.h"を使ってコンパイル
    (サンプルのMakefile参照)

  - 基本関数(最低限の利用方法は、サンプルプログラム参照)
    struct configList *initConfigList()
      初期化処理を行う。本機能を利用する場合、必ず実行する必要がある。

    int freeConfigList(struct configList *cfgList)
      メモリ領域の開放処理を行う。使用後に必ず実行する必要がある。

    int readConfigFile(int fd, struct configList *cfgList)
    int readConfigChar(char *val, struct configList *cfgList)
      ファイル、char[]型に記述されたパラメータ定義からパラメータリストを作成
      する。処理に成功した場合は、0を返し、失敗した場合は、-1を返す。

    int getParameterValue(char *result, char *paragramName,
                  char *parameterName, int MODE, struct configList *cfgList)
    int getnParameterValue(char *result, char *paragramName,
                  char *parameterName, int MODE, ...)
      paragramNameおよびparameterNameに指定された設定値をresultに返す。パラグラ
      ムが必要ない場合は、NULLを指定する。getnParameterValueは複数のconfigList
      構造体を指定でき、指定した順番にパラメータを検索し、最初に見つかった設定
      値をresultに返す。resultのサイズは、PARAMETER_VALUE_MAX + 1以上であること
      を推奨する。設定値を取得した場合は0を返し、パラメータが存在しなかった場合
      は1を返し、エラーが発生した場合は-1を返す。
      また、MODEにより、設定値の取得方法を変更できる（orで連結可能）。
        NORMAL_PARAMETER    : 取得した設定値に対して次の処理を順番に行い、その
                              結果をresultに返す。
                              ・環境変数に対象パラメータを取得
                              ・指定したパラグラムにパラメータが設定されて
                                いない場合defaultパラグラムからの取得を行う
                              ・""で括られている場合は、その中の文字列を取得
                              ・設定値に#が含まれている場合は、それ以降を削除
                              ・トリム処理（文字列前後の空白を削除）
        NO_ENV_PARAMETER    : 環境変数でパラメータが指定されていても無視する
        NO_GET_DEF_PARAGRAM : 指定したパラグラムにパラメータが設定されていない
                              場合でも、defaultパラグラムの値を取得しない
        NO_EXTRACT_STRING   : ""で括られていても抽出処理を行わない
        NO_DEL_COMMENT      : 文字列に#が含まれていても、削除処理を行わない
        NO_TRIMMING         : トリム処理を行わない
        NO_PROCESSING       : 設定値の文字列操作を行わない。NO_EXTRACT_STRING |
                               NO_DEL_COMMENT | NO_TRIMMINGと等価。

    char **getParagramList(struct configList *cfgList)
      指定したconfigList構造体に設定されているパラグラムの一覧を返す。
      getParagramList[0]には、必ずdefaultが設定される。本関数はmallocにてメモリ
      領域を確保しているため、使用後はfreeする必要がある。処理に失敗した場合は
      NULLを返す。

    char *convConfig2Char(strcut configList *cfgList)
      configListに設定されている設定情報を文字列に変換する。本関数はmallocにて
      メモリ領域を確保しているため、使用後はfreeする必要がある。処理に失敗した
      場合はNULLを返す。



■設定ファイル・環境変数
  - 設定ファイルによるパラメータの定義
    --------------------------------------------------
    # コメント1                  <- #が先頭にある場合は、コメント行とする
    設定項目名1=設定値           <- 設定項目名の前と"="の間に空白を挿入すること
    設定項目名2=設定値              が可能
    パラグラム名A:               <- パラグラム名の前と":"の間には空白はNG
    	設定項目名A1=設定値      <- パラグラム内の設定項目名には、先頭に必ず
    	設定項目名A2=設定値         タブを挿入しなければならない
                                 <- パラグラムの終了は空行
    # コメント2
    default:                     <- パラメータ名"default"は、他パラメータの
    	設定項目名B1=設定値         既定値として機能する
    	設定項目名B2=設定値
    
    設定項目名3=設定値           <- パラグラムの終了後であれば、パラグラムなし
                                    のパラメータを定義できる。上記の空行が無い
                                    場合、本定義は無視される
    --------------------------------------------------

  - ハードコーディングによるパラメータの定義
    あらかじめデフォルト値を定義しておきたい場合に利用する。定義の方法は、
    改行を追加する以外は、「設定ファイル」と同じ。
    --------------------------------------------------
    char *defineParameter = 
                    {#コメント1\n}
                    {設定項目名1=設定値\n}
                    {設定項目名2=設定値\n}
                    {パラグラム名A:\n}
                    {	設定項目名A1=設定値\n}
                    {	設定項目名A2=設定値\n}
                    {\n}
                    {#コメント2\n}
                    {default:\n}
                    {	設定項目名B1=設定値\n}
                    {	設定項目名B2=設定値\n}
                    {\n}
                    {設定項目名3=設定値\n};
    --------------------------------------------------

  - 環境変数によるパラメータの定義
    「設定ファイル」や「ハードコーディング」による定義の他に、環境変数を使って
    パラメータの定義をすることができる。環境変数名の規約は以下の通り。
    ・PARAM_パラメータ名=設定値
    ・PARAM_パラグラム名_パラメータ名=設定値
    例１：設定項目名が"BASE_DIRECTORY"で、その設定値が"/opt/app"の場合
    --------------------------------------------------
    $ export PARAM_BASE_DIRECTORY=/opt/app
    $ echo $PARAM_BASE_DIRECTORY
    /opt/app
    $
    --------------------------------------------------
    例２："operator"パラグラムには、"PASSWORD_AGE"と"PASSWORD_MIN"の設定項目
          があり、それぞれの設定値が"90 days"と"8"の場合
    --------------------------------------------------
    $ export PARAM_operator.PASSWORD_AGE="90 days"
    $ export PARAM_operator.PASSWORD_MIN=8
    $ echo $PARAM_operator.PASSWORD_AGE
    90 days
    $ echo $PARAM_operator.PASSWORD_MIN
    8
    $
    --------------------------------------------------
    この機能を使うことにより、一時的なパラメータ定義の設定や変更を行うことが
    できる。また、隠しパラメータの変更を行うなどの用途に利用できる。

  - 利用可能な文字および最大文字数
    パラグラム名：大文字・小文字・数字・_(アンダスコア)、32文字
    パラメータ名：大文字・小文字・数字、32文字
    設定値：すべての文字、5120文字
    ※最大文字数を超えた場合は、切り捨てた文字列が利用される

  - 同名のパラメータ名の取り扱い
    同名のパラメータ名が複数指定されていた場合は、最後に定義された設定値が有効
    となる。同名のパラグラム名かつ同名のパラメータ名が複数指定されていた場合は
    同様に最後に定義された設定値が有効となる。



■動作確認環境
  - Fedora 9 i686/gcc 4.3.0



■著作権および配布・改造について
  このソフトウェアおよびドキュメントの著作権は「仲艸　まどか」が保持し、
  GNU GENERAL PUBLIC LICENSE Version 2 に従って配布されています。
  配布、および改造については GPLv2 に従ってください。



■利用者の方へ
  動作確認環境にて単体テストを行っていますが、不具合ならびに機能拡張、改善等が
  ありましたら報告していただけたら幸いです。



■作者への連絡先
  e-mail : m_nakakusa@users.sourceforge.jp



■最新バージョンの在処
  SourceForge.jp
  https://sourceforge.jp/projects/ctlparameter/



---------------------------
Madoka Nakakusa

