はじめに
次の設定の解説は空白設定にしようと思っていたが、項目が150項目もある。もはや、ちょちょっと解説するには苦痛なレベルだ。なので、空白設定はとりあえず飛ばそうと思う。
で、今回の設定の解説は、アラインメント設定についてだある。インデントとほとんど同じだけど、まぁもう少し細かな、行送りの時にはどうするとか、operatorキーワードに対してはどう位置揃えするとか、そういうことまで設定させてしまう。
あまりにも細かすぎて、ちょっとびっくりすると思うが、前回のインデントの設定も相当に細かいので、徐々に細かさに慣れてくる。しかし、uncrustifyというツールはパワフルだけど、誰も詳しく設定項目を解説してないのは何でだろうと思う。どうやら、UncrustifyXというツールが説明とかも付いているし、インタラクティブにUncrustifyの設定もできる便利ツールらしい。まだ試してはいないが、いつか試してみよう。
また、このアラインメントに関しては、「ラインスパン (Span)」、「カラム閾値 (Threshold)」、「カラムギャップ (Gap)」という3つのパラメータが登場する。Uncrustifyのドキュメントには、それぞれ以下のように説明されている。
- ラインスパン
ラインスパンというのは、アラインメントのための基準である。ラインスパンに行数を設定することで、前後何行分を見て位置揃えするかを判断する。これは、空行が間にあったり、カラムが非常に長いトークンが間にあったりする場合に、インテリジェントに位置揃えをしてくれる。単に、スパンとも呼ばれる。 - カラム閾値
カラム閾値というのは、アラインメントのための基準である。カラム閾値に桁数を設定することで、位置揃えされるトークンの左側にあるトークンのカラム差に対する制限幅である。単に、閾値とも呼ばれる。 - カラムギャップ
カラムギャップというのは、アラインメントのための基準である。位置揃えされたトークンの左側に付ける半角空白数である。単に、ギャップとも呼ばれる。
だいたい、それぞれの概念を例示してみる。
span_thresh_gap.cpp
// 4つの変数宣言の位置合わせについて考える。1つだけ、非常に変数型が長い。
{
double d;
int i;
unsign long long ull;
char c;
}
// ラインスパンが1行の場合、直前の行だけを見て位置揃えをする。
{
double d;
int i;
unsigned long long ull;
char c;
}
// ラインスパンが2行の場合、前2行分を見て位置揃えをする。
{
double d;
int i;
unsigned long long ull;
char c;
}
// カラム閾値が2桁の場合、どの変数型(トークン)もカラム差が3文字以上なので、全く揃わない。
// (ラインスパンは1行)
{
double d;
int i;
unsigned long long ull;
char c;
}
// カラム閾値が3桁の場合、unsigned long long 以外のトークンのカラム差は3文字以内なので揃う。
// (ラインスパンは2行: そうでないと、int と char は行が離れていて、位置揃えの関係にならない。)
{
double d;
int i;
unsigned long long ull;
char c;
}
// カラムギャップは非常に簡単だ。
// ギャップを4桁に設定すれば、トークン (ここでは変数名) は少なくとも半角空白4個分のスペースを作る。
{
double d;
int i;
char c;
}
ただし、実際にUncrustifyのフォーマッタがこれらのアラインメントを実行するアルゴリズムはもう少し複雑だ。ユーザの期待した通りに整形してくれない場合もあるだろう。アラインメントの仕様については、リポジトリのdocumentation/配下にある"align-thresholds.txt"を参照してほしい。
アラインメント設定
なお、アラインメントオプションは、左側(行頭)にある半角空白やタブ文字はアライメント対象ではなく、それ以外の半角空白やタブ文字に対するオプションである。
| 項目 | 説明 |
|---|---|
| align_keep_tabs | インデントではないタブ文字を残すか { true, false } |
| align_with_tabs | 整列位置合わせにタブ文字を利用するか { true, false } |
| align_on_tabstop | 整列位置合わせで次のタブストップ位置にするか { true, false } |
| align_number_left | 数値を左揃えにするかどうか (align_struct_init_spanと関連) { true, false } |
| align_func_params | プロトタイプ宣言と関数定義で、変数定義の位置を揃えるかどうか { true, false } |
| align_same_func_call_params | 同じ名前を持つシングルライン関数のパラメータの位置を揃えるかどうか (関数名はすでにそれぞれ位置合わせされていなければならない。) { true, false } |
| align_var_def_star_style | 変数定義でのポインタの'*'の位置揃えの方法 { 0: 型の一部、1: 変数名の一部、2: ダングリング } |
| align_var_def_amp_style | 変数定義での参照の'&'位置揃えの方法 { 0: 型の一部、1: 変数名の一部、2: ダングリング } |
| align_var_def_colon | 構造体ビットフィールドの':'を位置揃えするかどうか { true, false } |
| align_var_def_attribute | 変数名の後の属性を位置揃えするかどうか { true, false } |
| align_var_def_inline | struct/enum/unionのメンバ変数定義を位置揃えするかどうか { true, false } |
| align_var_def_span | 変数定義の位置揃えに対するラインスパン (0: 揃えない) { number } |
| align_var_def_thresh | 変数定義の位置揃えのカラム閾値 (0: 制限無し) { number } |
| align_var_def_gap | 変数定義の位置揃えのカラムギャップ { number } |
| align_assign_span | 代入式の'='の位置揃えをするラインスパン (0: 揃えない) { number } |
| align_assign_thresh | 代入式の'='の位置揃えをするカラム閾値 (0: 制限無し) { number } |
| align_enum_equ_span | enumの'='の位置揃えをするラインスパン (0: 揃えない) { number } |
| align_enum_equ_thresh | enumの'='の位置揃えをするカラム閾値 (0: 制限無し) { number } |
| align_var_struct_span | struct/unionのメンバー定義の位置揃えをするラインスパン (0: 揃えない) { number } |
| align_var_struct_thresh | struct/unionのメンバー定義の位置揃えをするカラム閾値 (0: 制限無し) { number } |
| align_var_struct_gap | struct/unionのメンバー定義のカラムギャップ { number } |
| align_struct_init_span | structのメンバ変数の指定初期化の位置揃えのラインスパン (0: 揃えない) { number } |
| align_typedef_gap | typedefの型とシノニムの間の空白の最小数 { number } |
| align_typedef_span | 一行typedefの位置揃えをするラインスパン (0: 揃えない) { number } |
| align_typedef_func | typedefされた関数とその他typedefの位置揃えの方法 { 0: ミックスして位置を揃えない、1: 開丸括弧と型の位置を揃える、2: 関数の型名とその他の型名の位置を揃える } |
| align_typedef_star_style | typedefの''の位置揃えの方法 { 0: typedef typeで揃える、1: ''を型名の一部とする、2: '*'を型名の一部としてダングリングする } |
| align_typedef_amp_style | typedefの'&'の位置揃えの方法 { 0: typedef typeで揃える、1: '&'を型名の一部とする、2: '&'を型名の一部としてダングリングする } |
| align_right_cmt_span | 行末コメントを位置揃えするラインスパン (0: 揃えない) { number } |
| align_right_cmt_mix | If aligning comments, mix with comments after '}' and #endif with less than 3 spaces before the comment { true, false } |
| align_right_cmt_gap | 行末コメントがこの桁数以上コードと離れている場合、位置揃えする (0: 揃えない) { number } |
| align_right_cmt_at_col | 行末コメントの位置揃えするカラム位置 (嬉しい副産物 'pulls in' コメント) (0: 揃えない) { number } |
| align_func_proto_span | プロトタイプ宣言の位置揃えのラインスパン (0: 揃えない) { number } |
| align_func_proto_gap | プロトタイプ宣言の返値型と関数名の間のギャップカラム { number } |
| align_on_operator | 'operator'キーワードでプロトタイプ宣言を位置揃えするかどうか { number } |
| align_mix_var_proto | プロトタイプと変数宣言のミックス整形するかどうか (trueの場合、align_var_def_XXXオプションがalign_func_proto_XXXオプションの代わりに使用される。) { true, false } |
| align_single_line_func | 一行関数を関数プロトタイプと同様に位置揃えするかどうか (align_func_proto_spanを使用) { true, false } |
| align_single_line_brace | 一行関数のオープンブレースを位置揃えするかどうか (align_single_line_func=trueの場合のみ) (align_func_proto_spanを使用) { true, false } |
| align_single_line_brace_gap | align_single_line_braceに対するギャップ { number } |
| align_nl_cont | バックスラッシュ-改行で囲われた複数行マクロを位置揃えするかどうか (ただし、マクロが複数行コメントを内包している場合、うまく動かない) { true, false } |
| align_pp_define_span | プリプロセッサ定義のボディの位置揃えのスパン (0: 揃えない) { number } |
| align_pp_define_gap | プリプロセッサ定義のラベルと値の間の空白の最小幅 { number } |
| align_pp_define_together | マクロ関数とマクロ変数を一緒に位置揃えするかどうか { true, false } |
| align_left_shift | '<<'で開始する行を前の行の'<<'の位置に揃えるかどうか (デフォルト: true) { true, false } |
| align_oc_msg_spec_span | Objective-Cのメッセージ仕様宣言のスパン (0: 揃えない) { number } |
| align_oc_msg_colon_span | Objective-Cのメッセージコールにおけるパラメータ':'の位置揃えのスパン (0: 揃えない) { number } |
| align_oc_msg_colon_first | trueの場合、最初のパラメータの位置に後続パラメータの位置を揃える (メッセージが短くとも) { true, false } |
| align_oc_decl_colon | Objective-Cの'+'もしくは'-'宣言行のパラメータを':'で位置揃えするかどうか { true, false } |
僕の設定
align.cfg
align_keep_tabs = false
align_with_tabs = false
align_on_tabstop = false
align_number_left = false
align_func_params = true
align_same_func_call_params = false
align_var_def_star_style = 0
align_var_def_amp_style = 0
align_var_def_colon = true
align_var_def_attribute = true
align_var_def_inline = true
align_var_def_span = 2
align_var_def_thresh = 6
align_var_def_gap = 0
align_assign_span = 2
align_assign_thresh = 6
align_enum_equ_span = 2
align_enum_equ_thresh = 6
align_var_struct_span = 2
align_var_struct_thresh = 6
align_var_struct_gap = 0
align_struct_init_span = 1
align_typedef_gap = 0
align_typedef_span = 2
align_typedef_func = 1
align_typedef_star_style = 0
align_typedef_amp_style = 0
align_right_cmt_span = 4
align_right_cmt_mix = false
align_right_cmt_gap = 1
align_right_cmt_at_col = 0
align_func_proto_span = 2
align_func_proto_gap = 0
align_on_operator = true
align_mix_var_proto = false
align_single_line_func = true
align_single_line_brace = true
align_single_line_brace_gap = 0
align_nl_cont = true
align_pp_define_span = 2
align_pp_define_gap = 0
align_pp_define_together = true
align_left_shift = true
align_oc_msg_spec_span = 0
align_oc_msg_colon_span = 0
align_oc_msg_colon_first = false
align_oc_decl_colon = false
ALIGN_KEEP_TABS
align_keep_tabs.cpp
// 整形前
int var,--->var2;
// align_keep_tabs = true
// タブ文字は残る。
int var,--->var2;
// align_keep_tabs = false
// タブ文字は半角空白4個に展開される。
// この半角空白の数は、input_tab_sizeとoutput_tab_sizeに依存する。
int var,....var2;
ALIGN_WITH_TABS
align_with_tabs.cpp
// 整形前
int foo = 1;
int bar = 1;
int foobar = 2;
int foobarfoobar = 4;
// align_with_tabs = true
// '='の位置合わせでは、このようにタブ文字が使われる。(output_tab_size = 4)
int foo>--->---> = 1;
int bar>--->---> = 1;
int foobar->---> = 2;
int foobarfoobar = 4;
// align_with_tabs = false
// 半角空白のみで位置が揃えられる。
int foo......... = 1;
int bar......... = 1;
int foobar...... = 2;
int foobarfoobar = 4;
ALIGN_ON_TABSTOP
align_on_tabstop.cpp
// 整形前
int foo = 1;
int bar = 1;
int foobar = 2;
int foobarfoobar = 4;
// align_on_tabstop = true
// '='の位置合わせでは、次のタブ位置で揃えられる。(output_tab_size = 4)
int foo = 1;
int bar = 1;
int foobar = 2;
int foobarfoobar = 4;
// align_on_tabstop = false
// 一番短く揃えられる位置で揃えられる。
int foo = 1;
int bar = 1;
int foobar = 2;
int foobarfoobar = 4;
ALIGN_NUMBER_LEFT
align_number_left
// align_number_left = true (&& align_struct_init_span = 10)
// 構造体フィールドの初期化の数値リテラルが右寄せになる。
struct Foo foo = {
.x = 1,
.y = 23,
.z = 456,
};
ALIGN_FUNC_PARAMS
align_func_params.cpp
// align_func_params = true
// 関数定義やプロトタイプ宣言の引数リストの型と変数名の間が位置揃えされる。
void func(
int param1,
short param2,
long param3);
// align_func_params = false
// 関数定義やプロトタイプ宣言の引数リストの型と変数名の間は揃えられない。(何しない)
void func(
int param1,
short param2,
long param3);
ALIGN_SAME_FUNC_CALL_PARAMS
align_same_func_call_params
// align_same_func_call_params = true
// 同じ関数呼び出すが複数行並んでいた場合、引数の位置を揃える。
void function(void)
{
foo(abc, def, xyz);
foo(abcd, efgh, ijkl);
}
// align_same_func_call_params = false
// 同じ関数呼び出しが並んでいても、引数の位置は自動的には揃わない。(何もしない)
void function(void)
{
foo(abc, def, xyz);
foo(abcd, efgh, ijkl);
}
ALIGN_VAR_DEF_STAR_STYLE
align_var_def_star_style.cpp
// align_var_def_star_style = 0
// 変数宣言におけるポインタの'*'を変数の型に付ける。
int integer;
int* i_ptr;
char* c_ptr;
double* d_ptr;
float* f_ptr;
// align_var_def_star_style = 1
// 変数宣言におけるポインタの'*'を変数名の先頭に付け、'*'は非ポインタ型の変数名の先頭位置と位置揃えする。
int integer;
int *i_ptr;
char *c_ptr;
double *d_ptr;
float *f_ptr;
// align_var_def_star_style = 2
// 変数宣言におけるポインタの'*'を変数名の先頭に付ける。変数名の先頭で位置揃えを行う。'*'はダングリングさせる。
int integer;
int *i_ptr;
char *c_ptr;
double *d_ptr;
float *f_ptr;
ALIGN_VAR_DEF_AMP_STYLE
align_var_def_amp_style.cpp
// align_var_def_amp_style = 0
// 変数宣言における参照の'&'を変数の型に付ける。
int integer;
int& i_ptr;
char& c_ptr;
double& d_ptr;
float& f_ptr;
// align_var_def_amp_style = 1
// 変数宣言における参照の'&'を変数名の先頭に付け、'&'は非参照型の変数名の先頭位置と位置揃えする。
int integer;
int &i_ptr;
char &c_ptr;
double &d_ptr;
float &f_ptr;
// align_var_def_amp_style = 2
// 変数宣言における参照の'&'を変数名の先頭に付ける。変数名の先頭で位置揃えを行う。'&'はダングリングさせる。
int integer;
int &i_ptr;
char &c_ptr;
double &d_ptr;
float &f_ptr;
ALIGN_VAR_DEF_COLON
align_var_def_colon.cpp
// align_var_def_colon = true
// 構造体のビットフィールドの':'の位置を揃える。
struct Bitfields
{
unsigned int bit1 : 1;
unsigned int bit2_8 : 7;
unsigned int bit9_16 : 8;
unsigned int bit17_32 : 16;
};
// align_var_def_colon = false
// ビットフィールドを揃えない。(何もしない)
struct Bitfields
{
unsigned int bit1 : 1;
unsigned int bit2_8 : 7;
unsigned int bit9_16 : 8;
unsigned int bit17_32 : 16;
};
ALIGN_VAR_DEF_ATTRIBUTE
align_var_def_attribute.cpp
// align_var_def_attribute = true
// 変数属性の'__attribute__'の位置を合わせる。
unsigned char original[128] __attribute__(aligned(128));
unsigned char copy[128] __attribute__(aligned(128));
unsigned char result[128] __attribute__(aligned(128));
// align_var_def_attribute = false
// 変数属性の'__attribute__'の位置を合わせない。(何もしない)
unsigned char original[128] __attribute__(aligned(128));
unsigned char copy[128] __attribute__(aligned(128));
unsigned char result[128] __attribute__(aligned(128));
ALIGN_VAR_DEF_INLINE
align_var_def_inline.cpp
// align_var_def_inline = true
// 構造体のメンバ変数の宣言(型名とメンバ変数名)の位置を揃える。
struct Foo
{
int bar1;
short bar2;
}
// align_var_def_inline = false
// 構造体のメンバ変数の宣言(型名とメンバ変数名)の位置を揃えない。(何もしない)
struct Foo
{
int bar1;
short bar2;
}
ALIGN_VAR_DEF_SPAN
align_var_def_span.cpp
// align_var_def_span = 0
// 変数定義の位置揃えは行わない。
{
int a;
char bbb;
long ccc;
float dddd;
double eeeeee;
unsigned int ff;
unsigned char gggg;
}
// align_var_def_span = 1;
// 行が連続した変数定義の範囲だけ一緒に位置揃えを行う。
{
int a; // aligned 1
char bbb; // aligned 1
long ccc; // aligned 1
float dddd; // aligned 2
double eeeeee; // aligned 2
unsigned int ff; // aligned 3
unsigned char gggg; // aligned 3
}
// align_var_def_span = 2;
// 空行が1行開いている変数定義でも一緒に位置揃えを行う。
{
int a; // aligned 1
char bbb; // aligned 1
long ccc; // aligned 1
float dddd; // aligned 1
double eeeeee; // aligned 1
unsigned int ff; // aligned 2
unsigned char gggg; // aligned 2
}
// align_var_def_span = 3 ;
// 空行が2行開いている変数定義でも一緒に位置揃えを行う。
{
int a; // aligned with all
char bbb; // aligned with all
long ccc; // aligned with all
float dddd; // aligned with all
double eeeeee; // aligned with all
unsigned int ff; // aligned with all
unsigned char gggg; // aligned with all
}
ALIGN_VAR_DEF_THRESH
align_var_def_thresh.cpp
// align_var_def_thresh = 3
// double(6文字)とint(3文字)のカラム差(3文字)は位置揃えされるが、
// long(4文字)とunsigned char(13文字)のカラム差(9文字)は位置揃えされない。
{
float dddd;
double eeeeee;
int a;
char bbb;
long ccc;
unsigned int ff;
unsigned char gggg;
}
// align_var_def_thresh = 2
// floatとdouble、intとcharとlong、unsigned intとunsigned charは揃えられるが、
// doubleとint、longとunsigned charは位置揃えされない。
{
float dddd;
double eeeeee;
int a;
char bbb;
long ccc;
unsigned int ff;
unsigned char gggg;
}
ALIGN_VAR_DEF_GAP
align_var_def_gap.cpp
// align_var_def_gap = 0 (align_var_def_gap = 1も同じ)
// 変数の型と変数名の間に半角空白1文字分の余白を空ける。
{
float dddd;
double eeeeee;
int a;
char bbb;
long ccc;
unsigned int ff;
unsigned char gggg;
}
// align_var_def_gap = 4
// 変数の型と変数名の間を最小で半角空白4文字分を確保して位置揃えする。
{
float ....dddd;
double ....eeeeee;
int ....a;
char ....bbb;
long ....ccc;
unsigned int ....ff;
unsigned char....gggg;
}