editor.text

Свойства и функции для работы с редактором
==========================================


Свойства
--------

`Editor.CurLine`
:	`number`
:	номер текущей строки

`Editor.CurPos`
:	`number`
:	текущая позиция курсора в строке; учитывается размер табуляции

`Editor.FileName`
:	`string`
:	полное имя редактируемого файла

`Editor.Lines`
:	`number`
:	количество строк в редакторе

`Editor.RealPos`
:	`number`
:	текущая позиция курсора в строке без привязки к размеру табуляции
	(табуляция считается за 1 символ)

`Editor.SelValue`
:	`string`
:	содержимое выделенного блока.  
	Аналогично тому, как Far поместил бы в _Clipboard_ (блок текста с наличием `crlf` в конце строк).

`Editor.State`
:	`number`
:	различные состояния текущего редактора - набор битовых флагов:

	`0x00000001`
	:	файл совершенно новый либо его успели удалить

	`0x00000002`
	:	разрешено переключение на программу просмотра по ~F6~

	`0x00000004`
	:	после закрытия редактора удалить файл

	`0x00000008`
	:	редактируемый файл модифицирован (в статусной строке редактора присутствует символ '`*`')

	`0x00000010`
	:	в наличии есть выделенный поточный блок
	:	(альтернативный вариант - функция [`Editor.Sel(0,4)`][Editor.Sel])

	`0x00000020`
	:	в наличии есть выделенный вертикальный блок
	:	(альтернативный вариант - функция [`Editor.Sel(0,4)`][Editor.Sel])

	`0x00000040`
	:	редактируемый файл изменялся в сеансе редактирования

	`0x00000080`
	:	курсор в режиме замены

	`0x00000100`
	:	позиция курсора была изменена плагином

	`0x00000200`
	:	редактор заблокирован (ReadOnly)

	`0x00000400`
	:	используются постоянные блоки

	`0x00000800`
	:	модальный редактор

	`0x08000000`
	:	Far запущен с ключом `/e`

	Например,

	~~~lua
	if band(Editor.State,0x8) then 
	  -- выполнить действия, если файл модифицирован
	end
	~~~

`Editor.Value`
:	`string`
:	содержимое текущей строки в редакторе под курсором.
	Например, показать текущий символ под курсором:

	~~~lua
	local pos = Editor.CurPos
	mf.msgbox(nil,Editor.Value:sub(pos,pos))
	~~~


Функции
-------

:::functions
`N=Editor.DelLine([Line])`
:	Удаление строки с номером `Line`. Если `Line` не указан или меньше `1`,
	то удаляется текущая строка.

	Возвращает `1` для успешно выполненной операции или
	`0` - если редактор не в фокусе/редактор залочен/нет строки с запрашиваемым номером.

`S=Editor.GetStr([Line])`
:	Получить содержимое строки с номером `Line`. Если `Line` не указан или меньше `1`,
	то возвращается текущая строка.

	Возвращает строку с запрашиваемым номером.

`N=Editor.InsStr([S[,Line]])`
:	Вставить значение `S` после строки с номером `Line`.
	Если `S` не указан, то вставляется пустая строка.
	Если `Line` не указан или меньше `1`, то вставляется в текущую строку.

	Возвращает `1` для успешно выполненной операции или `0` - если редактор
	не в фокусе/редактор залочен/нет строки с запрашиваемым номером.

`N=Editor.Pos(Action,Object[,Value])`
:	Получение/установка позиций в редакторе.

	Параметр `Action` задаёт поведение функции:

	`0`
	:	получить данные
	:	возвращает текущее значение

	`1`
	:	установить данные
	:	возвращает `1`/`0` - успешно/неуспешно выполнена установка

	Функция возвращает `-1` в случае прочих ошибок (например, неверные параметры, 
	или функция вызвана не из редактора).

	Параметр `Object` - над чем выполняется операция:

	`1`
	:	строка

	`2`
	:	положение курсора в строке

	`3`
	:	экранная позиция курсора

	`4`
	:	новая строка вверху экрана

	`5`
	:	позиция левой границы окна редактора

	`6`
	:	режим вставки

	Пример см. в разделе [Примеры].

`V=Editor.Sel(Action[,Opt])`
:	Функция позволяет производить некоторые операции с блоками в тексте
	(в редакторе, в строках ввода в диалогах, в командной строке).

	`Action`:

	`0`
	:	*получить параметры текущего блока*

		`Opt`:

		`0`
		:	вернуть номер строки начала блока

		`1`
		:	вернуть номер позиции в строке начала блока

		`2`
		:	вернуть номер строки конца блока

		`3`
		:	вернуть номер позиции в строке конца блока

		`4`
		:	вернуть тип выделенного блока:

			`0` - блок не выделен, `1` - обычный блок, `2` - вертикальный блок

		:	(альтернативный вариант - свойство [`Editor.State`][Editor.State])

	`1`
	:	*позиционировать курсор внутри текущего блока*

		`Opt`:

		`0`
		:	установить курсор в начало отмеченного блока

		`1`
		:	установить курсор в конец отмеченного блока

		При позиционировании курсора состояние блока не изменяется.

	`2`
	:	*установка позиций блока*

		`Opt`:

		`0`
		:	отметить позицию начала блока

		`1`
		:	отметить позицию конца блока

		Позицией начала/конца блока считается текущая позиция курсора.

		Блок помечается только после указания конечной позиции (`Opt=1`),
		с ранее выделенного блока пометка снимается.

		Если позиция начала и конца блока совпадают, то эта операция равносильна
		снятию пометки блока.

	`3`
	:	*установка позиций вертикального блока*

		`Opt`:

		`0`
		:	отметить позицию начала вертикального блока

		`1`
		:	отметить позицию конца вертикального блока

		Позицией начала/конца блока считается текущая позиция курсора.

		Блок помечается только после указания конечной позиции (`Opt=1`),
		с ранее выделенного блока пометка снимается.

		Если позиция начала и конца блока совпадают, то эта операция равносильна
		снятию пометки блока.

	`4`
	:	*снять выделение с блока*

		Параметр `Opt` игнорируется.

		Всегда возвращается `1`.

	В случае ошибки (в т. ч. функция вызвана не из *редактора*) возвращаемое значение равно `0`,
	иначе `1`.

	Для `Action=0` возвращается запрошенное значение.

	Например, повторим некоторые сочетания клавиш из *Turbo*-сред
	(~Ctrl+K+B~, ~Ctrl+K+K~, ~Ctrl+K+C~, ~Ctrl+K+Y~):

	~~~lua
	local SET = 2
	local START,END = 0,1
	Macro {
	  description="повторим некоторые сочетания клавиш из Turbo-сред";
	  area="Editor"; key="CtrlK";
	  action=function()
	    local k = mf.waitkey():lower()
	    local function KeyIs(key)
	      return k==key or k=="ctrl"..key
	    end
	    if KeyIs("b") then
	      Editor.Sel(SET,START)             -- пометить начало блока
	    elseif KeyIs("k") then
	      Editor.Sel(SET,END)               -- пометить конец блока
	    elseif KeyIs("c") then
	      Keys(Object.Selected and "CtrlC") -- копировать
	    elseif KeyIs("y") then
	      Keys(Object.Selected and "CtrlD") -- удалить
	    else
	      Keys("F1")
	    end
	  end;
	}
	~~~

`V=Editor.Set(Option[,Value])`
:	Получить/изменить настройки текущей копии редактора.

	`Option`:

	`0`
	:	`number`
	:	Размер табуляции

	`1`
	:	`number`
	:	Преобразование табуляции:

		`Value` может принимать следующие значения:

		- `0` - не преобразовывать табуляцию
		- `1` - преобразовывать все символы табуляции в пробелы
		- `2` - преобразовывать новые символы табуляции в пробелы

	`2`
	:	`number`
	:	Постоянные блоки

	`3`
	:	`number`
	:	Клавиша ~Delete~ удаляет блоки. Если есть помеченный блок, ~Delete~ будет
		удалять этот блок, а не символ под курсором.

	`4`
	:	`number`
	:	Автоотступ. Включает режим автоотступа при вводе текста.

	`5`
	:	`number`
	:	Автоопределение таблицы символов

	`7`
	:	`number`
	:	Разрешить перемещение курсора за пределы строки

	`8`
	:	`number`
	:	`Editor.BSLikeDel` (`far:config`).

		Задаёт поведение клавиши ~BackSpace~ в редакторе, когда выделен вертикальный блок.
		Если значение отлично от `0`, то ~BackSpace~ удаляет вертикальный блок
		подобно клавише ~Delete~.

	`9`
	:	`number`
	:	`Editor.CharCodeBase` (`far:config`).

		Представление кода символа под курсором в статусной строке.

		`Value` может принимать следующие значения:

		- `0` - восьмеричное значение (3 символа с ведущим нулями)
		- `1` - десятеричное значение (3 символа с ведущими пробелами)
		- `2` - шестнадцатеричное значение (2 символа под цифру + символ '`h`')

	`10`
	:	`number`
	:	Сохранять позицию файла

	`11`
	:	`number`
	:	Сохранять закладки

	`12`
	:	`string`
	:	`System.WordDiv` (`far:config`).

		Символы разделители слов.
		По умолчанию: ``~!%^&*()+|{}:"<>?`-=\[];',./``

	`14`
	:	`number`
	:	`Editor.AllowEmptySpaceAfterEof` (`far:config`)

		Окончание файла в редакторе всегда находится внизу экрана, если строк в файле
		больше чем строк экрана. При построчном скроллировании вниз (например, с помощью
		~Ctrl+Down~), скроллирование прекращается, когда показывается последняя строка.

		`Value` может принимать следующие значения:

		- `0` - прекратить скроллинг, если последняя строка внизу экрана
		- `1` - продолжать скроллинг, при этом:
		   a) поместить курсор за пределы файла по-прежнему нельзя
		   b) скроллинг с помощью ~Ctrl+Down~ сдвинет текст до курсора

	`15`
	:	`number`
	:	Показать полосу прокрутки в редакторе

	`16`
	:	`number`
	:	Редактировать открытые на запись файлы

	`17`
	:	`number`
	:	Выделять найденное - найденные последовательности будут выделены.

	`18`
	:	`number`
	:	Вести поиск с использованием регулярных выражений

	`19`
	:	`number`
	:	Cлово под курсором. При вызове диалога поиска/замены в строку поиска будет
		подставляться слово, на котором стоит курсор.

	`20`
	:	`number`
	:	Показывать в редакторе пробельные символы.

	Значение `Value` может быть опущено или равно `-1`, в этом случае функция ничего не изменит,
	а вернёт текущее значение настройки.

	Возвращает предыдущее значение опций или `-1`, если данные указаны некорректно,
	или функция вызвана не из редактора.

	Значения опции `16` изменить нельзя.

	Например, макрос, перемещающий выделенный фрагмент на одну строку
	(сохраняет выделение вне зависимости от настроек постоянных блоков):

	~~~lua
	local PERSISTENT = 2
	Macro {
	  description="перемещение выделенного фрагмента на одну строку вниз/вверх";
	  area="Editor"; key="CtrlShiftDown CtrlShiftUp"; flags="NoSendKeysToPlugins";
	  action=function()
	    if not Object.Selected then
	      Keys("Home CtrlIns")
	    end
	    local key = mf.akey(1,1):match("Down") or "Up"
	    mf.clip(5)
	    local a = Editor.Set(PERSISTENT,1) -- включить постоянные блоки
	    Keys("CtrlX",key,"CtrlV")
	    Editor.Set(PERSISTENT,a)           -- вернуть предыдущий режим
	  end;
	}
	~~~

`N=Editor.SetStr([S[,Line]])`
:	Заменить строку с номером `Line` на значение `S`.

	Если `S` не указан, то строка будет пустой.
	Если `Line` не указан или меньше `1`, то заменяется текущая строка.

	Позиция курсора в редакторе не меняется.

	Возвращает `1` для успешно выполненной операции или `0` - если редактор
	не в фокусе/редактор залочен/нет строки с запрашиваемым номером.

`E=Editor.SetTitle([Title])`
:	Установка заголовка в статусной строке редактора.

	Если параметр `Title` отсутствует или равен пустой строке, то восстанавливается
	предыдущее значение статусной строки.

	При показе заголовок будет усечён до размера, не затрагивающего служебную
	информацию (кодировка, позиция, etc.)

	Возвращает `1` для успешно выполненной операции или `0` - редактор не в фокусе.

`E=Editor.Undo(Action)`
:	Работа с *Undo/Redo*. Здесь `N` - одно из:

	`0`
	:	начало блочной операции

	`1`
	:	конец блочной операции

	`2`
	:	выполнить *Undo*

	`3`
	:	выполнить *Redo*

	Возвращает `1` для успешно выполненной операции или `0` в случае ошибки.
:::

Удаление пустых строк:

~~~lua
local GET = 0
local START_LINE, END_LINE = 0, 2
local BEGIN,END = 0,1
Macro {
  description="Удаление пустых строк";
  area="Editor"; key="CtrlShiftX";
  action=function()
    local StartLine, EndLine = 1, Editor.Lines
    if Object.Selected then
      StartLine = Editor.Sel(GET,START_LINE)
      EndLine = Editor.Sel(GET,END_LINE)
    end
    Editor.Undo(BEGIN)
    for i=EndLine,StartLine,-1 do
      if Editor.GetStr(i):match"^%s*$" then
        Editor.DelLine(i)
      end
    end
    Editor.Undo(END)
  end;
}
~~~


Стековые закладки
-----------------

:::functions
`E=BM.Push()`
:	Добавить закладку с текущими параметрами.

`E=BM.Pop()`
:	Восстановить параметры из последней закладки и удалить её.

`E=BM.Add()`
:	Добавить закладку с текущими параметрами и обрезать "хвост"
	(все закладки с индексом больше текущего).

`E=BM.Del([Idx])`
:	Удалить закладку с указанным индексом `Idx`.

	Если параметр `Idx` не указан или равен `0` - удаляется текущая закладка.

`E=BM.Clear()`
:	Очистить все закладки.

`E=BM.Next()`
:	Перейти на следующую закладку.

`E=BM.Prev()`
:	Перейти на предыдущую закладку.

`E=BM.Back()`
:	Перейти на предыдущую закладку.

	Если непосредственно перед ней была вызвана `BM.Add` - добавить перед переходом
	закладку с текущими параметрами.

`N=BM.Goto([Idx])`
:	Перейти на закладку с указанным индексом `Idx`.

	Если параметр `Idx` не указан или равен `0` - переход на текущую закладку.

`N=BM.Get(Idx,Param)`
:	Получить параметры закладки с индексом `Idx`. `Idx=0` - текущая закладка.

	Параметр `Param` может быть одним из следующих:

	`0`
	:	номер текущей строки

	`1`
	:	номер текущей колонки

	`2`
	:	номер первой видимой колонки на экране

	`3`
	:	номер первой видимой строки на экране

`N=BM.Stat([Param])`
:	Получить информацию о закладках.

	Параметр `Param` может быть одним из следующих:

	`0`
	:	текущее количество закладок

	`1`
	:	индекс текущей закладки (возвращает `0` если закладок нет)
:::

Пример работы с закладками:

Для редактируемого файла `newarc.ModuleManager.cpp` вставляет в начало

~~~cpp
#ifndef __NEWARC_MODULEMANAGER_CPP__
#define __NEWARC_MODULEMANAGER_CPP__
~~~

в конец

~~~cpp
#endif //! __NEWARC_MODULEMANAGER_CPP__
~~~

при наличии строки "`#pragma once`" в начале файла, строки вставляются после неё.

~~~lua
local ptnNameExt = "[^\\/]$"
local ptnTrim = "^%s*(.-)%s*$"
Macro {
  description="Пример работы с закладками";
  area="Editor"; key="CtrlShiftV";
  filemask="newarc.ModuleManager.cpp";
  action=function()
    local d = ("__%s__\n"):format(Editor.FileName:match(ptnNameExt):upper():gsub("%.","_"))
    BM.Add()
    Keys("CtrlHome")
    if Editor.Value:lower():match(ptnTrim)=="#pragma once" then
      Keys("Down")
    end
    mf.print(("#ifndef %s\tdefine %s"):format(d,d))
    Keys("CtrlEnd Enter Home")
    mf.print("#endif //! "..d)
    BM.Next()
    BM.Del()
  end;
}
~~~


### Замечания

* Нумерация строк в редакторе начинается с `1`.
* Нумерация колонок (позиций курсора в строке) начинается с `1`.
* Нумерация закладок начинается с `1`.


- - -
Смотрите также:

[Примеры]


[Примеры]: examples.md
[Editor.Sel]: ...
[Editor.State]: ...