Home

#unite-outline

ヘルプの草稿的ななにか

##概要

ファイルの見出しを抽出し、unite.vim のインターフェースを使ってそれらを一覧表示、各見出しへのジャンプ機能を提供する source です。見出しを抽出するためのパターン及び見出しレベルの決定ロジックをファイルタイプごとに設定することができます。

##outline info

ファイルタイプごとの見出しの抽出パターンと見出しレベルの決定ロジック（関数）などをまとめた辞書。これを vimrc にて、あるいは所定の位置に配置した VimScript によって定義することで、ファイルタイプごとに見出し抽出を自在にカスタマイズすることが可能です。

###探索経路

g:unite_source_outline_info.filetype
　↓
unite#sources#outline#filetype#outline_info()
　↓
unite#sources#outline#fdefaults#filetype#outline_info()

最初の1回に限り、上記のパスで探索が行われます。取得された outline info は g:unite_source_outline_info.filetype に設定され、以後はそこから取得されます。

unite-outline がデフォルトで提供する outline info を上書きする方法は以下の２つ

１、vimrc にてグローバル変数に設定する

vimrc にて g:unite_source_outline_info.filetype に outline info を設定する。

２、オートロード関数を定義する

(runtimepath)/autoload/unite/sources/outline/ に filetype.vim を作成し、そこに unite#sources#outline#filetype#outline_info() 関数を定義。その返値として outline info を返す。

こちらは遅延評価になるので必要になるまでロードされません。vimrc を肥大化させることもないので outline info を作り込むのであればこちらの方法がおすすめです。

(runtimepath)/autoload/unite/sources/outline/defaults/ にあるデフォルトの outline info が参考になると思います。

###属性一覧

今のところまだ仕様が確定していません。（が、大体固まってきた）

とりあえず暫定仕様ということで現在の outline info の属性一覧↓

####heading-1

パターン文字列（任意）

次の行が見出しであるような行にマッチするパターンを設定する。

これを設定することで、例えば

==============================================================================
見出し１

や

------------------------------------------------------------------------------
見出し２

のような、飾りの枠線の下にくるタイプの見出しを抽出することができます。また、

/****************************************
*
*   見出し３
*
*****************************************/

こういうタイプにも対応できるよう、次の行が空行っぽい場合はもうひとつ次の行も見るにようになっています。

####heading

パターン文字列（任意）

その行が見出しであるような行にマッチするパターンを設定する。

####heading+1

パターン文字列（任意）

前の行が見出しであるような行にマッチするパターンを設定する。

これを設定することで、例えば Markdown の

見出し
------

のような、下線をともなうタイプの見出しを抽出することができます。

####create_heading

関数（任意）

設定されていると、heading-1, heading, heading+1 によるマッチが成功する度に呼ばれ、その返値が見出し一覧に表示される。この関数を定義することによって、ユーザーは自由に見出し一覧に設定する文字列の整形、および見出しレベル（インデント）の設定を行うことができる。

参考として、HTML の create_heading() 関数を示します。

function! s:outline_info.create_heading(which, heading_line, matched_line, context)
  if a:which ==# 'heading'
    let level = str2nr(matchstr(a:heading_line, '<[hH]\zs[1-6]\ze[^>]*>'))
    let text = substitute(substitute(a:heading_line, '<[^>]*>', '', 'g'), '^\s*', '', '')
    return unite#sources#outline#indent(level) . "h" . level. ". " . text
  endif
  return ""
endfunction

create_heading() 関数に渡される引数は以下の通り。関数側では、これらの情報を元に、見出しかどうかの判定や見出しレベルの決定、見出し一覧に表示する文字列の整形を行う。

• which - 文字列：マッチの種類、'heading-1', 'heading', 'heading+1' のいずれか
• heading_line - 文字列：見出しとなる行
• matched_line - 文字列：マッチした行
• context - 辞書：その他の情報
  • heading_index - 数値：lines における heading_line の index
  • matched_index - 数値：lines における matched_line の index
  • lines - リスト：ファイルの全行（ヘッダ除く）

create_heading() 関数は文字列を返さなければならない。その文字列が見出し一覧に表示される。空文字列を返すと、見出しではないとみなされ、無視される。

####skip

辞書（任意）

見出し抽出の対象としない領域を指定するための辞書

この辺は仕様がふらふらしているのでまだ書かない。

あとで書く

##ToDo

###対応ファイルタイプの充実

ぼちぼちやっていきたいですが、妥当な初期値を決めるのは結構難しいです。特に、自分が普段使っていない言語では。初期値が用意されていないファイルタイプに関してはユーザー（いるのか？）から outline info の定義を募りたいところですが、肝心の outline info の仕様がまだ固まっていないのでまずはそちらをしっかり確定することから。