Text/Docu/ru/Mappers.odc

TextMappers
ENGLISH

DEFINITION TextMappers;

	IMPORT Views, TextModels;

	CONST
		returnCtrlChars = 1; returnQualIdents = 2; returnViews = 3;
		interpretBools = 4; interpretSets = 5;
		maskViews = 6;
		char = 1; string = 3; int = 4; real = 5;
		bool = 6; set = 7; view = 8; tab = 9; line = 10; para = 11;
		lint = 16;
		eot = 30; invalid = 31;
		charCode = -1; decimal = 10; hexadecimal = -2;
		hideBase = FALSE; showBase = TRUE;

	TYPE
		String = ARRAY 256 OF CHAR;

		Scanner = RECORD
			opts-: SET;
			rider-: TextModels.Reader;
			type: INTEGER;
			start, lines, paras: INTEGER;
			char: CHAR;
			int, base: INTEGER;
			lint: LONGINT;
			real: REAL;
			bool: BOOLEAN;
			set: SET;
			len: INTEGER;
			string: String;
			view: Views.View; w, h: INTEGER;
			(VAR s: Scanner) ConnectTo (text: TextModels.Model), NEW;
			(VAR s: Scanner) SetPos (pos: INTEGER), NEW;
			(VAR s: Scanner) SetOpts (opts: SET), NEW;
			(VAR s: Scanner) Pos (): INTEGER, NEW;
			(VAR s: Scanner) Skip (OUT ch: CHAR), NEW;
			(VAR s: Scanner) Scan, NEW
		END;

		Formatter = RECORD
			rider-: TextModels.Writer;
			(VAR f: Formatter) ConnectTo (text: TextModels.Model), NEW;
			(VAR f: Formatter) SetPos (pos: INTEGER), NEW;
			(VAR f: Formatter) Pos (): INTEGER, NEW;
			(VAR f: Formatter) WriteChar (x: CHAR), NEW;
			(VAR f: Formatter) WriteInt (x: LONGINT), NEW;
			(VAR f: Formatter) WriteSString (x: ARRAY OF SHORTCHAR), NEW;
			(VAR f: Formatter) WriteString (x: ARRAY OF CHAR), NEW;
			(VAR f: Formatter) WriteReal (x: REAL), NEW;
			(VAR f: Formatter) WriteBool (x: BOOLEAN), NEW;
			(VAR f: Formatter) WriteSet (x: SET), NEW;
			(VAR f: Formatter) WriteTab, NEW;
			(VAR f: Formatter) WriteLn, NEW;
			(VAR f: Formatter) WritePara, NEW;
			(VAR f: Formatter) WriteView (v: Views.View), NEW;
			(VAR f: Formatter) WriteIntForm (x: LONGINT;
				base, minWidth: INTEGER; fillCh: CHAR; showBase: BOOLEAN), NEW;
			(VAR f: Formatter) WriteRealForm (x: REAL;
				precision, minW, expW: INTEGER; fillCh: CHAR), NEW;
			(VAR f: Formatter) WriteViewForm (v: Views.View; w, h: INTEGER), NEW;
			(VAR f: Formatter) WriteParamMsg (msg, p0, p1, p2: ARRAY OF CHAR), NEW;
			(VAR f: Formatter) WriteMsg (msg: ARRAY OF CHAR), NEW
		END;

	PROCEDURE IsQualIdent (IN s: ARRAY OF CHAR): BOOLEAN;
	PROCEDURE ScanQualIdent (VAR s: Scanner; OUT x: ARRAY OF CHAR; OUT done: BOOLEAN);

END TextMappers.


Модуль TextMappers содержит преобразователи, которые используют тектовых курьеров для сканирования и форматирования текста.


CONST returnCtrlChars
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, то сканер будет возвращать символы tab, line, и para; иначе эти управляющие символы трактуются как пробельные и игнорируются.

CONST returnQualIdents
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, то сканер будет возвращать "уточненные идентификаторы" (qualified identifiers) как одну строку; иначе сканер будет возвращать имена (name) и точку из которых состоит уточненный идентификатор по отдельности. (Строка, содержащая уточненный идентификатор, согласно определению языка Компонентный Паскаль имеет следующий синтаксис name ["." name].)

CONST returnViews
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, то сканер будет возвращать внедренные отображения; иначе они будут трактоваться как пробельные символы и игнорироваться.

CONST interpretBools
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, то сканер будет распозновать логические значения истинности "$TRUE" и "$FALSE" - как они выводятся форматтером при записи; иначе "$", "TRUE", и "FALSE" будут возвращаться по отдельности без интерпретации.

CONST interpretSets
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, сканер будет распознавать значения типа множество: множества целых из диапазона MIN(SET) .. MAX(SET) согласно синтаксису, определенному языком Компонентный Паскаль; иначе "{", ".", и вложенные целые будут возвращаться по отдельности. (Синтаксис значений-множеств следующий: {" integer [".." integer "]" { "," integer [".." integer] "}.)

CONST maskViews
Элемент множества опций
Элемент множества Scanner.opts. Если присутствует в множестве, то сканер будет пробовать обработать отображение как символ, если оно предпочитает маскироваться некоторым символом. Иначе, возвращается отображение.

CONST char
Возможное значение scanner.type, означающее, что был сосканирован обычный символ. Символы попадают в этот класс только в том случае, если они не являются первыми символами последовательностей, распознаваемых сканером и представляющих ниже указанные сканируемые типы.

CONST string
Возможное значение scanner.type, означающее, что была сосканирована строка.

CONST int
Возможное значение scanner.type, означающее, что было сосканировано целое число.

CONST real
Возможное значение scanner.type, означающее, что было сосканировано вещественное число.

CONST bool
Возможное значение scanner.type, означающее, что было сосканировано логическое значение.

CONST set
Возможное значение scanner.type, означающее, что было сосканировано множество.

CONST view
Возможное значение scanner.type, означающее, что было сосканировано внедренное отображение.

CONST tab
Возможное значение scanner.type, означающее, что был сосканирован символ tab.

CONST line
Возможное значение scanner.type, означающее, что был сосканирован символ line.

CONST para
Возможное значение scanner.type, означающее, что был сосканирован символ para.

CONST lint
Возможное значение scanner.type, означающее, что было сосканировано длинное целое.

CONST eot
Возможное значение scanner.type, означающее, что при последнем вызове Scan сканер находился в конце текста.

CONST invalid
Возможное значение scanner.type, означающее, что при последнем вызове Scan попалась синтаксически некорректная последовательность.

CONST charCode
Возможное значение параметра base процедуры formatter.WriteIntForm, означающее требование вывода целых как числовых литер Компонентного Паскаля. (Например, 0DX - код символа line, а 37X - код символа "7".)

CONST decimal
Возможное значение параметра base процедуры formatter.WriteIntForm, означающее требование вывода целых как десятичных чисел.

CONST hexadecimal
Возможное значение параметра base процедуры formatter.WriteIntForm, означающее требование вывода целых как шестнадцатеричных чисел.

CONST hideBase
Возможное значение параметра showBase процедуры formatter.WriteIntForm, означающее требование не выводить признак системы счисления.

CONST showBase
Возможное значение параметра showBase процедуры formatter.WriteIntForm, означающее требование выводить признак системы счисления.


TYPE String
Строка символов, распознаваемая сканерами.


TYPE Scanner
Сканеры, которые могут быть подключены к текстам. Они позволяют сканировать последовательости символов и внедренных отображений, которые формируют текст, распознавая структурированные подпоследовательности. Различные подпоследовательности, распознаваемые сканером, определены на основе сканируемых типов (см. константы выше).

opts-: SET
Параметры сканирования из множества {returnCtrlChars, returnQualIdents, returnViews, interpretBools, interpretSets, maskViews}.

rider-: TextModels.Reader
Курьер, подключающий сканер к тексту. Состояние курьера используется сканером как одноэлементный буфер предпросмотра. ,     :     rider.Read  rider.ReadPrev;      rider.Read.

type: INTEGER
Тип только что прочитанного значения. Одно из значений char, string, int, real, bool, set, view, tab, line, para, lint, eot, или invalid.

start: INTEGER
Начальное положение только что считанного значения. Устанавливается в scanner.Scan после изначального пропуска пробельных символов.

lines, paras: INTEGER
Число строк (символов line) и абзацев (символов para) обаруженных сканером с момента подключения. Обновляются в scanner.Skip (изначально вызывается в scanner.Scan) при пропуске пробельных символов.

char: CHAR	определено если type = char
Только что прочтенный символ. Строковое представление этого символа доступно после сканирования в string.

int: INTEGER	определено если type = int
Только что прочтенное целое. Строковое представление этого целого доступно после сканирования в (len, string).

base: INTEGER	определено если type IN {int, lint} 
Основание системы счисления, в которой было представлено только что прочтенное целое или длинное целое.

lint: LONGINT	определено если type IN {int, lint} 
Только что прочтенное длинное целое. Строковое представление этого длинного целого доступно после сканирования в (len, string).

real: REAL	определено если type = real
Только что прочтенное вещественное.

bool: BOOLEAN	определено если type = bool
Только что прочтенное логическое значение. Строковое представление этого значения доступно после сканирования в string.

set: SET	определено если type = set
Только что прочтенное множество.

len: INTEGER	определено если type IN {string, int, lint} 
Длина строки в поле string.

string: String	определено если type IN {string, int, lint, bool, char}
Только что прочтенная строка символов. Чтобы число было прочтено как строка, оно должно быть заключено в пару (двойных или одинарных) кавычек (например, если строка начинается с цифр, она будет интерпретироваться как число).

view: Views.View; w, h: INTEGER	определено если type = view
Только что прочитанное отображение, его ширина и высота.

PROCEDURE (VAR s: Scanner) ConnectTo (text: TextModels.Model)
Если сканер был подключен к некоторому тексту, он отключается от него. После сканер подключается к данному тексту (если text # NIL).

Постусловия
text = NIL
	s.rider = NIL
text # NIL
	s.rider.Base() = text
	s.Pos() = 0
	s.opts = {}

PROCEDURE (VAR s: Scanner) Pos (): INTEGER
Текущее положение предпросмотра сканера (положение курьера).

Предусловия
s.rider # NIL	явно не проверяется

Постусловия
result = s.rider.Pos()

PROCEDURE (VAR s: Scanner) SetPos (pos: INTEGER)
Установка положения сканера.

Предусловия
s.rider # NIL	явно не проверяется
предусловия s.rider.SetPos

Постусловия
s.Pos() = pos
s.start = pos
s.lines = 0
s.paras = 0
s.type = invalid

PROCEDURE (VAR s: Scanner) SetOpts (opts: SET)
Установка параметров сканирования.

Постусловия
s.opts = opts

PROCEDURE (VAR s: Scanner) Skip (VAR ch: CHAR)
Пропуск пробельных символов согласно параметрам сканирования извлекаемых из {returnCtrlChars, returnViews}.

Предусловия
s.rider # NIL	явно не проверяется

Постусловия
~s.rider.eot
	s.start = s.rider.Pos() - 1
s.rider.eot
	s.start = s.rider.Base().Length()
	s.type = eot

PROCEDURE (VAR s: Scanner) Scan
Сканирование в тексте следующего значения согласно параметров сканирования.

Предусловия
s.rider # NIL	явно не проверяется

Постусловия
s.rider.eot  OR  s.Pos() = s.start + Length(symbol) + 1


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

rider-: TextModels.Writer
Курьер, подключающий форматтер к тексту.

PROCEDURE (VAR f: Formatter) ConnectTo (text: TextModels.Model)
Если форматтер был подключен к некоторому тексту, он отключается от него. После форматтер подключается к данному тексту (если text # NIL).

Постусловия
text = NIL
	f.rider = NIL
text # NIL
	f.rider # NIL
	f.rider.Base() = text
	f.Pos() = text.Length()

PROCEDURE (VAR f: Formatter) Pos (): INTEGER
Положение форматтера.

Предусловия
f.rider # NIL	явно не проверяется

PROCEDURE (VAR f: Formatter) SetPos (pos: INTEGER)
Установка положения форматтера.

Предусловия
f.rider # NIL	явно не проверяется
предусловия f.rider.SetPos

Постусловия
f.Pos() = pos

PROCEDURE (VAR f: Formatter) WriteChar (x: CHAR)
Пишет символ x. Управляющие символы пишутся в виде числовой литеры, окруженной пробелами.

Предусловия
f.rider # NIL	явно не проверяется

Постусловия
x >= " "  &  x # 7FX
	записан сам символ
x < " "  OR  x = 7FX
	записаны " " code(x) " "

PROCEDURE (VAR f: Formatter) WriteInt (x: LONGINT)
Пишет целое, форматируя его по умолчанию.

За исключением производительности, равносильно:
	f.WriteIntForm(x, decimal, 0, TextModels.digitspace, showBase)

PROCEDURE (VAR f: Formatter) WriteReal (x: REAL)
Пишет вещественное, форматируя его по умолчанию.

За исключением производительности, равносильно:
	f.WriteRealForm(x, 7, 0, 0, TextModels.digitspace)

PROCEDURE (VAR f: Formatter) WriteString (x: ARRAY OF CHAR)
Пишет строку символов.

За исключением производительности, равносильно:
	VAR i: INTEGER;
	i := 0; WHILE x[i] # 0X DO f.WriteChar(x[i]); INC(i) END

PROCEDURE (VAR f: Formatter) WriteSString (x: ARRAY OF SHORTCHAR)
Пишет строку символов типа SHORTCHAR.

За исключением производительности, равносильно:
	VAR i: INTEGER;
	i := 0; WHILE x[i] # 0 DO f.WriteChar(x[i]); INC(i) END

PROCEDURE (VAR f: Formatter) WriteBool (x: BOOLEAN)
Пишет логическое.

За исключением производительности, равносильно:
	IF x THEN f.WriteString("$TRUE") ELSE f.WriteString("$FALSE") END

PROCEDURE (VAR f: Formatter) WriteSet (x: SET)
Пишет множество.

За исключением производительности, равносильно:
	VAR i: INTEGER;
	f.WriteChar("{"); i := MIN(SET);
	WHILE x # {} DO
		IF i IN x THEN
			f.WriteInt(i); EXCL(x, i);
			IF (i + 2 <= MAX(SET)) & (i + 1 IN x) & (i + 2 IN x) THEN
				f.WriteString("..");
				x := x - {i + 1, i + 2}; INC(i, 3);
				WHILE (i <= MAX(SET)) & (i IN x) DO EXCL(x, i); INC(i) END;
				f.WriteInt(i - 1)
			END;
			IF x # {} THEN f.WriteString(", ") END
		END;
		INC(i)
	END;
	f.WriteChar("}")

PROCEDURE (VAR f: Formatter) WriteTab
Пишет символ tab.

За исключением производительности, равносильно:
	f.rider.WriteChar(TextModels.tab)

PROCEDURE (VAR f: Formatter) WriteLn
Пишет символ line.

За исключением производительности, равносильно:
	f.rider.WriteChar(TextModels.line)

PROCEDURE (VAR f: Formatter) WritePara
Пишет символ para.

За исключением производительности, равносильно:
	f.rider.WriteChar(TextModels.para)

PROCEDURE (VAR f: Formatter) WriteView (v: Views.View)
Внедряет отображение.

За исключением производительности, равносильно:
	f.WriteViewForm(v, Views.undefined, Views.undefined)

Предусловия
v # NIL	20
v.context = NIL	21

PROCEDURE (VAR f: Formatter) WriteIntForm (x: LONGINT; base, minWidth: INTEGER;
																						fillCh: CHAR; showBase: BOOLEAN)
Пишет целое x. Строковое представление данного числа зависит от base (основание системы счисления в которую будет переводиться число). Конечное представление будет состоять как минимум из minWidth символов, для этого (при необходимости) оно дополняется слева нужным числом символов fillCh. Если представление не десятичное, showBase указывает, нужно ли включить основание base в представление. Для специального значения основания base = charCode выводится суффикс"X", в то время как для base = hexadecimal выводится суффикс "H". Все остальные недесятичные основания указываются добавлением "%", за которым следует само значение base. Недесятичные представления отрицательных целых формируются как дополнение по основанию шириной minWidth. Например, x = -3 при основании base = 16 и минимальной ширине minWidth = 2 будет выглядеть как "FD". Для отрицательных шестнадцатеричных чисел, fillCh игнорируется и вместо него используется символ "F".
Более подробное описание см. в документации по Strings.IntToStringForm.

Предусловия
f.rider # NIL	явно не проверяется
(base = charCode) OR (base = hexadecimal) OR ((base >= 2) & (base <= 16))	20
minWidth >= 0	22

PROCEDURE (VAR f: Formatter) WriteRealForm (x: REAL; precision, minW,
																							expW: INTEGER; fillCh: CHAR)
Пишет вещественное x. Строковое представление числа, в зависимости от expW, будет в формате с фиксированной точкой или научном. precision задает точность - число значащих десятичных цифр (обычно 7 для SHORTREAL и 16 для REAL). minW задает минимальную длину строкового представления. При необходимости, оно будет дополнено слева символами fillCh. Все числа округляются до последней видимой значащей цифры.
expW > 0: експоненциальное представление (научное) с как минимум expW цифрами в экспоненте.
expW = 0: представление в формате с фиксированной или плавающей точкой, в зависимости от x.
expW < 0: представление в формате с фиксированной точкой с как минимум -expW цифрами после десятичной точки.
Более подробное описание см. в документации по Strings.RealToStringForm.

Предусловия
f.rider # NIL	явно не проверяется
precision > 0	20
0 <= minW	21
expW <= 3	22

PROCEDURE (VAR f: Formatter) WriteViewForm (v: Views.View; w, h: INTEGER)
Внедряет отображение с шириной w и высотой h. w и h могут быть равны Views.undefined.

Предусловия
f.rider # NIL	явно не проверяется
v # NIL	20
v.context = NIL	21

PROCEDURE (VAR f: Formatter) WriteParamMsg (msg, p0, p1, p2: ARRAY OF CHAR)
Пишет строку с параметризированным сообщением, транслируя её при помощи процедуры Dialog.MapParamString. Результирующая строка может содержать символы line, para и tab, каждый из которых будет записан непосредственно.

Предусловия
f.rider # NIL	явно не проверяется

PROCEDURE (VAR f: Formatter) WriteMsg (msg: ARRAY OF CHAR)
Пишет строку с параметризированным сообщением, транслируя её с помощью процедуры Dialog.MapParamString.

За исключением производительности, равносильно:
	f.WriteParamMsg(msg, "", "", "")


PROCEDURE IsQualIdent (VAR s: ARRAY OF CHAR): BOOLEAN
Проверяет, удовлетворяет ли содержимое строки s синтаксису уточнённого идентификатора Компонентного Паскаля, т. е. ident ["." ident].

PROCEDURE ScanQualIdent (VAR s: Scanner; VAR x: ARRAY OF CHAR;
														VAR done: BOOLEAN)
При условии, что сканер прочитал строку, проверяет, могут ли последующие символы дополнить её до уточнённого идентификатора. Если прочтённая строка не является уточнённым идентификатором, то восстанавливается положение сканера до вызова ScanQualIdent.

Постусловия
s'.type = string
	IsQualIdent(s'.string)
		done = TRUE
		x = s'.string
		s = s'
	~IsQualIdent(s'.string)
		s'.Scan.type = char  &  s'.Scan.char = "."
			s'.Scan.Scan.type = string  &  (s'.len + 1 + s'.Scan.Scan.len < LEN(x))
				done = TRUE
				x = s'.string + "." + s'.Scan.Scan.string
				s = s'.Scan.Scan
			s'.Scan.Scan.type # string  OR  (s'.len + 1 + s'.Scan.Scan.len >= LEN(x))
				done = FALSE
		s'.Scan.type # char  OR  s'.Scan.char # "."
			done = FALSE
s'.type # string
		done = FALSE
~done
	s = s'.SetPos(s'.start).Scan()