对一个vim 函数的详细注释。

对我而言， 这是一个复杂的函数， 虽然详细注释， 但还是有些难懂， 注释也是参考原作者的。

我只是简单的整理了一下。将注释添加到了函数中，方便阅读理解。

函数功能， 能够自动对齐赋值运算符的位置。 查找，替换是核心目的。（调试通过）

function! AlignAssignments ()

    "Patterns needed to locate assignment operators...
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"ASSIGN_OP 中的模式匹配任何标准的赋值运算符：=、+=、-=、*=，等等，
"但是注意不要匹配其他包含 = 的运算符，比如 == 和 =~。
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    let ASSIGN_OP   = '[-+*/%|&]\?=\@<!=[=~]\@!'

    echo "ASSIGN_OP = " ASSIGN_OP
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"ASSIGN_LINE 中的模式只在行的起始部分（^）开始匹配，首先匹配最小字符数（.\{-}），
"然后匹配任何空白（\s*），最后匹配赋值运算符。
"注意，最初的 “最小字符数” 子模式和运算符子模式都在捕捉圆括号内进行了指定：\(...\)。
"这两个正则表达式组件捕获的子字符串稍后将通过调用内置 submatch() 函数来提取；
"具体来讲，通过调用 submatch(1) 来提取运算符前面的所有内容，
"然后调用 submatch(2) 来提取运算符本身。
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    let ASSIGN_LINE = '^\(.\{-}\)\s*\(' . ASSIGN_OP . '\)'

    echo "ASSIGN_LINE =" ASSIGN_LINE
    "Locate block of code to be considered (same indentation, no blanks)

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"直接计算行范围。实现方法，
"它首先调用内置 matchstr() 函数来确定出现在当前行（getline('.')）起始部分的前导空白（'^\s*'）。
"随后在 indent_pat 中构建一个新的正则表达式，精确匹配任何非空行的起始处的相同序列的空白（即拖尾 '\S'）。
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    let indent_pat = '^' . matchstr(getline('.'), '^\s*') . '\S'
    
    echo "indent_pat = " indent_pat
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"内置 search() 函数向上搜索（使用标记 'bnW'）并定位位于游标上方的第一个不具有相同缩进的行。
"向此行号加 1 将得出感兴趣的范围的起始行号，也就是说，具有相同缩进的第一个相邻行就作为第一行
"内置 search() 函数向下搜索（'nW'）来判断 lastline：具有相同缩进的最后一个相邻行。
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    let firstline  = search('^\%('. indent_pat . '\)\@!','bnW') + 1
    let lastline   = search('^\%('. indent_pat . '\)\@!', 'nW') - 1
    echo "firstline =" firstline
    echo "lastline = " lastline

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"搜索可能会到达文件的末尾，并且没有找到具有不同缩进的行，这种情况下 search() 将返回 -1。
"要正确地处理这种情况， if 语句需要显式地将 lastline 设置为文件末端的行号
"即设置为由 line('$') 返回的行号
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    if lastline < 0
        let lastline = line('$')
    endif

    "Find the column at which the operators should be aligned...
    let max_align_col = 0
    let max_op_width  = 0

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"for 循环功能： 获取赋值运算符应当对齐的列。
"实现方法:
"遍历所选范围内的行列表（由 getline(firstline, lastline) 取回的行）
"并检查每个行是否包含赋值运算符（运算符的前面可能包含空格）：
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    for linetext in getline(firstline, lastline)
        "Does this line have an assignment in it?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"如果该行中没有运算符，那么内置 match() 函数将无法找到匹配，因此将返回 -1。
"对于这种情况，循环将直接跳到下一行。
"如果存在 运算符，那么 match() 将返回在其中显示运算符的（正）指数。
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        let left_width = match(linetext, '\s*' . ASSIGN_OP)

        "If so, track the maximal assignment column and operator width...
        if left_width >= 0
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"使用内置 max() 函数判断这个最近的列位置是否比此前找到的运算符更靠右，
"从而跟踪所需的最大列位置来对齐范围内的所有赋值运算符：
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
            let max_align_col = max([max_align_col, left_width])
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"使用内置 matchstr() 函数检索实际的运算符，
"然后使用内置 strlen() 函数判断行的长度（"=" 的长度为 1，'+='、'-=' 的长度为 2，等等）。
"max_op_width 变量随后被用来跟踪所需的最大宽度，以对范围内的各种运算符执行对齐：
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
            let op_width      = strlen(matchstr(linetext, ASSIGN_OP))
            let max_op_width  = max([max_op_width, op_width+1])
         endif
    endfor

    "Code needed to reformat lines so as to align operators...

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"vim 的printf 函数， 类似于c/perl 的sprintf 函数， 返回一个字符串
"这个内嵌的 printf() 将把运算符左侧的所有内容（submatch(1)）靠左对齐（使用 %-*s 占位符）
"并将结果放到字符宽度为 max_align_col 的字段中。
"随后将运算符本身（submatch(2)）右对齐（使用%*s）到第二个字段，其字符宽度为 max_op_width。
"参考 :help printf()，了解 - 和 * 选项如何修改
"这里使用的两个 %s 格式说明符（specifier）
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    let FORMATTER = '\=printf("%-*s%*s", max_align_col, submatch(1), max_op_width,  submatch(2))'

    " Reformat lines with operators aligned in the appropriate column...
    for linenum in range(firstline, lastline)
        let oldline = getline(linenum)

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"substitute() 中 "\=expr"。
"前导 \= 要求对随后的表达式求值并使用结果作为替换文本。
"注意，这类似于 Insert 模式下的 <C-R>= 机制，
"这种奇妙的行为只针对内置 substitute() 函数的替换字符串（或在标准 :s/.../.../ Vim 命令中）
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        let newline = substitute(oldline, ASSIGN_LINE, FORMATTER, "")
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"与当前编辑的文本缓冲区进行交互（通过 getline() 和 setline()）
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
        call setline(linenum, newline)
    endfor
endfunction

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
"创建一个键映射来调用 AlignAssignments()
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
nmap <silent>  ;=  :call AlignAssignments()<CR>