% -*- mode: LaTeX; coding: koi8-r -*-
% $Id: rm_test_inf.tex,v 1.7 2004/04/29 04:12:21 cher Exp $
% Copyright (C) 2003,2004 Alexander Chernov <cher@unicorn.cmc.msu.ru>

\section{Файл описания теста \V{test.inf}}
\label{sectionTestInf}
\hypertarget{F:test.inf}{}

В данном разделе описывается формат файла описания теста. В нем
определяются такие характеристики теста, как аргументы командной
строки, передаваемые тестируемой программе, комментарий к тесту,
комментарий для участников (подсказка) к тесту.

\subsection{Использование}

Файлы описания тестов используются только в случае, если
конфигурационная переменная
\hyperlink{F:serve.cfg,S:problem,T:use_info}{\V{use\_info}} описания
задачи установлена в \I{true}. Для каждой задачи турнира этот флаг
может устанавливаться независимо от других задач. Если
конфигурационная переменная \V{use\_info} установлена, то для каждого
теста, определённого для задачи, должен существовать файл описания
теста. Эти файлы располагаются в каталоге, задаваемом конфигурационной
переменной \hyperlink{F:serve.cfg,S:problem,T:info_dir}{\V{info\_dir}}
описания задачи. Каждый файл описания теста должен называться
$\I{NUM}\V{.}\I{SFX}$, где \I{NUM} --- номер теста, которому он
соответствует, напечатанный тремя цифрами, включая ведущие
нули. \I{SFX} --- это суффикс файлов описания тестов, который по
умолчанию равен \V{.inf}, но может быть переопределён с помощью
конфигурационной переменной
\hyperlink{F:serve.cfg,S:problem,T:info_sfx}{\V{info\_sfx}}. Например,
если для некоторой задачи определены 3 теста и установлен флаг
\V{use\_info}, то в каталоге, определяемом переменной \V{info\_dir},
должны находиться файлы \V{001.inf}, \V{002.inf}, \V{003.inf} (при
условии, что используется значение переменной \V{info\_sfx} по
умолчанию).

Далее для удобства изложения файл описания теста мы будем называть
\V{test.inf}.

\subsection{Общая структура}

Файл \V{test.inf} представляет собой текстовый файл, аналогичный по
структуре файлу \hyperlink{F:serve.cfg}{\V{serve.cfg}}. Файл имеет
построчную структуру. Строки текста в файле, состоящие только из
пробельных символов, игнорируются. Содержимое строки от первого в ней
символа \V{\#} и до конца строки игнорируется.

Значимая строка в конфигурационном файле имеет следующий формат:
\begin{verbatim}
NAME = VALUE
\end{verbatim}
Здесь \V{NAME} --- это имя конфигурационной переменной. Имя
конфигурационной переменной может состоять из латинских заглавных и
строчных букв, цифр и символа подчёркивания. Все поддерживаемые
конфигурационные переменные описаны ниже. \V{VALUE} --- это значение
переменной. Допускается строка вида
\begin{verbatim}
NAME
\end{verbatim}
В этом случае \V{VALUE} полагается равным \V{1}.

\V{VALUE} может состоять из нескольких <<слов>>, аналогично
тому, как команда интерпретатора строки состоит из имени команды
и её аргументов. К \V{VALUE} применяется процедура разбиения
строки на слова, аналогичная процедуре, реализованной в
командном интерпретаторе \S{bash}. Пробельные символы в начале и
конце значения \V{VALUE} отбрасываются. Слова в \V{VALUE} ---
это последовательности символов отделённые друг от друга
произвольным числом пробельных символов. При разбиении на слова
учитываются специальные символы \verb|'|, \verb|"| и \verb|\|.

Символ \verb|'| начинает последовательность символов, которая
завершается первым символом \verb|'|. В этой последовательности
пробельные символы рассматриваются как обычные символы, и
символы \verb|"|, \verb|\| не работают как специальные. После
чтения такой последовательности символы \verb|'| с концов
отбрасываются.

Символ \verb|"| начинает последовательность символов, которая
завершается первым символом \verb|"|. В этой последовательности
пробельные символы рассматриваются как обычные символы, и
символы \verb|'|, \verb|\| не работают как специальные. После
чтения такой последовательности символы \verb|"| с концов
отбрасываются.

Символ \verb|\| воздействует на следующий за ним символ. Для
некоторых символов (пробельные, \verb|'|, \verb|"|) отменяется
их специальный смысл. Для других символов (\verb|n|, \verb|r|)
они интерпретируются как специальная запись управляющего кода
(как в языке Си). Кроме этого можно задавать код символа в
восьмеричной или шестнадцатеричной записи (как в языке Си).
Полное описание поддерживаемых последовательностей дано в
таблице \ref{tableTestInfEscapes}. Если подходят одновременно
несколько вариантов из данной таблицы, предпочтение отдаётся
варианту максимальной длины.

\begin{table}[ht]
\begin{center}
\begin{tabular}{|l|p{14cm}|}
\hline
\verb|\| $X$ $H_1 H_2$
& Задаёт символ с указанным шестнадцатеричным кодом. Здесь $X$
  --- символ \V{x} или \V{X}, $H_1$, $H_2$ --- шестнадцатеричные
  цифры (\V{[0-9a-fA-F]}). \\
\verb|\| $X$ $H_1$
& Задаёт символ с указанным шестнадцатеричным кодом. $H_1$ ---
  шестнадцатеричная цифра. \\
\verb|\| $O_1 O_2 O_3$
& Задаёт символ с указанным восьмеричным кодом. Здесь $O_1$ ---
  цифра от \V{0} до \V{3}, $O_2$ и $O_3$ --- восьмеричные цифры
  (\V{[0-7]}). \\
\verb|\| $O_1 O_2$
& Задаёт символ с указанным восьмеричным кодом. $O_1$, $O_2$ ---
  восьмеричные цифры. \\
\verb|\| $O_1$
& Задаёт символ с указанным восьмеричным кодом. $O_1$ ---
  восьмеричная цифра. \\
\verb|\a|
& Символ \verb|\a| в нотации языка Си. \\
\verb|\b|
& Символ \verb|\b| в нотации языка Си. \\
\verb|\f|
& Символ \verb|\f| в нотации языка Си. \\
\verb|\n|
& Символ \verb|\n| в нотации языка Си. \\
\verb|\r|
& Символ \verb|\r| в нотации языка Си. \\
\verb|\t|
& Символ \verb|\t| в нотации языка Си. \\
\verb|\v|
& Символ \verb|\v| в нотации языка Си. \\
\verb|\| $C$
& Символ $C$, здесь $C$ --- символ, не перечисленный выше. \\
\hline
\end{tabular}
\end{center}
\caption{Действие символа обратной косой черты}
\label{tableTestInfEscapes}
\end{table}

\B{Примеры.}

\I{Пример 1.}
\begin{verbatim*}
     a  b    c  
\end{verbatim*}
В данном случае строка будет разбита на три слова: \verb|a|,
\verb|b| и \verb|c|.

\I{Пример 2.}
\begin{verbatim*}
"  a "\ ' b ' ' "aa"  '
\end{verbatim*}
В данном случае строка будет разбита на два слова:
\verb*|  a   b | и \verb*| "aa"  |.

\subsection{Конфигурационные переменные}

В файле описания теста \V{test.inf} допускаются следующие
конфигурационные переменные:

\noindent
\begin{longtable}{|>{\ttfamily\small}l|>{\small}l|>{\small}p{8.5cm}|}
\hline
\rmfamily\normalsize Название & Стр. & Описание\\
\hline
\endhead

\hline
\multicolumn{3}{|r|}%
{\small\itshape Продолжение на следующей странице}\\
\hline
\endfoot

\hline
\endlastfoot

\strut\hyperlink{F:test.inf,T:comment}{comment}
  & \pageref{descTestInfComment}
  & Основной (судейский) комментарий к тесту. \\
\strut\hyperlink{F:test.inf,T:params}{params}
  & \pageref{descTestInfParams}
  & Параметры командной строки для тестируемой программы. \\
\strut\hyperlink{F:test.inf,T:team_comment}{team\_comment}
  & \pageref{descTestInfTeamComment}
  & Комментарий к тесту для участников. \\

\end{longtable}

\subsubsection{Переменная \V{comment}}
\label{descTestInfComment}
\hypertarget{F:test.inf,T:comment}{}

\begin{tabular}{@{}>{\bfseries}lp{10.5cm}}
Имя переменной:        & \K{comment} \\
Используются:          & \S{run} \\
Тип содержимого:       & \I{string}\\
Может отсутствовать:   & \I{да}\\
Значение по умолчанию: & \I{не установлено}\\
Может повторяться:     & \I{нет}\\
\end{tabular}

\B{Описание.} Данная конфигурационная переменная позволяет
задать комментарий к тесту. Текст комментария вставляется в
судейский протокол тестирования и недоступен участникам
турнира. Значение данной конфигурационной переменной должно быть
одним словом.

\B{Пример.}
\begin{verbatim}
comment = "Тест на отрицательные X"
\end{verbatim}

\subsubsection{Переменная \V{team\_comment}}
\label{descTestInfTeamComment}
\hypertarget{F:test.inf,T:team_comment}{}

\begin{tabular}{@{}>{\bfseries}lp{10.5cm}}
Имя переменной:        & \K{team\_comment} \\
Используются:          & \S{run} \\
Тип содержимого:       & \I{string}\\
Может отсутствовать:   & \I{да}\\
Значение по умолчанию: & \I{не установлено}\\
Может повторяться:     & \I{нет}\\
\end{tabular}

\B{Описание.} Данная конфигурационная переменная позволяет
задать комментарий к тесту для участников. Текст этого
комментария вставляется в протокол тестирования, доступный
команде-автору решения, если на данном тесте решение команды
дало неправильный результат. Значение данной конфигурационной
переменной должно быть одним словом.

\B{Пример.}
\begin{verbatim}
team_comment = "Проверьте диапазон переменной X!"
\end{verbatim}

\newpage
\subsubsection{Переменная \V{params}}
\label{descTestInfParams}
\hypertarget{F:test.inf,T:params}{}

\begin{tabular}{@{}>{\bfseries}lp{10.5cm}}
Имя переменной:        & \K{params} \\
Используются:          & \S{run} \\
Тип содержимого:       & \I{string}\\
Может отсутствовать:   & \I{да}\\
Значение по умолчанию: & \I{не установлено}\\
Может повторяться:     & \I{нет}\\
\end{tabular}

\B{Описание.} Данная конфигурационная переменная позволяет
установить параметры командной строки для тестируемой
программы. Значение данной переменной может состоять из
нескольких слов. Каждое слово будет отдельным параметром
командной строки.

\B{Пример.}
\begin{verbatim}
params = a b c
\end{verbatim}
В данном случае тестируемой программе будут переданы три
параметра командной строки: \V{a}, \V{b}, \V{c}. Как обычно,
нулевым параметром командной строки будет передан путь к самой
запускаемой программе. Таким образом, общее количество
параметров (значение аргумента \V{argc} в функции \V{main})
окажется равным 4.

\clearpage

% Local variables:
%  compile-command: "make"
% End:
