Справочник по Vim: Складки

СПРАВОЧНИК ПО VIM - Брам Мооленаар

Начальные сведения по использованию складок приводятся в главе 28 Руководства пользователя.

1. Способы создания складок
2. Команды для работы со складками
3. Опции для работы со складками
4. Поведение складок

Vi не умеет работать со складками.
Доступно только в том случае, если Vim скомпилирован с особенностью |+folding|.

1. Способы создания складок

Способ создания складок может быть назначен при помощи опции 'foldmethod'.

Если новое значение опции 'foldmethod' отличается от "manual", то все существующие складки удаляются и создаются новые складки. При переключении к методу "manual" существующие складки не удаляются. Этим можно воспользоваться, чтобы определить складки в автоматическом режиме, а затем изменить их вручную.

Для создания складок применяется шесть методов:

РУЧНОЙ СПОСОБ (MANUAL)

Для определения областей складок используются специальные команды. Этот способ можно также использовать в сценарии, который просматривает текст для размещения в нём складок.

Уровень складки определяется только её вложенностью. Для увеличения уровня складки для диапазона строк, определите внутри этой складки ещё одну складку, которая соответствовала бы тому же самому диапазону строк.

Ручные складки исчезают как только вы оставите файл. Для сохранения определённых вручную складок можно пользоваться командой |:mkview|. Вид может быть восстановлен позже по команде |:loadview|.

ОПРЕДЕЛЕНИЕ СКЛАДОК ПО ОТСТУПАМ (INDENT)

При использовании этого метода глубина складки автоматически определяется по величине отступа в строке.

Значение уровня складки вычисляется путём деления величины отступа на значение опции 'shiftwidth' (округлённое до меньшего целого). Последовательность строк с одинаковым или более глубоким уровнем складки образует складку, причём строки с более глубоким уровнем попадают во вложенную складку.

Вложенность складок ограничивается значением опции 'foldnestmax'.

При вычислении глубины складки отступ в некоторых строках игнорируется, а соответствующее значение наследуется от предыдущей или последующей строки, в зависимости от того, какая из соседних строк имеет наименьшую глубину складки. К таким строкам относятся пустые строки, строки, состоящие из пробелов, и строки, которые начинаются с одного из символов, заданных в значении опции 'foldignore'. Перед символами, определёнными в значении опции 'foldignore' может следовать любое количество пробельных символов. Для использования данного метода в тексте исходного кода на языке C хорошо подходит строка "#" в качестве значения опции 'foldignore' -- это позволяет пропускать строки с командами препроцессора.

Другим способом пропуска строк в складках является использование метода 'expr'. Он основан на использовании выражения, которое записывается в значение опции 'foldexpr'. В этом выражении можно использовать функцию |indent()| для получения величины отступа в строке.

ОПРЕДЕЛЕНИЕ СКЛАДОК С ПОМОЩЬЮ ВЫРАЖЕНИЯ (EXPR)

Как и при использовании метода "indent" складки автоматически создаются в соответствии с вычисленной глубиной складки. Для получения величины глубины складки для данной строки используется выражение, заданное в значении опции 'foldexpr'. Приведём несколько примеров:

Создание складки, включающей все последующие строки, начинающиеся с символа табуляции:

:set foldexpr=getline(v:lnum)[0]==\"\\t\"

Использование вызова функции для вычисления глубины складки:

:set foldexpr=MyFoldLevel(v:lnum)

Создание складок из отдельных абзацев, разделённых пустыми строками:

:set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1

ещё один способ добиться того же самого эффекта:

:set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':1

Обратите внимание, что для экранирования специальных для команды ":set" символов (пробела, обратной косой черты, двойной кавычки и т.д.,  см. |опции-обратная_косая|) применяется символ обратной косой черты.

При вычислении выражения принимаются во внимание следующие условия:

• текущий буфер и активное окно, в которых находится соответствующая строка;
• значение переменной "v:lnum", которой присваивается номер соответствующей строки.

Результат выражения используется для определения глубины складки следующим образом:

Помечать начало и конец складки с помощью ">1" и "<1" не является обязательным, складка автоматически может начинаться и заканчиваться в том случае, если величина глубины складки больше или меньше, чем величина глубины складки предыдущей строки.

Выражение не должно создавать побочных эффектов. Текст в буфере, позиция курсора, шаблоны для поиска, значения опций и т.д. не должны изменяться  в процессе вычисления выражения.

Если в выражении имеется какая-либо ошибка, либо результат вычисления выражения не является допустимым для данной ситуации, то сообщение об ошибке не выводится, а глубина складки устанавливается равной нулю. Для отладки выражений для работы со складками можно назначить опции 'debug' значение "msg": в этом случае сообщения об ошибках будут выводиться.

Замечание: поскольку выражение должно вычисляться для каждой строки, использование этого метода определения складок может быть очень непроизводительным решением!

Постарайтесь избегать возвращаемых значений "=", "a" и "s", поскольку при их использовании часто приходится выполнять поиск предыдущей строки с определённой величиной глубины складки, что может также тормозить работу Vim.

Функция |foldlevel()| может применяться для вычисления уровня глубины складки по отношению к предыдущему уровню. Следует, однако, иметь в виду, что эта функция может возвращать значение -1, если уровень складки не известен. Кроме того, эта функция возвращает значение глубины складки для начала строки, в то время как складка может заканчиваться в этой строке.

ОПРЕДЕЛЕНИЕ СКЛАДОК В СООТВЕТСТВИИ С ПРАВИЛАМИ СИНТАКСИСА (SYNTAX)

При использовании данного способа, складки определяются по синтаксическим элементам, в которых указан параметр "fold", см. |:syn-fold|.

Глубина складки устанавливается в соответствии с вложенными складками. Вложенность складок может быть ограничена при помощи опции 'foldnestmax'.

Будьте внимательны: синхронизация синтаксиса должна быть задана правильно. Если синхронизация синтаксиса выполняется неправильно, то складки могут пойти вразнобой с отображаемой подсветкой синтаксиса. Это особенно важно при использовании шаблонов, которым может соответствовать несколько строк. Если вы испытываете сомнения, то используйте полномасштабную синхронизацию:

:syn sync fromstart

ОПРЕДЕЛЕНИЕ СКЛАДОК ДЛЯ ПРОСМОТРА РАЗЛИЧИЙ МЕЖДУ БУФЕРАМИ (DIFF)

При использовании данного способа складки создаются автоматически для текста, который совпадает в сличаемых файлах и находится достаточно далеко от различающихся фрагментов.

Этот метод работает только в том случае, если в активном окне включена опция 'diff' и оно используется для отображения различий с другим буфером. В противном случае весь буфер будет одной большой складкой.

Опция 'diffopt' может применяться для изменения количества строк контекста. Речь идёт о числе строк между складкой и различающимися фрагментами текста, которые в складку не включаются. Например, для использования 8 строк контекста:

:set diffopt=filler,context:8

По умолчанию для контекста используется 6 строк.

Если включена опция 'scrollbind', то Vim будет пытаться открывать при необходимости соответствующие складки в других окнах, используемых для просмотра различий, чтобы везде отображался один и тот же текст.

ОПРЕДЕЛЕНИЕ СКЛАДОК ПРИ ПОМОЩИ МАРКЕРОВ (MARKER)

При использовании данного способа начало и конец складки отмечаются в тексте при помощи специальных маркеров. Это позволяет определять складки с максимальной точностью, удалять и вклеивать складки без риска изменения структуры складок. Опция 'foldtext' обычно настраивается таким образом, что текст перед маркером отображается в строке складки, что позволяет давать складкам имена.

Маркеры могут включать указание на глубину складки. Возможно также применение парных маркеров. Явное указание глубины складки является более простым, поскольку в этом случае вы не обязаны использовать маркеры для конца складки и у вас не болит голова о совпадении парных маркеров. Например:

/* глобальные переменные {{{1 */
int varA, varB;

/* функции {{{1 */
/* funcA() {{{2 */
void funcA() {}

/* funcB() {{{2 */
void funcB() {}

Складка начинается с маркера "{{{". Следующее за этим маркером число указывает на глубину складки. Поведение Vim зависит от того, как отличаются друг от друга глубина складки для данной строки и глубина, заданная с помощью маркера:

1. Если по тексту встречается новый маркер с той же самой глубиной, то предыдущая складка завершается и начинается новая складка с тем же самым уровнем глубины.
2. Если по тексту встречается маркер с более глубоким уровнем, то создаётся вложенная складка.
3. Если по тексту встречается маркер с менее глубоким уровнем, то завершаются все складки с большим или равным уровнем глубины и создаётся новая складка с заданным уровнем.

Число после маркера указывает на глубину складки. Ноль не используется. Вы можете применять маркер "}}}" с числом для указания уровня складки, который должен быть завершён в этом месте. Глубина складки для следующей строки в этом случае будет на единицу меньше, чем заданное число. Обратите внимание, что Vim не проверяет глубину парного начального маркера, поскольку это было бы крайне неэффективно. Покажем это на примере:

{{{1
глубина складки равна 1
{{{3
глубина складки равна 3
}}}3
глубина складки равна 2

Кроме того, вы также можете задавать складки с помощью парных маркеров "{{{" и "}}}". Каждый маркер "{{{" увеличивает глубину складки на единицу, а маркер "}}}" уменьшает её на то же самое значение. Следите за парностью маркеров!

Пример:

{{{
глубина складки равна 1
{{{
глубина складки равна 2
}}}
глубина складки равна 1

Вы можете свободно смешивать в тексте маркеры с числом и без числа. Например, полезно использовать маркеры с числом для больших складок, в то время как внутри кода функции небольшие фрагменты могут выделяться маркерами без числа. Используйте уровень 1 для таких разделов текста, как "определения структур данных", "местные переменные", "функции"; уровень 2 можно применять для отдельных определений и функций. Внутри функций можно пользоваться ненумерованными маркерами, тогда вам не нужно будет изменять числа после маркеров в том случае, если складка будет разбита при внесении изменений в код функции.

Символы, применяемые в качестве маркеров, могут быть заданы с помощью опции 'foldmarker'. Чтобы файлами, созданными в Vim с использованием маркеров для определения складок, можно было обмениваться с другими пользователями, лучше не изменять принятое по умолчанию значение этой опции "{{{,}}}" без особой необходимости. Изменение значения этой опции может потребоваться в тех случаях, когда это диктуется разметкой редактируемого файла (например, если он содержит маркеры для другого редактора, или если принятые по умолчанию маркеры не допускаются правилами синтаксиса языка этого файла).

Команда "zf" может применяться для создания складки, определённой при помощи маркеров. Vim автоматически вставит необходимые маркеры в текст, добавляя маркеры начала и конца складки в соответствии со значением опции 'foldmarker'. Маркеры добавляются в конец соответствующей строки. Если значение опции 'commentstring' не является пустой строкой, то оно будет учтено при добавлении маркеров.

Эта возможность не работает как следует в следующих случаях:

• Строка уже содержит маркер с величиной уровня глубины складки. В этом случае Vim не знает, что ему делать.
• Близлежащие складки используют число для указания на величину уровня глубины складки, которое препятствует вставки маркера.
• Строка находится внутри комментария, значение опции 'commentstring' не является пустой строкой, а вложенные комментарии не допускаются. Например, в тексте исходного кода программы на языке C: при добавлении /* {{{ */ внутрь комментария обрезается уже существующий комментарий. В этом случае имеет смысл поместить маркер либо до комментария, либо после, или добавить маркер вручную.

Как правило не следует позволять Vim'у создавать маркеры, если у вас уже есть маркеры, использующие число для указания величины уровня глубины.

Для удаления складки, определённой при помощи маркеров, может применяться команда "zd". При выполнении этой команды Vim удалит соответствующие маркеры для начала и конца складки, как они заданы в значении опции 'foldmarker', из текста. Если текст вокруг маркера совпадает со значением опции 'commentstring', то он также будет удалён.

Эта возможность не работает как следует в следующих случаях:

• В строке содержится несколько маркеров, один из которых использует число для указания уровня глубины складки. В этом случае удаляется только первый маркер, но проверка последствий удаления маркера не выполняется.
• Маркер содержит число для указания уровня глубины складки и используется для указания начала или конца сразу нескольких складок одновременно.

2. Команды для работы со складками

Все команды для работы со складками начинаются с буквы "z". Кстати, буква "z" похожа на сложенный лист бумаги, если посмотреть на него со стороны.

СОЗДАНИЕ И УДАЛЕНИЕ СКЛАДОК

ОТКРЫТИЕ И ЗАКРЫТИЕ СКЛАДОК

Складка, которая занимает меньше строк, чем указано в значении опции 'foldminlines', всегда отображается на экране в открытом состоянии. Команды, которые перечислены ниже, могут работать иначе, если они выполняются над небольшими складками.

ПЕРЕМЕЩЕНИЕ ПО СКЛАДКАМ

ВЫПОЛНЕНИЕ КОМАНД В ОТНОШЕНИИ СКЛАДОК

:folddoopen s/end/loop_end/ge

3. Опции для работы со складками

ЦВЕТА

Цвета подсветки закрытых складок настраиваются с помощью группы Folded, см. |подсветка-Folded|.  Цвета колонки складок настраиваются с помощью группы FoldColumn, см. |подсветка-FoldColumn|.

Пример настройки цветов:

:highlight Folded guibg=grey guifg=blue
:highlight FoldColumn guibg=darkgrey guifg=white

ГЛУБИНА СКЛАДОК (FOLDLEVEL)

Значением опции 'foldlevel' является число: чем оно выше, тем больше складок будет открыто.

При значении опции 'foldlevel' равном 0 все складки будут закрыты.

При положительном значении опции 'foldlevel' открываются некоторые складки, в соответствии с уровнем глубины.

При очень большом значении опции 'foldlevel' будут открыты все складки.

Значение опции 'foldlevel' применяется при его изменении. После этого складки могут открываться и закрываться вручную.

При увеличении значения опции 'foldlevel' открываются складки, глубина которых меньше нового значения. При этом складки, открытые вручную, не закрываются.

При уменьшении значения опции 'foldlevel' закрываются складки, глубина которых больше нового значения. Складки, закрытые вручную, не открываются.

ИМЯ СКЛАДКИ (FOLDTEXT)

Значением строковой опции 'foldtext' является выражение, которое вычисляется для получения имени складки. Именем складки называется текст, который отображается в строке закрытой складки. Приведём пример:

:set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g')

В данном случае в качестве имени складки используется первая строка складки с удалёнными символами "/*", "*/" и "{{{".

Обратите внимание на использование обратной косой черты для экранирования символов, которые имеют специальное значение при использовании в команде ":set". Гораздо проще определить функцию и вызвать её из выражения в значении данной опции:

:set foldtext=MyFoldText()
:function MyFoldText()
:  let line = getline(v:foldstart)
:  let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g')
:  return v:folddashes . sub
:endfunction

Вычисление выражения для 'foldtext' выполняется в |песочнице|. Активным окном при вычислении выражения становится окно, в котором отображается соответствующая строка. Ошибки игнорируются.

По умолчанию выражение в данной опции вызывает функцию |foldtext()|. Эта функция возвращает подходящее для большинства складок имя. Если вас не устраивает значение по умолчанию, то вы можете задать собственное выражение 'foldtext', которое может использовать ряд специальных переменных Vim:

Символы табуляции в результате вычисления выражения заменяются пробелами, а непечатные символы превращаются в печатные символы.

Полученная в результате строка обрезается, чтобы её можно было поместить в окне. Эта строка никогда не переносится. Если после имени остаётся пустое место, то оно заполняется символом, указанным в значении опции 'fillchars'.

Обратите внимание, что для экранирования специальных для команды ":set" символов (пробела, обратной косой, двойной кавычки) следует использовать символ обратной косой черты. См. |опции-обратная_косая|.

ШИРИНА КОЛОНКИ СКЛАДОК (FOLDCOLUMN)

Значением опции 'foldcolumn' является число, которое задаёт ширину колонки сбоку от окна, которая используется для отображения складок. Если значение этой опции равно нулю, то колонка складок не используется. Обычно применяется значение 4 или 5. Минимальное полезное значение этой опции равно 2, а максимально возможное - 12.

Открытая складка в колонке складок помечается символом '-' в верхней строке складок и символами '|' в последующих строках, вплоть до последней строки открытой складки. Если открыто несколько вложенных складок, то вложенные складки отображаются в колонке складок символами, расположенными справа от символов внешней складки.

Закрытая складка отображается в колонке с помощью символа '+'.

Если ширина колонки складок недостаточна для отображения всех вложенных складок, то для отображения уровня вложенности используются цифры.

Колонка складок также позволяет использовать мышь для открытия и закрытия соответствующих складок:

• Щелчок мышью на символе '+' открывает закрытую складку в этой строке.
• Щелчок мышью на любом другом непробельном символе закрывает открытую складку в этой строке.

ДРУГИЕ ОПЦИИ

4. Поведение складок

При перемещении курсора на строку вверх или вниз или при выполнении прокрутки, курсор перемещается в первую строку закрытой складки. Если курсор уже находится на строке с закрытой складкой, то он перемещается к следующей раскрытой строке или к следующей закрытой складке.

Пока курсор находится на сложенной строке, он всегда помещается в первую колонку. Линейка отображает фактическую позицию курсора, но поскольку строка сложена, то курсор не может быть показан в этой позиции.

Многие команды перемещения рассматривают последовательность строк в закрытой складке как пустую строку. Например, команда "w" останавливается в первой колонке.

В режиме Вставки строка, в которой находится курсор, никогда не входит в закрытую складку. Это позволяет вам видеть текст в процессе ввода!

При использовании оператора, закрытая складка включается в операцию как одно целое. Например, команда "dl" над закрытой складкой удаляет все строки в этой складке.

При выполнении команд Ex диапазон изменяется таким образом, чтобы он начинался на первой строке складки, а заканчивался последней строкой складки. Таким образом, при использовании команды

:s/цол/оло/g

с курсором, помещённым на закрытую складку, будет выполнена замена "цол" на "оло" во всех строках складки. Это не касается команд |:folddoopen| и |:folddoclosed|.

При редактировании раннее загруженного буфера используются настройки складок, которые применялись в последний раз. При использовании ручного способа определения складок восстанавливаются раннее определённые складки. Во всех случаях восстанавливается состояние складок, открытое или закрытое. Если данный буфер редактировался в этом окне, то используются значения для данного окна, в противном случае восстанавливаются значения, которые были в силе в том окне, где буфер редактировался в последний раз.