Go to the first, previous, next, last section, table of contents.


Команды для определений

Команда @deffn и другие команды для определений позволяют вам описывать функции, переменные, макросы, команды, пользовательские параметры, специальные формы и другие объекты в едином формате.

В Info-файле, определение вызывает появление в начале первой строки определения категории объекта -- `Функция', `Переменная' или другой, за которой идет имя объекта и его аргументы. В печатном руководстве, эта команда велит TeX печатать имя объекта и его аргументы с левого края, а название его категории -- с правого. В обоих выходных форматах для тела определения делается отступ. Также, имя объекта вносится в соответствующий именной указатель: @deffn вносит имя в указатель функций, @defvr в указатель переменных и так далее.

Руководство не должно и не может содержать более одного определения для заданного имени. Приложение, содержащее обзор, должно использовать @table, а не команды определений.

Шаблон определения

Команда @deffn используется для определений объектов, похожих на функции. Чтобы записать определение с помощью @deffn, напишите команду @deffn в начале строки и продолжите строку категорией объекта, именем объекта и его аргументами (если они есть). Потом напишите тело определения на последующих строках. (Вы можете вставлять в тело примеры.) И наконец, завершайте определение командой @end deffn, записанной на отдельной строке. (Другие команды для определений придерживаются того же формата.)

Шаблон определения выглядит так:

@deffn категория имя аргументы...
тело-определения
@end deffn

Например,

@deffn Команда forward-word счетчик
Эта команда перемещает точку вперед на столько слов, сколько задано
аргументом @var{счетчик} (или назад, если @var{счетчик}
отрицателен). ...
@end deffn

дает

Команда: forward-word счетчик
Эта команда перемещает точку вперед на столько слов, сколько задано аргументом счетчик (или назад, если счетчик отрицателен). ...

Пишите название категории с заглавной буквы. Если название категории содержит пробелы, как, скажем, `Интерактивная команда', заключайте его в фигурные скобки. Например:

@deffn {Интерактивная команда} isearch-forward
...
@end deffn

Иначе второе слово будет ошибочно принято за имя объекта.

Некоторые команды для определений имеют более общий смысл, чем другие. Команда @deffn, например, -- это общая команда для функций и похожих объектов: для объектов, которые могут принимать аргументы. Когда вы используете эту команду, вы задаете категорию, к которой принадлежит данный объект. Команда @deffn предлагает три предопределенных специализированных варианта, @defun, @defmac и @defspec, которые задают для вас категории "Функция", "Макро" и "Специальная форма", соответственно. (В Лиспе специальной формой называется объект, во многом похожий на функцию.) Команда @defvr также сопровождается несколькими предопределенными специализированными вариантами для описания конкретных типов переменных.

Шаблон для специализированного определения, такого как @defun, похож на шаблон общего определения, за исключением того, что вам не нужно задавать категорию:

@defun имя аргументы...
тело-определения
@end defun

Таким образом,

@defun buffer-end флаг
Эта функция возвращает @code{(point-min)}, если @var{флаг}
меньше 1, и @code{(point-max)} в противном случае.
...
@end defun

дает

Function: buffer-end флаг
Эта функция возвращает (point-min), если флаг меньше 1, и (point-max) в противном случае. ...

See section Пример определения функции, для получения более подробного примера определения функции, включающего использование @example внутри определения.

Другие специализированные команды работают подобно @defun.

Необязательные и повторяющиеся аргументы

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

Аргумент, заключенный в квадратные скобки является необязательным. Таким образом, фраза `[аргумент]' означает, что аргумент необязателен. Аргумент, после которого стоит многоточие, является необязательным и может быть повторен несколько раз. Таким образом, `аргумент...' обозначает ноль или более аргументов. Круглые скобки используются когда несколько аргументов сгруппированы в дополнительные уровни структуры списка в языке Лисп.

Вот, к примеру, строка @defspec для воображаемой специальной формы:

Special Form: foobar (var [from to [inc]]) body...

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

В исходном Texinfo-файле эта строка @defspec записана следующим образом (за исключением того, что он не была разбита на две строки, как в этом примере).

@defspec foobar (@var{var} [@var{from} @var{to}
     [@var{inc}]]) @var{body}@dots{}

Эта функция вносится в указатель команд и переменных под именем `foobar'.

Две или более "первых" строк

Чтобы создать две или более `первые' строки, напишите после первой строки @deffn строку, начинающуюся с @deffnx. Команда @deffnx работает в точности, как и @deffn, но не создает дополнительный вертикальный пропуск между ней и предыдущей строкой.

Например,

@deffn {Интерактивная команда} isearch-forward
@deffnx {Интерактивная команда} isearch-backward
Две эти команды аналогичны, за исключением ...
@end deffn

дает

Интерактивная команда: isearch-forward
Интерактивная команда: isearch-backward
Две эти команды аналогичны, за исключением ...

Каждая команда для определений имеет форму с `x': @defunx, @defvrx, etc.

Форма с `x' действует так же, как и @itemx; смотрите section @itemx.

Команды для определений

Texinfo предоставляет более дюжины команд для определений; все они описаны в этом разделе.

Команды для определений автоматически вносят имя объекта в соответствующий именной указатель: например, @deffn, @defun и @defmac вносят имена функций в указатель функций; @defvr и @defvar вносят имена переменных в указатель переменных.

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

Функции и похожие объекты

В этом разделе рассматриваются команды для описания функций и похожих объектов:

@deffn категория имя аргументы...
Команда @deffn -- это общая команда для функций, интерактивных команд и похожих объектов, которые могут принимать аргументы. Вы должны выбрать термин для описания категории, к которой принадлежит определяемый объект; например, если объект является функцией, то можно использовать категорию "Функция". Команда @deffn записывается в начале строки, а после нее на той же строке пишутся категория определяемого объекта, имя объекта и его аргументы, если таковые имеются. Завершайте определение с помощью @end deffn на отдельной строке. Например, вот определение:
@deffn Команда forward-char nchars
Переместить точку назад на @var{nchars} символов.
@end deffn
Этот пример показывает довольно сжатое определение "команды", называемой forward-char, с одним аргументом, nchars. @deffn печатает имена аргументов, таких как nchars, курсивом или заглавными буквами, как при использовании @var, потому что мы думаем об этих именах, как о метасинтаксических переменных --- они обозначают значения действительных аргументов. Внутри текста описания, чтобы сослаться на значение аргумента, пишите имя аргумента с явной командой @var. В примере выше мы использовали таким образом `@var{nchars}'. Шаблон для @deffn выглядит так:
@deffn категория имя аргументы...
тело-определения
@end deffn
@defun имя аргументы...
Команда @defun -- это команда для определений функций. @defun эквивалентна команде `@deffn Функция ...'. Например,
@defun set символ новое-значение
Изменить значение символа @var{символ} на
@var{новое-значение}.
@end defun
показывает довольно сжатое определение функции set с аргументами символ и новое-значение. Имена аргументов в строке @defun автоматически выводятся курсивом или заглавными буквами, как если бы они были заключены в @var. Завершайте определение с помощью @end defun на отдельной строке. Шаблон таков:
@defun имя-функции аргументы...
тело-определения
@end defun
@defun создает вхождение в указателе функций.
@defmac имя аргументы...
Команда @defmac -- это команда для определений макросов. @defmac эквивалентна `@deffn Макро ...' и работает подобно @defun.
@defspec имя аргументы...
Команда @defspec -- это команда для определений специальных форм. (В Лиспе специальной формой называется объект, во многом похожий на функцию, see section `Special Forms' in GNU Emacs Lisp Reference Manual.) @defspec эквивалентна `@deffn {Специальная форма} ...' и работает подобно @defun.

Переменные и похожие объекты

Ниже перечислены команды для определений переменных и похожих объектов:

@defvr категория имя
Команда @defvr -- это общая команда для определений объектов, схожих с переменными -- объектов, в которых записано значение. Вы должны выбрать термин для описания категории определяемого объекта; это может быть, например, "Переменная", если объект является переменной. Пишите команду @defvr в начале строки и, за ней на той же строке, категорию объекта и его имя. Пишите название категории с заглавной буквы, как заголовок. Если название категории содержит пробелы, как например "Пользовательский параметр", заключайте его в фигурные скобки. Иначе второе слово будет ошибочно принято за имя объекта. Например,
@defvr {Пользовательский параметр} fill-column
Эта локальная переменная задает максимальную
ширину заполненных строк.
...
@end defvr
Завершайте определение с помощью @end defvr на отдельной строке. Шаблон таков:
@defvr категория имя
тело-определения
@end defvr
@defvr создает для имени вхождение в указателе переменных.
@defvar имя
Команда @defvar -- это команда для определений переменных. @defvar эквивалентна команде `@defvr Переменная ...'. Например:
@defvar kill-ring
...
@end defvar
Шаблон таков:
@defvar имя
тело-определения
@end defvar
@defvar создает для имени вхождение в указателе переменных.
@defopt имя
Команда @defopt -- это команда для определений пользовательских параметров, то есть переменных, предназначенных для изменения пользователем по его вкусу; их много в Emacs (see section `Переменные' in Руководство по GNU Emacs). @defopt эквивалентна `@defvr {Пользовательский параметр} ...' и работает подобно @defvar.

Функции в языках с контролем типов

Команда @deftypefn и ее варианты предназначены для описания функций в языках, в которых вы должны объявлять типы переменных и функций, таких как Си и Си++.

@deftypefn категория тип-данных имя аргументы...
Команда @deftypefn -- это общая команда для определений функций и похожих объектов, которые могут принимать аргументы и имеют тип. Команда @deftypefn пишется в начале строки, и за ней на той же строке следуют название категории описываемого объекта, тип возвращаемого им значения, имя этого объекта и его аргументы, если таковые имеются. Например,
@deftypefn {Библиотечная функция} int foobar
   (int @var{foo}, float @var{bar})
...
@end deftypefn
(где текст перед "...", показанный выше как две строки, на самом деле был бы в настоящем Texinfo-файле на одной строке) дает в Info следующее:
-- Библиотечная функция: int foobar (int FOO, float BAR)
...
В печатном руководстве, это дает:

Библиотечная функция: int foobar (int foo, float bar)
...
Это означает, что foobar является "библиотечной функцией", которая возвращает int, а ее аргументы -- это foo (int) и bar (float). Имена аргументов, которые вы пишете в @deftypefn, не передаются неявно @var -- так как действительные имена аргументов в @deftypefn обычно разбросаны между именами типов данных и ключевыми словами, и Texinfo не может найти их без вашей помощи. Вместо этого вы должны явно писать @var вокруг имен аргументов. В примере выше, имена аргументов -- это `foo' и `bar'. Вот шаблон для @deftypefn:
@deftypefn категория тип-данных имя аргументы ...
тело-определения
@end deftypefn
Заметьте, что если категория или тип-данных занимает более одного слова, они должны быть заключены в фигурные скобки, чтобы стать одним аргументом. Если вы описываете процедуру в языке, в котором есть пакеты, таком как Ада, вам стоит использовать @deftypefn способом, несколько противоречащим описанным в предыдущих абзацах соглашениям. Например:
@deftypefn stacks private push
        (@var{s}:in out stack;
        @var{n}:in integer)
...
@end deftypefn
(Аргументы @deftypefn показаны разбитыми на три строки, но в действительном Texinfo-файле должны быть одной строкой.) В этом случае процедура классифицируется как принадлежащая к пакету stacks, а не как `процедура', и ее тип описывается как private. (Имя этой процедуры push, а ее аргументы -- это s и n.) @deftypefn создает для имени вхождение в указателе функций.
@deftypefun тип-данных имя аргументы...
Команда @deftypefun -- это специализированная команда для определений функций в языках с контролем типов. Эта команда эквивалентна `@deftypefn Функция ...'. Таким образом,
@deftypefun int foobar (int @var{foo}, float @var{bar})
...
@end deftypefun
дает в Info следующее:
-- Функция: int foobar (int FOO, float BAR)
...
и следующее печатном руководстве:

Function: int foobar (int foo, float bar)
...
Вот шаблон:
@deftypefun тип имя аргументы...
тело-определения
@end deftypefun
@deftypefun создает для имени вхождение в указателе функций.

Переменные в языках с контролем типов

Переменные в языках с контролем типов обрабатываются методом, похожим метод для функций в таких языках. See section Функции в языках с контролем типов. Общая команда для определений @deftypevr соответствует @deftypefn, а специализированная команда @deftypevar соответствует @deftypefun.

@deftypevr категория тип-данных имя
Команда @deftypevr -- это общая команда для определений объектов, похожих на переменные в языках с контролем типов -- объектов, в которых записано значение. Вы должны выбрать термин для описания категории определяемого объекта; это может быть, например, "Переменная", если объект является переменной. Команда @deftypevr записывается в начале строки, и за ней на той же строке следуют название категории описываемого объекта, тип данных и имя этого объекта. Например:
@deftypevr {Глобальный флаг} int enable
...
@end deftypevr
дает в Info следующее:
-- Глобальный флаг: int enable
...
и следующее в печатном руководстве:

Глобальный флаг: int enable
...
Шаблон такой:
@deftypevr категория тип-данных имя
тело-определения
@end deftypevr
@deftypevr создает для имени вхождение в указателе переменных.
@deftypevar тип-данных имя
Команда @deftypevar -- это специализированная команда для определений переменных в языках с контролем типов. @deftypevar эквивалентна `@deftypevr Переменная ...'. Например:
@deftypevar int fubar
...
@end deftypevar
дает в Info следующее:
-- Переменная: int fubar
...
и следующее в печатном руководстве:

Variable: int fubar
...
Шаблон такой:
@deftypevar тип-данных имя
тело-определения
@end deftypevar
@deftypevar создает для имени вхождение в указателе переменных.

Объектно-ориентированное программирование

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

В определении, если имя класса на самом деле является именем, определенным для класса в программной системе, вы должны окружать его @code, иначе в печатном руководстве оно будет напечатано шрифтом для обычного текста.

@defcv категория класс имя
Команда @defcv -- это общая команда для определений переменных, связанных с классами а объектно-ориентированном программировании. После команды @defcv следуют три аргумента: категория определяемого, класс, к которому оно принадлежит и его имя. Таким образом,
@defcv {Параметр класса} Window border-pattern
...
@end defcv
показывает, как вы могли бы написать первую строку определения параметра класса border-pattern для класса Window. Шаблон выглядит так:
@defcv категория класс имя
...
@end defcv
@defcv создает вхождение в указателе переменных.
@defivar класс имя
Команда @defivar -- это команда для определений переменных экземпляров в объектно-ориентированном программировании. @defivar эквивалентна `@defcv {Переменная экземпляра} ...' Шаблон выглядит так:
@defivar класс имя-переменной-экземпляра
тело-определения
@end defivar
@defivar создает вхождение в указателе переменных.
@deftypeivar класс тип-данных имя
Команда @deftypeivar -- это команда для определений типизированных переменных экземпляра в объектно-ориентированном программировании. Она похожа на @defivar, но добавляет параметр тип-данных для указания типа этой переменной экземпляра. @deftypeivar создает вхождение в указателе переменных.
@defop категория класс имя аргументы...
Команда @defop -- это общая команда для определений элементов, которые похожи на методы в объектно-ориентированном программировании. Такие элементы принимают аргументы, как функции, но связаны с конкретным классом объектов. Например, в некоторых системах есть конструкции, называемые обертками, которые связаны с классами, как и методы, но действуют во многом подобно макросам, а не как функции. Вы можете использовать @defop Обертка для описания одного из них. Иногда полезно различать методы и операции. Вы можете думать об операциях, как об описании для метода. Таким образом, оконная система может указать, что все классы окон имеют метод, называемый expose; вы могли бы сказать, что оконная система определяет операцию expose для окон вообще. Как правило, у операции есть имя, а также образец аргументов; все методы, реализующие операцию, должны принимать одинаковые аргументы, так как приложения, использующие эту операцию, используют ее, не зная, какой метод ее реализует. Часто более полезным оказывается документировать операции, а не методы. Например, разработчики оконных приложений должны знать об операции expose, но не обязаны быть в курсе, имеет ли данный класс окон собственный метод для реализации этой операции. Для описания этой операции, вы могли бы написать:
@defop Операция windows expose
Команда @defop записывается в начале строки, и за ней на той же строке следуют общее название категории операции, имя класса этой операции, ее имя и аргументы, если таковые имеются. Вот шаблон:
@defop категория класс имя аргументы...
тело-определения
@end defop
@defop создает вхождение, такое как `expose для windows', в указателе функций.
@deftypeop категория класс тип-данных имя аргументы...
Команда @deftypeop -- это команда определения для типизированных операций в объектно-ориентированном программировании. Она похожа на @defop, но в ней лобавлен параметр тип-данных для указания типа возвращаемого значения метода. @deftypeop создает вхождение в указателе функций.
@defmethod класс имя аргументы...
Команда @defmethod -- это команда для определений методов в объектно-ориентированном программировании. Метод -- это разновидность функции, которая реализует операцию для конкретного класса объектов и его подклассов. В Лисп-машине методы на самом деле были функциями, но обычно их определяли с помощью defmethod. @defmethod эквивалентна `@defop Метод ...'. Эта команда записывается в начале строки, и за ней на той же строке следуют имя класса этого метода, имя этого метода и его аргументы, если таковые имеются. Например,
@defmethod bar-class bar-method argument
...
@end defmethod
показывает определение метода, называемого bar-method, класса bar-class. Этот метод принимает один аргумент. Шаблон таков:
@defmethod класс имя-метода аргументы...
тело-определения
@end defmethod
@defmethod создает вхождение, такое как `bar-method для bar-class', в указателе функций.
@deftypemethod класс тип-данных имя аргументы...
Команда @deftypemethod -- это команда для определений методов в объектно-ориентированных языках с контролем типов, таких как Си++ и Java. Она похожа на команду @defmethod, но в ней добавлен параметр тип-данных для задания типа возвращаемого методом значения.

Типы данных

Здесь приведены команды для типов данных:

@deftp категория имя атрибуты...
Команда @deftp -- это общая команда для типов данных. Эта команда пишется в начале строки, и за ней на той же строке следуют название категории, имя этого типа данных (слово вроде int или float) и затем имена атрибутов объектов этого типа. Таким образом, вы можете использовать эту команду для описания int или float, в этом случае вы могли бы использовать в качестве категории слова тип данных. (Тип данных является категорией определенных объектов, предназначенной для решения, какие операции можно с ними производить.) Например, в Лиспе, парой называется некий тип данных, и объект этого типа имеет два гнезда, называемых CAR и CDR. Вот как вы могли бы написать первую строку определения для пары.
@deftp {Тип данных} пара car cdr
...
@end deftp
Вот шаблон:
@deftp категория имя-типа атрибуты...
тело-определения
@end deftp
@deftp создает вхождение в указателе типов данных.

Соглашения по написанию определений

Когда вы пишете определение с использованием @deffn, @defun или одной из других команд для определений, пожалуйста, используйте аргументы, указывающие свой смысл, как аргумент счетчик для функции forward-word. Также, если имя аргумента содержит имя его типа, позаботьтесь, чтобы аргумент в действительности был этого типа.

Пример определения функции

Определение функции использует команды @defun и @end defun. Имя этой функции следует сразу после команды @defun, а за ним на той же строке пишется список параметров.

Вот определение из @ref{Calling Functions,,,@external{elisp}, The GNU Emacs Lisp Reference Manual}.

Function: apply function &rest arguments
apply calls function with arguments, just like funcall but with one difference: the last of arguments is a list of arguments to give to function, rather than a single argument. We also say that this list is appended to the other arguments.

apply returns the result of calling function. As with funcall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense in apply.

(setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)

An interesting example of using apply is found in the description of mapcar.

В исходном Texinfo-файле, этот пример выглядит так::

@defun apply function &rest arguments
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended}
to the other arguments.

@code{apply} returns the result of calling
@var{function}.  As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.

@example
(setq f 'list)
     @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     @result{} 10
(apply '+ '(1 2 3 4))
     @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
     @result{} (a b c x y z)
@end example

An interesting example of using @code{apply} is found
in the description of @code{mapcar}.@refill
@end defun

В этом руководстве данная функция перечислена в указателе команд и переменных под именем apply.

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


Go to the first, previous, next, last section, table of contents.