map型プロパティ

概要

map型プロパティとは、"DBFluteプロパティ(dfprop)" や "ReplaceSchemaのDataプロパティ(dataprop)" など ほとんどのプロパティで利用されている記述形式 です。単なる key-value形式 ではなく、など map型やlist型のネストした要素を簡単に記述できる ことが主な特徴です。

記述仕様

map型の基本

map: で始まり、{ ... } で囲われた中が key-value形式の記述となります。key と value の関連付け記号が = (イコール)、要素のデリミタが ; (セミコロン)となります。

e.g. map型の基本形式 @mapprop
map:{ [KEY] = [VALUE] ; [KEY] = [VALUE] ; ... }

コメント

"#" よりも右側の改行まではコメントになります。

e.g. map型の基本形式 @mapprop
map:{
    # comment here
    [KEY] = [VALUE]
    ; [KEY] = [VALUE] # comment here too

定義値のトリム

定義値(KEYもVALUEも)は全てトリムされます。

e.g. map型の基本形式 @mapprop
map:{AAA= BBB   ; CCC =    DDD  }
# {AAA=BBB;CCC=DDD} と同じ

定義値の中の空白や改行

定義値の中の空白は保持されます。但し、改行は保持されません のでご注意下さい。

e.g. map型の基本形式 @mapprop
map:{AAA= BB
B   ; CCC =    DD D  }
# {AAA=BBB;CCC=DD D} と同じ
# 値の中の改行は保持されない
# 値の中の空白は保持される

map型のネスト

map型プロパティをネストして記述することが可能です。

e.g. map型にmap型をネスト @mapprop
map:{ [KEY] = map:{ [KEY] = [VALUE] ; ... } ; [KEY] = [VALUE] ; ... }

list型のネスト

list型プロパティをネストして記述することが可能です。

e.g. map型にlist型をネスト @mapprop
map:{ [KEY] = list:{ [ELEMENT] ; [ELEMENT] ; ... } ; [KEY] = [VALUE] ; ... }

空要素

空要素(空文字もしくは空白のみ)は、存在しない要素として扱われます。

e.g. 空要素 @mapprop
map:{ ; [KEY] = [VALUE] ; [KEY] = [VALUE] ; ; [KEY] = [VALUE] }
# 要素数は三つ

追加したときやコピーしたときなど、"デリミタが足りなくなってしまう" というようなケアレスミスを無くすために、この空要素は良く利用されます。例えば、"先頭の要素の前にもデリミタを付ける" ことが多いです(DBFluteプロパティはほとんどそうなっています)。

e.g. 先頭の要素の前にもデリミタを付ける(空要素の有効利用) @mapprop
map:{
    ; database = h2
    ; targetLanguage = java
    ; targetContainer = seasar
    ...
}

空行

定義値は全てトリムされるので、同時に空行もなかったことになります。

e.g. 空行 @mapprop
map:{

[KEY] = [VALUE]
; [KEY] = [VALUE]

}
# 要素数は二つ

制御文字のエスケープ

制御文字 "{ } ; =" を、バックスラッシュでエスケープすることができます。@since 1.0.4B

e.g. "ba;r" というvalue値を定義 @mapprop
map:{
    foo = ba\;r
}

エスケープ文字 "バックスラッシュ" 自体は、そのまま値として利用できます。 つまり、エスケープ文字をエスケープする必要はありません。(制御文字の直前のバックスラッシュは必ずエスケープ文字として認識されます)

e.g. "ba\r" というvalue値を定義 @mapprop
map:{
    foo = ba\r
}
e.g. "ba\}r" というvalue値を定義 @mapprop
map:{
    foo = ba\\}r
}

ただし、この仕様だと完璧なエスケープができません。例えば、制御文字としての括弧閉じ "}" の直前に、値としてのバックスラッシュを定義してしまった場合、そのバックスラッシュはエスケープ文字と判定されてしまって、 括弧閉じが制御文字ではなく単なる値になってしまいます。その場合は、文字の間に空白を一つ空けて定義することで回避できます。

e.g. "qux\" というvalue値を定義 @mapprop
map:{
    # qux\} -> qux\ }
    foo = map:{ bar = qux\ }
}

互換性と利便性のためのエスケープ仕様

通常は、エスケープ文字はエスケープ文字を重ねてエスケープさせるものです。 ですが、ここでは単品のエスケープ文字は単なる値として定義できるようにしています。 それがゆえに、完璧なエスケープにはならないケースがあります。

完璧なエスケープの仕様にすると、互換性を失ってしまう可能性があります。 バックスラッシュを値として普通に使っている場合です。それが大きな理由の一つ。 もう一つは、めったにありえない状況を想定して、バックスラッシュを簡易に記述するやり方を捨てるのは、 費用対効果があまりないと考えたからです。

制御文字の前で空白を一つあければいいだけですし、Exampleでは空白を空けているパターンがほとんどですし、 HistoryHTMLのdiffmapは空白をあけて生成していますので、実質的な問題にはならないと思われます。 それゆえ、このような仕様となっています。

ちなみに、HistoryHTMLのdiffmapでは、エスケープされたものが出力されます。 差分データの値に制御文字が含まれていても特に問題なく動作します。@since 1.0.4B

1.0.4Bより前では

残念ながらできません。 なので定義値に "=" や ";" などを含めることは基本的にできません。

ただし、一部DBFluteプロパティでは工夫して指定できるようにしている箇所もあります。 例えば、databaseInfoMap.dfprop では、接続URLの接続プロパティのデリミタとして ";" を指定できるようにしています。

また、mapのvalue値では、"="は指定できます。e.g. map:{ foo = bar=qux }

読み込みライブラリ

このmap型プロパティ(ファイル)の読み込みライブラリが、DBFluteランタイム にあります。通常、利用することはあまりないかと思いますが、どうしても必要なときは利用することができます。

クラス名
DfPropFile @since 0.9.7.1
(旧)クラス名
DfPropFileReader @until 0.9.7.0

但し、このクラスは内部クラスとして予告なく変更される可能性があるのでご注意下さい。

さらに内部的な話(通常、不要な話)

読み込みライブラリの先には、パーサーライブラリがあります。このパーサーライブラリは、既に読み込まれた文字列を解析するだけのもので、 厳密には、map型プロパティの仕様とそのパーサーライブラリの仕様は完全に一致はしません。例えば、"定義値の中の改行を保持しない" という仕様は、読み込みライブラリの仕様であって、パーサーライブラリの仕様ではありません。また、"#" をコメントとする仕様は、読み込みライブラリの仕様であって、パーサーライブラリの仕様ではありません。 もし、内部の世界にまで入り込むのであれば、この辺をご注意下さい。