Racket

Русский язык программирования Ади́на🔗ℹ

Клочков Роман <kalimehtar@mail.ru>

Документация основана на The Racket Guide.

Это руководство описывает русскоязычный язык программирования, основанный на идеях из расширения синтаксиса Scheme readable.

Название Ади́на взято из названия симпатичного кустарника и похоже на название цифры 1. Поэтому в дальнейшем для идентификации имени языка и расширения файлов на этом языке используется эта цифра. Использование кириллического имени не поддерживается в Racket, а использование иностранных слов неудобно, если вся остальная программа на русском.

Семантика языка на данный момент полностью унаследована от Racket, обеспечивая полную совместимость: из этого языка можно вызывать любые функции и синтаксические конструкции Racket, а из Racket можно вызывать модули Адины.

Для установки скачайте дистрибутив Racket с сайта. Затем запустите DrRacket, в меню Файл выберите "Install Package..." и в открывшемся окне введите "russian-lang".

Для включения синтаксиса данного языка просто укажите в модуле Racket в первой строке

#lang 1

или

#!1

Второй вариант рекомендуется при использовании русского языка для написания программы.

Можно использовать англоязычный вариант, написав во второй строке

english()

Тогда доступны все команды Racket, но по-прежнему работают отступы и операторы.

1 Основы языка🔗ℹ

Программа состоит из команд. Команда может быть вызовом функции, синтаксической конструкцией или определением переменной. Первая строка в программе определяет используемый язык программирования и является строкой #!1.

Комментарий начинается с литер --. и заканчивается концом строки.

Например, эта программа запрашивает имя и выводит приветствие:

#!1
вывести "введите имя: "
имя = прочитать-строку()
вывести
"Привет, " ++ имя

1.1 Простые значения🔗ℹ

Значения языка программирования включают числа, логические значения, строки и массивы байтов. В DrRacket и документации они выделены зелёным цветом.

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

10      2.5
1/3     10200000000000.0
5+6i    12345678123456781234567812345678

Бесконечные целые и простые дроби позволяют выполнять арифметические операции без потери точности и риска переполнения. Числа с десятичной точкой или экспонентой являются вещественными числами двойной точности и хранят только 15-17 литер.

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

Строковые значения записываются между двойными кавычками. Для записи кавычек используется последовательность литер \", для записи литеры \ — \\. Все остальные литеры Юникода можно писать как есть.

"Привет!"
"Автомобиль \"Москвич\""
"你好"

Второй вариант ввода строковых значений — между кавычками « и ». В этом случае внутри строки можно использовать двойные кавычки без обратной черты и при соблюдении парности можно писать кавычки внутри кавычек. Если парность нарушается, то также можно поставить обратную черту перед кавычкой: \« и \».

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

Примеры:

> 1.0000
1.0
> "\u0022ok\u0022"
"\"ok\""
> «Язык «Адина»»
"Язык «Адина»"
> «Кавычка \«»
"Кавычка «"
> «Кавычки " можно писать как есть»
"Кавычки \" можно писать как есть"

1.2 Выражения🔗ℹ

Выражение — это команда языка Адина, которая возвращает значение.

Выражения записываются в виде последовательности слов, разделённых пробельными литерами.

Обычно первое слово определяет синтаксис выражения. Если первое слово является функцией, то остальные слова — аргументы этой функции.

Примеры:

> список 1 2 3
'(1 2 3)
> пара 5 6
'(5 . 6)

Если какие-то аргументы также являются функциями, то можно использовать отступы

> список 1 2 3 4
список 5 6
7
'(1 2 3 (5 6) 7)

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

Если по какой-либо причине выписывать последние элементы по одному на строке некрасиво, например, если первый аргумент является командой, а остальные простыми значениями, то можно функцию писать в виде «функция(аргумент1 аргумент2 ...)». Предыдущий пример тогда будет выглядеть как

> список 1 2 3 4 список(5 6) 7
'(1 2 3 (5 6) 7)

Следует запомнить, что в таком случае скобка должна идти сразу за именем функции.

Ещё один альтернативный способ записи: в стиле лиспа. Можно просто взять всю команду в скобки:

> список 1 2 3 4 (список 5 6) 7
'(1 2 3 (5 6) 7)

и тогда внутри скобок переносы и отступы игнорируются.

Если строка очень длинная, то можно перед переносом вставить литеру \, тогда перенос не будет нести синтаксического смысла.

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

Также есть ещё две особые синтаксические конструкции: «список 1 2 3 4 список(5 6)» можно записать как «список 1 2 3 4 $ список 5 6», то есть оператор $ позволяет слова после неё выделить в отдельную команду. Чтобы объединить несколько коротких команд или значений в одну строку, можно использовать оператор ;.

Пример:

> список 1 2 3 4
список 5 6
7; список 8; 9
'(1 2 3 4 (5 6) 7 (8) 9)

Можно заметить, что перед ; пробел не обязателен.

Операторы $ и ; работают также и в скобках, но ; разбивает выражение на подвыражения равного уровня, то есть

Пример:

> (список; список 1 2; список 3 4)
'((1 2) (3 4))

Аналогичная конструкция для стандартного синтаксиса требует одинакового отступа для подвыражений, поэтому её корень будет пустым и замещаться ;:

Пример:

> ;
    список
    список 1 2
    список 3 4
'((1 2) (3 4))

Также внутри скобок можно использовать функциональный синтаксис со скобкой сразу после имени функции.

Пример:

> (список; список(1 2); список 3 4; список())
'((1 2) (3 4) ())

Некоторые слова являются операторами. Оператором является слово, состоящее только из литер !#$%&⋆+./<=>?@^~:*-, которые называются операторными литерами. Исключения: слова . и ... операторами не являются. Также оператором является любое слово, которое начинается и заканчивается на ^. Примеры операторов: +, -, ^пара^.

Если оператор встречается в команде и не является первым словом, то из выражений до оператора будет собрано одно выражение, а из выражений после — второе. Затем будет сформирована команда, в которой первым словом будет оператор, а его аргументами — эти два выражения. Например (список 2 3 ++ список 4 5 6) то же самое, что (++ (список 2 3) (список 4 5 6)). Особым образом обрабатываются операторы = и ?: выражения после них не объединяются в одно, а переносятся в результирующую команду как есть, потому что эти операторы требуют больше двух аргументов.

Если оператор начинается и заканчивается на ^ и между ними есть литеры кроме операторных, то он вызывает функцию по имени между ^ со своими аргументами. Например, (2 ^пара^ 3) то же самое, что (пара 2 3). Таким образом можно любую двухаргументную функцию использовать как оператор.

Если в строке несколько операторов, то порядок их применения определяется приоритетами. Например, (2 + 2 * 2) будет равно 6, как и должно с точки зрения приоритетов арифметических операторов: на первом шаге преобразуется в (+ 2 (2 * 2)), затем в (+ 2 (* 2 2)), и затем вычислится как (+ 2 4) = 6.

1.3 Основы определений🔗ℹ

При описании синтаксиса «...» обозначает, что предыдущий элемент может повторяться 0 и более раз, «...+» — 1 и более раз. В угловых скобках указываются синтаксические переменные. Например, вместо <идентификатор> может быть подставлен любой допустимый идентификатор языка.

Определение в форме

(<идентификатор> = <выражение>)

связывает <идентификатор> с результатом вычисления выражения, а в форме

(<идентификатор>(<идентификатор> ...) = <команда> ... <выражение>)

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

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

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

Примеры:

> часть = 3
> кусок строка =
подстрока строка 0 часть
> часть
3
> кусок "три литеры"
"три"

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

Примеры:

> испечь вкус =
вывести "разогрев печи...\n"
вкус ++ " пирог"
> испечь "вишнёвый"
разогрев печи...
"вишнёвый пирог"

Если попробовать записать функцию в одну строку, то получится

Примеры:

> не-печётся вкус = вкус ++ " пирог"
> не-печётся "вишнёвый"
" пирог"

Это потому, что определение прочитано как

не-печётся вкус =
  вкус
  ++
  " пирог"

и последовательно выполняется: вычисление значения переменной, значения операции и строки. Последнее возвращается как результат функции.

И, на самом деле, определение функции, так же, как и определение не функции, всего лишь связывает идентификатор с значением, и этот идентификатор можно тоже использовать как выражение.

Примеры:

> кусок
#<функция:кусок>
> подстрока
#<функция:подстрока>

1.4 Идентификаторы🔗ℹ

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

Примеры идентификаторов:

не-печётся
++
=
Проверка
проверка/вывод
а+б
с+1
1\;2\\3
|идентификатор со спецлитерами ( ) [ ] { } " , ' ` ; # \|

1.5 Вызовы функций🔗ℹ

Мы уже видели много вызовов функций. Синтаксис вызова

(<имя> <выражение> ...)

где количество выражений определяется количеством аргументов функции с именем <имя>.

Разумеется, при записи с начала строки скобки можно опустить.

Язык Адина предопределяет множество функций, таких как подстрока и добавить-строки. Ниже будут ещё примеры.

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

> добавить-строки "рос" "сель" "торг" -- добавить строки
"россельторг"
> подстрока "паровоз" 0 3 -- извлечь подстроку
"пар"
> строка? "это строка" -- распознать строку
истина
> строка? 42
ложь
> корень 16 -- вычислить квадратный корень
4
> корень -16
0+4i
> + 1 2 -- сложить
3
> - 2 2 -- вычесть
1
> < 2 2 -- сравнить
ложь
> >= 2 2
истина
> число? "это не число" -- распознать число
ложь
> число? 1
истина
> == 6 "шесть" -- сравнить что угодно
ложь
> == 6 6
истина
> == "шесть" "шесть"
истина

Если функция является оператором, то её можно писать вторым словом.

Примеры:

> 1 + 2 -- сложить
3
> 2 - 1 -- вычесть
1
> 2 < 1 -- сравнить
ложь
> 2 >= 1
истина
> 6 == "шесть" -- сравнить что угодно
ложь
> 6 == 6
истина
> "шесть" == "шесть"
истина

1.6 Условные конструкции с если и операторами ?, && и ||🔗ℹ

Следующий простейший вид выражения — это условное выражение:

(? <выражение-условия> <выражение-если-истина> <выражение-если-ложь>)

Первое выражение вычисляется всегда. Если его результат равен ложь, тогда условное выражение вычисляет выражение-если-ложь и возвращает его резулоьтат. Если же результат любой другой, то вычисляется и возвращается выражение-если-истина. Обратите внимание, что оба выражения (на истину и ложь) обязательны.

Оператор ? имеет три аргумента и поэтому обрабатывается особым образом. Слова слева от него объединяются в одно выражение, а слова справа остаются как есть, так же, как в определении функции.

Пример:

> 2 > 3 ?
"2 больше, чем 3"
"2 не больше, чем 3"
"2 не больше, чем 3"

Для следующих примеров необходимо ввести команду

> используется строка

чтобы была возможность использовать функции строка-начинается-с? и строка-заканчивается-на?.

ответ запрос =
строка-начинается-с? запрос "Привет" ? "Привет!" "Чего?"
> ответ "Приветствую, Адина!"
"Привет!"
> ответ "λx:(μα.α→α).xx"
"Чего?"

В случае, если при выполнении условия необходимо не только вернуть результат, но и выполнить какие-либо действия, есть вариант синтаксиса с ключевыми словами:

(если <выражение-условия> ... тогда <выражения-если-истина> ... иначе <выражения-если-ложь> ...)
(если <выражение-условия> ... тогда <выражения-если-истина> ...)

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

Пример:

ответ запрос =
  если строка-начинается-с? запрос "Привет" тогда
    "Привет!"
    иначе
    "Чего?"

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

Сложные условия могут формироваться путём вложения условных выражений. Например, в предыдущем примере в ответ должна передаваться строка, так как подстрока завершится с ошибкой, если ей передать не строку. Можно убрать это ограничение, добавив ещё одну проверку:

ответ-на-что-угодно запрос =
  строка? запрос ?
    строка-начинается-с? запрос "Привет" ?
      "Привет!"
      "Чего?"
    "Чего?"

Вместо того, чтобы дублировать ветку «Чего?», лучше записать эту функцию как:

ответ-на-что-угодно запрос =
  ?
    строка? запрос ?
      строка-начинается-с? запрос "Привет"
      ложь
    "Привет!"
    "Чего?"

Но такие вложенные условия сложно читать. Адина предоставляет удобочитаемые короткие формы:

(&& <выражение>*)
(|| <выражение>*)

Форма && выполняет выражения-аргументы. Если текущее выражение возвращает ложь, то остальные выражения не вычисляются. Возвращается результат последнего вычисленного выражения. Такой способ вычисления называется вычислением по короткой схеме.

Форма || аналогично выполняет выражения пока они возвращают ложь.

Также обратите внимание, что эти обе формы являются операторами, поэтому если выражений всего два, то можно ставить оператор между выражениями. Приоритет && выше, чем приоритет ||.

Примеры:

ответ-на-что-угодно запрос =
  строка? запрос && строка-начинается-с? запрос "Привет" ?
    "Привет!"
    "Чего?"
> ответ-на-что-угодно "Приветствую, Адина!"
"Привет!"
> ответ-на-что-угодно 17
"Чего?"

Обратите внимание, что здесь в одном выражении есть операторы && и ?. Так как приоритет оператора && выше, то сначала группируется всё выражение слева от ?, а потом уже результат сравнения используется как условие.

Обратите внимание, что && и || работают с любым количеством выражений:

Примеры:

ответ-на-восклицание запрос =
  ?
    &&
      строка? запрос
      строка-начинается-с? запрос "Привет"
      строка-заканчивается-на? запрос "!"
    "Привет!"
    "Чего?"
> ответ-на-восклицание "Приветствую, Адина!"
"Привет!"
> ответ-на-восклицание "Приветствую."
"Чего?"

То же самое можно сделать в операторном стиле:

ответ-на-восклицание запрос =
  строка? запрос && строка-начинается-с? запрос "Привет" \
                 && строка-заканчивается-на? запрос "!" ?
    "Привет!"
    "Чего?"

Как видно, пришлось сделать перенос строки, чтобы она была не слишком длинной. Выбирайте ту синтаксическую конструкцию, которую потом будет легче читать.

Часто вложенные условия используются для проверки последовательности условий, каждое из которых возвращает свой результат:

больше-ответов запрос =
  строка-начинается-с? запрос "Привет" ?
    "Привет!"
    строка-начинается-с? запрос "Пока" ?
      "Пока!"
      строка-заканчивается-на? запрос "?" ?
        "Я не знаю."
        "Чего?"

Короткая форма записи для последовательности проверок если без «тогда».

(если (<выражение> <команда> ... <выражение>) ...)

В этом варианте синтаксиса тело формы если состоит из последовательности правил. Каждое правило состоит из выражения и последовательности команд. Если выражение истинно (не равно ложь), то выполняется последовательность команд и возвращается результат последнего выражения. Если ложно, то аналогично обрабатывается следующее правило. В последнем правиле можно писать «иначе» вместо истина. Если команды вводят определения, то они видны только внутри правила.

Таким образом можно переписать функцию больше-ответов как:

больше-ответов запрос =
  если
    строка-начинается-с?(запрос "Привет") "Привет!"
    строка-начинается-с?(запрос "Пока") "Пока!"
    строка-заканчивается-на?(запрос "?") "Я не знаю."
    иначе "Чего?"
> больше-ответов "Приветствую!"
"Привет!"
> больше-ответов "Пока, Адина."
"Пока!"
> ответ-на-восклицание "Какой твой любимый цвет?"
"Я не знаю."
> больше-ответов "Мой зелёный."
"Чего?"

Обратите внимание, что условное выражение обязательно должно быть одним элементом. То есть оно либо должно быть одним словом, либо вызовом функции со скобками как в этом примере, либо просто взято в скобки. Кроме того, обязателен отступ после каждого условия или «иначе».

Если условное выражение очень сложное, то можно использовать синтаксис с «;» в качестве начала правила:

Пример:

ответ-на-восклицание запрос =
  если
    ;
      &&
        строка? запрос
        строка-начинается-с? запрос "Привет"
        строка-заканчивается-на? запрос "!"
      "Привет!"
    иначе
      "Чего?"

1.7 Вызовы функций, снова🔗ℹ

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

(<выражение> <выражение> ...)

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

удвоить п =
(строка? п ? добавить-строки +) п п
> удвоить "бла"
"блабла"
> удвоить 5
10

Если выражение, вычисляющее функцию достаточно сложно, то можно использовать синтаксис с «;» в начале вызова:

удвоить п =
  ;
    строка? п ? добавить-строки +
    п; п

Также не забывайте, что если используете оператор в качестве значения и он не на первом и не на последнем месте в выражении, то его надо писать в виде (. +).

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

> 1 2 3 4
вызов функции: ожидалась функция, которую можно применить к аргументам получено: 1

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

1.8 Безымянные функции🔗ℹ

Программирование было бы утомительным, если бы приходилось именовать все значения. Вместо того, чтобы написать 1 + 2, пришлось бы писать:

> а = 1
> б = 2
> а + б
3

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

> дважды ф п =
ф $ ф п
> дважды корень 16
2

Здесь ф $ ф п является бесскобочным вариантом ф (ф п). Если скобка заканчивается с концом команды, то вместо открывающей скобки можно поставить разделитель «$» и убрать закрывающую.

Если в функцию дважды надо передать ещё не определённую функцию, то её придётся сначала определить, а потом передать в дважды.

> громче строка =
строка ++ "!"
> дважды громче "Привет"
"Привет!!"

Но если вызов дважды — это единственное место, где используется громче, то жаль писать целое определение. В Адине можно использовать выражение функция, чтобы создавать функцию напрямую. Форма функция содержит список аргументов и команды тела функции.

(функция (<идентификатор> ...) <команда> ... <выражение>)

Вызов этой формы возвращает новую функцию:

> функция (строка)
строка ++ "!"
#<функция>

Короткий вариант — оператор ==>: слева аргументы, справа одно выражение-тело. Записи строка ==> строка ++ "!" и функция (строка) $ строка ++ "!" равносильны. Несколько аргументов перечисляются слева через пробел: с ч ==> подстрока с 0 ч. В отличие от функция, справа у ==> только одно выражение; несколько команд можно собрать в блок.

Приоритет ==> выше, чем у =, поэтому громче = строка ==> строка ++ "!" связывает имя с новой функцией.

Так вышеприведённый пример может быть переписан как:

> дважды
    функция (строка) $ строка ++ "!"
    "Привет"
"Привет!!"
> дважды
    строка ==> строка ++ "?!"
    "Привет"
"Привет?!?!"

Другое применение выражения функция и оператора ==> — результат для функции, принимающей функции.

> добавлятель-суффикса строка2 =
функция (строка) $ строка ++ строка2
> дважды добавлятель-суффикса("!") "Привет"
"Привет!!"
> дважды добавлятель-суффикса("?!") "Привет"
"Привет?!?!"
> дважды добавлятель-суффикса("...") "Привет"
"Привет......"

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

> громче = добавлятель-суффикса "!"
> неувереннее = добавлятель-суффикса "?"
> дважды неувереннее "действительно"
"действительно??"
> дважды громче "действительно"
"действительно!!"

Когда используется определение в форме <идентификатор> = <выражение>, то также можно определить функцию. Эти определения эквивалентны:

> громче строка =
строка ++ "!"
> громче = функция (строка)
строка ++ "!"
> громче = строка ==> строка ++ "!"
> громче
#<функция:громче>

Обратите внимание, что несмотря на то, что во втором случае используется безымянная функция, компилятор всё равно выводит имя функции, чтобы сделать печать и сообщения об ошибках максимально информативными.

Также можно и добавлятель-суффикса написать без использования формы функция.

> добавлятель-суффикса(строка2)(строка) = $ строка ++ строка2

1.9 Локальное связывание внутри функций и через выражение пусть🔗ℹ

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

> преобразовать строка =
    начинается? строка2 = -- видно только в функции «преобразовать»
      строка2-с-пробелом = строка2 ++ " " -- видно только в функции «начинается?»
      строка-начинается-с? строка строка2-с-пробелом
    если
      начинается?("Привет") "Привет!"
      начинается?("Пока") "Пока!"
      иначе "Чего?"
> преобразовать "Привет, мир!"
"Привет!"
> преобразовать "Приветствую, Земля!"
"Чего?"
> преобразовать "Пока, друзья."
"Пока!"
> преобразовать "Гы"
"Чего?"
> начинается? -- вне функции «преобразовать», поэтому ...
начинается?: не определено; не могу использовать идентификатор до его определения

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

> добавлятель-суффикса строка2 =
    результат строка =
      строка ++ строка2
    результат

Ещё один способ сделать ограниченную привязку — использование выражения пусть.

(пусть ((<имя> <выражение>) ...) <команда> ... <выражение>)

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

> а = 5
> пусть (а (а + 2); б (а - 1))
список а б
'(7 4)

В выражениях (а + 2) и (а - 1) используется значение «а», установленное перед формой пусть.

1.10 Списки, их перебор и рекурсия🔗ℹ

Адина семантически является диалектом языка Лисп. Поэтому в ней есть мощные встроенные средства работы со списками.

Функция список получает любое количество значений и возвращает список из этих значений.

> список "красный" "зелёный" "синий"
'("красный" "зелёный" "синий")
> список 1 2 3 4 5
'(1 2 3 4 5)

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

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

> длина $ список "раз" "два" "три" -- считаем элементы
3
> элемент-списка список("раз" "два" "три") 1 -- получаем элемент по номеру позиции
"два"
> список("раз" "два" "три")[0] -- то же самое оператором
"раз"
> добавить список("раз" "два") список("три") -- объединяем элементы
'("раз" "два" "три")
> список "раз" "два" ++ список "три" -- то же самое оператором
'("раз" "два" "три")
> подсписок "четыре" $ список "раз" "два" "три" -- проверяем наличие элемента
ложь

1.10.1 Предопределённые циклы по спискам🔗ℹ

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

Разные функции обработки элементов по-разному комбинируют результаты обработки. Функция отобразить собирает результаты выполнения обработки в новый список То есть математически отображает обрабатываемый список на новый список.

> отобразить корень $ список 1 4 9 16
'(1 2 3 4)
> отобразить
функция (с) $ с ++ "!"
список "орехи" "печенье" "шоколад"
'("орехи!" "печенье!" "шоколад!")

Функции отобразить/и и отобразить/или объединяют результаты через && и || соответственно.

> отобразить/и строка? $ список "а" "б" "в"
истина
> отобразить/и строка? $ список "а" "б" 6
ложь
> отобразить/или число? $ список "а" "б" "в"
истина

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

> отобразить
    функция (с ч) $ подстрока с 0 ч
    список "орехи" "печенье" "шоколад"
    список 4 6 3
'("орех" "печень" "шок")

Функция отобрать оставляет только те элементы, для которых результат функции не равен ложь.

> отобрать строка? $ список "а" "б" 6
'("а" "б")
> отобрать
функция (ч) $ ч > 0
список 1 -2 6 7 0
'(1 6 7)

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

> свернуть
    функция (элемент текущее)
      текущее + элемент * элемент
    0
    '(1 2 3)
14

1.10.2 Обход списка вручную🔗ℹ

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

Так как в Адине список является односвязным списком, то базовыми операциями для непустого списка являются:

первый: получает первый элемент списка
оставшиеся: получает оставшиеся элемент списка

Примеры:

> первый $ список 1 2 3
1
> оставшиеся $ список 1 2 3
'(2 3)

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

Примеры:

> пустой-список
'()
> пара "голова" пустой-список
'("голова")
> пара "белая" $ пара "голова" пустой-список
'("белая" "голова")

Также для конструирования можно использовать операцию :. Эта операция имеет группировку справа, то есть а : б : в трактуется как а : (б : в). И если точка стоит в конце выражения, то она трактуется как пустой список:

Примеры:

> "голова" : .
'("голова")
> "белая" : "голова" : .
'("белая" "голова")

Чтобы обработать список, надо иметь возможность отличать пустой список от непустого, потому что первый и оставшиеся работают только с непустыми списками. Функция пустой? выявляет пустые списки, а пара? непустые списки и пары, не являющиеся списками.

Примеры:

> пустой? пустой-список
истина
> пустой? $ пара "голова" пустой-список
ложь
> пара? пустой-список
ложь
> пара? $ пара "голова" пустой-список
истина

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

Примеры:

моя-длина сп =
  пустой? сп ?
    0
    1 + моя-длина $ оставшиеся сп
> моя-длина пустой-список
0
> моя-длина $ список "а" "б" "в"
3

моё-отобразить ф сп =
  пустой? сп ?
    пустой-список
    ф первый(сп) : моё-отобразить ф $ оставшиеся сп
> моё-отобразить прописные $ список "на старт" "внимание" "марш"
'("НА СТАРТ" "ВНИМАНИЕ" "МАРШ")

Алгоритмы для списочных структур удобно описывать через рекурсию как в вышеприведённых примерах. При реализации алгоритма для списка длины Н предполагаем, что для списка длины Н-1 реализация уже есть и описываем всего два варианта результата: значение для Н = 0 и вычисление для всех остальных, используя описываемую функцию для хвоста списка.

1.10.3 Хвостовая рекурсия🔗ℹ

И моя-длина и моё-отобразить при работе требуют место для хранения временных значений пропорционально длине обрабатываемого списка. Иначе говоря, использумая память О(n).

Это легко увидеть, если представить, как моя-длина $ список "а" "б" "в" должна вычисляться:

моя-длина $ список "а" "б" "в"
= 1 + моя-длина $ список "б" "в"
= 1 + (1 + моя-длина $ список "в")
= 1 + (1 + (1 + моя-длина пустой-список))
= 1 + (1 + (1 + 0))
= 1 + (1 + 1)
= 1 + 2
= 3

Для списка из n элементов вычисление будет запоминать операции сложения n раз и выполнять их только когда список закончится.

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

моя-длина сп =
  -- локальная функция цикл
  цикл сп н
    пустой? сп ?
      н
      цикл
        оставшиеся сп
        1 + н
  -- тело функции моя-длина - вызов функции цикл
  цикл сп 0

Теперь вычисление будет выглядеть так:

моя-длина $ список "а" "б" "в"
= цикл список("а" "б" "в") 0
= цикл список("б" "в") 1
= цикл список("в") 2
= цикл пустой-список 3
= 3

Переделанная моя-длина использует постоянный объём памяти для списков любой длины, как видно из шагов выполнения. То есть когда результатом выполнения функции является результат вызова другой функции (или той же с другими аргументами), то не обязательно запоминать состояние вычисления и ждать результата от того другого вызова, можно сразу подменить вызов текущей функции.

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

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

1.10.4 Рекурсия против цикла🔗ℹ

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

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

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

удалить-повторы сп =
  пустой? сп || пустой? оставшиеся(сп) ?
    сп
    первый сп == первый оставшиеся(сп) ?
      удалить-повторы $ оставшиеся сп
      первый сп : удалить-повторы $ оставшиеся сп
> удалить-повторы $ список "а" "б" "б" "б" "в" "в"
'("а" "б" "в")

В общем, эта функция использует память пропорционально длине обрабатываемого списка. Но это нормально, так как результат функции также пропорционален О(n). Но если обрабатываемый список состоит большей частью из повторов, то результат будет значительно меньше и функция удалить-повторы также будет использовать гораздо меньше памяти! Причина в том, что когда отбрасываются повторы, то происходит прямой вызов удалить-повторы и работает оптимизация хвостовых вызовов.

удалить-повторы $ список "а" "б" "б" "б" "б" "б"
= "а" : удалить-повторы $ список "б" "б" "б" "б" "б"
= "а" : удалить-повторы $ список "б" "б" "б" "б"
= "а" : удалить-повторы $ список "б" "б" "б"
= "а" : удалить-повторы $ список "б" "б"
= "а" : удалить-повторы $ список "б"
= "а" : список "б"
= список "а" "б"

1.10.5 Удобные циклы🔗ℹ

Когда нужно просто пройти по элементам, удобнее готовые формы цикл, цикл/список и цикл/первый, чем писать рекурсию вручную.

Форма цикл выполняет тело для каждого элемента последовательности. Результат тела обычно не важен — важны побочные эффекты:

цикл (элемент $ в-списке список(«а» «б» «в»))
вывести/перенос элемент

Справа от переменной цикла — последовательность. Часто это в-списке или в-диапазоне; число означает диапазон от нуля до этого числа (не включая):

цикл (номер 3)
вывести/перенос номер

выведет 0, 1 и 2.

Форма цикл/список собирает результаты тела в список — удобная замена рекурсии, которая в хвосте склеивает элементы через ::

цикл/список (элемент $ в-списке список(1 2 3))
элемент * 10

даст (list 10 20 30).

Форма цикл/первый останавливается на первом результате тела, который не ложь, и возвращает его. Если такого результата нет — ложь:

цикл/первый
  для
    сдвиг $ в-диапазоне 0 10
    #:когда $ сдвиг % 2 == 1
  сдвиг

вернёт 1: нечётные значения отбирает #:когда, а цикл/первый берёт первое из них.

Несколько переменных цикла и дополнительные ключи пишут после слова для:

цикл/список
  для
    слово $ в-списке список(«раз» «два» «три»)
    номер $ от-нуля()
  добавить-строки (число->строка номер) «:» слово

даст (list "0:раз" "1:два" "2:три"). от-нуля — бесконечная последовательность 0, 1, 2, …; цикл заканчивается вместе с более короткой последовательностью.

Ключи в заголовке цикла:

#:когда — выполнять тело, только если условие истинно;
#:когда-не — выполнять тело, только если условие ложно;
#:прервать — завершить цикл, когда условие истинно;
#:последняя — сделать текущую итерацию последней, если условие истинно.

1.11 Пары, списки и синтаксис Адины🔗ℹ

Функция пара (и соответствующая операция «:») на самом деле принимает любые два аргумента, а не только список в качестве второго аргумента. Если второй аргумент на создан при помощи этой функции и не является пустым списком, то результат выводится особым образом. Два значения, объединённые при помощи функции пара выводятся в скобках как список, но с точкой между ними.

> пара 1 2
'(1 . 2)
> пара "мир" "дверь"
'("мир" . "дверь")

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

Примеры:

> первый $ пара 1 2
1
> оставшиеся $ 1 : 2
2
> пара? пустой-список
ложь
> пара? $ 1 : 2
истина
> пара? $ список 1 2 3
истина

Наверное, чаще всего такие пары встречаются, когда при построении списка программист путает аргументы местами:

> пара список(2 3) 1
'((2 3) . 1)
> пара 1 список(2 3)
'(1 2 3)

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

Если второй элемент пара, но не список, то результат выводится так:

> 0 : 1 : 2
'(0 1 . 2)

В целом, можно считать, что запись через точку используется всегда, но если после точки идёт пара, то тогда убирается точка и та пара сразу пишется через пробел. Таким образом, ’(0 . (1 . 2)) сокращается до '(0 1 . 2), а ’(1 . (2 . (3 . ()))) сокращается до '(1 2 3).

1.11.1 Буквальный вывод пар и символов формой буквально🔗ℹ

Списки выводятся с апострофом перед ними, но если элемент списка тоже список, то апострофа перед ним нет.

> список список(1) список(2 3) список(4)
'((1) (2 3) (4))

Форма буквально позволяет писать списки таким же образом

> буквально "красный" "зелёный" "синий"
'("красный" "зелёный" "синий")
> буквально (1) (2 3) (4)
'((1) (2 3) (4))
> буквально ()
'()

Эта форма также позволяет писать через точку:

> буквально 1 . 2
'(1 . 2)
> буквально 0 1 . 2
'(0 1 . 2)

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

> список список(1 2 3) 5 список("a" "b" "c")
'((1 2 3) 5 ("a" "b" "c"))
> буквально (1 2 3) 5 ("a" "b" "c")
'((1 2 3) 5 ("a" "b" "c"))

Если в форму буквально передать идентификатор, то будет выведено нечто, выглядящее как идентификатор с апострофом перед ним.

> буквально иван-иванович
'иван-иванович

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

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

Фактически, символ хранит только строку со своим именем. В этом смысле символы и строки отличаются только тем, как они выводятся. Функции символ->строка и строка->символ преобразуют их друг в друга.

Примеры:

> отобразить
отобразить
> буквально отобразить
'отобразить
> символ? $ буквально отобразить
истина
> символ? отобразить
ложь
> функция? отобразить
истина
> строка->символ "отобразить"
'отобразить
> символ->строка $ буквально отобразить
"отобразить"

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

> первый $ буквально (имя фамилия)
'имя
> символ? $ первый $ буквально (имя фамилия)
истина

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

> буквально (имя фамилия)
'(имя фамилия)

Форма буквально не оказывает влияния на уже буквальные выражения, например, числа и строки:

> буквально 42
42
> буквально "для записи"
"для записи"

1.11.2 Сокращение буквально до апострофа🔗ℹ

Как уже возможно стало понятно, можно сократить форму буквально, просто ставя вместо неё апостроф.

> '(1 2 3)
'(1 2 3)
> ' 1 2 3
'(1 2 3)
> 'имя
'имя
> '((1 2 3) имя ("а" "б" "в"))
'((1 2 3) имя ("а" "б" "в"))

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

Апостроф преобразуется в буквально простой подстановкой:

> первый ''имя
'буквально
> первый '(буквально имя)
'буквально

При выводе аналогично. Если печататель видит символ 'буквально как первый элемент двухэлементного списка, то он вместо этого печатает апостроф:

> буквально буквально имя
'(буквально имя)
> '(буквально имя)
'(буквально имя)
> ''имя
'(буквально имя)

1.11.3 Списки и синтаксис Адины🔗ℹ

Синтаксис Адины не определяется напрямую в терминах потоков литер. Вместо этого синтаксис определяется двумя слоями:

слой читателя, который превращает литеры в списки, символы и другие константы.
слой раскрывателя, который преобразовывает получившиеся списки и константы в выражения.

Правила для чтения списков и выражений одинаковы. В частности, это позволяет использовать запись через точку при записи выражений:

> + 1 . (2)
3

Это работает, так как «+ 1 . (2)» всего лишь другой метод для записи «+ 1 . 2».

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

> буквально 2 + 2 * 2
'(+ 2 (* 2 2))

Это можно использовать, если есть сомнения в приоритете операторов или понимании сложной конструкции.

1.12 Сеть🔗ℹ

В Адине три вида соединений. Нужный модуль подключают командой используется. Функции описаны в справочнике.

Ненадёжное соединение — модуль ненадёжное-соединение. Соответствует протоколу UDP: обмен идёт отдельными пакетами, доставка и порядок не гарантируются.

Надёжное соединение — модуль надёжное-соединение. Соответствует протоколу TCP: это поток с гарантией доставки и порядка. Клиент подключается к узлу, сервер ждёт входящие подключения; обе стороны получают порты ввода и вывода.

Постоянное соединение — модуль постоянное-соединение. Строится поверх надёжного. Позволяет передавать сериализуемые значения Адины и автоматически восстанавливает связь, если она оборвётся. Подходят строки, числа, списки, массивы и другие данные, которые написать выводит в читаемом обратно виде. Функции, объекты и пусто так передать нельзя.

1.13 Быстрый код на Си++🔗ℹ

Если фрагмент программы нужно выполнить особенно быстро, его можно написать синтаксисом Адины внутри надо-быстро: при загрузке модуля этот код компилируется в Си++ (g++) и вызывается через FFI.

Семантика тела блока — из Си++, а не из Адины: обычные функции Адины внутри недоступны, зато через форму си можно включать любой код на Си++. Снаружи функции блока — обычные FFI-процедуры. Отладочный вывод — вывести (выводит в std::cout).

#!1
надо-быстро
  быстрый-код() целое =
    вывести "hello, world\n"
    вернуть 1

вывести/перенос формат("вернула ~a" быстрый-код())

Подробности — в Надо быстро.

1.14 Проверки🔗ℹ

Модуль проверки — обёртка над RackUnit. Подключается командой используется.

Форма проверки помещает тело в подмодуль test. Так проверки можно держать рядом с кодом, и они не мешают обычному запуску программы: срабатывают только когда файл проверяют как набор тестов.

#!1
используется проверки

сложить а б =
  а + б

проверки
  проверить-равно? (сложить 2 3) 5
  проверить-истину (число? (сложить 1 1))

Основные формы: проверить-равно?, проверить-не-равно?, проверить-истину, проверить-ложь, проверить-не-ложь, проверить-предикатом, проверить-=, проверить-исключение, проверить-без-исключения, проверка-случая, набор-проверок.

Запуск:

из командной строки — raco test файл.1 (или каталог: raco test каталог);
в DrRacket — при запуске файла (Run) по умолчанию выполняется и подмодуль test. Если проверки не срабатывают, в Language → Choose Language… → Show Details проверьте список Submodules to Run.

Подробности по формам — в Проверки.

2 Встроенные типы данных🔗ℹ

В предыдущей главе были рассмотрены некоторые встроенноые типы Адины: числа, логические, строки, списки и функции. Этот раздел предоставляет более полное описание встроенных типов для простых форм данных.

2.1 Логические выражения🔗ℹ

В Адине есть две константы для представления логических (булевых) значений: истина и ложь. Функция булево? распознаёт эти две константы. Но при использовании в если, ?, &&, ||, ... любое значение кроме ложь трактуется как истинное.

Примеры:

> 1 + 1 == 2
истина
> булево? истина
истина
> булево? ложь
истина
> булево? "нет"
ложь
> "нет" ? 1 0
1

2.2 Числа🔗ℹ

Числа в Адине бывают точные и неточные.

К точным числам относятся
- целые числа любой длины, такие как 5, 99999999999999999 или -17;
- рациональные числа, являющиеся дробью с целыми числителем и знаменателем, например, 1/2, 99999999999999999/2 или -3/4;
- комплексные числа с точными вещественной и мнимой частью, такие как 1+2i или 1/2+3/4i.
К неточным числам относятся
- вещественные числа в формате IEEE, такие как 2.0 и 3.14e+87, где бесконечности и не числа записываются как +inf.0, -inf.0, +nan.0 и -nan.0;
- комплексные числа с неточной вещественной или мнимой частью, такие как 2.0+3.0i или -inf.0+nan.0i.

Неточные числа выводятся с десятичной точкой или показателем экспоненты, а точные числа выводятся как целые числа или простые дроби. Такое же соглашение используется при чтении, но если необходимо, перед числом можно написать (латинскую) #e, тогда число будет прочитано как точное или #i — тогда оно будет прочитано как неточное. Префиксы (латинскими) #b, #o и #x позволяют вводить числа в двоичной, восьмеричной и шестнадцатеричной системах счисления.

Примеры:

> 0.5
0.5
> #e0.5
1/2
> #x03BB
955

Вычисление, включающее неточные числа (кроме логических операций), возвращает неточный результат, так что неточность действует на числа в каком-то смысле как зараза. Процедуры точное->неточное и неточное->точное позволяют преобразовывать точные и неточные числа друг в друга.

Примеры:

> 0.5
0.5
> 1 / 2
1/2
> 1 / 2.0
0.5
> 3.0 == 2.999 ? 1 2
2
> неточное->точное 0.1
3602879701896397/36028797018963968

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

Примеры:

> синус 0 -- рациональный результат
0
> синус 1/2 -- иррациональный результат
0.479425538604203

Вычисления с небольшими целыми числами производятся быстрее. Под небольшими подразумеваются числа, занимающие на несколько бит меньше, чем машинное представление знаковых чисел. Например, для 64-битной системы таковыми являются числа -1152921504606846976..1152921504606846975, но конкретные границы могут зависеть от используемой платформы. Для конкретного компьютера можно проверять при помощи функции небольшое-число?.

Вычисления с большими целыми числами или с точными нецелыми числами медленнее, чем вычисления с неточными числами.

сумма ф а б =
а == б ? 0
ф а + сумма ф (а + 1) б
> замерить-время $ округлить $ сумма (функция (ч) $ 1.0 / ч) 1 2000
время процессора: 24 реальное: 12 сборки мусора: 0
> замерить-время $ округлить $ сумма (функция (ч) $ 1 / ч) 1 2000
время процессора: 0 реальное: 0 сборки мусора: 0

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

Примеры:

> целое? 5
истина
> комплексное? 5
истина
> целое? 5.0
истина
> целое? 1+2i
ложь
> комплексное? 1+2i
истина
> комплексное? 1.0+2.0i
истина
> абс -5
5
> абс -5+2i
абс: нарушение контракта ожидалось: вещественное? получено: -5+2i
> синус -5+2i
3.6076607742131563+1.0288031496599335i

Операторы === и == сравнивают числа с учётом того, точное ли число

Примеры:

> 1 === 1.0
ложь
> 1 == 1.0
ложь
> 1 >= 1.0 && 1 <= 1.0
истина

Сравнение неточных чисел может приводить к неожиданным результатам. Даже достаточно простые неточные числа могут обозначать не то, что можно было бы подумать. Например, формат IEEE, будучи основанным на степенях двойки, может представить 1/2 точно, но 1/10 только приближённо.

Примеры:

> 1/2 >= 0.5 && 0.5 <= 1/2
истина
> 1/10 >= 0.1
ложь
> неточное->точное 0.1
3602879701896397/36028797018963968

2.3 Литеры🔗ℹ

Литеры Адины соответствуют кодам Юникода. Код Юникода можно трактовать как беззнаковое целое число, которое можно отобразить в 21 бит и которое соответствует символу естественного языка или части символа. Технически, код является более простым понятием, чем то, что в стандарте Юникода называется символом, но его достаточно в большинстве случаев. Например, любую акцентированную латинскую букву, любую кириллическую букву или любой обычный китайский иероглиф можно представить в виде кода.

Несмотря на то, что каждая литера Адины соответствует числу, литеральный тип отделён от числового. Функции литера->число и число->литера позволяют преобразовывать целые числа и соответствующие литеры друг в друга.

Печатные литеры обычно выводятся как #\ и отображаемая литера. Непечатные обычно выводятся как #\u и код литеры в виде шестнадцатеричного числа. Некоторые литеры печатаются особым образом: например, пробел и перенос строки выводятся как #\пробел и #\перенос.

Примеры:

> число->литера 1025
#\Ё
> литера->число #\Ё
1025
> #\λ
#\λ
> число->литера 17
#\u0011
> литера->число #\пробел
32

Функция вывести прямо пишет переданную литеру в текущий порт вывода, а не использует синтаксис для вывода литерных констант.

Примеры:

> #\Ё
#\Ё
> вывести #\Ё
"Ё"

2.4 Строки🔗ℹ

Строка — это массив литер фиксированной длины. Она выводится при помощи двойных кавычек (знаков дюйма). Если в строке встречается двойная кавычка, она выводится как \", если встречается обратная косая черта, то \\. Также, при помощи обратной косой черты выводятся пробельные литеры: \n — перенос строки, \r — возврат каретки. Большинство непечатных литер выводится как \u и четырёхзначный шестнадцатеричный номер литеры.

Функция вывести прямо пишет литеры строк, не используя синтаксис из предыдущего абзаца.

Примеры:

> "Пример"
"Пример"
> "\u03BB"
"λ"
> вывести "Пример"
Пример
> вывести "Пример с \"кавычками\""
Пример с "кавычками"
> вывести "две\nстроки"
две строки
> вывести "\u03BB"
λ

Строка может быть изменяемой или неизменяемой. Строки, введённые в тексте программы, являются неизменяемыми. Строки, полученные из функций, обычно изменяемые. Функция новая-строка создаёт изменяемую строку заданной длины и, при необходимости, заполняет её указанной литерой. Функция элемент-строки получает литеру на указанной позиции (нумерация начинается с нуля). Функция установить-элемент-строки! изменяет литеру в изменяемой строке. Вместо последних двух функций можно использовать синтаксис с квадратными скобками.

Примеры:

> элемент-строки "Эльбрус" 0
#\Э
> "Эльбрус"[0]
#\Э
> с = новая-строка 5 #\.
> с
"....."
> установить-элемент-строки! с 2 #\λ
> с
"..λ.."
> с[0] := #\ё
#\ё
> с
"ё.λ.."

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

Например, в Unicode «Ё» раньше, чем «Б», а в русском алфавите, наоборот:

Примеры:

> строки-возрастают? "Ёж" "Белка"
истина
> строки-возрастают?/местные "Ёж" "Белка"
ложь
> параметризуя
$ текущее-место ложь
строки-возрастают?/местные "Ёж" "Белка"
истина

Функция разделить-по-регулярному-выражению разбивает строку на части по вхождениям шаблона регулярного выражения. В качестве шаблона можно передать значение, полученное функцией регулярное-выражение, или литерал #rx"...".

Примеры:

> разделить-по-регулярному-выражению #rx"," "a,b,c"
'("a" "b" "c")

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

2.5 Байты и байтовые строки🔗ℹ

Байт — это точное целое число с 0 по 255. Предикат (то есть функция проверяющая условие) байт? позволяет определить, является ли значение байтом.

Примеры:

> байт? 0
истина
> байт? 256
ложь

Байтовая строка — это массив байтов фиксированной длины. Работа с ней аналогична работе со строкой, но вместо литер в байтовой строке хранятся байты. При выводе байтовой строки байты от 32 по 126 выводятся как литеры с этими номерами, но перед кавычкой и обратной чертой как и при выводе строк выводится обратная черта. Байты с 7 по 13 и 33 выводятся по их традиционным именам: #\a\b\t\n\v\f\r\e. Остальные выводятся в виде обратной черты и числа в восьмеричной кодировке.

Примеры:

> #"Elbrus"
#"Elbrus"
> элемент-байтов #"Elbrus" 0
69
> #"Elbrus"[0]
69
> новые-байты 3 65
#"AAA"
> а = новые-байты 2
> а
#"\0\0"
> установить-элемент-байтов! а 0 1
> а[1] := #o377
255
> а
#"\1\377"

Функция вывести выводит байтовую строку как поток байтов в порт вывода. Технически, вывод обычной (литерной) строки сводится к переводу строки в байты в кодировке UTF-8 и выводу полученных байтов в порт вывода, так как операционная система понимает вывод только в байтах.

Примеры:

> вывести #"Elbrus"
Elbrus
> вывести #"\316\273" -- λ в кодировке UTF-8
λ

Для явного преобразования между строками и байтами Адина поддерживает UTF-8 и местную кодировку операционной системы. Также есть функции для преобразования между произвольными кодировками.

Примеры:

> байты->строка #"\316\273"
"λ"
> параметризуя
$ текущее-место "C"
байты->строка/местные #"\316\273"-- кодировка C понимает только байты от 0 по 127
байты->строка/местные: строка байтов не является правильной в местной кодировке строка байтов: #"\316\273"

2.6 Символы🔗ℹ

Символ — это атомарное значение, которое выводится в виде идентификатора с апострофом перед ним. При вводе также: выражение из апострофа и идентификатора является символом.

Примеры:

> 'а
'а
> символ? 'а
истина

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

Примеры:

> 'а === 'а
истина
> 'а === строка->символ "а"
истина
> 'а === 'б
ложь
> 'а === 'А
ложь

При вводе и выводе идентификаторов с символами

( ) [ ] { } " , ' ` ; # | \

может использоваться экранирование при помощи | и \.

Примеры:

> строка->символ "один, два"
'|один, два|
> строка->символ "6"
'|6|

Функция написать выводит символ без апострофа. Функция вывести выводит имя символа как строку.

Примеры:

> написать 'символ
символ
> вывести 'символ
символ
> написать '|6|
|6|
> вывести '|6|
6

Функция новый-символ создаёт новый, ничему другому не равный символ. Её можно использовать для генерации значений, которые не могут встретиться в переданных данных.

2.7 Ключевые слова🔗ℹ

Ключевые слова похожи на символы и при вводе/выводе выглядят почти как символы из идентификаторов, начинающихся на #:.

Примеры:

> строка->ключевое-слово "тыква"
'#:тыква
> '#:тыква
'#:тыква
> '#:тыква === строка->ключевое-слово "тыква"
истина

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

Примеры:

> символ? '#:тыква
ложь
> ключевое-слово? '#:тыква
истина

Используются ключевые слова при работе с именованными параметрами функций и макросов.

Примеры:

> каталог = системный-путь 'временный-каталог-- здесь символ
> записывая-файл построить-путь (каталог "что-то.txt")
    функция () $ вывести "пример"
    -- именованный аргумент #:если-существует может быть ’заменить, ’обрезать, ...
    #:если-существует 'заменить

В описании синтаксиса ключевые слова для краткости называются ключами.

2.8 Пары и списки🔗ℹ

Пара объединяет два произвольных значения. Функция пара позволяет создавать пары. Функции первый и оставшиеся позволяют получать первый и второй элемент из пары, а функция пара? распознаёт пары. Для удобства записи вместо функции пара можно использовать оператор :. Этот оператор имеет правую ассоциативность, то есть 1 : 2 : 3 трактуется как 1 : (2 : 3). Это позволяет с его помощью описывать списки без лишних скобок.

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

Примеры:

> 1 : 2
'(1 . 2)
> (1 : 2) : 3
'((1 . 2) . 3)
> первый $ 1 : 2
1
> оставшиеся $ 1 : 2
2
> пара? $ 1 : 2
истина

Как правило, из пар составляется список. Тогда в первый элемент кладётся значение первого элемента списка, а во второй — список из оставшихся элементов. Список может быть либо парой, либо специальным значением пустой-список, представляющим пустой список.

Для его формирования можно использовать функцию список или конструкцию

значение1 : значение2 : последнее-значение : .

Эта конструкция аналогична

список значение1 значение2 последнее-значение

Список обычно выводится как апостроф ', после которого в скобках выводятся значения элементов списка.

Примеры:

> пустой-список
'()
> 0 : 1 : 2 : .
'(0 1 2)
> список? пустой-список
истина
> список? $ 1 : 2 : .
истина
> список? $ 1 : 2
ложь

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

Примеры:

> написать $ 1 : 2
’(1 . 2)
> вывести $ 1 : 2
’(1 . 2)
> написать $ список 1 2 "3"
’(1 2 "3")
> вывести $ список 1 2 "3"
’(1 2 3)

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

> отобразить
    функция (х)
      1 / х
    ' 1 2 3
'(1 1/2 1/3)
> отобразить/и
    функция (х)
      х < 3
    ' 1 2 3
ложь
> отобразить/или
    функция (х)
      х < 3
    ' 1 2 3
истина
> отобрать
    функция (х)
      х < 3
    ' 1 2 3
'(1 2)
> свернуть
    функция (сум х)
      х + сум
    10
    ' 1 2 3
16
> подсписок "осёл"
    ' "козёл" "осёл" "мартышка"
'("осёл" "мартышка")
> ассоциация 'где
    ' кто("Чебурашка") где("Москва") когда("Сейчас")
'(где "Москва")

2.9 Массивы🔗ℹ

Массив — это набор произвольных значений фиксированной длины.

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

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

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

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

Массив печатается подобно списку, но после апострофа ' добавляется решётка #. При вводе апостроф можно не писать. Также можно после решётки указать длину массива, тогда все элементы после явно указанных будут заполнены зхначением последнего.

Примеры:

> #(«а» «б» «в»)
'#("а" "б" "в")
> #(имя (список из четырёх элементов))
'#(имя (список из четырёх элементов))
> #4(два имени)
'#(два имени имени имени)
> #(имя (список из четырёх элементов))[1]
'(список из четырёх элементов)
> элемент-массива #(«а» «б» «в») 1
"б"

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

Пример:

> список->массив
отобразить прописные
массив->список #(«раз» «два» «три»)
'#("РАЗ" "ДВА" "ТРИ")

2.10 Соответствия🔗ℹ

Соответствие позволяет сопоставить произвольным значениям-ключам произвольные значения. Ключи сравниваются либо при помощи ==, если соответствие создано при помощи соответствие или новое-соответствие, либо при помощи ===, если соответствие создано при помощи соответствие=== или новое-соответствие===.

Пример:

> справочник = новое-соответствие()
> справочник[«яблоко»] := '(красное круглое)
'(красное круглое)
> установить-значение-соответствия! справочник «банан»'(жёлтый длинный)
> справочник[«яблоко»]
'(красное круглое)
> значение-соответствия справочник «яблоко»
'(красное круглое)
> значение-соответствия справочник «кокос»
значение-соответствия: нет значения для ключа ключ: "кокос"
> значение-соответствия справочник «кокос» «такого нет»
"такого нет"

2.11 Структуры🔗ℹ

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

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

Структура — это тип, у которого есть имя и набор именованных полей. Таким образом, можно различать структуры разных типов, даже если у них одинаковые поля. Объявление типа осуществляется формой структура.

В первом приближении синтаксис этой формы выглядит так:

(структура <имя> (<поле> ...))

Пример:

> структура позиция
ряд колонка

Форма структура создаёт функции для работы с определяемым типом и связывает с ними переданное имя, а также идентификаторы, полученные из имени и полей.

Из имени создаётся конструктор: функция, которая создаёт новую структуру с заданными значениями полей. У неё столько аргументов, сколько полей в описании структуры.

Пример:

> позиция 1 2
#<позиция>

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

Примеры:

> позиция? 3
ложь
> позиция? $ позиция 1 2
истина

Из имени структуры и имени поля создаётся функция чтения значения поля.

Примеры:

> позиция-ряд $ позиция 1 2
1
> позиция-колонка $ позиция 1 2
2

Можно добавить ключ суффикс, чтобы имя функции чтения значений было согласовано по падежам:

Примеры:

> структура позиция
ряд колонка
#:суффикс -позиции
> ряд-позиции $ позиция 1 2
1
> колонка-позиции $ позиция 1 2
2

Также можно делать структуру с изменяемыми полями. Тогда создаётся функция для установки значений полей путём добавления перед именем функции «установить-», а после имени восклицательного знака. Или можно устанавливать значения при помощи функции чтения и оператора :=.

Примеры:

> структура позиция
ряд(#:изменяемое) колонка
#:суффикс -позиции
> моя-позиция = позиция 1 2
> ряд-позиции моя-позиция
1
> ряд-позиции моя-позиция := 5
> ряд-позиции моя-позиция
5
> установить-ряд-позиции! моя-позиция 6
> ряд-позиции моя-позиция
6

Есть возможность сделать структуру-подтип. Тогда значения данного типа будут проходить проверку предикатом надтипа, у него будут все поля надтипа и к значениям можно применять все функции доступа надтипа. То есть, фактически, значения данного типа являются одновременно и значениями надтипа. Синтаксис для этого случая:

(структура <имя> <имя-надтипа> (<поле> ...))

Примеры:

> структура человек (имя) #:суффикс -человека
> структура ученик человек (класс) #:суффикс -ученика
> Вася = ученик «Вася» 5
> имя-человека Вася
"Вася"
> класс-ученика Вася
5

2.12 Классы🔗ℹ

Вышеприведённых типов данных уже достаточно для описания любоых данных.

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

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

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

Чтобы не переписывать надтип при добавлении каждой функции и иметь возможность иметь разные функции у разных иерархий объектов, были придуманы классы. Класс это тип, в котором описаны поля и функции (чтобы отличить от обычных, эти функции называются «методы»). Класс может быть наследниковм (подтипом) другого класса. Тогда в нём есть все поля и методы родительского класса, но методы можно переопределить. В отличие от структур, для вызова метода класса и для доступа к полю класса не используется имя типа. Поэтому можно единообразно обращаться к полям с одинаковыми именами или вызывать методы с одинаковыми именами для совершенно разных классов.

Значения классов традиционно называются объектами или экземплярами классов.

Чтобы работать с классами, сначала надо включить необходимую библиотеку.

> используется класс

Общая структура определения класса выглядит так:

(класс <имя-родительского-класса> <команда> ...)

По соглашению имена классов заканчиваются знаком процента. Встроенный класс без полей и методов объект% можно использовать как родителя для классов, которые ничего не должны наследовать.

Команды внутри класса выполняются при создании объекта. Среди команд обязательно должна быть ровно одна команда базовый-объект, выполняющая инициализацию данных, унаследованных от родительского объекта. Даже если этот родительский объект всего лишь объект%.

Определим, например, класс рыб с методами получить-размер, расти и кушать.

рыба% = класс объект%
  инициализировать размер
  текущий-размер = размер
  базовый-объект()
  методы получить-размер вырасти кушать
  получить-размер() = текущий-размер
  вырасти количество =
    текущий-размер := текущий-размер + количество
    пусто
  кушать другая-рыба =
    вырасти другая-рыба{получить-размер}

Теперь можно создавать объекты этого класса:

флаундер = объект рыба%
размер 10

Аргумент инициализации размер должен быть передан при создании объекта. Он доступен только в процессе инициализации и не может быть прочитан из метода. Поэтому значение этого аргумента мы сохраняем в поле текущий-размер.

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

> флаундер{вырасти 6}
> флаундер{получить-размер}
16
> вызвать-метод флаундер получить-размер
16

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

голодная-рыба% = класс рыба%
  базовый-объект()
  методы кушать-больше
  кушать-больше рыба1 рыба2 =
    этот{кушать рыба1}
    этот{кушать рыба2}

Или лучше использовать специальную команду унаследованные. Тогда к методу родителя можно обращаться как к своему и этот вызов работает быстрее.

голодная-рыба% = класс рыба%
  базовый-объект()
  методы кушать-больше
  унаследованные кушать
  кушать-больше рыба1 рыба2 =
    кушать рыба1
    кушать рыба2

Неважно, вызывается метод через прямой вызов или через этот, в любом случае работает переопределение методов.

разборчивая-рыба% = класс рыба%
  базовый-объект()
  переопределить вырасти
  вырасти количество =
    базовый вырасти (количество * 3/4)

> фрося = объект разборчивая-рыба% размер(20)
> фрося{кушать флаундер}
> фрося{получить-размер}
32

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

2.12.1 Аргументы инициализации🔗ℹ

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

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

> рыба-размером-10% = класс рыба% $ базовый-объект размер(10)
> объект(рыба-размером-10%){получить-размер}
10

2.12.2 Поля🔗ℹ

Как было сказано выше, поле можно определить равенством в контексте класса. Но бывает удобно сделать поле публичным. Если в классе рыба% вместо текущий-размер = размер написать команду поля текущий-размер (размер), то класс будет работать также, но появится возможность устанавливать значение поля напрямую:

> установить-поле! текущий-размер фрося
> объект(рыба-размером-10%){получить-размер}
10

3 Графический интерфейс🔗ℹ

Модули каталога "графический-интерфейс" дают русскоязычную оболочку над racket/gui/base: окна, кнопки, поля ввода, панели, меню и текстовый редактор. Классы Адины хранят внутри объект Racket (поле внутренний) и переводят имена методов, аргументов инициализации и событий.

Чтобы подключить сразу основные классы, напишите:

#!1
используется графический-интерфейс

Можно подключать отдельные файлы каталога, например графический-интерфейс/кнопка или графический-интерфейс/табличная-панель. Модуль графический-интерфейс сам подтягивает класс, поэтому отдельно писать (используется класс) не обязательно.

Объекты создаются формой объект, как в разделе Классы. Окно нужно показать методом показать:

#!1
используется графический-интерфейс

окно = объект главное-окно%
  заголовок "Привет"
  ширина 320
  высота 140

поле = объект текстовое-поле%
  родитель окно
  заголовок "Имя:"

объект кнопка%
  родитель окно
  заголовок "Сказать привет"
  команда
    функция (кнопка событие)
      вывести/перенос
        "Привет, " ++ поле{значение}

окно{показать истина}

Родитель элемента задаётся аргументом инициализации родитель. У кнопок действие передаётся аргументом команда (функция от элемента и события). У текстового поля текущая строка читается и записывается методом значение.

3.1 Как устроены классы🔗ℹ

Иерархия интерфейсов повторяет Racket GUI:

область<%> — общие размеры и растягивание;
окно<%> расширяет область: заголовок, показ, фокус, курсор;
подобласть<%> — поля (отступы) внутри вместилища;
подокно<%> — окно, которое живёт внутри родителя (кнопка%, надпись%, текстовое-поле%, панели);
вместилище<%> — контейнер элементов (группа%, панель%, главное-окно%);
вместилище-окно<%> — вместилище, которое само является окном;
главное-окно<%> — рамка или диалог верхнего уровня;
элемент-управления<%> — типичный виджет на панели;
картина<%> — холст или поле редактора.

События объявлены как методы с приставкой при- (при-закрытии, при-изменении-размера) или вопросом (можно-закрыть?). В базовых классах они ничего не делают или возвращают разумное значение по умолчанию; их можно переопределить в наследнике. Часть действий задаётся и колбэком при создании (команда у кнопки, при-изменении у поля, обработка у картины).

Многие методы работают как «геттер и сеттер»: без аргументов читают значение, с одним аргументом записывают его. Так устроены заголовок, значение, минимальная-ширина, выравнивание.

Символы стиля и выравнивания русские. Для выравнивания вместилища: 'лево, 'центр, 'право по горизонтали и 'верх, 'центр, 'низ по вертикали. Для текстового поля стиль по умолчанию '(однострочное); допустимы также 'многострочное и 'скрытая (элемент создан, но ещё не показан в родителе). У кнопки в стиле бывают 'граница, 'многострочная, 'скрытая.

Подробные описания интерфейсов, классов, аргументов инициализации и методов собраны в справочнике: Графический интерфейс. Классы и функции рисования — Рисование.

3.2 Окна и диалоги🔗ℹ

главное-окно% — окно верхнего уровня. Аргументы инициализации: заголовок (строка, по умолчанию пустая), ширина и высота (число или ложь — размер по содержимому), плюс общие аргументы вместилища: родитель, граница, интервал, выравнивание (по умолчанию '(центр верх)), минимальная-ширина, минимальная-высота, растягивается-ширина, растягивается-высота, включен.

Основные методы: показать, включить, заголовок, ширина, высота, переместить, установить-размер, установить-иконку, в-центр (направление 'оба, 'по-горизонтали или 'по-вертикали), создать-строку-состояния, показать-состояние, сфокусировать, обновить. События: можно-закрыть?, при-закрытии, при-активации, при-выходе, при-изменении-дисплея.

диалог% — модальное или вспомогательное окно. Те же аргументы инициализации и методы главное-окно<%>, что у главное-окно%.

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

область-уведомлений% — иконка в области уведомлений (Windows и Linux), модуль графический-интерфейс/область-уведомлений (подключается отдельно). Аргументы: заголовок (подсказка), иконка (по умолчанию 'сведения; ещё 'приложение, 'ошибка, 'вопрос, 'предупреждение, 'эмблема, 'пустая или результат загрузить-иконку), команда (функция от области и событие-мыши%). Методы показать и показано?; заголовок, иконка и команда читают и задают свойства.

Функция уведомление показывает системное уведомление (модуль графический-интерфейс/уведомление, подключается отдельно): заголовок, сообщение, приложение, иконка (путь или ложь), ожидание (секунды; по умолчанию 10). Windows — всплывающая подсказка в лотке, Linux — портал рабочего стола.

Интерфейс область<%> задаёт родитель, главное-окно, минимальная-ширина, минимальная-высота, минимальные-размеры-вывода, растягивается-ширина, растягивается-высота.

окно<%> расширяет область<%>. Показ и активность: показать, показано?, включить, включено?, есть-фокус?, сфокусировать. Геометрия: ширина, высота, лево, верх, размеры, внутренние-размеры, окно->экран, экран->окно. Прочее: заголовок, курсор, принимать-файлы, контекстное-меню, режим-колеса-мыши ('по-одному, 'по-целым, 'сразу).

главное-окно<%> расширяет вместилище-окно<%>. Дополнительно: пространство-событий, объект-в-фокусе, окно-в-фокусе, установить-иконку.

3.3 Вместилища: панели и группы🔗ℹ

группа% только раскладывает детей и сама не рисуется. панель% — видимый контейнер. Горизонтальные и вертикальные варианты задают направление раскладки.

группа% — контейнер без собственной рамки. Реализует вместилище<%> и подобласть<%>. Аргументы: родитель, граница, интервал, выравнивание (по умолчанию '(центр центр)), размеры и растягивание области, горизонтальные-поля, вертикальные-поля.

горизонтальная-группа% — дети слева направо. Выравнивание по умолчанию '(лево центр).

вертикальная-группа% — дети сверху вниз. Выравнивание по умолчанию '(центр верх).

панель% — видимая панель (вместилище-окно<%> и подокно<%>). Дополнительный аргумент стиль — список символов стиля.

горизонтальная-панель% — горизонтальная панель. Метод ориентация читает и задаёт направление.

вертикальная-панель% — вертикальная панель с тем же методом ориентация.

У вместилище<%>: элементы, добавить-элемент, удалить-элемент, изменить-элементы, начать-изменения и закончить-изменения (пакет обновлений раскладки), пересчитать-положения, граница, интервал, выравнивание.

Не входит в модуль графический-интерфейс, подключается отдельно:

табличная-панель% — панель-таблица из модуля графический-интерфейс/табличная-панель. Аргументы: измерения — список '(ряды колонки), по умолчанию '(1 1); заполнять — 'ряд или 'колонку; колонки-растягиваются и ряды-растягиваются — 'любая или 'каждая.

3.4 Элементы управления и меню🔗ℹ

кнопка% — кнопка. Аргументы: заголовок, родитель, команда (функция от кнопки и события; по умолчанию ничего не делает), шрифт (по умолчанию шрифт-элемента-управления), стиль, размеры и растягивание (по умолчанию кнопка не растягивается).

надпись% — статический текст или картинка-подпись. Аргументы: заголовок (строка или изображение), цвет, размер-по-заголовку. Методы цвет и размер-по-заголовку читают и меняют эти свойства.

текстовое-поле% — однострочное или многострочное поле. Аргументы: заголовок, значение (начальная строка, по умолчанию пустая), при-изменении (функция от поля и событие-управления), стиль (по умолчанию '(однострочное)), растягивается-ширина (по умолчанию истина). Метод значение читает и записывает текст.

список% — прокручиваемый список строк (список<%>). Аргумент элементы обязателен. стиль по умолчанию '(одиночный); ещё 'множественный и 'расширенный. команда вызывается при смене выделения; тип события — 'список или 'двойной-щелчок-по-списку.

поле-даты% — поле ввода даты из графический-интерфейс/поле-даты (отдельное подключение). Наследует текстовое-поле%.

строка-меню% — строка меню окна. Аргумент родитель — главное окно или диалог.

меню% — выпадающее меню. Аргументы родитель и заголовок.

пункт-меню% — пункт меню. Аргументы: родитель, заголовок, действие (колбэк). Методы интерфейсов пункт-меню<%> и пункт-меню-с-заголовком<%>: удалить, восстановить, удалён?, родитель, заголовок, включить, включён?, строка-помощи.

3.5 Шрифты и события🔗ℹ

шрифт% описывает шрифт. Аргументы инициализации: размер (12), семейство, имя, стиль ('нормальный, 'наклонный, 'курсив), насыщенность ('тонкая, 'светлая, 'нормальная, 'жирная, 'тяжёлая и промежуточные значения в том же ряду), подчёркнутый?, сглаживание ('стандартное, 'частичное, 'полное, 'отсутствует), размер-в-пикселях?, округлять-метрики?, свойства. Методы с теми же именами читают параметры.

шрифт-элемента-управления — шрифт, совпадающий со стандартным шрифтом элементов управления.

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

буфер-обмена — системный буфер обмена (буфер-обмена<%>). Методы получить-строку и установить-строку читают и записывают текст; время — метка времени события, по умолчанию 0.

событие% — базовое событие с методом время. События мыши, клавиатуры и элементов управления создаются обёртками при доставке в методы Адины. У события мыши: тип ('вход, 'выход, 'левая-нажата, 'левая-отпущена, 'средняя-нажата, 'средняя-отпущена, 'правая-нажата, 'правая-отпущена, 'движение), лево, верх, нажата-кнопка? и отпущена-кнопка? с аргументом 'левая, 'правая, 'средняя или 'любая. У события управления тип бывает 'кнопка, 'текстовое-поле, 'ввод-в-текстовом-поле, 'меню, 'флажок и другие значения из того же словаря.

3.6 Картина, редактор и куски🔗ℹ

картина% — холст для рисования. Аргумент обработка — функция от картины и холста, вызываемая при перерисовке. Методы картина<%>: холст, фон, отрисовать-немедленно.

поле-редактора% — холст редактора. Аргумент редактор — объект текст% или другой редактор<%>.

текст% — текстовый редактор. Аргументы: межстрочный-промежуток (1.0), автоматический-перенос. Методы: вставить, очистить, только-просмотр, найти-позицию, найти-кусок, изменить-стиль, последняя-позиция, начало-выделения, конец-выделения, текст, установить-выделение, конец-абзаца, первый-кусок.

Функция для-каждого-куска вызывает переданную функцию для каждого куска документа по порядку.

кусок% — фрагмент документа редактора. Методы: следующий, предыдущий, текст, количество, параметры, стиль, скопировать.

кусок-со-строкой% — текстовый кусок. Аргумент содержимое — строка или начальный размер.

кусок-с-изображением% — кусок-картинка. Метод изображение читает и задаёт растр.

кусок-с-редактором% — вложенный редактор. Аргументы редактор и есть-граница.

Стили редактора живут в графический-интерфейс/стиль (список-стилей%, стиль%, отклонение-стиля%), привязки клавиш — в графический-интерфейс/набор-команд (набор-команд%).

3.7 Файлы каталога🔗ℹ

Коллекция "1/графический-интерфейс" соответствует модулю графический-интерфейс и его подмодулям:

Модуль		Что экспортирует
графический-интерфейс		сводка: окна, диалог, виджеты, меню, шрифт, редактор, куски
графический-интерфейс/главное-окно		главное-окно%
графический-интерфейс/диалог		диалог%, получить-файл
графический-интерфейс/область-уведомлений		область-уведомлений%, загрузить-иконку
графический-интерфейс/уведомление		уведомление
графический-интерфейс/кнопка		кнопка%
графический-интерфейс/список		список%
графический-интерфейс/списочный-интерфейс		список<%>
графический-интерфейс/меню		меню%, строка-меню%, пункт-меню%, всплывающее-меню%
графический-интерфейс/надпись		надпись%
графический-интерфейс/текстовое-поле		текстовое-поле%
графический-интерфейс/поле-даты		поле-даты%
графический-интерфейс/панель		панель%, горизонтальная и вертикальная
графический-интерфейс/группа		группа%, горизонтальная и вертикальная
графический-интерфейс/табличная-панель		табличная-панель%
графический-интерфейс/шрифт		шрифт%, шрифт-элемента-управления, на-основе-шрифта
графический-интерфейс/картина		картина%
графический-интерфейс/поле-редактора		поле-редактора%
графический-интерфейс/текст		текст%, кусок%, для-каждого-куска
графический-интерфейс/событие		событие% и обёртки событий
графический-интерфейс/буфер-обмена		буфер-обмена, буфер-обмена<%>
графический-интерфейс/стиль		список стилей, стиль, отклонение
графический-интерфейс/набор-команд		набор-команд%
графический-интерфейс/объект		общий предок виджетов Адины
графический-интерфейс/интерфейс-…		интерфейсы и синтаксис методов для остальных файлов

4 Справочник🔗ℹ

4.1 Синтаксические формы🔗ℹ

синтаксис
(идентификатор = выражение)
(значения идентификатор ... = выражение)
(заголовок(аргументы) = команда ... выражение)

заголовок = идентификатор
| (заголовок аргументы)

аргументы = аргумент ...
| аргумент ... . аргумент-оставшихся

аргументы = идентификатор
| [идентификатор выражение]
| ключ идентификатор
| [ключ идентификатор выражение]

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

синтаксис
(идентификатор := выражение)
(значения идентификатор ... := выражение)
(выражение-коллекция[индекс] := выражение)
(доступ-к-полю выражение-структура := выражение)

Эта команда позволяет изменить значение существующей переменной. Первые две формы аналогичны первым двум формам команды = и позволяют изменить значение определённых ранее переменных. Третья форма позволяет при помощи квадратных скобок изменить значение элемента изменяемой коллекции: массива, строки, соответствия или списка. Учитывайте, что для списка время доступа пропорционально номеру элемента. Четвёртая форма позволяет изменить значение изменяемого поля структуры. Результатом этой команды является значение выражения.

синтаксис
(структура имя (поле ...) параметр ...)
(структура имя надструктура (поле ...) параметр ...)

поле = идентификатор
| (идентификатор #:изменяемое)

параметр = #:суффикс идентификатор
| #:префикс идентификатор
| #:читаемая

Описывает тип структуры. Создаёт функции для создания структур и доступа к полям. Имя функции для создания совпадает с именем структуры. Имя функции для проверки типа создаётся путём склеивания имени структуры и вопросительного знака. Имя функции для доступа к поля создаётся путём склеивания префикса, имени поля и суффикса. Если ни префикс ни суффикс не указаны, считается, что префиксом является склейка имени структуры и дефиса. Если у поля указан ключ #:изменяемое, для него осоздаётся функция изменения путём склейки слова «установить», дефиса, имени функции доступа и восклицательного знака.

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

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

синтаксис
(функция (аргументы) = команда ... выражение)

аргументы = аргумент ...
| аргумент ... . аргумент-оставшихся

аргумент = идентификатор
| (идентификатор выражение)
| ключ идентификатор
| (ключ идентификатор выражение)

Возвращает функцию с указанными аргументами и телом.

оператор
(аргументы ==> выражение)

аргументы = идентификатор
| (идентификатор ...)

Возвращает функцию с телом выражение. Если слева один идентификатор, он становится единственным аргументом. Если слева несколько идентификаторов, все они — аргументы.

Оператор собирает слова слева в аргументы, а справа — в одно выражение. Приоритет выше, чем у =, поэтому имя = аргумент ==> выражение связывает имя с новой функцией.

В отличие от функция, тело — одно выражение. Несколько команд можно записать через блок.

функция
(применить функция аргумент ... список) → любой
  функция : функция?
  аргумент : любой
  список : список?

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

синтаксис
(буквально элемент ...+)

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

синтаксис
(блок команда ...)

Выполняет команды слева направо. Результат — значение последней команды. Так несколько команд можно записать там, где ожидается одна.

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

синтаксис
(рекурсивно (имя привязка ...) команда ... выражение)

привязка = (идентификатор выражение)

Определяет локальную функцию имя с параметрами из привязка и сразу вызывает её с начальными значениями. В теле можно вызывать имя рекурсивно.

Удобно для локального цикла: вместо отдельного определения функции и начального вызова пишется одна конструкция. Модуль базовая/управление.

сумма-байтов байты =
  рекурсивно
    шаг
      позиция 0
      нак 0
    если позиция >= длина-байтов(байты) тогда
      нак
      иначе
      шаг
        позиция + 1
        нак + элемент-байтов байты позиция

синтаксис
(цикл (переменная последовательность) команда ... выражение)
(цикл (для предложение ...) команда ... выражение)

предложение = (переменная последовательность)
| #:когда условие
| #:когда-не условие
| #:прервать условие
| #:последняя условие

переменная = идентификатор

последовательность = выражение

Выполняет тело для каждого элемента последовательность. Результат формы не используется — важны побочные эффекты тела.

последовательность — выражение, дающее последовательность (в-списке, в-диапазоне, от-нуля и т.п.). Число означает диапазон от нуля до этого числа (не включая).

Несколько переменных и ключи отбора пишут после для. #:когда и #:когда-не отбирают итерации; #:прервать завершает цикл при истинном условии; #:последняя делает текущую итерацию последней.

Модуль базовая/управление. Введение — Удобные циклы.

синтаксис
(цикл/список заголовок команда ... выражение)

Как цикл, но результаты тела собираются в список. заголовок — как у цикл: одна привязка (переменная последовательность) или (для предложение ...).

синтаксис
(цикл/первый заголовок команда ... выражение)

Как цикл, но возвращает первый результат тела, который не ложь, и на нём останавливается. Если такого нет — ложь. заголовок — как у цикл.

синтаксис
(попытка обработчик команда ...)
(попытка (условие обработчик) команда ...)
(попытка (исключения (условие обработчик) ...)
команда ...)

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

обработчик — функция от одного аргумента (исключения). условие — функция от исключения: обработчик вызывается, если она вернула не ложь.

В первой форме обрабатывается любое исключение.

Во второй форме проверяется одно условие.

В третьей форме пары условия и обработчика перебираются по порядку; срабатывает первая подходящая. Если ни одна не подошла, исключение передаётся дальше.

значение
пусто : пусто?

Если значением функции является пусто, тогда результат не выводится

функция
(пусто? аргумент) → булево?
аргумент : любой

Возвращает истина, если аргумент равен пусто

4.2 Классы🔗ℹ

Команды доступны после подключения модуля класс:

(используется класс)

синтаксис
(класс выражение-базового-класса команда-класса ...)

команда-класса = (инициализировать объявление-инициализации ...)
| (инициализированные-поля объявление-инициализации ...)
| (поля объявление-поля ...)
| (унаследованные-поля возможно-переименованное ...)
| (методы возможно-переименованное ...)
| (дополняемые-методы возможно-переименованное ...)
| (переопределить возможно-переименованное ...)
| (дополнить возможно-переименованное ...)
| (абстрактные идентификатор ...)
| (унаследованные возможно-переименованное ...)
| определение
| выражение
| (блок команда-класса ...)

объявление-инициализации = идентификатор
| (переименованное)
| (возможно-переименованное выражение-значения-по-умолчанию)

объявление-поля = (возможно-переименованное выражение-значения-по-умолчанию)

возможно-переименованное = идентификатор
| переименованное

переименованное = (внутреннее-имя внешнее-имя)

Возвращает значение класса.

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

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

наследование: объект производного класса поддерживает методы и создаёт поля, объявленные в базовом классе, а также методы и поля, объявленные в выражении производного класса;
переопределение: некоторые методы базового класса можно заменить в производном. Обращения к переопределённому методу из базового класса используют реализацию из производного класса;
дополнение: некоторые методы базового класса можно лишь расширить в производном. Метод базового класса явно передаёт управление дополняющему методу производного класса.

выражение-базового-класса вычисляется при вычислении команды класс. Результат должен быть значением класса (в том числе встроенным классом объект%), иначе вызывается исключение. Этот результат становится базовым классом нового класса. У объект% нет полей и методов; от него порождаются все остальные классы.

Остальные команда-класса задают аргументы инициализации, открытые и закрытые поля, открытые и закрытые методы. Для каждого имени в командах методы, переопределить, дополнить или дополняемые-методы должна быть ровно одна соответствующая команда определения метода. Команда абстрактные объявляет имена методов без реализации: объект такого класса нельзя создать, пока производный класс не задаст реализацию командой переопределить. Все прочие определения внутри класса создают закрытые поля. Оставшиеся выражения — выражения инициализации; они выполняются при создании объекта.

Если команда класса — выражение блок, его подвыражения поднимаются из блока и обрабатываются как отдельные команды класса.

Результат команды класс — новый класс, порождённый указанным базовым классом. Объекты создаются формой объект или функцией создать-объект.

Внутри команды класс для экземпляров нового класса этот связан с самим объектом; этот% — с классом текущего объекта; базовый-объект и создать-базовый-объект — формы инициализации полей базового класса; базовый вызывает метод базового класса; производный вызывает дополнение метода в производном классе. Использование этот, этот%, базовый и производный вне тела команды класс является ошибкой синтаксиса.

Переменные инициализации. Переменные, объявленные командами инициализировать и инициализированные-поля, создаются для каждого объекта класса. Их можно использовать в выражениях начальных значений полей, в выражениях значений по умолчанию для аргументов инициализации и в выражениях инициализации. Из методов доступны только переменные, объявленные инициализированные-поля; обращение к прочим переменным инициализации из метода — ошибка синтаксиса.

Значения этих переменных — аргументы, переданные форме объект или функции создать-объект, если объект создаётся как непосредственный экземпляр класса; либо аргументы, переданные форме инициализации базового класса, если объект создаётся как экземпляр производного класса.

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

Аргументы можно передать по имени или по позиции. Внешнее имя переменной инициализации используется с формой объект и с формой инициализации базового класса. Функция создать-объект и процедура инициализации базового класса принимают только аргументы по позиции.

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

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

Поле из инициализированные-поля одновременно является открытым полем и переменной инициализации.

Команда унаследованные-поля делает открытое поле базового класса напрямую доступным в выражении класса. Если указанного поля в базовом классе нет, при вычислении выражения класса вызывается исключение. Каждое поле базового класса присутствует и в производном, даже без унаследованные-поля; эта команда не управляет наследованием, а только лексической областью видимости внутри выражения класса.

При создании объекта все поля сначала не определены. Поля класса инициализируются одновременно с вычислением выражений инициализации класса. Среди выражений инициализации должна быть инициализация базового класса (базовый-объект или создать-базовый-объект).

Методы. Каждая команда методы, переопределить, дополнить или дополняемые-методы объявляет одно или несколько имён методов. У каждого имени должна быть соответствующая команда определения метода. Порядок таких команд и определений (между собой и относительно других команд класса) неважен.

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

Метод, объявленный методы или дополняемые-методы, вводится в класс как новый. Его ещё не должно быть в базовом классе, иначе при вычислении выражения класса вызывается исключение. Метод из методы можно переопределить в производном классе командой переопределить. Метод из дополняемые-методы можно дополнить в производном классе командой дополнить.

Метод, объявленный переопределить, заменяет определение, уже присутствующее в базовом классе. Если метода там нет, вызывается исключение. Такой метод можно снова переопределить в следующем производном классе.

Метод, объявленный дополнить, расширяет метод базового класса, объявленный как дополняемый. Если дополняемого метода нет, вызывается исключение.

Команда унаследованные делает метод базового класса напрямую вызываемым в выражении класса (как свой метод). Если метода нет в базовом классе, вызывается исключение. Наличие метода в производном классе не зависит от унаследованные: команда задаёт только область видимости.

Если в возможно-переименованное указано переименованное, внутреннее-имя используется в теле класса, а внешнее-имя — при вызове метода или доступе к полю снаружи и в производных классах. Все внутренние имена в одном классе должны быть различны; различны должны быть и внешние имена методов, полей и аргументов инициализации.

Команда класс не принимает список интерфейсов. Если класс должен явно реализовывать интерфейсы, используйте класс*.

синтаксис
(класс* выражение-базового-класса (выражение-интерфейса ...) команда-класса ...)

Как класс, но новый класс реализует указанные интерфейсы. Команды класса те же, что у класс.

выражение-базового-класса вычисляется при вычислении команды класс*. Результат должен быть значением класса, иначе вызывается исключение. Этот результат становится базовым классом нового класса.

Выражения интерфейсов вычисляются следом, в порядке записи. Результат каждого должен быть значением интерфейса, иначе вызывается исключение. Новый класс реализует все эти интерфейсы. Для каждого имени метода каждого интерфейса класс или один из его предков должен объявить открытый метод с тем же именем, иначе вызывается исключение. Базовый класс должен удовлетворять требованию порождения каждого интерфейса, иначе вызывается исключение.

Результат — новый класс, порождённый указанным базовым классом и реализующий указанные интерфейсы. Объекты создаются формой объект или функцией создать-объект.

Внутри команды класс* действуют те же привязки, что внутри класс: этот, этот%, базовый-объект, создать-базовый-объект, базовый и производный.

синтаксис
(инициализировать объявление-инициализации ...)

См. класс* и класс (переменные инициализации); использование вне тела класс или класс* — ошибка синтаксиса.

> класс объект%
  базовый-объект()
  инициализировать репа
    (внутренняя-картошка картошка)
    (морковь 'хорошая)
    ((внутренняя-брюква брюква) 'нормальная)

синтаксис
(инициализированные-поля объявление-инициализации ...)

См. класс* и класс (переменные инициализации, поля); использование вне тела класс или класс* — ошибка синтаксиса.

> класс объект%
  базовый-объект()
  инициализированные-поля индейка
    (внутренний-страус страус)
    (курица 7)
    ((внутренний-эму эму) 13)

синтаксис
(поля объявление-поля ...)

См. класс* и класс (поля); использование вне тела класс или класс* — ошибка синтаксиса.

> класс объект%
  базовый-объект()
  поля (минестроне 'готово)
    ((внутреннее-рагу рагу) 'тушится)

синтаксис
(унаследованные-поля возможно-переименованное ...)

См. класс* и класс (поля); использование вне тела класс или класс* — ошибка синтаксиса.

> книга-рецептов% = класс объект%
  базовый-объект()
  поля (рецепты '(суп яичница)) (страницы 389)
> класс книга-рецептов%
  базовый-объект()
  унаследованные-поля рецепты (внутренние-страницы страницы)

синтаксис
(методы возможно-переименованное ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> прыгун% = класс объект%
  базовый-объект()
  пропуск() = 'пропуск
  подскок() = 'подскок
  методы пропуск (подскок прыжок)
> объект(прыгун%){пропуск}
'пропуск
> объект(прыгун%){прыжок}
'подскок

синтаксис
(дополняемые-методы возможно-переименованное ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> бегун% = класс объект%
  базовый-объект()
  бег() = 'бег
  рысь() = 'рысь
  дополняемые-методы бег (рысь трусца)
> объект(бегун%){бег}
'бег
> объект(бегун%){трусца}
'рысь

синтаксис
(переопределить возможно-переименованное ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> овца% = класс объект%
  базовый-объект()
  методы блеять
  блеять() = вывести/перенос(«бе-е-е»)
> растерянная-овца% = класс овца%
  базовый-объект()
  блеять() =
    базовый блеять
    вывести/перенос(«???»)
  переопределить блеять
> объект(овца%){блеять}
бе-е-е
> объект(растерянная-овца%){блеять}
бе-е-е ???

синтаксис
(дополнить возможно-переименованное ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> зуммер% = класс объект%
  базовый-объект()
  дополняемые-методы жужжать
  жужжать() =
    вывести/перенос(«жжжт»)
    производный(пусто жужжать)
> громкий-зуммер% = класс зуммер%
  базовый-объект()
  жужжать() = вывести/перенос(«ЖЖЖЖТ»)
  дополнить жужжать
> объект(зуммер%){жужжать}
жжжт
> объект(громкий-зуммер%){жужжать}
жжжт ЖЖЖЖТ

синтаксис
(абстрактные идентификатор ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> поезд% = класс объект%
  базовый-объект()
  абстрактные скорость
  инициализированные-поля (положение 0)
  методы ехать
  ехать() =
    объект этот% положение(положение + скорость())
> скорый% = класс поезд%
  базовый-объект()
  скорость() = 241
  переопределить скорость
> объект(поезд%)
объект: нельзя создать объект класса с нереализованными методами класс: #<класс:поезд%> методы: скорость
> объект(скорый%){ехать}
(объект:скорый% ...)

синтаксис
(унаследованные возможно-переименованное ...)

См. класс* и класс (методы); использование вне тела класс или класс* — ошибка синтаксиса.

> сирена% = класс объект%
  базовый-объект()
  методы сирена
  сирена() = вывести/перенос(«бииип»)
> автомобильная-сирена% = класс сирена%
  базовый-объект()
  инициализированные-поля близость
  унаследованные сирена
  если близость < 10 тогда сирена()
> объект автомобильная-сирена% близость(5)
бииип
(объект:автомобильная-сирена% ...)

синтаксис
(базовый-объект (идентификатор выражение) ...)

Вызывает инициализацию базового класса с указанными именными аргументами. См. класс* и объект. Использование вне тела класс или класс* — ошибка синтаксиса.

синтаксис
создать-базовый-объект

Возвращает функцию, которая принимает позиционные аргументы и вызывает инициализацию базового класса. См. класс* и создать-объект. Использование вне тела класс или класс* — ошибка синтаксиса.

синтаксис
(интерфейс (выражение-базового-интерфейса ...) имя ...)

Возвращает интерфейс. Интерфейс — набор имён методов, которые должен реализовать класс, вместе с требованием порождения. Класс реализует интерфейс, когда он

объявляет (или наследует) открытый метод для каждого имени интерфейса;
порождён от класса, которого требует интерфейс, если такое требование есть;
явно указывает намерение реализовать интерфейс.

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

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

имя должны быть попарно различны.

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

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

Если выражения базовых интерфейсов не заданы, требование порождения тривиально: реализующий класс должен быть порождён от объект%. Иначе требование — наиболее конкретное из требований базовых интерфейсов. Если требования несогласованы, вызывается исключение.

Классы, объекты и интерфейсы — значения. Однако класс или интерфейс не является объектом.

класс
объект% : любой

Встроенный класс без методов и полей. Реализует только свой собственный интерфейс. Непосредственные экземпляры считаются равными в смысле ==. Все остальные классы порождаются от объект%.

синтаксис
(объект выражение-класса (идентификатор выражение) ...)

Создаёт экземпляр значения выражение-класса (оно должно дать класс). Значение каждого выражение передаётся как именной аргумент инициализации с соответствующим идентификатор.

Все поля нового объекта сначала не определены. Переменные инициализации с выражениями по умолчанию (если значение не передано) тоже сначала не определены. После подстановки аргументов вычисляются выражения в командах поля, в инициализированные-поля и инициализировать без переданного аргумента, определения закрытых полей и прочие выражения — в порядке записи в классе.

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

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

Унаследованные поля инициализируются только при вызове инициализации базового класса. Методы доступны сразу после создания объекта; переопределение методов не зависит от хода инициализации.

синтаксис
этот

Внутри команды класс или класс* обозначает текущий объект: тот, который инициализируется, или тот, чей метод вызван. Использование вне тела класс или класс* — ошибка синтаксиса.

синтаксис
этот%

Внутри команды класс или класс* обозначает класс текущего объекта: того, который инициализируется, или того, чей метод вызван. Использование вне тела класс или класс* — ошибка синтаксиса.

> счёт% = класс объект%
  базовый-объект()
  инициализированные-поля баланс
  методы добавить
  добавить n =
    объект этот% баланс(n + баланс)
> вклад% = класс счёт%
  базовый-объект()
  унаследованные-поля баланс
  процент = 0.04
  методы начислить-процент
  начислить-процент() =
    этот{добавить процент * баланс}
> счёт = объект вклад% баланс(500)
> счёт{добавить 500}
> счёт{начислить-процент}
> поле баланс счёт
1040.0

синтаксис
(базовый идентификатор аргумент ...)
(базовый идентификатор аргумент ... . выражение-списка-аргументов)

Всегда вызывает метод базового класса (или базового интерфейса) с именем идентификатор, независимо от того, переопределён ли метод в производных классах. Использование вне тела класс или класс* — ошибка синтаксиса.

Вторая форма передаёт дополнительные аргументы списком, как применить; выражение-списка-аргументов не должно быть выражением в скобках.

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

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

Если класс объекта не задаёт дополняющий метод с именем идентификатор, вычисляется выражение-по-умолчанию, а выражения аргументов не вычисляются. Иначе вызывается дополняющий метод с результатами аргументов, а выражение-по-умолчанию не вычисляется. Если для метода ни разу не вычислить производный, дополнения из производных классов не используются. Использование вне тела класс или класс* — ошибка синтаксиса.

Если метод объявлен командой дополняемые-методы или дополнить, дополнение из производного класса вызывается через производный.

синтаксис
(поле идентификатор выражение-объекта)

Возвращает значение поля с внешним именем идентификатор у значения выражение-объекта.

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

синтаксис
(установить-поле! идентификатор выражение-объекта выражение)

Записывает значение выражение в поле с внешним именем идентификатор у значения выражение-объекта.

функция
(создать-объект класс параметр ...) → любой
класс : любой
параметр : любой

Создаёт экземпляр класс. Значения параметр передаются как позиционные аргументы инициализации и связываются с переменными инициализации класса, как описано для команды класс. Если класс не является классом, вызывается исключение.

функция
(объект-класса? значение тип) → булево?
значение : любой
тип : любой

Возвращает истина, если значение — экземпляр класса тип или класса, реализующего интерфейс тип, иначе возвращает ложь.

функция
(класс? значение) → булево?
значение : любой

Возвращает истина, если значение — класс, иначе возвращает ложь.

Класс — значение, но не объект: для экземпляра класса ложь, для самого класса истина.

функция
(интерфейс? значение) → булево?
значение : любой

Возвращает истина, если значение — интерфейс, иначе возвращает ложь.

Интерфейс — значение, но не объект.

4.3 Логические выражения🔗ℹ

функция
(булево? аргумент) → булево?
аргумент : любой

Возвращает истина, если аргумент истина или ложь, в противном случае возвращает ложь.

функция
(не значение) → булево?
  значение : любой
(не функция аргумент ...) → булево?
  функция : функция?
  аргумент : любой

В форме с одним аргументом возвращает истина, если значение — ложь, и ложь иначе.

В форме с несколькими аргументами вызывает функция с аргументами и отрицает результат: (не ф а б) то же, что (не (ф а б)).

функция
(== аргумент ...+) → булево?
аргумент : любой

Возвращает истина, если аргументы равны. Списки и массивы считаются равными, если равны их элементы.

функция
(=== аргумент ...+) → булево?
аргумент : любой

Возвращает истина, если аргументы равны. Списки и массивы считаются равными, если являются одним и тем же объектом, а не просто состоят из одинаковых элементов.

функция
(/= аргумент ...+) → булево?
аргумент : любой

Возвращает ложь, если аргументы равны в смысле ==.

4.4 Условия🔗ℹ

синтаксис
(? условие выражение-если-истина выражение-если-ложь)

условие : булево?

Если условие истинно, выполняет выражение-если-истина иначе выполняет выражение-если-ложь. Возвращает результат выполненного выражения.

При использовании как оператор не объединяет в одно выражение слова справа от себя.

синтаксис
(&& выражение ...)

Выполняет выражения слева направо, пока одно из них не вернёт ложь или они не закончатся. Возвращает результат последнего выполненного выражения.

синтаксис
(|| выражение ...)

Выполняет выражения слева направо, пока одно из них не вернёт что-то кроме ложь или они не закончатся. Возвращает результат последнего выполненного выражения.

синтаксис
(если слова-условия ... тогда команда ... иначе команда ...)
(если слова-условия ... тогда команда ...)
(если правило ...)
(если правило ... (иначе команда ... выражение))

правило = (условие команда ... выражение)
| (выполнить команда ...)
| (условие => выражение)

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

4.5 Символы🔗ℹ

функция
(символ? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является символом.

функция
(символ->строка символ) → строка?
символ : символ?

Возвращает имя символа.

функция
(строка->символ строка) → символ?
строка : строка?

Возвращает символ с заданным именем. Для одинаковых строк возвращает одинаковые символы.

функция
(новый-символ) → символ?

Возвращает новый символ, который невозможно получить ни из какой строки. Он выводится с некоторым именем, но не равен ни одному другому, только самому себе.

4.6 Ключевые слова🔗ℹ

функция
(ключевое-слово? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является ключевым словом.

функция
(строка->ключевое-слово строка) → символ?
строка : строка?

Возвращает ключевое слово с заданным именем. Для одинаковых строк возвращает одинаковые ключевые слова.

4.7 Числа🔗ℹ

функция
(число? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является числом.

функция
(точное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является точным числом.

функция
(неточное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является неточным числом.

функция
(целое? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является целым числом. Внимание, неточное число тоже может быть целым!

функция
(точное-целое? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является точным целым числом.

функция
(целое-неотрицательное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является точным целым неотрицательным числом.

функция
(вещественное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является вещественным числом.

функция
(рациональное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является рациональным числом.

функция
(комплексное? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является комплексным числом.

оператор
(// делимое делитель) → целое?
делимое : целое?
делитель : целое?

Целочисленное деление делимое на делитель. Дробная часть отбрасывается в сторону нуля: (10 // 3) даёт 3, (-10 // 3) даёт -3.

оператор
(% делимое делитель) → целое?
делимое : целое?
делитель : целое?

Остаток от целочисленного деления делимое на делитель. Знак остатка совпадает со знаком делимое: (10 % 3) даёт 1, (-10 % 3) даёт -1.

функция
(округлить число) → (одно-из целое? +inf.0 -inf.0 +nan.0)
число : вещественное?

Возвращает целое, ближайшее к аргументу. Если число одно из +inf.0, -inf.0 или +nan.0, возвращает его же.

функция
(корень число) → число?
число : число?

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

функция
(синус число) → число?
число : число?

Возвращает синус угла в радианах.

функция
(косинус число) → число?
число : число?

Возвращает косинус угла в радианах.

функция
(тангенс число) → число?
число : число?

Возвращает тангенс угла в радианах.

функция
(арксинус число) → число?
число : число?

Возвращает арксинус в радианах.

функция
(арккосинус число) → число?
число : число?

Возвращает арккосинус в радианах.

функция
(арктангенс число) → число?
число : число?

Возвращает арктангенс в радианах.

функция
(экспонента число) → число?
число : число?

Возвращает число Эйлера (e) в степени число.

функция
(логарифм число [основание]) → число?
число : число?
основание : число? = (экспонента 1)

Возвращает натуральный логарифм. Если передано основание, то возвращает логарифм по этом основанию.

функция
(неточное->точное число) → точное?
число : число?

Преобразовывает число в точное. Если число одно из +inf.0, -inf.0, +nan.0, +inf.f, -inf.f или +nan.f, тогда вызывается исключение.

функция
(точное->неточное число) → неточное?
число : число?

Преобразовывает число в неточное.

функция
(небольшое-число? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является небольшим числом. Вычисления с небольшими числами выполняются быстрее.

функция
(абс число) → вещественное?
число : вещественное?

Возвращает абсолютное значение аргумента.

функция
(строка->число строка [основание]) → (одно-из число? ложь)
строка : строка?
основание : (одно-из 2 8 10 16) = 10

Возвращает число из строкового представления числа или ложь, если это не число.

функция
(число->строка число [основание]) → строка?
число : число?
основание : (одно-из 2 8 10 16) = 10

Возвращает строковое представление числа.

функция
(байты->целое байты
со-знаком?
от-старшего?
[ начало
конец]) → точное-целое?
  байты : байты?
  со-знаком? : любой
  от-старшего? : любой
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Читает целое из машинного представления в байты (длина отрезка 1, 2, 4 или 8). Если со-знаком? не ложь — дополнение до двух, иначе беззнаковое. Если от-старшего? не ложь — старший байт первым (big-endian), иначе младший. По умолчанию порядок байтов как в системе. Модуль базовая/число.

функция
(целое->байты число
размер
со-знаком?
от-старшего?
[ назначение
начало]) → байты?
  число : точное-целое?
  размер : (один-из 1 2 4 8)
  со-знаком? : любой
  от-старшего? : любой
  назначение : байты? = (новые-байты размер)
  начало : целое-неотрицательное? = 0

Пишет число в машинном формате длиной размер (1, 2, 4 или 8 байт) в назначение с позиции начало. со-знаком? и от-старшего? — как у байты->целое. Возвращает назначение. Модуль базовая/число.

4.8 Литеры🔗ℹ

функция
(литера? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является литерой.

функция
(литера->число аргумент) → точное-целое?
аргумент : литера?

Возвращает код литеры.

функция
(число->литера аргумент) → литера?
аргумент : точное-целое?

Возвращает литеру по коду.

4.9 Списки🔗ℹ

функция
(список? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является списком. Любой список также является парой.

функция
(пустой? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является пустым списком.

константа
пустой-список : пустой?

Пустой список.

функция
(список аргумент ...) → список?
аргумент : любой

Возвращает список из произвольных значений.

функция
(пара? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является парой.

функция
(пара аргумент1 аргумент2) → пара?
аргумент1 : любой
аргумент2 : любой

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

функция
(: аргумент1 аргумент2) → пара?
аргумент1 : любой
аргумент2 : любой

Аналогично функции пара возвращает пару из переданных аргументов. Если второй аргумент список, то возвращаемое значение тоже список.

функция
(первый аргумент) → любой
аргумент : пара?

Возвращает первый элемент пары. Если пара является списком, то он же первый элемент списка.

функция
(оставшиеся аргумент) → любой
аргумент : пара?

Возвращает второй элемент пары. Если пара является списком, то это список из всех элементов кроме первого (то есть «оставшиеся» элементы списка).

функция
(длина аргумент) → число?
аргумент : список?

Возвращает количество элементов списка.

функция
(развернуть аргумент) → список?
аргумент : список?

Возвращает список из значений аргумента в обратном порядке.

функция
(элемент-списка аргумент позиция) → любой
аргумент : список?
позиция : число?

Возвращает элемент списка в указанной позиции. Нумерация позиций начинается с нуля.

функция
(подсписок значение аргумент) → любой
значение : любой
аргумент : список?

Если в списке аргумент есть элемент значение, то возвращает хвост списка, начиная с этого элемента. Если нет, возвращает ложь.

Сравнение элементов с значением происходит при помощи ==.

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

функция
(подсписок=== значение аргумент) → любой
значение : любой
аргумент : список?

Функция полностью аналогична функции подсписок за исключением того, что для сравнения используется ===.

функция
(отобрать обработчик аргумент) → список?
обработчик : функция?
аргумент : список?

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

функция
(отобразить обработчик аргумент ...) → список?
обработчик : функция?
аргумент : список?

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

Вызов (отобразить ф список(а б в)) аналогичен (список ф(а) ф(б) ф(в))..

функция
(отобразить/и обработчик аргумент ...) → любой
обработчик : функция?
аргумент : список?

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

Вызов (отобразить/и ф список(а б в)) аналогичен (&& ф(а) ф(б) ф(в)).

функция
(отобразить/или обработчик аргумент ...) → любой
обработчик : функция?
аргумент : список?

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

Вызов (отобразить/или ф список(а б в)) аналогичен (|| ф(а) ф(б) ф(в)).

функция
(свернуть обработчик начальное аргумент ...) → список?
  обработчик : функция?
  начальное : любое
  аргумент : список?

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

Если свернуть вызывается с n списками, то обработчик должен принимать n+1 аргументов. Последний аргумент получает результат предыдущего вызова обработчика, при первом вызове получает значение аргумента начальное. Результатом функции свернуть является последний результат вызова обработчика.

функция
(добавить аргумент ...) → список?
  аргумент : список?
(добавить аргумент ... последний-аргумент) → любой
  аргумент : список?
  последний-аргумент : любой

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

Если последний аргумент не список, он всё равно используется в хвостовой позиции.

Если передан всего один аргумент, он возвращается как есть. Если передано ноль аргументов, возвращается пустой список.

Время выполнения пропорционально сумме длин аргументов кроме последнего.

Примеры:

> добавить список(1 2) список(3 4)
'(1 2 3 4)
> добавить список(1 2) 3
'(1 2 . 3)
> добавить 4
4

функция
(++ аргумент ...) → (одно-из список? строка? массив? байты?)
аргумент : (одно-из список? строка? массив? байты?)

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

функция
(ассоциация значение список [равенство]) → (одно-из пара? ложь)
  значение : любой
  список : список?
  равенство : (любой любой . -> . любой) = ==

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

4.10 Массивы🔗ℹ

функция
(массив? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является массивом.

функция
(массив аргумент ...) → список?
аргумент : любой

Возвращает массив из произвольных значений.

функция
(длина-массива массив) → число?
массив : массив?

Возвращает количество элементов массива.

функция
(элемент-массива массив позиция) → литера?
массив : массив?
позиция : целое-неотрицательное?

Возвращает значение на заданной позиции. Позиции нумеруются с нуля.

функция
(установить-элемент-массива! массив
позиция
значение) → пусто?
  массив : массив?
  позиция : целое-неотрицательное?
  значение : любой

Устанавливает значение элемента на заданной позиции. Позиции нумеруются с нуля.

функция
(массив->список массив) → список?
массив : массив?

Возвращает список из значений массива.

функция
(список->массив список) → список?
список : список?

Возвращает массив из значений списка.

4.11 Соответствия🔗ℹ

функция
(соответствие? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является соответствием.

функция
(соответствие===? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является соответствием, ключи которого сравниваются ===.

функция
(соответствие ключ значение ...) → соответствие?
ключ : любой
значение : любой

Возвращает неизменяемое соответствие из произвольных значений.

функция
(соответствие=== ключ значение ...) → соответствие?
ключ : любой
значение : любой

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

функция
(новое-соответствие [список-пар]) → соответствие?
список-пар : (список-из пара?) = пустой-список

Возвращает новое соответствие. Если список пар не пуст, то заполняет созданное соответствие ключами и значениями из него.

функция
(новое-соответствие=== [список-пар]) → соответствие?
список-пар : (список-из пара?) = пустой-список

Возвращает новое соответствие, ключи которого сравниваются ===. Если список пар не пуст, то заполняет созданное соответствие ключами и значениями из него.

функция
(значение-соответствия соответствие
ключ
[ не-найден]) → любой
  соответствие : соответствие?
  ключ : любой
  не-найден : любой = ошибка-нет-ключа

Возвращает значение для заданного ключа. Если ключа в соответствии нет, то используется значение не-найден: если это функция, она выполняется и возвращается её значение, иначе возвращается само значение не-найден.

функция
(установить-значение-соответствия! соответствие
ключ
значение) → пусто?
  соответствие : соответствие?
  ключ : любой
  значение : любой

Устанавливает значение соответствия для заданного ключа.

4.12 Строки🔗ℹ

функция
(строка? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является строкой.

функция
(новая-строка длина [литера]) → строка?
длина : целое-неотрицательное?
литера : литера? = (число->литера 0)

Создаёт строку заданной длины и заполняет её указанным значением аргумента литера. Если литера не указана, заполняет литерой с нулевым кодом, то есть #\пусто.

функция
(длина-строки строка) → целое-неотрицательное?
строка : строка?

Возвращает длину строки в литерах.

функция
(элемент-строки строка позиция) → литера?
строка : строка?
позиция : целое-неотрицательное?

Возвращает литеру на заданной позиции. Позиции нумеруются с нуля.

функция
(установить-элемент-строки! строка
позиция
литера) → пусто?
  строка : строка?
  позиция : целое-неотрицательное?
  литера : литера?

Устанавливает литеру на заданной позиции. Позиции нумеруются с нуля.

функция
(подстрока строка начало [конец]) → строка?
  строка : строка?
  начало : целое-неотрицательное?
  конец : целое-неотрицательное? = (длина-строки строка)

Возвращает подстроку из аргумента строка с позиции начало по позицию конец.

функция
(добавить-строки строка ...) → строка?
строка : строка?

Возвращает сцепку строк. Создаётся новая изменяемая строка достаточного размера, затем все литеры всех строк последовательно копируются в новую.

функция
(прописные строка) → строка?
строка : строка?

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

функция
(строчные строка) → строка?
строка : строка?

Возвращает строку, в которой все литеры заменены на строчные.

функция
(строки-равны? строка ...) → строка?
строка : строка?

Возвращает истину, если все строки равны.

функция
(строки-возрастают? строка ...) → строка?
строка : строка?

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

функция
(строки-не-убывают? строка ...) → строка?
строка : строка?

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

функция
(строки-убывают? строка ...) → строка?
строка : строка?

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

функция
(строки-не-возрастают? строка ...) → строка?
строка : строка?

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

функция
(строки-равны?/без-регистра строка ...) → строка?
строка : строка?

Возвращает истину, если все строки равны без учёта регистра.

функция
(строки-возрастают?/без-регистра строка
...) → строка?
строка : строка?

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

функция
(строки-не-убывают?/без-регистра строка
...) → строка?
строка : строка?

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

функция
(строки-убывают?/без-регистра строка ...) → строка?
строка : строка?

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

функция
(строки-не-возрастают?/без-регистра строка
...) → строка?
строка : строка?

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

функция
(прописные/местные строка) → строка?
строка : строка?

Возвращает строку, в которой все литеры заменены на прописные с учётом региональных настроек.

функция
(строчные/местные строка) → строка?
строка : строка?

Возвращает строку, в которой все литеры заменены на строчные с учётом региональных настроек.

функция
(строки-равны?/местные строка ...) → строка?
строка : строка?

Возвращает истину, если все строки равны с учётом региональных настроек.

функция
(строки-возрастают?/местные строка ...) → строка?
строка : строка?

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

функция
(строки-убывают?/местные строка ...) → строка?
строка : строка?

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

функция
(строки-равны?/местные/без-регистра строка
...) → строка?
строка : строка?

Возвращает истину, если все строки равны с учётом региональных настроек без учёта регистра.

функция
(строки-возрастают?/местные/без-регистра строка
...) → строка?
строка : строка?

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

функция
(строки-убывают?/местные/без-регистра строка
...) → строка?
строка : строка?

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

Следующие функции доступны только при использовании модуля строка.

функция
(строка-начинается-с? строка подстрока) → булево?
строка : строка?
подстрока : строка?

Возвращает истину, если строка начинается с литер в аргументе подстрока.

функция
(строка-заканчивается-на? строка подстрока) → булево?
строка : строка?
подстрока : строка?

Возвращает истину, если строка заканчивается на литеры в аргументе подстрока.

4.13 Регулярные выражения🔗ℹ

функция
(регулярное-выражение строка) → любой
строка : (один-из строка? байты?)

Компилирует строка в регулярное выражение. Для обычной строки используется синтаксис egrep, для байтовой строки — байтовое регулярное выражение. Литералы #rx"..." и #rx#"..." задают уже скомпилированное выражение того же вида.

функция
(расширенное-регулярное-выражение строка) → любой
строка : (один-из строка? байты?)

Компилирует строка в регулярное выражение с расширенным синтаксисом (как в Perl). Для байтовой строки получается байтовое регулярное выражение. Литералы #px"..." и #px#"..." задают уже скомпилированное выражение того же вида.

функция
(совпадение-с-регулярным-выражением регулярное-выражение
строка)
→ любой
регулярное-выражение : любой
строка : (один-из строка? байты?)

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

функция
(совпадения-с-регулярным-выражением регулярное-выражение
строка)
→ (список-из (список-из (один-из строка? байты?)))
регулярное-выражение : любой
строка : (один-из строка? байты?)

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

функция
(совпадает-с-регулярным-выражением? регулярное-выражение
строка)
→ булево?
регулярное-выражение : любой
строка : (один-из строка? байты?)

Возвращает истина, если регулярное-выражение встречается в строка.

функция
(заменить-по-регулярному-выражению регулярное-выражение
строка
замена)
→ (один-из строка? байты?)
  регулярное-выражение : любой
  строка : (один-из строка? байты?)
  замена : (один-из строка? байты?)

Заменяет первое вхождение регулярное-выражение в строка на замена и возвращает новую строку или байтовую строку. В замена можно использовать "\\1", "\\2" и т. д. для ссылок на скобочные подвыражения.

функция
(заменить-по-регулярному-выражению/все регулярное-выражение
строка
замена)
→ (один-из строка? байты?)
  регулярное-выражение : любой
  строка : (один-из строка? байты?)
  замена : (один-из строка? байты?)

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

функция
(разделить-по-регулярному-выражению регулярное-выражение
строка)
→ (список-из строка?)
регулярное-выражение : любой
строка : строка?

Разбивает строка на части по вхождениям регулярное-выражение и возвращает список подстрок. Между двумя соседними совпадениями в списке может оказаться пустая строка.

4.14 Байты🔗ℹ

функция
(байт? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является целым точным числом в диапазоне 0..255.

функция
(байты? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является байтовой строкой.

функция
(новые-байты длина [значение]) → байты?
длина : целое-неотрицательное?
значение : байт? = 0

Создаёт строку заданной длины и заполняет её указанным значением аргумента значение. Если значение не указано, заполняет числом 0.

функция
(длина-байтов байты) → целое-неотрицательное?
байты : байты?

Возвращает длину байтовой строки в байтах.

функция
(элемент-байтов байты позиция) → байт?
байты : байты?
позиция : целое-неотрицательное?

Возвращает число на заданной позиции. Позиции нумеруются с нуля.

функция
(установить-элемент-байтов! байты
позиция
байт) → пусто?
  байты : байты?
  позиция : целое-неотрицательное?
  байт : байт?

Устанавливает число на заданной позиции. Позиции нумеруются с нуля.

функция
(добавить-байты байты ...) → байты?
байты : байты?

Склеивает байтовые строки в одну. Модуль базовая/байт.

функция
(подбайты байты начало [конец]) → байты?
  байты : байты?
  начало : целое-неотрицательное?
  конец : целое-неотрицательное? = (длина-байтов байты)

Возвращает отрезок байтов от начало до конец (не включая). Модуль базовая/байт.

функция
(байты->строка байты
[ литера-ошибки
начало
конец]) → строка?
  байты : байты?
  литера-ошибки : (одно-из литера? ложь) = ложь
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

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

функция
(байты->строка/местные байты
[ литера-ошибки
начало
конец]) → строка?
  байты : байты?
  литера-ошибки : (одно-из литера? ложь) = ложь
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

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

функция
(строка->байты строка
[ байт-ошибки
начало
конец]) → байты?
  строка : строка?
  байт-ошибки : (один-из байт? ложь) = ложь
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-строки строка)

Преобразует отрезок строки в байты в кодировке UTF-8. байт-ошибки не используется: любая литера кодируется; параметр есть для единообразия с строка->байты/местные.

функция
(строка->байты/местные строка
[ байт-ошибки
начало
конец]) → байты?
  строка : строка?
  байт-ошибки : (один-из байт? ложь) = ложь
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-строки строка)

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

4.15 Ввод-вывод🔗ℹ

функция
(порт-вывода? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является портом вывода.

функция
(порт-ввода? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является портом ввода.

функция
(порт? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является портом ввода или вывода.

функция
(написать аргумент [вывод]) → пусто?
аргумент : любой
вывод : порт? = (текущий-порт-вывода)

Выводит значение аргумента в вывод таким образом, чтобы результат можно было прочитать обратно.

функция
(написать/перенос аргумент [вывод]) → пусто?
аргумент : любой
вывод : порт? = (текущий-порт-вывода)

Как написать, но после значения дополнительно выводит литеру переноса строки.

функция
(вывести аргумент [вывод]) → пусто?
аргумент : любой
вывод : порт? = (текущий-порт-вывода)

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

функция
(вывести/перенос аргумент [вывод]) → пусто?
аргумент : любой
вывод : порт? = (текущий-порт-вывода)

Как вывести, но после значения дополнительно выводит литеру переноса строки.

функция
(написать-строку строка [порт]) → целое-неотрицательное?
строка : строка?
порт : порт-вывода? = (текущий-порт-вывода)

Пишет литеры строка в порт. Возвращает число записанных литер.

функция
(прочитать [порт]) → любой
порт : порт-ввода? = (текущий-порт-ввода)

Читает одно значение из порт в том же виде, в каком его пишет написать. В конце потока возвращает конец-файла.

функция
(прочитать-байт [порт]) → (один-из байт? конец-файла)
порт : порт-ввода? = (текущий-порт-ввода)

Читает один байт из порт. В конце потока возвращает конец-файла. Модуль базовая/порт.

функция
(прочитать-байты количество [порт]) → (один-из байты? конец-файла)
количество : целое-неотрицательное?
порт : порт-ввода? = (текущий-порт-ввода)

Читает до количество байтов из порт. В конце потока возвращает конец-файла. Модуль базовая/порт.

функция
(прочитать-строку [ввод режим]) → (один-из строка? конец-файла)
  ввод : порт? = (текущий-порт-ввода)
   режим :
(одно-из 'перенос 'возврат 'перенос/возврат
  'любой 'любой-один)
= 'перенос

Читает строку из порта ввод. Аргумент режим определяет разделитель строки:

'перенос — литера переноса #\перенос (с кодом 10);
'возврат — литера возврата каретки #\возврат (с кодом 13);
'перенос/возврат — пара литер перенос и возврат каретки;
'любой — любой из перечисленных выше;
'любой-один — перенос или возврат каретки, но не их комбинация.

константа
конец-файла : конец-файла?

Значение конца потока ввода.

функция
(конец-файла? аргумент) → булево?
аргумент : любой

Истина, если аргумент — конец-файла.

функция
(открыть-запись-в-строку [имя]) → порт-вывода?
имя : символ? = 'строка

Порт вывода, пишущий в строку. Имя порта — имя.

функция
(получить-записанную-строку порт) → строка?
порт : порт-вывода?

Строка, накопленная портом из открыть-запись-в-строку.

функция
(открыть-чтение-из-строки строка [имя]) → порт-ввода?
строка : строка?
имя : символ? = 'строка

Порт ввода из содержимого строка.

функция
(открыть-чтение-из-байтов байты [имя]) → порт-ввода?
байты : байты?
имя : символ? = 'строка

Порт ввода из содержимого байты.

функция
(получить-записанные-байты порт) → байты?
порт : порт-вывода?

Байты, накопленные портом записи в байты.

функция
(немедленно-записать порт) → пусто?
порт : порт-вывода?

Сбрасывает буфер порт на устройство.

функция
(закрыть-порт-ввода порт) → пусто?
порт : порт-ввода?

Закрывает порт ввода.

функция
(закрыть-порт-вывода порт) → пусто?
порт : порт-вывода?

Закрывает порт вывода.

параметр
(текущий-порт-вывода) → порт-вывода?
(текущий-порт-вывода порт) → пусто?
порт : порт-вывода?

Параметр, определяющий текущий порт вывода.

параметр
(текущий-порт-ввода) → порт-ввода?
(текущий-порт-ввода порт) → пусто?
порт : порт-ввода?

Параметр, определяющий текущий порт ввода.

параметр
(текущее-место) → (одно-из строка? ложь)
(текущее-место место) → пусто?
место : (один-из строка? ложь)

Параметр, определяющий текущее место (региональные настройки) для функций с суффиксом «/местные», например, строки-равны?/местные/без-регистра.

Когда этот параметр установлен в ложь, результат функций с суффиксом «/местные» должен быть переносим и совпадать с результатом функций без суффикса «/местные».

Значение "" является псевдонимом для региональных настроек операционной системы и является значением по умолчанию. Значение "C" (латинская) всегда доступно и для него результат совпадает с тем, который получен при значении ложь, для литер с кодами от 0 до 127 (цифры, латинский алфавит, ...).

Другие доступные имена мест определяются операционной системой.

Вывод при помощи функции написать и аналогичных не зависит от данного параметра.

4.16 Файлы🔗ℹ

функция
(путь? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является путём файловой системы. Модуль базовая/путь.

функция
(строка->путь строка) → путь?
строка : строка?

Преобразует строку в путь. Модуль базовая/путь.

функция
(путь->строка путь) → строка?
путь : путь?

Преобразует путь в строку. Модуль базовая/путь.

функция
(построить-путь база элемент ...) → путь?
база : (один-из строка? путь?)
элемент : (один-из строка? путь?)

Собирает путь из база и дополнительных элементов. Не обращается к файловой системе и не проверяет, существует ли путь. Модуль базовая/путь.

функция
(разделить-путь путь) → любой
путь : (один-из строка? путь?)

Разбирает путь на три значения: база (путь, символ 'relative или ложь для корня), имя последнего элемента (путь или 'up / 'same) и признак, что путь синтаксически задаёт каталог. Модуль базовая/путь.

функция
(текущий-каталог) → путь?

Текущий рабочий каталог процесса. Модуль базовая/файл.

функция
(существует-файл? путь) → булево?
путь : (один-из строка? путь?)

Проверяет, существует ли файл по пути путь. Модуль базовая/файл.

функция
(существует-каталог? путь) → булево?
путь : (один-из строка? путь?)

Проверяет, существует ли каталог по пути путь. Модуль базовая/файл.

функция
(создать-каталог путь [права]) → пусто?
путь : (один-из строка? путь?)
права : целое? = 511

Создаёт каталог по пути путь. права — права доступа (на системах, где они поддерживаются). Модуль базовая/файл.

функция
(в-каталоге [каталог]) → последовательность?
каталог : (один-из строка? путь? ложь) = ложь

Последовательность путей файлов и подкаталогов в каталог. Если каталог — ложь, обходится текущий каталог. Модуль базовая/файл.

функция
(удалить-файл путь) → пусто?
путь : (один-из строка? путь?)

Удаляет файл по пути путь. Если путь указывает на ссылку, удаляется сама ссылка, а не то, на что она указывает. Модуль базовая/файл.

функция
(удалить-каталог путь) → пусто?
путь : (один-из строка? путь?)

Удаляет пустой каталог по пути путь. Модуль базовая/файл.

функция
(удалить-каталог/файлы
путь
[ #:должен-существовать? должен-существовать?])
→ пусто?
путь : (один-из строка? путь?)
должен-существовать? : булево? = истина

Удаляет файл или каталог по пути путь. Каталог удаляется вместе с содержимым. Если должен-существовать? — истина и пути нет, вызывается исключение; если ложь, отсутствие пути не считается ошибкой. Модуль базовая/файл.

функция
(читая-файл имя обработка [#:режим режим]) → любой
  имя : (один-из строка? путь?)
  обработка : (порт-ввода? . -> . любой)
  режим : (один-из 'двоичный 'текстовый) = 'двоичный

Открывает файл имя для чтения, вызывает обработка с портом ввода и закрывает порт. Результат — значение обработка. Модуль базовая/порт.

функция
(записывая-файл имя
обработка
[ #:режим режим
#:если-существует если-существует
#:права права]) → любой
  имя : (один-из строка? путь?)
  обработка : (порт-вывода? . -> . любой)
  режим : (один-из 'двоичный 'текстовый) = 'двоичный
   если-существует :
(один-из 'ошибка 'добавить 'обновить 'заменить 'обрезать
'обрезать/заменить)
= 'ошибка
  права : целое? = 438

Открывает файл имя для записи, вызывает обработка с портом вывода и закрывает порт. если-существует задаёт поведение, если файл уже есть:

'ошибка — вызвать исключение, если файл существует (умолчание);
'заменить — удалить существующий файл (если есть) и создать новый;
'обрезать — очистить содержимое, если файл есть; иначе создать новый;
'обрезать/заменить — сначала как 'обрезать, при неудаче (например, из‑за прав) — как 'заменить;
'обновить — открыть существующий файл без очистки; если файла нет, вызвать исключение;
'добавить — писать в конец файла; если файла нет, создать его.

Модуль базовая/порт.

4.17 Функции🔗ℹ

функция
(функция? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является функцией.

4.18 Параметры🔗ℹ

функция
(параметр? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является параметром.

функция
(параметр аргумент [охрана имя]) → параметр?
  аргумент : любой
   охрана :
(один-из (любой . -> . любой)
         ложь)
= ложь
  имя : символ? = 'функция-параметра

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

синтаксис
(параметризуя ((выражение-параметра выражение-значения) ...)
команда ... выражение)

выражение-параметра = параметр?

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

4.19 Последовательности🔗ℹ

функция
(последовательность? аргумент) → булево?
аргумент : любой

Возвращает истину, если аргумент является последовательностью.

функция
(в-диапазоне конец) → последовательность?
  конец : число?
(в-диапазоне начало конец [шаг]) → последовательность?
  начало : число?
  конец : число?
  шаг : число? = 1

Возвращает последовательность чисел начиная с 0 или начало до конец с шагом шаг.

функция
(в-списке аргумент) → последовательность?
аргумент : список?

Возвращает последовательность элементов списка.

функция
(от-нуля [начало]) → последовательность?
начало : целое-неотрицательное? = 0

Бесконечная последовательность целых начиная с начало (по умолчанию 0): 0, 1, 2, … В цикл и родственных формах заканчивается вместе с более короткой последовательностью.

4.20 Потоки🔗ℹ

Модуль базовая/поток (входит в базовая). Параллельные потоки выполнения и обмен сообщениями через почтовый ящик потока.

функция
(поток? аргумент) → булево?
аргумент : любой

Истина, если аргумент — поток.

функция
(поток функция) → поток?
функция : функция?

Создаёт поток, который вызывает функция без аргументов.

функция
(текущий-поток) → поток?

Поток, в котором выполняется вызов.

функция
(поток-завершён? поток) → булево?
поток : поток?

Истина, если поток уже завершён.

функция
(прервать-поток поток) → пусто?
поток : поток?

Немедленно завершает поток. Завершение главного потока завершает программу. Если поток уже завершён, ничего не делает.

функция
(во-вложенном-потоке функция) → любой
функция : функция?

Вызывает функция во вложенном потоке и ждёт её результата. Результат формы — результат функция.

функция
(послать-в-поток поток объект) → пусто?
поток : поток?
объект : любой

Кладёт объект в почтовый ящик поток без ожидания.

функция
(получить-для-потока) → любой

Забирает сообщение из почтового ящика текущего потока. Если сообщений нет, ждёт, пока не появится.

функция
(попытаться-получить-для-потока) → (один-из любой ложь)

Как получить-для-потока, но не ждёт: если ящик пуст, возвращает ложь.

функция
(событие-получения) → любой

Синхронизируемое событие, готовое, когда получить-для-потока не заблокируется.

функция
(ждать-события время событие) → (один-из любой ложь)
время : любой
событие : любой

Ждёт готовности событие не дольше время секунд (sync/timeout). Если время вышло — ложь, иначе — результат синхронизации. время может быть ложь (ждать без ограничения) или неотрицательным числом.

функция
(спать секунд) → пусто?
секунд : число?

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

функция
(не-дольше время
действие
[ #:при-ошибке при-ошибке]) → любой
  время : любой
  действие : функция?
  при-ошибке : любой = ложь

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

4.21 Дата🔗ℹ

Модуль дата — календарная дата и время суток:

используется дата
д = дата 2026 9 22 15 30
дата->строка д
дата->строка $ начало-дня д

Имена дата, год, час совпадают с модулем база-данных: подключайте один из модулей с префиксом.

структура
дата% : любой

Календарная дата и время суток. Поля: секунда, минута, час, день, месяц, год, день-недели, день-года, летнее-время?, временная-зона и наносекунда. Структура читаемая.

функция
(дата [ год
месяц
день
час
минута
секунда
наносекунда]) → дата%
  год : целое? = 1
  месяц : целое? = 1
  день : целое? = 1
  час : целое? = 0
  минута : целое? = 0
  секунда : целое? = 0
  наносекунда : целое? = 0

Собирает дату. День недели, день года, летнее время и зона считаются по местному часовому поясу.

функция
(секунда дата) → целое?
  дата : дата%
(минута дата) → целое?
  дата : дата%
(час дата) → целое?
  дата : дата%
(день дата) → целое?
  дата : дата%
(месяц дата) → целое?
  дата : дата%
(год дата) → целое?
  дата : дата%
(наносекунда дата) → целое?
  дата : дата%
(день-недели дата) → целое?
  дата : дата%
(день-года дата) → целое?
  дата : дата%
(летнее-время? дата) → булево?
  дата : дата%
(временная-зона дата) → целое?
  дата : дата%

Селекторы полей дата%. день-недели: 0 — воскресенье, 6 — суббота. день-года: 0 — 1 января. временная-зона — смещение в секундах к востоку от GMT. летнее-время? — истина, если действует летнее время.

функция
(секунды->дата секунды) → дата%
секунды : число?

Дата по числу секунд с 1 января 1970 года (UTC) в местном часовом поясе.

функция
(дата->секунды дата) → целое?
дата : дата%

Число секунд с 1 января 1970 года (UTC).

функция
(дата->строка дата) → строка?
дата : дата%

Строка ДД.ММ.ГГГГ ЧЧ:ММ:СС. Если наносекунды не нуль, они добавляются после точки девятью цифрами.

функция
(начало-дня дата) → дата%
дата : дата%

Копия с временем 00:00:00.

функция
(конец-дня дата [совсем]) → дата%
дата : дата%
совсем : булево? = ложь

Копия с временем 23:59:59. Если совсем — истина, наносекунды 999999999, иначе 0.

функция
(начало-месяца дата) → дата%
дата : дата%

Первый день того же месяца, время 00:00:00.

функция
(конец-месяца дата [совсем]) → дата%
дата : дата%
совсем : булево? = ложь

Последний день того же месяца. Время как у конец-дня.

функция
(начало-года дата) → дата%
дата : дата%

1 января того же года, время 00:00:00.

функция
(конец-года дата) → дата%
дата : дата%

31 декабря того же года. Время как у конец-дня без совсем.

функция
(добавить-месяц дата количество) → дата%
дата : дата%
количество : целое?

Сдвигает месяц на количество (отрицательное — назад). Если такого дня в новом месяце нет, берётся последний день месяца.

4.22 Модули🔗ℹ

синтаксис
(используется выражение-модуля ...)
(используется (с-префиксом префикс выражение-модуля))
(используется (кроме выражение-модуля имя ...))
(используется (файл строка))

Подключает указанные модули: их экспортируемые имена становятся доступны в текущем модуле.

выражение-модуля — символ с именем модуля (файл ".1" в коллекции 1 или относительно текущего каталога) либо строка с путём к файлу.

с-префиксом добавляет префикс ко всем именам из модуля. кроме подключает модуль без перечисленных имён. файл подключает файл по строке пути.

Несколько модулей можно перечислить в одной форме используется или вызвать её несколько раз.

синтаксис
(предоставлять имя ...)
(предоставлять (всё-из выражение-модуля))
(предоставлять (с-контрактом выражение ...))

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

Обычная форма перечисляет экспортируемые идентификаторы. всё-из реэкспортирует всё из уже подключённого модуля. с-контрактом экспортирует с контрактами (как contract-out в Racket).

4.23 Рисование🔗ℹ

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

рисование/цвет — цвет%, стандартные-цвета, внутренний-цвет;
рисование/холст — холст-адины (объекты класса холст%);
рисование/изображение — изображение%;
рисование/картинка — функции значков переработка, галочка, лямбда, стоп и текст.

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

4.23.1 цвет%🔗ℹ

класс
цвет% : класс?

Базовый класс: объект-графического-интерфейса%. Цвет: красный, зелёный и синий составляющие (целые числа от 0 до 255) и укрывистость (вещественное число от 0 до 1). Например, все нули и укрывистость 1 — непрозрачный чёрный; все 255 и укрывистость 1 — непрозрачный белый; красный 255 и укрывистость 0,5 — полупрозрачный красный.

конструктор
(цвет% [ красный
зелёный
синий
укрывистость
образец
внутренний]) → цвет%
  красный : целое-неотрицательное? = 0
  зелёный : целое-неотрицательное? = 0
  синий : целое-неотрицательное? = 0
  укрывистость : число? = 0.0
  образец : любой = ложь
  внутренний : любой = ложь

Создаётся формой объект:

объект цвет%
  красный красный
  зелёный зелёный
  синий синий
  укрывистость укрывистость
  образец образец
  внутренний внутренний

Вместо составляющих можно передать образец: другой цвет%, символ имени из стандартные-цвета или уже готовое значение цвета. Если задан внутренний или образец, составляющие игнорируются; по умолчанию оба ложь. Без образца и без внутреннего объекта создаётся цвет из составляющих; укрывистость по умолчанию 0.0 — цвет полностью прозрачный, пока её не задать явно.

константа
стандартные-цвета : объект%

Справочник имён цветов из базы Racket. Модуль рисование/цвет. Символы имён можно передавать в образец конструктора цвет%, в внутренний-цвет и туда, где ожидается цвет (например, кисть на холст%).

метод
(найти имя) → любой
имя : символ?

Ищет цвет по символу имя. Для русских имён есть встроенный перевод: 'белый, 'синий, 'голубой, 'красный, 'оранжевый, 'чёрный, 'жёлтый, 'зелёный, 'тёмно-зелёный, 'серый, 'светло-жёлтый. Иначе имя ищется в базе как есть. Возвращает внутреннее значение цвета для цвет% и холста.

метод
(имена) → список?

Список всех имён цветов, известных базе Racket.

метод
(красный) → целое-неотрицательное?

читает красный компонент цвета (от 0 до 255).

метод
(зелёный) → целое-неотрицательное?

читает зелёный компонент цвета (от 0 до 255).

метод
(синий) → целое-неотрицательное?

читает синий компонент цвета (от 0 до 255).

метод
(установить красный
зелёный
синий
укрывистость) → пусто?
  красный : целое-неотрицательное?
  зелёный : целое-неотрицательное?
  синий : целое-неотрицательное?
  укрывистость : число?

устанавливает компоненты цвета. красный, зелёный, синий — от 0 до 255; укрывистость — от 0 (полная прозрачность) до 1 (непрозрачный).

метод
(укрывистость) → число?

читает укрывистость (непрозрачность) цвета. Значение от 0 (полная прозрачность) до 1 (непрозрачный).

функция
(внутренний-цвет образец) → любой
образец : любой

Преобразует образец во внутреннее значение цвета Racket. Если образец — цвет%, берётся его внутренний; если символ — ищется через стандартные-цвета; иначе образец считается уже готовым внутренним цветом. Используется при создании цвет% и в API, ожидающем низкоуровневый цвет.

функция
(неизменный-цвет [ красный
зелёный
синий
укрывистость]) → цвет%
  красный : целое-неотрицательное? = 0
  зелёный : целое-неотрицательное? = 0
  синий : целое-неотрицательное? = 0
  укрывистость : число? = 1.0

Создаёт неизменяемый объект цвета. красный, зелёный, синий — от 0 до 255; укрывистость — от 0 до 1 (по умолчанию 1.0 — непрозрачный).

4.23.2 холст%🔗ℹ

класс
холст% : класс?

Базовый класс: объект-графического-интерфейса%. Контекст рисования: линии, фигуры, текст и изображения. Холст картины даёт метод холст; у изображение% — тоже холст. Модуль рисование/холст предоставляет холст-адины; объекты, которые она возвращает, принадлежат этому классу. Координаты — в единицах рисования холста. Углы — в радианах: 0 направо, половина пи вверх, против часовой стрелки.

функция
(холст-адины внутренний) → холст%
внутренний : любой

Оборачивает внутренний объект контекста рисования Racket в холст%. Модуль рисование/холст. внутренний — низкоуровневый указатель на объект (например, из make-dc у изображение% или get-dc у картина%).

метод
(залить-фоном) → пусто?

заполняет область текущим цветом фона. См. также очистить.

метод
(очистить) → пусто?

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

метод
(копировать лево
верх
ширина
высота
лево-цели
верх-цели) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?
  лево-цели : число?
  верх-цели : число?

копирует прямоугольник в точку (лево-цели, верх-цели) на том же холсте. Области могут пересекаться.

метод
(нарисовать-дугу лево
верх
ширина
высота
начальный-угол
конечный-угол) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?
  начальный-угол : число?
  конечный-угол : число?

дуга эллипса, вписанного в прямоугольник лево–верх–ширина–высота. Углы: от начального к конечному против часовой стрелки. Если углы равны, рисуется полный эллипс. Контур — текущим пером; если кисть не прозрачная, сектор заливается кистью.

метод
(нарисовать-эллипс лево верх ширина высота) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?

эллипс в прямоугольнике лево–верх–ширина–высота. Перо — контур, кисть — заливка.

метод
(нарисовать-прямоугольник лево
верх
ширина
высота) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?

прямоугольник с тем же смыслом пера и кисти.

метод
(нарисовать-закруглённый-прямоугольник лево
верх
ширина
высота
[ радиус]) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?
  радиус : число? = -0.25

прямоугольник со скруглёнными углами. радиус по умолчанию $-0.25$: положительный — радиус дуги угла, отрицательный — доля меньшей стороны. Если величина слишком велика, берётся половина ширины или высоты.

метод
(нарисовать-линию лево-начала
верх-начала
лево-конца
верх-конца) → пусто?
  лево-начала : число?
  верх-начала : число?
  лево-конца : число?
  верх-конца : число?

отрезок от (лево-начала, верх-начала) до (лево-конца, верх-конца).

метод
(нарисовать-линии список-линий
[ сместить-вправо
сместить-вниз]) → пусто?
  список-линий : список?
  сместить-вправо : число? = 0
  сместить-вниз : число? = 0

ломаная по списку точек.

метод
(нарисовать-многоугольник точки
[ сместить-вправо
сместить-вниз
стиль-заполнения]) → пусто?
  точки : список?
  сместить-вправо : число? = 0
  сместить-вниз : число? = 0
  стиль-заполнения : символ? = 'чёт-нечет

многоугольник по списку точек. стиль-заполнения по умолчанию 'чёт-нечет; иное значение — правило ненулевой обмотки.

метод
(нарисовать-контур контур
[ сместить-вправо
сместить-вниз
стиль-заполнения]) → пусто?
  контур : любой
  сместить-вправо : число? = 0
  сместить-вниз : число? = 0
  стиль-заполнения : символ? = 'чёт-нечет

рисует контур. Смещения и стиль-заполнения как у многоугольника.

метод
(нарисовать-точку лево верх) → пусто?
лево : число?
верх : число?

точка в (лево, верх).

метод
(нарисовать-лекало начало
контрольная-точка
конец) → пусто?
  начало : любой
  контрольная-точка : любой
  конец : любой

сплайн от начала до конца через контрольную точку. Каждая точка — список из лево и верх или объект с полями лево и верх.

метод
(нарисовать-текст текст
лево
верх
[ комбинировать
начальная-литера
угол]) → пусто?
  текст : строка?
  лево : число?
  верх : число?
  комбинировать : любой = ложь
  начальная-литера : целое? = 0
  угол : число? = 0

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

метод
(нарисовать-изображение источник
лево-цели
верх-цели
[ стиль
цвет
маска]) → булево?
  источник : изображение%
  лево-цели : число?
  верх-цели : число?
  стиль : любой = 'обычный
  цвет : любой = 'чёрный
  маска : любой = ложь

стиль и цвет учитываются только для чёрно-белого изображения: 'непрозрачный закрашивает белые пиксели фоном. маска — другое изображение того же размера или ложь. Возвращает истина, если рисунок удался.

метод
(нарисовать-часть-изображения источник
лево-цели
верх-цели
лево-части
верх-части
ширина-части
высота-части
[ стиль
цвет
маска]) → булево?
  источник : изображение%
  лево-цели : число?
  верх-цели : число?
  лево-части : число?
  верх-части : число?
  ширина-части : число?
  высота-части : число?
  стиль : любой = 'обычный
  цвет : любой = 'чёрный
  маска : любой = ложь

как нарисовать-изображение, но копирует прямоугольник источника.

метод
(начать-слой прозрачность) → пусто?
прозрачность : число?

откладывает рисование до конца слоя, затем переносит результат с заданной прозрачностью (от 0 до 1), умноженной на текущую. На время слоя текущая прозрачность становится 1. В отличие от прозрачность, перекрывающиеся штрихи слоя тускнеют вместе, а не по отдельности.

метод
(закончить-слой) → пусто?

завершает слой, начатый начать-слой.

метод
(отрисовать-немедленно) → пусто?

сбрасывает отложенную отрисовку картины; для прочих холстов ничего не делает.

метод
(начать-документ сообщение) → пусто?
сообщение : строка?

начало печати: сообщение к началу документа.

метод
(закончить-документ) → пусто?

завершает документ печати.

метод
(начать-страницу) → пусто?

начало страницы при печати.

метод
(закончить-страницу) → пусто?

завершение страницы при печати.

метод
(ключ-метрики-шрифта) → целое?

целое число для кэша размеров текста: одинаковый ключ значит одинаковые метрики. Ноль — кэшировать нельзя.

метод
(прозрачность) → число?
(прозрачность значение) → пусто?
значение : число?

без аргумента читает непрозрачность рисования (от 0 до 1), с аргументом задаёт её.

метод
(фон) → любой
(фон цвет) → пусто?
цвет : любой

цвет фона для залить-фоном (чтение и запись).

метод
(цвет-текста) → любой
(цвет-текста цвет) → пусто?
цвет : любой

цвет текста для нарисовать-текст (чтение и запись).

метод
(кисть) → любой
(кисть значение) → пусто?
  значение : любой
(кисть цвет стиль) → пусто?
  цвет : любой
  стиль : любой

без аргументов возвращает текущую кисть; с кистью задаёт её; с цветом и стилем создаёт кисть этого цвета. Цвет может быть символом из стандартные-цвета. Стиль 'непрозрачный — непрозрачная кисть, иначе сплошная.

метод
(масштаб) → любой
(масштаб по-ширине по-высоте) → пусто?
по-ширине : число?
по-высоте : число?

без аргументов возвращает два значения — масштаб по ширине и по высоте; с по-ширине и по-высоте задаёт его. Это абсолютный масштаб логических координат; масштабировать умножает текущее преобразование.

метод
(масштаб-подложки) → число?

масштаб подложки холста: сколько пикселей на одну единицу рисования.

метод
(высота-литеры) → число?

высота литеры текущего шрифта.

метод
(ширина-литеры) → число?

средняя ширина литеры текущего шрифта.

метод
(область-отсечения) → любой
(область-отсечения значение) → пусто?
значение : любой

без аргумента — текущая область отсечения или ложь; с аргументом задаёт её. ложь снимает отсечение. См. также отсечь-прямоугольник.

метод
(отсечь-прямоугольник лево
верх
ширина
высота) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?

задаёт прямоугольную область отсечения.

метод
(масштаб-устройства) → любой

два значения: масштаб устройства по ширине и по высоте.

метод
(шрифт) → любой
(шрифт значение) → пусто?
значение : любой

без аргумента — текущий шрифт; с аргументом задаёт его.

метод
(контекст-opengl) → любой

контекст OpenGL или ложь, если его нет.

метод
(начальная-матрица) → любой
(начальная-матрица матрица) → пусто?
матрица : любой

без аргумента — начальная матрица преобразования (вектор из шести чисел); с аргументом задаёт её.

метод
(начало-координат) → любой
(начало-координат лево верх) → пусто?
лево : число?
верх : число?

без аргументов возвращает начало логических координат в координатах устройства; с лево и верх задаёт его. сдвинуть добавляет сдвиг к текущему преобразованию.

метод
(перо) → любой
(перо значение) → пусто?
  значение : любой
(перо цвет толщина стиль) → пусто?
  цвет : любой
  толщина : число?
  стиль : любой

без аргументов возвращает текущее перо; с пером задаёт его; с цветом, толщиной и стилем создаёт перо. Цвет может быть символом из стандартные-цвета. Стиль: 'прозрачный, 'сплошной, 'исключающее-или, 'подсветка, 'точки, 'длинный-пунктир, 'короткий-пунктир, 'штрих-пунктир и те же с приставкой исключающее-или-.

метод
(рамка-контура контур тип) → любой
контур : любой
тип : символ?

четыре значения: лево, верх, ширина и высота рамки контура. тип — 'контур (точки пути), 'обводка (с учётом пера) или 'заливка.

метод
(поворот) → число?
(поворот угол) → пусто?
угол : число?

без аргумента — угол поворота логических координат в радианах; с аргументом задаёт его. повернуть добавляет поворот к текущему преобразованию.

метод
(размер) → любой

два значения: ширина и высота области рисования.

метод
(сглаживание) → символ?
(сглаживание режим) → пусто?
режим : символ?

без аргумента — режим сглаживания; с аргументом задаёт его. Значения: 'без-сглаживания, 'сглаженное, 'выровненное.

метод
(цвет-фона-текста) → любой
(цвет-фона-текста цвет) → пусто?
цвет : любой

цвет фона текста (чтение и запись). Учитывается в режиме 'сплошной у режим-текста.

метод
(размеры-текста текст
[ шрифт
комбинировать
начальная-литера]) → любой
  текст : строка?
  шрифт : любой = ложь
  комбинировать : любой = ложь
  начальная-литера : целое? = 0

четыре значения: ширина текста, высота шрифта, спуск под базовую линию и дополнительный вертикальный зазор. Если шрифт — ложь, берётся текущий шрифт. комбинировать как у нарисовать-текст.

метод
(режим-текста) → символ?
(режим-текста режим) → пусто?
режим : символ?

без аргумента — режим рисования текста; с аргументом задаёт его. 'сплошной заливает фон цветом цвет-фона-текста; 'прозрачный рисует поверх уже нарисованного.

метод
(преобразование) → любой
(преобразование значение) → пусто?
значение : любой

без аргумента — полное преобразование холста; с аргументом задаёт его. преобразовать умножает текущее преобразование на матрицу.

метод
(есть-литера? литера) → булево?
литера : любой

истина, если для литеры есть знак.

метод
(работает?) → булево?

истина, если холст пригоден для рисования.

метод
(продолжить-отрисовку) → пусто?

возобновляет сброс отложенной отрисовки картины; для прочих холстов ничего не делает.

метод
(приостановить-отрисовку) → пусто?

откладывает сброс отрисовки картины; для прочих холстов ничего не делает.

метод
(повернуть угол) → пусто?
угол : число?

добавляет поворот на угол радиан к текущему преобразованию.

метод
(масштабировать по-ширине по-высоте) → пусто?
по-ширине : число?
по-высоте : число?

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

метод
(масштаб-выравнивания значение) → пусто?
значение : число?

масштаб выравнивания координат при рисовании без сглаживания или в выровненном режиме. По умолчанию 1.

метод
(преобразовать матрица) → пусто?
матрица : любой

умножает текущее преобразование на матрицу из шести чисел.

метод
(сдвинуть вправо вниз) → пусто?
вправо : число?
вниз : число?

добавляет сдвиг к текущему преобразованию.

метод
(подобрать-цвет проба результат) → пусто?
проба : любой
результат : любой

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

4.23.3 изображение%🔗ℹ

класс
изображение% : класс?

Базовый класс: объект-графического-интерфейса%. Растр: цветной, чёрно-белый или с каналом прозрачности. У изображения есть масштаб подложки: сколько пикселей приходится на одну единицу рисования (у чёрно-белого всегда 1). Нужно задать либо файл, либо оба ширина и высота, либо внутренний. Иначе вызывается исключение с сообщением, что ширина и высота обязательны. Пустой растр заданной ширины и высоты — белый; с каналом прозрачности начальная прозрачность полная. Если заданы байты, ширина и высота, создаётся чёрно-белый растр из этих битов.

конструктор
(изображение% [ ширина
высота
масштаб
файл
вид-файла
цвет-фона
неудачная-загрузка-ошибка?
хранить-данные-файла?
байты
чёрно-белое?
прозрачность?
внутренний]) → изображение%
  ширина : любой = ложь
  высота : любой = ложь
  масштаб : число? = 1.0
  файл : любой = ложь
  вид-файла : любой = 'unknown
  цвет-фона : любой = ложь
  неудачная-загрузка-ошибка? : булево? = ложь
  хранить-данные-файла? : булево? = ложь
  байты : любой = ложь
  чёрно-белое? : любой = ложь
  прозрачность? : булево? = ложь
  внутренний : любой = ложь

Создаётся формой объект:

объект изображение%
  ширина ширина
  высота высота
  масштаб масштаб
  файл файл
  вид-файла вид-файла
  цвет-фона цвет-фона
  неудачная-загрузка-ошибка? неудачная-загрузка-ошибка?
  хранить-данные-файла? хранить-данные-файла?
  байты байты
  чёрно-белое? чёрно-белое?
  прозрачность? прозрачность?
  внутренний внутренний

ширина и высота обязательны вместе, если нет файла и нет внутреннего объекта; по умолчанию оба ложь. масштаб по умолчанию 1.0. файл, цвет-фона, байты, чёрно-белое? и внутренний по умолчанию ложь. вид-файла по умолчанию 'unknown. неудачная-загрузка-ошибка? и хранить-данные-файла? по умолчанию ложь. прозрачность? по умолчанию ложь. байты — чёрно-белый растр из битов (восемь пикселей в байте, 1 — чёрный).

метод
(ширина) → целое-неотрицательное?

размер в единицах рисования.

метод
(высота) → целое-неотрицательное?

размер в единицах рисования.

метод
(масштаб) → число?

масштаб подложки.

метод
(глубина-цвета) → целое-неотрицательное?

1 для чёрно-белого, 32 для цветного.

метод
(чёрно-белое?) → булево?

истина, если растр не цветной.

метод
(есть-прозрачность?) → булево?

есть ли канал прозрачности.

метод
(работает?) → булево?

истина, если изображение удалось загрузить; иначе рисование в него и из него не действует.

метод
(холст) → любой

холст для рисования по этому растру или ложь.

метод
(загрузить-файл) → пусто?

читает файл. Аргументы: файл, вид-файла, цвет-фона, неудачная-загрузка-ошибка?, хранить-данные-файла?. Допустимо, только если масштаб подложки равен 1.

метод
(записать-файл) → пусто?

записывает файл. Аргументы: файл, вид-файла, качество (75), без-масштаба?.

метод
(данные-файла) → любой

если при загрузке просили сохранить данные, возвращает содержимое файла; иначе ложь.

метод
(указатель) → любой

низкоуровневый указатель на объект растра.

метод
(загруженная-маска) → любой
(загруженная-маска значение) → пусто?
значение : любой

маска прозрачности, полученная при загрузке, или ложь. Чтение и запись. Сама по себе при рисовании не применяется: её передают как маска в нарисовать-изображение.

метод
(пиксели-в-байты лево
верх
ширина
высота
байты
[ только-прозрачность?
учитывать-прозрачность?
без-масштаба?]) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?
  байты : любой
  только-прозрачность? : булево? = ложь
  учитывать-прозрачность? : булево? = ложь
  без-масштаба? : булево? = ложь

копирует прямоугольник в изменяемые байты (по четыре байта на пиксель: прозрачность, красный, зелёный, синий). только-прозрачность? — только канал прозрачности; учитывать-прозрачность? — значения уже умножены на прозрачность; без-масштаба? — координаты в пикселях, без масштаба подложки.

метод
(байты-в-пиксели лево
верх
ширина
высота
байты
[ только-прозрачность?
учитывать-прозрачность?
без-масштаба?]) → пусто?
  лево : число?
  верх : число?
  ширина : число?
  высота : число?
  байты : любой
  только-прозрачность? : булево? = ложь
  учитывать-прозрачность? : булево? = ложь
  без-масштаба? : булево? = ложь

обратная запись из байтов в прямоугольник растра. Те же необязательные аргументы.

4.23.4 Значки🔗ℹ

Функции модуля рисование/картинка возвращают изображение%. Общие ключевые аргументы: цвет (символ из стандартные-цвета или цвет%; если цвет — символ, он ищется в справочнике), высота и материал. Высота и материал по умолчанию — стандартные для значков. Цвет по умолчанию свой у каждой функции.

функция
(переработка #:цвет цвет
#:высота высота
#:материал материал) → изображение%
  цвет : любой
  высота : число?
  материал : любой

Значок переработки: три загнутые стрелки.

функция
(галочка #:цвет цвет
#:высота высота
#:материал материал) → изображение%
  цвет : любой
  высота : число?
  материал : любой

Значок галочки.

функция
(лямбда #:цвет цвет
#:высота высота
#:материал материал) → изображение%
  цвет : любой
  высота : число?
  материал : любой

Значок буквы «лямбда».

функция
(стоп #:цвет цвет
#:высота высота
#:материал материал) → изображение%
  цвет : любой
  высота : число?
  материал : любой

Значок остановки.

функция
(текст строка
шрифт
#:обрезать? обрезать
#:цвет цвет
#:высота высота
#:материал материал
#:толщина-контура толщина-контура) → изображение%
  строка : строка?
  шрифт : шрифт%
  обрезать : булево?
  цвет : любой
  высота : число?
  материал : любой
  толщина-контура : число?

Значок из строки строка шрифтом шрифт (по умолчанию новый объект шрифт%). обрезать? (по умолчанию истина) убирает лишние поля вокруг букв. Цвет по умолчанию 'белый. толщина-контура по умолчанию — высота, делённая на 32.

4.24 Графический интерфейс🔗ℹ

Классы и интерфейсы окон, кнопок, панелей, меню и текстового редактора доступны после

(используется графический-интерфейс)

Отдельные файлы каталога подключаются по имени, например графический-интерфейс/кнопка или графический-интерфейс/табличная-панель. Сводка графический-интерфейс не подключает графический-интерфейс/табличная-панель, графический-интерфейс/поле-даты, графический-интерфейс/область-уведомлений, графический-интерфейс/уведомление, графический-интерфейс/стиль и графический-интерфейс/набор-команд — их нужно указать самим. Модуль сам подключает класс. Объекты создаются формой объект.

Общий предок виджетов — объект-графического-интерфейса%. Многие методы читают значение без аргументов и записывают его, если аргумент передан: так устроены заголовок, значение, минимальная-ширина, выравнивание. События — методы с приставкой при- или с вопросом (можно-закрыть?); в базовых классах они ничего не делают или возвращают значение по умолчанию, их можно переопределить.

Класс реализует методы своих интерфейсов: у кнопка% доступны методы элемент-управления<%> и всех предков этого интерфейса.

4.24.1 объект-графического-интерфейса%🔗ℹ

класс
объект-графического-интерфейса% : класс?

Общий предок окон, элементов, шрифтов, событий, кусков и стилей. Модуль графический-интерфейс/объект.

конструктор
(объект-графического-интерфейса% внутренний)
→ объект-графического-интерфейса%
внутренний : любой

Создаётся формой объект:

объект объект-графического-интерфейса%
внутренний внутренний

внутренний — уже созданный внутренний объект; если его нет, наследник создаёт свой.

метод
(внутренний) → любой

Возвращает внутренний объект, обёрнутый этим классом.

4.24.2 область<%>🔗ℹ

интерфейс
область<%> : любой

Общие размеры и растягивание. Модуль графический-интерфейс/интерфейс-область.

родитель — вместилище, в котором лежит область, или ложь у окна верхнего уровня;
главное-окно — окно верхнего уровня, которому принадлежит область, или ложь;
минимальная-ширина и минимальная-высота — чтение и запись минимальных размеров; ложь — размер по содержимому;
минимальные-размеры-вывода — два значения: графические минимумы ширины и высоты (с учётом рамки и полей);
растягивается-ширина и растягивается-высота — можно ли отдавать области лишнее место во вместилище.

Аргументы инициализации у реализующих классов: родитель (обязателен, если не окно верхнего уровня), минимальная-ширина, минимальная-высота (по умолчанию ложь), растягивается-ширина и растягивается-высота (по умолчанию истина).

4.24.3 окно<%>🔗ℹ

интерфейс
окно<%> : интерфейс?

Расширяет: область<%>. Показ, фокус, геометрия и события окна. Модуль графический-интерфейс/интерфейс-окно. События (в базовой реализации ничего не делают; клавиша и мышь элемента возвращают ложь — событие можно обработать дальше). Дополнительный аргумент инициализации: включен (по умолчанию истина).

метод
(показать состояние) → пусто?
состояние : любой

Показать или скрыть окно (аргумент не ложь — показать).

метод
(показано?) → булево?

Видно ли окно.

метод
(включить) → булево?
(включить состояние) → пусто?
состояние : любой

Разрешить или запретить взаимодействие.

метод
(включено?) → булево?

Можно ли взаимодействовать.

метод
(есть-фокус?) → булево?

Есть ли клавиатурный фокус.

метод
(сфокусировать) → пусто?

Отдать окну фокус.

метод
(ширина) → целое-неотрицательное?

Внешний размер.

метод
(высота) → целое-неотрицательное?

Внешний размер.

метод
(лево) → число?

Положение относительно родителя или экрана у окна верхнего уровня.

метод
(верх) → число?

Положение относительно родителя или экрана у окна верхнего уровня.

метод
(размеры) → любой

Два значения: внешние ширина и высота.

метод
(внутренние-размеры) → любой

Два значения: ширина и высота клиентской области без рамки.

метод
(окно->экран лево верх) → любой
лево : число?
верх : число?

Из координат окна в экранные.

метод
(экран->окно лево верх) → любой
лево : число?
верх : число?

Из экранных в координаты окна.

метод
(переместить-курсор лево верх) → пусто?
лево : число?
верх : число?

Поставить указатель мыши в точку окна.

метод
(заголовок) → любой
(заголовок значение) → пусто?
значение : любой

Подпись окна или элемента (чтение и запись).

метод
(курсор) → любой
(курсор значение) → пусто?
значение : любой

Вид указателя над окном.

метод
(принимать-файлы) → булево?
(принимать-файлы значение) → пусто?
значение : любой

Принимать ли перетаскивание файлов (чтение и запись).

метод
(контекстное-меню меню лево верх) → пусто?
  меню : любой
  лево : число?
  верх : число?

Показать всплывающее-меню% в точке (меню, лево, верх).

метод
(указатель) → любой

Низкоуровневая ручка окна.

метод
(обновить) → пусто?

Запросить перерисовку.

метод
(режим-колеса-мыши) → любой
(режим-колеса-мыши значение) → пусто?
значение : любой

Без аргумента читает режим; с аргументом задаёт 'по-одному, 'по-целым или 'сразу.

метод
(при-получении-файла путь) → пусто?
путь : строка?

Этот метод переопределяется формой переопределить.

Перетащили файл; аргумент — путь.

метод
(при-изменении-фокуса есть-фокус?) → пусто?
есть-фокус? : булево?

Этот метод переопределяется формой переопределить.

Аргумент: появился ли фокус.

метод
(при-перемещении лево верх) → пусто?
лево : число?
верх : число?

Этот метод переопределяется формой переопределить.

Новое лево и верх.

метод
(при-изменении-размера ширина высота) → пусто?
ширина : число?
высота : число?

Этот метод переопределяется формой переопределить.

Новая ширина и высота.

метод
(при-получении-элементом-клавиши элемент
событие) → любой
элемент : любой
событие : событие-клавиши%

Этот метод переопределяется формой переопределить.

Клавиша ушла потомку; аргументы: элемент и событие клавиши. В базовой реализации возвращает ложь.

метод
(при-получении-элементом-события элемент
событие) → любой
элемент : любой
событие : событие-мыши%

Этот метод переопределяется формой переопределить.

Мышь у потомка. В базовой реализации возвращает ложь.

метод
(при-изменении-фокуса-элемента элемент
есть-фокус?) → пусто?
элемент : любой
есть-фокус? : булево?

Этот метод переопределяется формой переопределить.

Фокус потомка.

метод
(при-активации-содержащего-окна активно?) → пусто?
активно? : булево?

Этот метод переопределяется формой переопределить.

Изменилось охватывающее окно.

метод
(при-включении-содержащего-окна включено?) → пусто?
включено? : булево?

Этот метод переопределяется формой переопределить.

Изменилось охватывающее окно.

метод
(при-показывании-содержащего-окна показано?) → пусто?
показано? : булево?

Этот метод переопределяется формой переопределить.

Изменилось охватывающее окно.

4.24.4 подобласть<%>🔗ℹ

интерфейс
подобласть<%> : интерфейс?

Расширяет: область<%>. Отступы внутри вместилища. Модуль графический-интерфейс/интерфейс-подобласть. У элементов управления поля по умолчанию 2, у групп и панелей — 0. Аргументы инициализации с теми же именами.

метод
(горизонтальные-поля) → целое-неотрицательное?
(горизонтальные-поля значение) → пусто?
значение : любой

Отступ слева и справа (чтение и запись).

метод
(вертикальные-поля) → целое-неотрицательное?
(вертикальные-поля значение) → пусто?
значение : любой

Отступ сверху и снизу (чтение и запись).

4.24.5 подокно<%>🔗ℹ

интерфейс
подокно<%> : интерфейс?

Одновременно окно<%> и подобласть<%>. Модуль графический-интерфейс/интерфейс-подокно. Методы окно<%> и подобласть<%> тоже доступны.

метод
(родитель) → любой
(родитель новый-родитель) → пусто?
новый-родитель : любой

Без аргумента читает вместилище; с новым родителем переносит окно в другое вместилище.

4.24.6 вместилище<%>🔗ℹ

интерфейс
вместилище<%> : интерфейс?

Расширяет: область<%>. Контейнер дочерних элементов. Модуль графический-интерфейс/интерфейс-вместилище. Аргументы инициализации: граница, интервал, выравнивание — список из двух символов (у каждого класса своё умолчание).

метод
(элементы) → любой

Список детей (объекты Адины).

метод
(добавить-элемент элемент) → пусто?
элемент : любой

Показать уже созданного ребёнка (не уничтожая его).

метод
(удалить-элемент элемент) → пусто?
элемент : любой

Убрать уже созданного ребёнка (не уничтожая его).

метод
(изменить-элементы отбор) → пусто?
отбор : функция?

Функция от списка детей, возвращает новый список; порядок в списке — порядок раскладки.

метод
(начать-изменения) → пусто?

Начало пакета обновлений раскладки: между ним и закончить-изменения дети не пересчитываются.

метод
(закончить-изменения) → пусто?

Завершение пакета обновлений раскладки.

метод
(пересчитать-положения) → пусто?

Сразу переложить детей.

метод
(положения-изменены) → пусто?

Сообщить, что геометрия детей могла измениться, и нужна новая раскладка.

метод
(граница) → целое-неотрицательное?
(граница значение) → пусто?
значение : любой

Внутренний отступ у края контейнера (чтение и запись, по умолчанию 0).

метод
(интервал) → целое-неотрицательное?
(интервал значение) → пусто?
значение : любой

Промежуток между детьми (по умолчанию 0).

метод
(выравнивание) → любой
(выравнивание горизонтально вертикально) → пусто?
горизонтально : любой
вертикально : любой

Без аргументов возвращает два символа (горизонталь и вертикаль), с двумя символами задаёт их. Горизонталь: 'лево, 'центр, 'право. Вертикаль: 'верх, 'центр, 'низ.

метод
(размер-вместилища информация) → любой
информация : любой

По сведениям о детях вернуть желаемые ширину и высоту контейнера; в базовой реализации — расчёт предка.

метод
(разместить-элементы информация
ширина
высота) → пусто?
  информация : любой
  ширина : число?
  высота : число?

По сведениям о детях и размеру контейнера вернуть положения детей; в базовой реализации — расчёт предка.

метод
(после-добавления-элемента элемент) → пусто?
элемент : любой

Этот метод переопределяется формой переопределить.

Событие после появления нового ребёнка; аргумент — этот элемент. В базовой реализации ничего не делает.

4.24.7 вместилище-окно<%>🔗ℹ

интерфейс
вместилище-окно<%> : интерфейс?

Одновременно вместилище<%> и окно<%>. Модуль графический-интерфейс/интерфейс-вместилище-окно. Отдельных методов нет: это сочетание контейнера и видимого окна (панель, главное окно, диалог).

4.24.8 главное-окно<%>🔗ℹ

интерфейс
главное-окно<%> : интерфейс?

Расширяет: вместилище-окно<%>. Окно верхнего уровня. Модуль графический-интерфейс/интерфейс-главное-окно. Выравнивание по умолчанию '(центр верх), родитель необязателен.

метод
(в-центр [направление]) → пусто?
направление : любой = 'оба

Поставить окно в центр экрана. Направление 'оба (по умолчанию), 'по-горизонтали или 'по-вертикали.

метод
(переместить лево верх) → пусто?
лево : число?
верх : число?

Лево и верх на экране.

метод
(установить-размер ширина высота) → пусто?
ширина : число?
высота : число?

Внешние ширина и высота.

метод
(пространство-событий) → любой

Очередь событий этого окна.

метод
(объект-в-фокусе) → любой

Элемент или редактор с фокусом либо ложь.

метод
(окно-в-фокусе) → любой

Подокно с фокусом либо ложь.

метод
(объект-для-редактирования) → любой

Куда идёт ввод, если фокус на картине редактора.

метод
(окно-для-редактирования) → любой

Окно этого объекта.

метод
(установить-иконку иконка [маска какую]) → пусто?
  иконка : любой
  маска : любой = ложь
  какую : любой = 'обе

Значок окна. Аргументы: изображение, необязательная маска (ложь) и какой значок сменить: 'маленькую, 'большую или 'обе (по умолчанию).

метод
(можно-закрыть?) → булево?

Разрешить ли закрытие; по умолчанию истина.

метод
(можно-выйти?) → булево?

Разрешить ли выход из приложения; по умолчанию вызывает можно-закрыть?.

метод
(при-активации активно?) → пусто?
активно? : булево?

Этот метод переопределяется формой переопределить.

Окно стало активным или нет.

метод
(при-закрытии) → пусто?

Этот метод переопределяется формой переопределить.

Окно закрывают.

метод
(при-выходе) → пусто?

Этот метод переопределяется формой переопределить.

Приложение завершают через это окно.

метод
(при-получении-сообщения сообщение) → пусто?
сообщение : любой

Этот метод переопределяется формой переопределить.

Системное сообщение.

метод
(при-изменении-дисплея) → пусто?

Этот метод переопределяется формой переопределить.

Сменились экраны или масштаб (есть у главное-окно%).

метод
(при-получении-клавиши событие) → любой
событие : событие-клавиши%

Этот метод переопределяется формой переопределить.

Клавиша обхода фокуса; ложь — обработать как обычно, иначе клавиша уже обработана.

4.24.9 элемент-управления<%>🔗ℹ

интерфейс
элемент-управления<%> : интерфейс?

Расширяет: подокно<%>. Кнопка, надпись, поле ввода. Модуль графический-интерфейс/интерфейс-элемент-управления. По умолчанию элемент не растягивается. Аргументы инициализации: шрифт (по умолчанию шрифт-элемента-управления), стиль — список символов; 'скрытая — элемент создан, но не показан в родителе.

метод
(команда событие) → пусто?
событие : любой

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

4.24.10 список<%>🔗ℹ

интерфейс
список<%> : интерфейс?

Расширяет: элемент-управления<%>. Выбор из списка строк. Модуль графический-интерфейс/списочный-интерфейс.

метод
(добавить строка) → пусто?
строка : строка?

Добавляет строку в конец списка. Выделение не меняется.

метод
(очистить) → пусто?

Удаляет все строки.

метод
(удалить индекс) → пусто?
индекс : целое-неотрицательное?

Удаляет строку с индексом индекс (с нуля).

метод
(найти-строку строка) → (один-из целое-неотрицательное? ложь)
строка : строка?

Индекс первой совпавшей строки или ложь.

метод
(количество) → целое-неотрицательное?

Число строк.

метод
(выделение) → (один-из целое-неотрицательное? ложь)
(выделение индекс) → пусто?
индекс : целое-неотрицательное?

Индекс выделенной строки или ложь. Запись выделяет одну строку и снимает остальные. команда при этом не вызывается.

метод
(строка индекс) → строка?
индекс : целое-неотрицательное?

Текст строки с индексом индекс (с нуля).

метод
(выбранная-строка) → (один-из строка? ложь)
(выбранная-строка строка) → пусто?
строка : строка?

Текст выделенной строки или ложь. Запись выделяет совпавшую строку и снимает остальные. команда при этом не вызывается.

4.24.11 картина<%>🔗ℹ

интерфейс
картина<%> : интерфейс?

Расширяет: подокно<%>. Холст или поле редактора. Модуль графический-интерфейс/интерфейс-картина. События: если вернуть не ложь, стандартная обработка не выполняется. В базовой реализации все четыре возвращают ложь.

метод
(принимать-фокус-табом) → булево?
(принимать-фокус-табом значение) → пусто?
значение : любой

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

метод
(отрисовать-немедленно) → пусто?

Сбрасывает отложенную отрисовку картины на экран.

метод
(фон) → любой
(фон цвет) → пусто?
цвет : цвет%

Без аргумента возвращает цвет, которым стирают картину перед при-отрисовке. С аргументом задаёт этот цвет. Если картина создана с прозрачным стилем, чтение возвращает ложь; запись в таком случае ошибка.

метод
(холст) → любой

Возвращает холст% для рисования на картине или ложь, если внутренний холст ещё не создан.

метод
(минимальная-ширина-холста) → целое-неотрицательное?
(минимальная-ширина-холста ширина) → пусто?
ширина : целое-неотрицательное?

Читает или задаёт минимальную ширину клиентской области картины (без рамки и полос прокрутки) для раскладки. Значение меньше графического минимума игнорируется.

метод
(минимальная-высота-холста) → целое-неотрицательное?
(минимальная-высота-холста высота) → пусто?
высота : целое-неотрицательное?

Читает или задаёт минимальную высоту клиентской области картины (без рамки и полос прокрутки) для раскладки. Значение меньше графического минимума игнорируется.

метод
(приостановить-отрисовку) → пусто?

Временно отключает сброс буфера картины на экран. Вызовы можно вкладывать; сброс возобновляется после стольких же вызовов продолжить-отрисовку.

метод
(продолжить-отрисовку) → пусто?

Возобновляет сброс буфера после приостановить-отрисовку. См. приостановить-отрисовку.

метод
(при-получении-клавиши событие) → любой
событие : событие-клавиши%

Этот метод переопределяется формой переопределить.

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

метод
(при-получении-события событие) → любой
событие : событие-мыши%

Этот метод переопределяется формой переопределить.

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

метод
(при-отрисовке) → любой

Этот метод переопределяется формой переопределить.

Вызывается, когда картину нужно перерисовать (показ, изменение размера, запрос обновить). Если вернуть не ложь, стандартная отрисовка (в том числе обработка) не выполняется. В базовом классе возвращает ложь; тогда вызывается обработка.

метод
(при-входе-табом) → любой

Этот метод переопределяется формой переопределить.

Вызывается, когда клавиатурный фокус входит на картину обходом табуляцией (событие при-изменении-фокуса тоже вызывается). Если вернуть не ложь, стандартная обработка не выполняется. В базовом классе возвращает ложь.

4.24.12 редактор<%>🔗ℹ

интерфейс
редактор<%> : интерфейс?

Документ, который показывают через поле-редактора% или другую картину. Его реализует текст%. Модуль графический-интерфейс/интерфейс-редактор.

метод
(добавить-картину картина) → пусто?
картина : любой

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

метод
(добавить-отменятель отменятель) → пусто?
отменятель : функция?

Кладёт функцию отмены на стек отмен. Если сейчас выполняется отмена, функция попадает на стек повторов. Система вызывает её, когда она первая на стеке. Для встроенных действий (вставка, удаление, смена шрифта) записи отмены создаются сами. Свой отменятель нужен, когда надо откатить действие, которого в документе нет (например, смену своей подписи куска). После возврата функция снимается со стека; если её результат не ложь, сразу выполняется следующий отменятель — так несколько действий откатываются одним шагом. Имеет смысл возвращать не ложь, если отменяемое действие входило в последовательность редактирования.

метод
(начать-последовательность-редактирования) → пусто?

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

метод
(закончить-последовательность-редактирования) → пусто?

Завершение набора правок, начатого начать-последовательность-редактирования.

метод
(команды-редактора) → любой
(команды-редактора набор) → пусто?
набор : любой

Без аргументов возвращает текущий набор-команд% или ложь. С аргументом задаёт набор; ложь снимает все привязки клавиш.

метод
(первый-кусок) → любой

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

метод
(вставить-из-буфера [время]) → пусто?
время : число? = 0

Вставляет текущее содержимое буфера обмена. Необязательный аргумент — метка времени события (по умолчанию 0). Система может вставить из буфера и без вызова этого метода.

метод
(скопировать [дополнять? время]) → пусто?
дополнять? : любой = ложь
время : число? = 0

Копирует текущее выделение в буфер обмена. Если дополнять? не ложь, содержимое буфера дополняется, а не заменяется. Необязательный аргумент время — метка времени события (по умолчанию 0). Система может выполнить копирование и без вызова этого метода.

метод
(размеры) → любой

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

метод
(глобальные->местные лево верх) → любой
лево : число?
верх : число?

Переводит координаты лево и верх из системы показа (обычно картины) в координаты документа. Возвращает два значения: местные лево и верх.

метод
(максимальная-ширина) → число?
(максимальная-ширина значение) → пусто?
значение : любой

Без аргумента читает ограничение размера содержимого при показе, с аргументом записывает. Ноль значит, что ограничения нет. В текстовом документе отсутствие максимальной ширины отключает автоматический перенос строк.

метод
(минимальная-ширина) → число?
(минимальная-ширина значение) → пусто?
значение : любой

Без аргумента читает ограничение размера содержимого при показе, с аргументом записывает. Ноль значит, что ограничения нет.

метод
(максимальная-высота) → число?
(максимальная-высота значение) → пусто?
значение : любой

метод
(минимальная-высота) → число?
(минимальная-высота значение) → пусто?
значение : любой

метод
(обработать-изменение-размера) → пусто?

Вызывает при-изменении-размера, если документ не в середине последовательности редактирования и не перерисовывается сейчас. Иначе вызов откладывается.

метод
(при-получении-события событие) → любой
событие : событие-мыши%

Этот метод переопределяется формой переопределить.

Событие мыши по документу. Аргумент — обёрнутое событие мыши. В базовом классе возвращает истина: тогда обработка события продолжается (клавиши, кусок с курсором, выбор куска). Если переопределить и вернуть ложь, дальнейшая обработка не выполняется.

метод
(при-получении-необработанного-события событие) → любой
событие : событие-мыши%

Этот метод переопределяется формой переопределить.

Вызывается, когда событие мыши не обработал кусок с курсором и не обработал набор команд. Аргумент — обёрнутое событие мыши. В базовом классе возвращает истина, и обработка события продолжается. Значение ложь её прерывает.

метод
(при-изменении-размера) → пусто?

Этот метод переопределяется формой переопределить.

Показ изменил размер видимой области (как у размеры). Вызывается не напрямую, а через обработать-изменение-размера. В базовом классе ничего не делает. Если включён автоматический перенос, исходная реализация подстраивает максимальную ширину под картины документа.

метод
(при-начале-последовательности-редактировании) → пусто?

Этот метод переопределяется формой переопределить.

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

4.24.13 пункт-меню<%>🔗ℹ

интерфейс
пункт-меню<%> : интерфейс?

Пункт в строке меню, выпадающем или всплывающем меню. Модуль графический-интерфейс/меню.

метод
(родитель) → любой

Меню или строка меню, в которой лежит пункт.

метод
(удалить) → пусто?

Убрать пункт из меню, не уничтожая его.

метод
(восстановить) → пусто?

Вернуть ранее удалённый пункт на прежнее место.

метод
(удалён?) → булево?

Убран ли пункт.

4.24.14 пункт-меню-с-заголовком<%>🔗ℹ

интерфейс
пункт-меню-с-заголовком<%> : интерфейс?

Расширяет: пункт-меню<%>. Пункт с подписью. Модуль графический-интерфейс/меню.

метод
(заголовок) → любой
(заголовок значение) → пусто?
значение : любой

Текст пункта (чтение и запись).

метод
(включить включён?) → пусто?
включён? : любой

Разрешить или запретить выбор.

метод
(включён?) → булево?

Можно ли выбрать пункт.

метод
(строка-помощи) → любой
(строка-помощи значение) → пусто?
значение : любой

Подсказка в строке состояния (чтение и запись; ложь — без подсказки).

4.24.15 буфер-обмена<%>🔗ℹ

интерфейс
буфер-обмена<%> : интерфейс?

Системный буфер обмена: копирование и вставка текста, изображений и данных в именованных форматах. Модуль графический-интерфейс/буфер-обмена.

метод
(получить-строку [время]) → строка?
время : целое? = 0

Текст из буфера. Если текста нет — пустая строка. время — метка времени события, по умолчанию 0.

метод
(установить-строку текст [время]) → пусто?
текст : строка?
время : целое? = 0

Записывает текст в буфер и снимает текущего клиента, если он был.

метод
(получить-данные формат [время]) → (один-из байты? строка? ложь)
формат : строка?
время : целое? = 0

Данные в указанном формате или ложь, если такого типа нет.

метод
(получить-изображение [время]) → (один-из изображение% ложь)
время : целое? = 0

Изображение из буфера или ложь, если изображения нет.

метод
(установить-изображение изображение [время]) → пусто?
изображение : изображение%
время : целое? = 0

Записывает изображение в буфер и снимает текущего клиента, если он был.

метод
(тот-же-клиент? клиент) → булево?
клиент : любой

Является ли клиент текущим владельцем буфера.

метод
(установить-клиент клиент [время]) → пусто?
клиент : любой
время : целое? = 0

Ставит клиента владельцем буфера.

значение
буфер-обмена : буфер-обмена<%>

Системный буфер обмена.

4.24.16 главное-окно%🔗ℹ

класс
главное-окно% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс главное-окно<%>. Окно верхнего уровня с рамкой, заголовком и, при необходимости, строкой состояния. Модуль графический-интерфейс/главное-окно.

конструктор
(главное-окно% [ заголовок
ширина
высота
лево
верх
стиль]
родитель
[ граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
включен]) → главное-окно%
  заголовок : строка? = ""
  ширина : любой = ложь
  высота : любой = ложь
  лево : любой = ложь
  верх : любой = ложь
  стиль : список? = пустой-список
  родитель : любой
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр верх)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  включен : булево? = истина

Создаётся формой объект:

объект главное-окно%
  заголовок заголовок
  ширина ширина
  высота высота
  лево лево
  верх верх
  стиль стиль
  родитель родитель
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  включен включен

заголовок по умолчанию пустая строка. ширина и высота — число или ложь (размер по содержимому). лево и верх — положение на экране или ложь. стиль — список флагов: 'без-рамки-изменения-размера, 'без-заголовка, 'без-системного-меню, 'скрыть-меню, 'кнопка-панели, 'плавающее, 'металлическое, 'кнопка-полного-экрана, 'вспомогательное-полного-экрана. родитель необязателен; выравнивание по умолчанию '(центр верх). минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(создать-строку-состояния) → пусто?

Добавляет полосу состояния внизу окна.

метод
(показать-состояние состояние) → пусто?
состояние : строка?

Задаёт текст в полосе состояния.

4.24.17 диалог%🔗ℹ

класс
диалог% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс главное-окно<%>. Модальное или вспомогательное окно без строки состояния. Модуль графический-интерфейс/диалог. Методы главное-окно<%> тоже доступны.

конструктор
(диалог% [ заголовок
ширина
высота
лево
верх
стиль]
родитель
[ граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
включен]) → диалог%
  заголовок : строка? = ""
  ширина : любой = ложь
  высота : любой = ложь
  лево : любой = ложь
  верх : любой = ложь
  стиль : список? = пустой-список
  родитель : любой
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр верх)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  включен : булево? = истина

Создаётся формой объект:

объект диалог%
  заголовок заголовок
  ширина ширина
  высота высота
  лево лево
  верх верх
  стиль стиль
  родитель родитель
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  включен включен

Те же аргументы, что у главное-окно%, кроме флагов стиль: 'без-заголовка, 'рамка-изменения-размера, 'без-листа, 'кнопка-закрытия. Методы — как у главное-окно<%>, без создать-строку-состояния и показать-состояние.

функция
(получить-файл [ сообщение
родитель
каталог
имя-файла
расширение
стиль
фильтры]) → (один-из строка? ложь)
  сообщение : (один-из строка? ложь) = ложь
  родитель : (один-из главное-окно% диалог% ложь) = ложь
  каталог : (один-из строка? ложь) = ложь
  имя-файла : (один-из строка? ложь) = ложь
  расширение : (один-из строка? ложь) = ложь
  стиль : список? = пустой-список
  фильтры : список? = '((«Любые» «*.*»))

Показывает стандартный модальный диалог выбора файла. Возвращает путь к выбранному файлу или ложь, если пользователь отменил выбор. сообщение — текст в верхней части диалога. родитель — окно-родитель. каталог и имя-файла задают начальный каталог и имя. расширение — расширение по умолчанию. стиль — список флагов ('common, 'packages, 'enter-packages). фильтры — список пар (подпись, маска). Модуль графический-интерфейс/диалог.

функция
(сохранить-файл [ сообщение
родитель
каталог
имя-файла
расширение
стиль
фильтры]) → (один-из строка? ложь)
  сообщение : (один-из строка? ложь) = ложь
  родитель : (один-из главное-окно% диалог% ложь) = ложь
  каталог : (один-из строка? ложь) = ложь
  имя-файла : (один-из строка? ложь) = ложь
  расширение : (один-из строка? ложь) = ложь
  стиль : список? = пустой-список
  фильтры : список? = '((«Любые» «*.*»))

Показывает стандартный модальный диалог сохранения файла. Возвращает путь или ложь, если пользователь отменил выбор. Аргументы — как у получить-файл. Модуль графический-интерфейс/диалог.

4.24.18 Диспетчер событий🔗ℹ

Модуль графический-интерфейс/диспетчер-событий (в сводке графический-интерфейс).

функция
(поставить-в-очередь обработчик
[ высокий-приоритет?]) → пусто?
обработчик : функция?
высокий-приоритет? : любой = истина

Ставит обработчик (функцию без аргументов) в очередь текущего пространства событий. Обработчик вызовут один раз в потоке обработки событий. Если высокий-приоритет? не ложь, событие с высоким приоритетом, иначе — с низким.

функция
(уступить) → булево?
(уступить значение) → любой
значение : любой

Передаёт управление диспетчеру событий.

Без аргументов обрабатывает некоторое число событий, если текущий поток — поток обработки текущего пространства событий; иначе ничего не делает. Результат — истина, если события могли быть обработаны, иначе ложь.

Если значение — 'wait, в потоке обработки диспетчер работает, пока не закроются все окна пространства; в другом потоке сразу возвращает истина.

Если значение — синхронизируемое событие Racket, ждёт его как sync, но в потоке обработки параллельно разбирает очередь GUI-событий.

4.24.19 область-уведомлений%🔗ℹ

класс
область-уведомлений% : класс?

Базовый класс: объект-графического-интерфейса%. Иконка в области уведомлений (Windows и Linux). Подключается отдельно: графический-интерфейс/область-уведомлений.

конструктор
(область-уведомлений% [ заголовок
иконка
команда]) → область-уведомлений%
  заголовок : любой = ""
  иконка : любой = 'сведения
  команда : функция? = (функция (область событие-мыши%) пусто)

Создаётся формой объект:

объект область-уведомлений%
  заголовок заголовок
  иконка иконка
  команда команда

заголовок — подсказка при наведении (строка). иконка — системный символ или указатель на объект иконки из загрузить-иконку. Символы: 'приложение, 'ошибка, 'вопрос, 'предупреждение, 'сведения, 'эмблема, 'пустая. команда — функция от области и событие-мыши%. Левый щелчок: нажата-кнопка? с 'левая; правый — с 'правая. Windows и Linux.

метод
(показать состояние) → пусто?
состояние : любой

Показывает или скрывает иконку. Не ложь — показать, ложь — скрыть.

метод
(показано?) → булево?

Иконка сейчас в области уведомлений?

метод
(заголовок) → любой
(заголовок новое-значение) → пусто?
новое-значение : любой

Подсказка при наведении. Без аргумента читает, с аргументом задаёт строку.

метод
(иконка) → любой
(иконка новое-значение) → пусто?
новое-значение : любой

Системный символ или указатель на объект иконки. Без аргумента читает, с аргументом задаёт.

метод
(команда) → функция?
(команда новое-значение) → пусто?
новое-значение : функция?

Обработчик щелчка. Без аргумента читает, с аргументом задаёт функцию от области и событие-мыши%.

функция
(загрузить-иконку путь) → любой
путь : строка?

Загружает файл ".ico" или ".png" и возвращает указатель на объект иконки для аргумента иконка.

4.24.20 уведомление🔗ℹ

функция
(уведомление [ заголовок
сообщение
приложение
иконка
ожидание]) → пусто?
  заголовок : строка? = ""
  сообщение : строка? = ""
  приложение : строка? = ""
  иконка : (один-из строка? ложь) = ложь
  ожидание : любой = 10

Показывает системное уведомление. Windows — всплывающая подсказка в области уведомлений, Linux — портал рабочего стола. заголовок и сообщение — текст. приложение — имя в лотке (Windows). иконка — путь к ".ico" или ложь. ожидание — секунды показа (Windows); ложь — не убирать автоматически. Модуль графический-интерфейс/уведомление.

4.24.21 группа%🔗ℹ

класс
группа% : класс?

Базовый класс: объект-графического-интерфейса%. Реализует вместилище<%> и подобласть<%>. Контейнер без собственной рамки: только раскладывает детей. Модуль графический-интерфейс/группа. Методы вместилище<%> и подобласть<%> тоже доступны.

конструктор
(группа% родитель
[ граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля]) → группа%
  родитель : любой
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр центр)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0

Создаётся формой объект:

объект группа%
  родитель родитель
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля

Выравнивание по умолчанию '(центр центр). Поля по умолчанию 0. родитель обязателен. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

4.24.22 горизонтальная-группа%🔗ℹ

класс
горизонтальная-группа% : класс?

Базовый класс: группа%. Дети слева направо. Выравнивание по умолчанию '(лево центр). Методы вместилище<%> и подобласть<%> тоже доступны.

конструктор
(горизонтальная-группа% родитель
[ граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля])
→ горизонтальная-группа%
  родитель : любой
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(лево центр)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0

Создаётся формой объект:

объект горизонтальная-группа%
  родитель родитель
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля

Выравнивание по умолчанию '(лево центр). родитель обязателен. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

4.24.23 вертикальная-группа%🔗ℹ

класс
вертикальная-группа% : класс?

Базовый класс: группа%. Дети сверху вниз. Выравнивание по умолчанию '(центр верх). Методы вместилище<%> и подобласть<%> тоже доступны.

конструктор
(вертикальная-группа% родитель
[ граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля])
→ вертикальная-группа%
  родитель : любой
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр верх)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0

Создаётся формой объект:

объект вертикальная-группа%
  родитель родитель
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля

Выравнивание по умолчанию '(центр верх). родитель обязателен. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

4.24.24 панель%🔗ℹ

класс
панель% : класс?

Базовый класс: объект-графического-интерфейса%. Реализует вместилище-окно<%> и подокно<%>. Видимый контейнер с фоном. Модуль графический-интерфейс/панель. Методы вместилище-окно<%> и подокно<%> тоже доступны.

конструктор
(панель% родитель
[ стиль
граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля
включен]) → панель%
  родитель : любой
  стиль : любой = '()
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр центр)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект панель%
  родитель родитель
  стиль стиль
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

стиль — список символов стиля (по умолчанию пустой). Выравнивание по умолчанию '(центр центр). родитель обязателен. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

4.24.25 горизонтальная-панель%🔗ℹ

класс
горизонтальная-панель% : класс?

Базовый класс: панель%. Дети слева направо. Выравнивание по умолчанию '(лево центр). Методы вместилище-окно<%> и подокно<%> тоже доступны.

конструктор
(горизонтальная-панель% родитель
[ стиль
граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля
включен])
→ горизонтальная-панель%
  родитель : любой
  стиль : любой = '()
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(лево центр)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект горизонтальная-панель%
  родитель родитель
  стиль стиль
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

метод
(ориентация) → любой
(ориентация значение) → пусто?
значение : любой

Без аргумента: не ложь, если раскладка горизонтальная; с аргументом задаёт горизонтальную (истина) или вертикальную раскладку.

4.24.26 вертикальная-панель%🔗ℹ

класс
вертикальная-панель% : класс?

Базовый класс: панель%. Дети сверху вниз. Выравнивание по умолчанию '(центр верх). Методы вместилище-окно<%> и подокно<%> тоже доступны.

конструктор
(вертикальная-панель% родитель
[ стиль
граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля
включен])
→ вертикальная-панель%
  родитель : любой
  стиль : любой = '()
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(центр верх)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект вертикальная-панель%
  родитель родитель
  стиль стиль
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

метод
(ориентация) → любой
(ориентация значение) → пусто?
значение : любой

4.24.27 табличная-панель%🔗ℹ

класс
табличная-панель% : класс?

Базовый класс: панель%. Подключается отдельно: графический-интерфейс/табличная-панель. Дети в сетке рядов и колонок. Выравнивание по умолчанию '(лево центр). Методы вместилище-окно<%> и подокно<%> тоже доступны.

конструктор
(табличная-панель% родитель
[ стиль
измерения
заполнять
колонки-растягиваются
ряды-растягиваются
граница
интервал
выравнивание
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
горизонтальные-поля
вертикальные-поля
включен]) → табличная-панель%
  родитель : любой
  стиль : любой = '()
  измерения : любой = '(1 1)
  заполнять : символ? = 'ряд
  колонки-растягиваются : символ? = 'любая
  ряды-растягиваются : символ? = 'любая
  граница : целое-неотрицательное? = 0
  интервал : целое-неотрицательное? = 0
  выравнивание : любой = '(лево центр)
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект табличная-панель%
  родитель родитель
  стиль стиль
  измерения измерения
  заполнять заполнять
  колонки-растягиваются колонки-растягиваются
  ряды-растягиваются ряды-растягиваются
  граница граница
  интервал интервал
  выравнивание выравнивание
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

измерения — список из числа рядов и числа колонок, по умолчанию '(1 1). заполнять — 'ряд (по умолчанию) или 'колонку. колонки-растягиваются и ряды-растягиваются — 'любая или 'каждая, по умолчанию 'любая. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(измерения) → любой
(измерения ряды колонки) → пусто?
ряды : целое?
колонки : целое?

Читает или задаёт число рядов и колонок.

метод
(заполнять) → любой
(заполнять значение) → пусто?
значение : символ?

Читает или задаёт, что заполнять в первую очередь: 'ряд или 'колонку.

метод
(колонки-растягиваются) → любой
(колонки-растягиваются значение) → пусто?
значение : символ?

Читает или задаёт растягивание колонок: 'любая или 'каждая.

метод
(ряды-растягиваются) → любой
(ряды-растягиваются значение) → пусто?
значение : символ?

Читает или задаёт растягивание рядов: 'любая или 'каждая.

4.24.28 кнопка%🔗ℹ

класс
кнопка% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс элемент-управления<%>. Модуль графический-интерфейс/кнопка. Методы элемент-управления<%> тоже доступны.

конструктор
(кнопка% заголовок
родитель
[ команда
шрифт
стиль
растягивается-ширина
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → кнопка%
  заголовок : любой
  родитель : любой
   команда : функция?
= (функция (кнопка событие-управления%) пусто)
  шрифт : шрифт% = шрифт-элемента-управления
  стиль : любой = '()
  растягивается-ширина : булево? = ложь
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект кнопка%
  заголовок заголовок
  родитель родитель
  команда команда
  шрифт шрифт
  стиль стиль
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

заголовок — строка или изображение (обязателен). родитель обязателен. команда вызывается при нажатии. стиль — 'граница, 'многострочная, 'скрытая. шрифт по умолчанию шрифт-элемента-управления. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

4.24.29 кнопка-выбора%🔗ℹ

класс
кнопка-выбора% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейсы список<%> и элемент-управления<%>. Выпадающий список с выбором одного элемента. Модуль графический-интерфейс/кнопка-выбора. Методы список<%> и элемент-управления<%> тоже доступны.

конструктор
(кнопка-выбора% [ заголовок]
родитель
[ элементы
команда
выделение
шрифт
стиль
растягивается-ширина
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → кнопка-выбора%
  заголовок : любой = ложь
  родитель : любой
  элементы : список? = '()
   команда : функция?
= (функция (кнопка-выбора событие-управления%) пусто)
  выделение : целое-неотрицательное? = 0
  шрифт : шрифт% = шрифт-элемента-управления
  стиль : любой = '()
  растягивается-ширина : булево? = ложь
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект кнопка-выбора%
  заголовок заголовок
  родитель родитель
  элементы элементы
  команда команда
  выделение выделение
  шрифт шрифт
  стиль стиль
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

заголовок — строка. родитель обязателен. элементы — список строк для отображения в списке. команда вызывается при выборе элемента; тип события — 'кнопка-выбора. выделение — индекс выбранного элемента по умолчанию (начиная с 0). стиль — 'вертикальный-заголовок, 'горизонтальный-заголовок, 'скрытая. шрифт по умолчанию шрифт-элемента-управления. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(добавить элемент) → пусто?
  элемент : любой
(очистить) → пусто?
(удалить индекс) → пусто?
  индекс : целое-неотрицательное?
(найти-строку строка) → целое-неотрицательное?
  строка : строка?
(количество) → целое-неотрицательное?
(строка индекс) → любой
  индекс : целое-неотрицательное?
(выделение) → целое-неотрицательное?
(выделение новое-значение) → пусто?
  новое-значение : целое-неотрицательное?
(выбранная-строка) → строка?
(выбранная-строка новое-значение) → пусто?
  новое-значение : строка?

Методы класса кнопка-выбора% для управления элементами списка и выбором.

добавить — добавляет элемент в список. очистить — удаляет все элементы из списка. удалить — удаляет элемент по индексу. найти-строку — возвращает индекс первого элемента, равного строке, или ложь. количество без аргументов — возвращает количество элементов в списке. строка — возвращает элемент по индексу. выделение без аргументов — возвращает индекс выбранного элемента. выделение с аргументом — устанавливает выбранный элемент по индексу. выбранная-строка без аргументов — возвращает строку выбранного элемента. выбранная-строка с аргументом — устанавливает выбранный элемент по строке.

4.24.30 флажок%🔗ℹ

класс
флажок% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс элемент-управления<%>. Флажок (галочка). Модуль графический-интерфейс/флажок. Методы элемент-управления<%> тоже доступны.

конструктор
(флажок% заголовок
родитель
[ значение
команда
шрифт
стиль
растягивается-ширина
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → флажок%
  заголовок : любой
  родитель : любой
  значение : булево? = ложь
   команда : функция?
= (функция (флажок событие-управления%) пусто)
  шрифт : шрифт% = шрифт-элемента-управления
  стиль : любой = '()
  растягивается-ширина : булево? = ложь
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект флажок%
  заголовок заголовок
  родитель родитель
  значение значение
  команда команда
  шрифт шрифт
  стиль стиль
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

заголовок — строка или изображение% (обязателен). родитель обязателен. значение — начальное состояние, по умолчанию ложь. команда вызывается при переключении пользователем; тип события — 'флажок. стиль — 'скрытая. шрифт по умолчанию шрифт-элемента-управления. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(значение) → булево?
(значение новое-значение) → пусто?
новое-значение : булево?

Читает или записывает состояние флажка (без вызова команда).

4.24.31 надпись%🔗ℹ

класс
надпись% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс элемент-управления<%>. Статический текст или картинка. Модуль графический-интерфейс/надпись. Методы элемент-управления<%> тоже доступны.

конструктор
(надпись% заголовок
родитель
[ цвет
размер-по-заголовку
шрифт
стиль
растягивается-ширина
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → надпись%
  заголовок : любой
  родитель : любой
  цвет : любой = ложь
  размер-по-заголовку : булево? = ложь
  шрифт : шрифт% = шрифт-элемента-управления
  стиль : любой = '()
  растягивается-ширина : булево? = ложь
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект надпись%
  заголовок заголовок
  родитель родитель
  цвет цвет
  размер-по-заголовку размер-по-заголовку
  шрифт шрифт
  стиль стиль
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

заголовок — строка или изображение% (обязателен). цвет по умолчанию ложь. размер-по-заголовку по умолчанию ложь. шрифт по умолчанию шрифт-элемента-управления. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(цвет) → любой
(цвет значение) → пусто?
значение : любой

Цвет текста (чтение и запись).

метод
(размер-по-заголовку) → булево?
(размер-по-заголовку значение) → пусто?
значение : булево?

Подгонять ли размер под текущий заголовок (чтение и запись).

4.24.32 текстовое-поле%🔗ℹ

класс
текстовое-поле% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс элемент-управления<%>. Однострочное или многострочное поле. Модуль графический-интерфейс/текстовое-поле. Методы элемент-управления<%> тоже доступны.

конструктор
(текстовое-поле% родитель
[ заголовок
значение
при-изменении
стиль
растягивается-ширина
шрифт
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → текстовое-поле%
  родитель : любой
  заголовок : любой = ложь
  значение : строка? = ""
  при-изменении : функция? = ложь
  стиль : любой = '(однострочное)
  растягивается-ширина : булево? = истина
  шрифт : шрифт% = шрифт-элемента-управления
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект текстовое-поле%
  родитель родитель
  заголовок заголовок
  значение значение
  при-изменении при-изменении
  стиль стиль
  растягивается-ширина растягивается-ширина
  шрифт шрифт
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

заголовок — подпись, по умолчанию ложь. стиль — '(однострочное), 'многострочное или 'скрытая. шрифт по умолчанию шрифт-элемента-управления. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому. растягивается-ширина по умолчанию истина. При правке вызывается при-изменении; тип события — 'текстовое-поле или 'ввод-в-текстовом-поле.

метод
(значение) → строка?
(значение новое-значение) → пусто?
новое-значение : строка?

Читает или записывает текст поля.

4.24.33 список%🔗ℹ

класс
список% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс список<%>. Прокручиваемый список строк. Модуль графический-интерфейс/список. Методы список<%> тоже доступны.

конструктор
(список% элементы
родитель
[ заголовок
команда
выделение
шрифт
шрифт-заголовка
стиль
колонки
порядок-колонок
растягивается-ширина
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → список%
  элементы : список?
  родитель : любой
  заголовок : любой = ложь
   команда : функция?
= (функция (список событие-управления%) пусто)
  выделение : любой = ложь
  шрифт : шрифт% = шрифт-элемента-управления
  шрифт-заголовка : шрифт% = шрифт-элемента-управления
  стиль : любой = '(одиночный)
  колонки : список? = '(«Колонка»)
  порядок-колонок : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект список%
  элементы элементы
  родитель родитель
  заголовок заголовок
  команда команда
  выделение выделение
  шрифт шрифт
  шрифт-заголовка шрифт-заголовка
  стиль стиль
  колонки колонки
  порядок-колонок порядок-колонок
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

элементы и родитель обязательны. заголовок по умолчанию ложь — без подписи. стиль по умолчанию '(одиночный); ещё 'множественный, 'расширенный, 'вертикальный-заголовок, 'горизонтальный-заголовок, 'заголовки-колонок, 'нажимаемые-заголовки, 'переставляемые-заголовки, 'изменяемые-колонки, 'скрытая. команда вызывается при смене выделения; тип события — 'список, 'двойной-щелчок-по-списку или 'колонка-списка.

метод
(добавить строка [данные]) → пусто?
строка : строка?
данные : любой = ложь

Добавляет строку; данные хранятся вместе с ней и не показываются.

метод
(строка индекс значение [колонка]) → пусто?
  индекс : целое-неотрицательное?
  значение : строка?
  колонка : целое-неотрицательное? = 0

Записывает текст в строку индекс колонки колонка (с нуля).

метод
(добавить-колонку заголовок) → пусто?
заголовок : строка?

Добавляет колонку, если в стиле есть 'изменяемые-колонки.

метод
(удалить-колонку индекс) → пусто?
индекс : целое-неотрицательное?

Удаляет колонку с логическим индексом индекс. Нельзя удалить последнюю.

метод
(заголовки-колонок) → список?

Подписи колонок; длина списка — число колонок.

метод
(порядок-колонок) → список?
(порядок-колонок порядок) → пусто?
порядок : список?

Порядок показа логических колонок (чтение и запись).

метод
(ширина-колонки колонка) → любой
  колонка : целое-неотрицательное?
(ширина-колонки колонка
ширина
минимум
максимум) → пусто?
  колонка : целое-неотрицательное?
  ширина : целое-неотрицательное?
  минимум : целое-неотрицательное?
  максимум : целое-неотрицательное?

Чтение возвращает три значения: текущую, минимальную и максимальную ширину. Запись задаёт их для логической колонки колонка.

метод
(данные индекс) → любой
  индекс : целое-неотрицательное?
(данные индекс значение) → пусто?
  индекс : целое-неотрицательное?
  значение : любой

Данные, связанные со строкой (чтение и запись).

метод
(первый-видимый) → целое-неотрицательное?
(первый-видимый индекс) → пусто?
индекс : целое-неотрицательное?

Индекс строки вверху видимой области (чтение и запись).

метод
(шрифт-заголовка) → любой

Шрифт подписи списка.

метод
(выделения) → список?

Индексы всех выделенных строк.

метод
(выделен? индекс) → булево?
индекс : целое-неотрицательное?

Выделена ли строка с индексом индекс.

метод
(число-видимых) → целое-неотрицательное?

Сколько строк умещается в текущем размере списка (не меньше 1).

метод
(выделить индекс [выделен?]) → пусто?
индекс : целое-неотрицательное?
выделен? : любой = истина

Выделяет или снимает выделение со строки. Остальные выделения в множественном списке сохраняются. команда не вызывается.

метод
(установить-элементы элементы) → пусто?
элементы : список?

Заменяет все строки списка. Для одной колонки элементы — список строк.

4.24.34 поле-даты%🔗ℹ

класс
поле-даты% : класс?

Базовый класс: текстовое-поле%. Подключается отдельно: графический-интерфейс/поле-даты. Поле ввода даты. Методы элемент-управления<%> тоже доступны.

конструктор
(поле-даты% родитель
[ заголовок
значение
при-изменении
стиль
растягивается-ширина
шрифт
растягивается-высота
минимальная-ширина
минимальная-высота
горизонтальные-поля
вертикальные-поля
включен]) → поле-даты%
  родитель : любой
  заголовок : любой = ложь
  значение : строка? = ""
  при-изменении : функция? = ложь
  стиль : любой = '(однострочное)
  растягивается-ширина : булево? = истина
  шрифт : шрифт% = шрифт-элемента-управления
  растягивается-высота : булево? = ложь
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  включен : булево? = истина

Создаётся формой объект:

объект поле-даты%
  родитель родитель
  заголовок заголовок
  значение значение
  при-изменении при-изменении
  стиль стиль
  растягивается-ширина растягивается-ширина
  шрифт шрифт
  растягивается-высота растягивается-высота
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  включен включен

Те же аргументы и методы, что у текстовое-поле%.

4.24.35 строка-меню%🔗ℹ

класс
строка-меню% : класс?

Базовый класс: объект-графического-интерфейса%. Строка меню окна верхнего уровня. Модуль графический-интерфейс/меню.

конструктор
(строка-меню% родитель) → строка-меню%
родитель : любой

Создаётся формой объект:

объект строка-меню%
родитель родитель

родитель обязателен: главное-окно% или диалог%. В строку кладут объекты меню%.

4.24.36 меню%🔗ℹ

класс
меню% : класс?

Базовый класс: объект-графического-интерфейса%. Выпадающее меню. Модуль графический-интерфейс/меню.

конструктор
(меню% родитель заголовок) → меню%
родитель : любой
заголовок : любой

Создаётся формой объект:

объект меню%
родитель родитель
заголовок заголовок

родитель и заголовок обязательны.

4.24.37 всплывающее-меню%🔗ℹ

класс
всплывающее-меню% : класс?

Базовый класс: объект-графического-интерфейса%. Контекстное меню. Модуль графический-интерфейс/меню.

конструктор
(всплывающее-меню% [заголовок]) → всплывающее-меню%
заголовок : строка? = ""

Создаётся формой объект:

объект всплывающее-меню%
заголовок заголовок

Показывают методом контекстное-меню окна. Пункты — пункт-меню%.

4.24.38 пункт-меню%🔗ℹ

класс
пункт-меню% : класс?

Базовый класс: объект-графического-интерфейса%. Реализует пункт-меню<%> и пункт-меню-с-заголовком<%>. Модуль графический-интерфейс/меню. Методы пункт-меню<%> и пункт-меню-с-заголовком<%> тоже доступны.

конструктор
(пункт-меню% родитель заголовок [действие]) → пункт-меню%
  родитель : любой
  заголовок : любой
   действие : функция?
= (функция (пункт событие-управления%) пусто)

Создаётся формой объект:

объект пункт-меню%
  родитель родитель
  заголовок заголовок
  действие действие

Все три аргумента обязательны.

4.24.39 шрифт%🔗ℹ

класс
шрифт% : класс?

Базовый класс: объект-графического-интерфейса%. Описание шрифта. Модуль графический-интерфейс/шрифт.

конструктор
(шрифт% [ размер
семейство
имя
стиль
насыщенность
подчёркнутый?
сглаживание
размер-в-пикселях?
округлять-метрики?
свойства]) → шрифт%
  размер : число? = 12
  семейство : любой = 'default
  имя : любой = ложь
  стиль : символ? = 'нормальный
  насыщенность : символ? = 'нормальная
  подчёркнутый? : булево? = ложь
  сглаживание : символ? = 'стандартное
  размер-в-пикселях? : булево? = ложь
  округлять-метрики? : булево? = истина
  свойства : соответствие? = #hash()

Создаётся формой объект:

объект шрифт%
  размер размер
  семейство семейство
  имя имя
  стиль стиль
  насыщенность насыщенность
  подчёркнутый? подчёркнутый?
  сглаживание сглаживание
  размер-в-пикселях? размер-в-пикселях?
  округлять-метрики? округлять-метрики?
  свойства свойства

имя по умолчанию ложь. стиль — 'нормальный, 'наклонный или 'курсив. насыщенность — 'тонкая … 'сверхтяжёлая. сглаживание — 'стандартное, 'частичное, 'полное, 'отсутствует.

метод
(размер в-пикселях?) → число?
в-пикселях? : булево?

Кегль; необязательный аргумент: считать ли размер в пикселях.

метод
(размер-в-пикселях?) → булево?

Задан ли кегль в пикселях.

метод
(семейство) → любой

Семейство шрифта.

метод
(имя) → любой

Имя начертания.

метод
(стиль) → символ?

Стиль: 'нормальный, 'наклонный или 'курсив.

метод
(насыщенность) → символ?

Насыщенность начертания.

метод
(подчёркнутый?) → булево?

Подчёркнут ли шрифт.

метод
(сглаживание) → символ?

Режим сглаживания.

метод
(округлять-метрики?) → булево?

Округлять ли метрики.

метод
(свойства) → соответствие?

Дополнительные свойства.

метод
(идентификатор) → целое?

Целое число начертания в системе.

метод
(есть-литера? литера [для-заголовка?]) → булево?
литера : любой
для-заголовка? : булево? = ложь

Есть ли знак для литеры; для-заголовка? по умолчанию ложь.

значение
шрифт-элемента-управления : шрифт%

Стандартный шрифт кнопок, полей и надписей.

функция
(на-основе-шрифта шрифт
#:размер размер
#:семейство семейство
#:имя имя
#:стиль стиль
#:насыщенность насыщенность
#:подчёркнутый? подчёркнутый?
#:сглаживание сглаживание
#:размер-в-пикселях? размер-в-пикселях?
#:округлять-метрики? округлять-метрики?
#:свойства свойства)
→ шрифт%
  шрифт : шрифт%
  размер : число?
  семейство : любой
  имя : любой
  стиль : любой
  насыщенность : любой
  подчёркнутый? : булево?
  сглаживание : любой
  размер-в-пикселях? : булево?
  округлять-метрики? : булево?
  свойства : соответствие?

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

4.24.40 событие%🔗ℹ

класс
событие% : класс?

Базовый класс: объект-графического-интерфейса%. Базовое событие. Модуль графический-интерфейс/событие.

конструктор
(событие% [время]) → событие%
время : целое? = 0

Создаётся формой объект:

объект событие%
время время

Метка времени в миллисекундах (по умолчанию 0).

метод
(время) → целое?
(время значение) → пусто?
значение : целое?

Метка времени в миллисекундах (чтение и запись).

4.24.41 событие-мыши%🔗ℹ

класс
событие-мыши% : класс?

Базовый класс: событие%. Событие мыши. Обычно получают через событие-мыши-адины. Методы событие% тоже доступны.

конструктор
(событие-мыши% [тип время] внутренний) → событие-мыши%
  тип : символ? = 'вход
  время : целое? = 0
  внутренний : любой

Создаётся формой объект:

объект событие-мыши%
  тип тип
  время время
  внутренний внутренний

тип — 'вход, 'выход, 'левая-нажата, 'движение и др.

метод
(тип) → символ?
(тип значение) → пусто?
значение : символ?

Тип события мыши (чтение и запись).

метод
(лево) → число?

Координата лево в окне.

метод
(верх) → число?

Координата верх в окне.

метод
(нажата-кнопка? [кнопка]) → булево?
кнопка : символ? = 'любая

С аргументом 'левая, 'правая, 'средняя или 'любая.

метод
(отпущена-кнопка? [кнопка]) → булево?
кнопка : символ? = 'любая

С аргументом 'левая, 'правая, 'средняя или 'любая.

4.24.42 событие-клавиши%🔗ℹ

класс
событие-клавиши% : класс?

Базовый класс: событие%. Событие клавиатуры. Методы событие% тоже доступны.

конструктор
(событие-клавиши% внутренний) → событие-клавиши%
внутренний : любой

Создаётся формой объект:

объект событие-клавиши%
внутренний внутренний

Обычно получают через событие-клавиши-адины.

метод
(клавиша) → любой

Код нажатой клавиши (литера или символ специальной клавиши).

4.24.43 событие-управления%🔗ℹ

класс
событие-управления% : класс?

Базовый класс: событие%. Событие кнопки, поля, меню. Методы событие% тоже доступны.

конструктор
(событие-управления% внутренний) → событие-управления%
внутренний : любой

Создаётся формой объект:

объект событие-управления%
внутренний внутренний

Обычно получают через событие-управления-адины.

метод
(тип) → символ?
(тип значение) → пусто?
значение : символ?

Тип события (чтение и запись): 'кнопка, 'флажок, 'текстовое-поле, 'список, 'двойной-щелчок-по-списку, 'колонка-списка, 'меню и др.

функция
(событие-мыши-адины событие) → событие-мыши%
событие : любой

Оборачивает внутреннее событие мыши в событие-мыши%.

функция
(событие-клавиши-адины событие) → событие-клавиши%
событие : любой

Оборачивает внутреннее событие клавиши в событие-клавиши%.

функция
(событие-управления-адины событие) → событие-управления%
событие : любой

Оборачивает внутреннее событие управления в событие-управления%.

4.24.44 картина%🔗ℹ

класс
картина% : класс?

Базовый класс объект-графического-интерфейса%, реализует интерфейс картина<%>.

Холст для произвольного рисования и обработки событий мыши и клавиатуры. Модуль графический-интерфейс/картина.

Рисование обычно делают в обработка или в при-отрисовке, получая холст% через холст. Система вызывает отрисовку при показе, изменении размера и по запросу обновить; несколько запросов обновить могут объединиться в один вызов при-отрисовке.

Методы подокно<%> и картина<%> тоже доступны у объекта.

конструктор
(картина% родитель
[ заголовок
обработка
стиль
горизонтальные-поля
вертикальные-поля
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
включен]) → картина%
  родитель : любой
  заголовок : любой = ложь
  обработка : функция? = (функция (картина холст) пусто)
  стиль : любой = '()
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  включен : булево? = истина

Создаётся формой объект:

объект картина%
  родитель родитель
  заголовок заголовок
  обработка обработка
  стиль стиль
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  включен включен

родитель — вместилище, в котором создаётся картина (обязателен).

заголовок — имя картины для заголовок; на экране не показывается. По умолчанию ложь.

стиль — список символов (по умолчанию пустой): 'рамка, 'рамка-элемента-управления, 'комбинированное, 'горизонтальная-прокрутка, 'вертикальная-прокрутка, 'угол-изменения-размера, 'трёхмерная, 'без-автоочистки, 'прозрачная, 'без-фокуса, 'скрытая.

обработка — функция от картины и холста; вызывается, когда при-отрисовке возвращает ложь. Холст уже обёрнут в холст%. По умолчанию ничего не делает.

горизонтальные-поля и вертикальные-поля — внутренние отступы у краёв картины (по умолчанию 0). минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому. растягивается-ширина и растягивается-высота по умолчанию истина. включен по умолчанию истина.

метод
(принимать-фокус-табом) → булево?
(принимать-фокус-табом значение) → пусто?
значение : любой

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

Если фокус по табуляции включён, клавиши табуляции, стрелок, ввода и отмены обрабатываются при-получении-клавиши окна верхнего уровня, а не доходят до картины.

метод
(отрисовать-немедленно) → пусто?

Сбрасывает отложенную отрисовку картины на экран.

метод
(фон) → любой
(фон цвет) → пусто?
цвет : цвет%

Без аргумента возвращает цвет, которым стирают картину перед при-отрисовке. С аргументом задаёт этот цвет.

Если картина создана с прозрачным стилем, чтение возвращает ложь; запись в таком случае ошибка.

метод
(холст) → любой

Возвращает холст% для рисования на картине или ложь, если внутренний холст ещё не создан.

метод
(минимальная-ширина-холста) → целое-неотрицательное?
(минимальная-ширина-холста ширина) → пусто?
ширина : целое-неотрицательное?

метод
(минимальная-высота-холста) → целое-неотрицательное?
(минимальная-высота-холста высота) → пусто?
высота : целое-неотрицательное?

метод
(приостановить-отрисовку) → пусто?

метод
(продолжить-отрисовку) → пусто?

Возобновляет сброс буфера после приостановить-отрисовку. См. приостановить-отрисовку.

метод
(при-получении-клавиши событие) → любой
событие : событие-клавиши%

Этот метод переопределяется формой переопределить.

Вызывается, когда картина получает событие клавиатуры. Если вернуть не ложь, стандартная обработка не выполняется.

В базовом классе возвращает ложь.

метод
(при-получении-события событие) → любой
событие : событие-мыши%

Этот метод переопределяется формой переопределить.

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

В базовом классе возвращает ложь.

метод
(при-отрисовке) → любой

Этот метод переопределяется формой переопределить.

В базовом классе возвращает ложь; тогда вызывается обработка.

метод
(при-входе-табом) → любой

Этот метод переопределяется формой переопределить.

В базовом классе возвращает ложь.

4.24.45 поле-редактора%🔗ℹ

класс
поле-редактора% : класс?

Базовый класс: объект-графического-интерфейса%, реализует интерфейс картина<%>. Холст, показывающий документ-редактор. Модуль графический-интерфейс/поле-редактора. Методы картина<%> тоже доступны.

конструктор
(поле-редактора% родитель
[ заголовок
редактор
стиль
горизонтальные-поля
вертикальные-поля
минимальная-ширина
минимальная-высота
растягивается-ширина
растягивается-высота
включен]) → поле-редактора%
  родитель : любой
  заголовок : любой = ложь
  редактор : любой = ложь
  стиль : любой = '()
  горизонтальные-поля : целое-неотрицательное? = 0
  вертикальные-поля : целое-неотрицательное? = 0
  минимальная-ширина : любой = ложь
  минимальная-высота : любой = ложь
  растягивается-ширина : булево? = истина
  растягивается-высота : булево? = истина
  включен : булево? = истина

Создаётся формой объект:

объект поле-редактора%
  родитель родитель
  заголовок заголовок
  редактор редактор
  стиль стиль
  горизонтальные-поля горизонтальные-поля
  вертикальные-поля вертикальные-поля
  минимальная-ширина минимальная-ширина
  минимальная-высота минимальная-высота
  растягивается-ширина растягивается-ширина
  растягивается-высота растягивается-высота
  включен включен

Аргументы как у картина%, вместо обработка — редактор (текст% или другой редактор<%>, по умолчанию ложь — пустое поле). стиль — список символов (по умолчанию пустой): 'без-рамки, 'рамка-элемента-управления, 'комбинированное, 'без-горизонтальной-прокрутки, 'без-вертикальной-прокрутки, 'скрыть-горизонтальную-прокрутку, 'скрыть-вертикальную-прокрутку, 'авто-горизонтальная-прокрутка, 'авто-вертикальная-прокрутка, 'угол-изменения-размера, 'без-фокуса, 'скрытая, 'прозрачная. минимальная-ширина и минимальная-высота по умолчанию ложь — размер по содержимому.

метод
(редактор) → любой
(редактор новое-значение) → пусто?
новое-значение : любой

Читает или задаёт документ поля. Без документа — ложь.

4.24.46 текст%🔗ℹ

класс
текст% : класс?

Базовый класс объект-графического-интерфейса%, реализует интерфейс редактор<%>.

Обычный текстовый документ. На экране его показывают через поле-редактора% или другую картину. Модуль графический-интерфейс/текст.

Методы редактор<%> тоже доступны у объекта.

конструктор
(текст% [ межстрочный-промежуток
автоматический-перенос]) → текст%
межстрочный-промежуток : число? = 1.0
автоматический-перенос : любой = ложь

Создаётся формой объект:

объект текст%
межстрочный-промежуток межстрочный-промежуток
автоматический-перенос автоматический-перенос

межстрочный-промежуток — дополнительный промежуток между строками при показе (входит в сообщаемую высоту строки).

Если автоматический-перенос не ложь, включается перенос длинных строк; по умолчанию ложь.

Для нового документа создаются свой набор-команд% и свой список-стилей%.

метод
(после-вставки начало длина) → пусто?
начало : целое-неотрицательное?
длина : целое-неотрицательное?

Этот метод дополняется формой дополнить.

Вызывается после вставки элементов (и после обновления показа). начало — позиция начала вставки, длина — число вставленных элементов.

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

См. также можно-менять-стиль? и при-начале-последовательности-редактировании.

метод
(после-объединения-кусков позиция) → пусто?
позиция : целое-неотрицательное?

Этот метод дополняется формой дополнить.

Вызывается после слияния соседних кусков в один. позиция — место, где слились куски: один был сразу перед ней, другой сразу после, новый охватывает её.

В базовом классе ничего не делает.

метод
(можно-менять-стиль? начало длина) → булево?
начало : целое-неотрицательное?
длина : целое-неотрицательное?

Этот метод дополняется формой дополнить.

Вызывается перед сменой стиля на участке от начало длиной длина. Если вернуть ложь, смена отменяется.

Во время вызова документ заперт на запись; правки, если нужны, делайте после смены стиля или через последовательность редактирования.

В базовом классе возвращает истина.

См. также изменить-стиль и при-начале-последовательности-редактировании.

метод
(изменить-стиль стиль-или-отклонение
начало
конец
считать-изменением) → пусто?
  стиль-или-отклонение : любой
  начало : любой
  конец : любой
  считать-изменением : любой

Меняет стиль участка, применяя отклонение-стиля% или устанавливая стиль%. стиль-или-отклонение может быть ложь.

Если начало и конец не заданы, меняется текущее выделение. Если задано только начало, стиль меняется от него до конца выделения.

Если считать-изменением — ложь, документ не помечается изменённым. По умолчанию считается изменением.

Чтобы сменить стиль у многих кусков сразу, лучше передать готовый стиль%, а не отклонение: иначе отклонение приходится переводить в стиль для каждого куска.

метод
(очистить) → пусто?

Удаляет всё содержимое документа.

метод
(найти-позицию лево верх) → целое-неотрицательное?
лево : число?
верх : число?

По координатам лево и верх в документе возвращает позицию в этом месте.

метод
(найти-кусок позиция направление) → любой
позиция : целое-неотрицательное?
направление : символ?

Кусок в заданной позиция или ложь, если подходящего куска нет.

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

'перед-или-пусто — кусок перед позицией или ложь в начале документа;
'перед — кусок перед позицией или первый кусок в начале документа;
'после — кусок после позиции или последний кусок в конце документа;
'после-или-пусто — кусок после позиции или ложь в конце документа и дальше.

метод
(данные-куска кусок) → любой
  кусок : кусок%
(данные-куска кусок данные) → пусто?
  кусок : кусок%
  данные : любой

Без данные возвращает дополнительные данные куска или ложь, если данных нет. С куском и данными записывает эти данные (например, положение куска).

метод
(позиция-куска кусок) → любой
кусок : кусок%

Позиция начала кусок в документе или ложь, если куска в этом документе нет.

метод
(вставить элемент) → пусто?
  элемент : любой
(вставить элемент начало) → пусто?
  элемент : любой
  начало : целое-неотрицательное?
(вставить элемент начало конец) → пусто?
  элемент : любой
  начало : целое-неотрицательное?
  конец : любой
(вставить элемент начало конец прокрутка) → пусто?
  элемент : любой
  начало : целое-неотрицательное?
  конец : любой
  прокрутка : любой
(вставить элемент
начало
конец
прокрутка
объединять) → пусто?
  элемент : любой
  начало : целое-неотрицательное?
  конец : любой
  прокрутка : любой
  объединять : любой
(вставить количество
элемент
начало
конец
прокрутка
объединять) → пусто?
  количество : целое-неотрицательное?
  элемент : любой
  начало : целое-неотрицательное?
  конец : любой
  прокрутка : любой
  объединять : любой

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

Кусок нельзя вставить в несколько документов или дважды в один: при вставке его стиль переводится в список стилей документа.

Если начало не указано, берётся начало текущего выделения. Если выделена область, вставляемое значение заменяет её; начало и конец выделения сдвигаются к концу вставки.

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

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

Если объединять не ложь (или вставляется литера), соседние литеры, которые должны рисоваться как один знак, включаются во вставку, чтобы знак не разорвался по разным кускам.

метод
(последняя-позиция) → целое-неотрицательное?

Последняя позиция выделения в документе; она же равна числу элементов документа.

метод
(начало-выделения) → целое-неотрицательное?

Начальная позиция текущего выделения в документе.

метод
(конец-выделения) → целое-неотрицательное?

Конечная позиция текущего выделения в документе.

метод
(текст [ начало
конец
сплющить?
принудительный-перенос?]) → строка?
  начало : целое-неотрицательное? = 0
   конец : (или/c целое-неотрицательное? 'конец-файла)
= 'конец-файла
  сплющить? : любой = ложь
  принудительный-перенос? : любой = ложь

Возвращает текст документа от начало до конец. Если конец — 'конец-файла, берётся фрагмент от начало до конца документа.

Если сплющить? не ложь, возвращается «сплющенный» текст (см. Flattened Text в документации Racket). Если принудительный-перенос? не ложь, в конец каждого абзаца добавляется символ перевода строки.

метод
(установить-выделение начало
[ конец
в-конце-строки?
прокрутить?
тип-выделения]) → пусто?
  начало : целое-неотрицательное?
  конец : (или/c целое-неотрицательное? 'начало) = 'начало
  в-конце-строки? : любой = ложь
  прокрутить? : любой = истина
   тип-выделения : (или/c 'по-умолчанию 'x 'локально)
= 'по-умолчанию

Задаёт текущее выделение в документе (в Racket — set-position).

Если конец — 'начало или не больше позиции начало, и начало, и конец выделения становятся равны начало (курсор без выделения). Иначе выделяется диапазон от начало до конец.

Если прокрутить? не ложь, показ прокручивается так, чтобы выделение стало видимым. тип-выделения влияет на механизм X selection ('по-умолчанию, 'x, 'локально).

метод
(только-просмотр значение) → пусто?
значение : любой

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

На внутренние замки показа и пересчёта раскладки этот метод не влияет.

метод
(конец-абзаца абзац видимый?) → целое-неотрицательное?
абзац : целое?
видимый? : любой

Конечная позиция абзаца с номером абзац. Абзацы нумеруются с нуля. видимый? по умолчанию истина.

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

Если абзац заканчивается невидимыми элементами (например, переносом строки) и видимый? не ложь, возвращается первая позиция перед этими элементами.

метод
(прокрутить-к-позиции позиция) → булево?
позиция : целое-неотрицательное?

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

Если обновление отложено, запрос запоминается до конца отложения. Прокрутка запрещена, пока документ заперт на пересчёт раскладки.

Показ сам может прокручивать документ, не вызывая этот метод (например, полоса прокрутки картины).

метод
(обработчик-щелчка начало
конец
функция
отметка
при-нажатии?) → пусто?
  начало : целое-неотрицательное?
  конец : целое-неотрицательное?
  функция : функция?
  отметка : любой
  при-нажатии? : любой

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

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

отметка — отклонение-стиля%, которое применяется, пока кнопка мыши удерживается над участком; по умолчанию ложь — начертание при выборе не меняется.

Если при-нажатии? не ложь (по умолчанию ложь), функция вызывается сразу при нажатии, а не при отпускании; отметка тогда не используется.

функция
(для-каждого-куска текст функция) → пусто?
текст : текст%
функция : функция?

Вызывает функция для каждого куска документа по порядку.

4.24.47 кусок%🔗ℹ

класс
кусок% : класс?

Базовый класс: объект-графического-интерфейса%. Фрагмент документа. Модуль графический-интерфейс/текст. Создаётся без обязательных аргументов.

конструктор
(кусок% внутренний) → кусок%
внутренний : любой

Создаётся формой объект:

объект кусок%
внутренний внутренний

Обычно куски делают наследниками или получают из документа.

метод
(следующий) → любой

Соседний кусок или ложь.

метод
(предыдущий) → любой

Соседний кусок или ложь.

метод
(текст смещение количество) → строка?
смещение : целое?
количество : целое?

Строка содержимого; аргументы: смещение и количество литер.

метод
(скопировать) → любой

Копия куска, ещё не вставленная в документ.

метод
(количество) → целое?
(количество новое-значение) → пусто?
новое-значение : целое?

Число позиций, которые занимает кусок (чтение и запись).

метод
(стиль) → стиль%
(стиль новое-значение) → пусто?
новое-значение : стиль%

стиль% куска (чтение и запись).

метод
(параметры) → список?
(параметры новое-значение) → пусто?
новое-значение : список?

Список символов: 'текст, 'можно-объединять, 'невидимый, 'перенос и др.

метод
(при-получении-клавиши холст
лево
верх
лево-редактора
верх-редактора
событие) → пусто?
  холст : холст%
  лево : число?
  верх : число?
  лево-редактора : число?
  верх-редактора : число?
  событие : событие-клавиши%

В базовом классе ничего не делает.

метод
(при-получении-события холст
лево
верх
лево-редактора
верх-редактора
событие) → пусто?
  холст : холст%
  лево : число?
  верх : число?
  лево-редактора : число?
  верх-редактора : число?
  событие : событие-мыши%

В базовом классе ничего не делает.

метод
(изменён-размер ширина высота) → любой
ширина : число?
высота : число?

Этот метод переопределяется формой переопределить.

Если вернуть не ложь, стандартное изменение размера не выполняется. В базовом классе возвращает ложь.

функция
(кусок-адины внутренний) → любой
внутренний : любой

Оборачивает внутренний кусок в подходящий класс Адины. Если внутренний — ложь, возвращает ложь.

4.24.48 кусок-со-строкой%🔗ℹ

класс
кусок-со-строкой% : класс?

Базовый класс: кусок%. Текстовый фрагмент. Методы кусок% тоже доступны.

конструктор
(кусок-со-строкой% [содержимое]) → кусок-со-строкой%
содержимое : любой = 0

Создаётся формой объект:

объект кусок-со-строкой%
содержимое содержимое

содержимое — строка или целое число (запас мест под литеры), по умолчанию 0.

4.24.49 кусок-с-изображением%🔗ℹ

класс
кусок-с-изображением% : класс?

Базовый класс: кусок%. Рисунок в документе. Методы кусок% тоже доступны.

конструктор
(кусок-с-изображением% [содержимое]) → кусок-с-изображением%
содержимое : любой = ложь

Создаётся формой объект:

объект кусок-с-изображением%
содержимое содержимое

содержимое — изображение% или ложь.

метод
(изображение) → изображение%
(изображение значение) → пусто?
значение : изображение%

Читает или задаёт растр (изображение%).

4.24.50 кусок-с-редактором%🔗ℹ

класс
кусок-с-редактором% : класс?

Базовый класс: кусок%. Вложенный редактор в ячейке документа. Методы кусок% тоже доступны.

конструктор
(кусок-с-редактором% [редактор есть-граница])
→ кусок-с-редактором%
редактор : любой = ложь
есть-граница : булево? = истина

Создаётся формой объект:

объект кусок-с-редактором%
редактор редактор
есть-граница есть-граница

редактор — редактор<%> или ложь. есть-граница по умолчанию истина.

метод
(редактор) → любой

Вложенный документ.

метод
(максимальная-ширина) → число?
(максимальная-ширина новое-значение
редактор?) → пусто?
новое-значение : число?
редактор? : булево?

Ограничение размера ячейки (чтение и запись). При записи второй аргумент — менять ли те же пределы у вложенного редактора.

метод
(минимальная-ширина) → число?
(минимальная-ширина новое-значение
редактор?) → пусто?
новое-значение : число?
редактор? : булево?

метод
(максимальная-высота) → число?
(максимальная-высота новое-значение
редактор?) → пусто?
новое-значение : число?
редактор? : булево?

метод
(минимальная-высота) → число?
(минимальная-высота новое-значение
редактор?) → пусто?
новое-значение : число?
редактор? : булево?

4.24.51 список-стилей%🔗ℹ

класс
список-стилей% : класс?

Базовый класс: объект-графического-интерфейса%. Список именованных стилей документа. Модуль графический-интерфейс/стиль. Создаётся без аргументов.

конструктор
(список-стилей%) → список-стилей%

Создаётся формой объект:

объект список-стилей%

метод
(базовый-стиль) → стиль%

Корневой стиль списка.

метод
(найти-по-имени имя) → стиль%
имя : символ?

Стиль с этим именем или ложь.

метод
(новый-с-именем имя стиль) → стиль%
имя : символ?
стиль : стиль%

Зарегистрировать копию стиля под именем.

метод
(заменить-с-именем имя стиль) → стиль%
имя : символ?
стиль : стиль%

Подменить стиль с этим именем или создать новый.

4.24.52 стиль%🔗ℹ

класс
стиль% : класс?

Базовый класс: объект-графического-интерфейса%. Стиль начертания куска. Тот же модуль. Обычно получают из списка стилей, а не создают пустым.

конструктор
(стиль% внутренний) → стиль%
внутренний : любой

Создаётся формой объект:

объект стиль%
внутренний внутренний

Обычно получают из список-стилей%.

метод
(базовый-стиль) → стиль%

Стиль, от которого унаследован этот, или ложь.

метод
(установить-отклонение отклонение) → пусто?
отклонение : отклонение-стиля%

Применить отклонение-стиля% к этому стилю.

функция
(стиль-адины внутренний) → стиль%
внутренний : любой

Оборачивает внутренний стиль в стиль%.

4.24.53 отклонение-стиля%🔗ℹ

класс
отклонение-стиля% : класс?

Базовый класс: объект-графического-интерфейса%. Отличие стиля от базового при изменить-стиль. Создаётся без аргументов (пустое отклонение).

конструктор
(отклонение-стиля%) → отклонение-стиля%

Создаётся формой объект:

объект отклонение-стиля%

метод
(установить-цвет-текста цвет) → пусто?
цвет : любой

Цвет букв (цвет% или символ из стандартные-цвета).

метод
(установить-цвет-фона цвет) → пусто?
цвет : любой

Цвет фона участка.

4.24.54 набор-команд%🔗ℹ

класс
набор-команд% : класс?

Базовый класс: объект-графического-интерфейса%. Привязки клавиш редактора. Модуль графический-интерфейс/набор-команд.

конструктор
(набор-команд% внутренний) → набор-команд%
внутренний : любой

Создаётся формой объект:

объект набор-команд%
внутренний внутренний

внутренний — готовый набор; иначе создаётся пустой.

метод
(добавить-функцию имя функция) → пусто?
имя : символ?
функция : функция?

Регистрирует имя и функцию; функция получает источник и событие.

метод
(есть-функция? имя) → булево?
имя : символ?

Зарегистрировано ли имя.

метод
(вызвать-функцию имя источник событие) → пусто?
  имя : символ?
  источник : любой
  событие : любой

Вызывает функцию по имени.

метод
(функция-команды команда функция) → пусто?
команда : строка?
функция : символ?

Привязывает последовательность клавиш к имени функции.

метод
(отменить-последовательность) → пусто?

Сбрасывает частично введённую последовательность клавиш.

функция
(набор-команд-адины внутренний) → набор-команд%
внутренний : любой

Оборачивает внутренний набор команд в набор-команд%.

4.25 Операционная система🔗ℹ

синтаксис
(замерить-время команда ... выражение)

Выполняет переданные команды, возвращает результат выражения. После выполнения выводит в текущий порт вывода строку «время процессора: {т1} реальное: {т2} сборки мусора: {т3}» c значениями времени выполнения переданных команд и выражения в полях {т1}..{т3}.

функция
(применить-замеряя-время функция список) →
список?
точное-целое?
точное-целое?
точное-целое?
функция : функция?
список : список?

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

функция
(открыть-страницу-Интернета строка-адреса) → пусто?
строка-адреса : строка?

Открывает строка-адреса в браузере по умолчанию. Модуль операционная-система.

функция
(воспроизвести-звук файл [асинхронно?]) → булево?
файл : (один-из строка? путь?)
асинхронно? : любой = ложь

Воспроизводит звуковой файл. Если асинхронно? — ложь, не возвращает управление, пока звук не закончится. Возвращает истина, если воспроизведение удалось, иначе ложь.

функция
(завершить-работу [значение]) → любой
значение : любой = истина

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

Если значение — точное целое от 1 до 255, оно становится кодом завершения процесса (обычно неуспех); иначе код равен 0 (обычно успех). По умолчанию значение — истина, то есть успешное завершение. Модуль операционная-система.

4.26 Сеть🔗ℹ

Подключение к узлу, обмен пакетами и постоянная связь. Модули подключаются по имени:

надёжное-соединение — поток с гарантией доставки и порядка;
ненадёжное-соединение — пакеты без гарантии доставки и порядка;
постоянное-соединение — сериализуемые значения Адины и восстановление связи при обрыве.

4.26.1 надёжное-соединение🔗ℹ

Подключение к узлу сети: порты ввода и вывода.

функция
(соединить имя-сервера номер-порта) →
порт-ввода? порт-вывода?
имя-сервера : строка?
номер-порта : целое-неотрицательное?

Подключается к имя-сервера на порту номер-порта. Возвращает порт ввода и порт вывода установленного соединения.

функция
(ждать-соединения номер-порта) → любой
номер-порта : целое-неотрицательное?

Начинает ждать входящие подключения на порту номер-порта. Результат передают в принять-соединение.

функция
(принять-соединение ожидание) →
порт-ввода? порт-вывода?
ожидание : любой

Принимает одно подключение, полученное через ждать-соединения. Ждёт, пока клиент подключится. Возвращает порт ввода и порт вывода.

4.26.2 ненадёжное-соединение🔗ℹ

Обмен пакетами без гарантии доставки и порядка.

функция
(открыть [имя-сервера номер-порта]) → соединение?
имя-сервера : (один-из строка? ложь) = ложь
номер-порта : (один-из целое-неотрицательное? ложь) = ложь

Создаёт соединение для обмена пакетами. Пока оно не привязано к местному порту и не соединено с удалённым. Если заданы имя-сервера или номер-порта, они только задают тип адреса, а не привязку.

функция
(закрыть соединение) → пусто?
соединение : соединение?

Закрывает соединение. Непринятые пакеты отбрасываются.

функция
(соединение? значение) → булево?
значение : любой

Возвращает истина, если значение создано открыть.

функция
(привязать соединение
имя-сервера
номер-порта
[ повторно?]) → пусто?
  соединение : соединение?
  имя-сервера : (один-из строка? ложь)
  номер-порта : целое-неотрицательное?
  повторно? : любой = ложь

Привязывает соединение к местному порту номер-порта. Ноль выбирает свободный порт; его затем даёт адреса. Если имя-сервера — ложь, принимаются пакеты на все местные адреса; иначе только на указанный. Пока соединение не привязано, пакеты получить нельзя; отправка сама привяжет его к случайному порту. Если повторно? не ложь, порт можно делить с другими процессами.

функция
(привязано? соединение) → булево?
соединение : соединение?

Возвращает истина, если соединение привязано к местному адресу и порту.

функция
(соединить соединение
имя-сервера
номер-порта) → пусто?
  соединение : соединение?
  имя-сервера : (один-из строка? ложь)
  номер-порта : (один-из целое-неотрицательное? ложь)

Направляет соединение на удалённый узел. Дальше отправить шлёт туда, а принимаются пакеты только оттуда. Если имя-сервера и номер-порта — ложь, направление снимается. Можно задавать снова.

функция
(соединено? соединение) → булево?
соединение : соединение?

Возвращает истина, если соединение соединено с удалённым адресом.

функция
(отправить-на соединение
имя-сервера
номер-порта
байты
[ начало
конец]) → пусто?
  соединение : соединение?
  имя-сервера : строка?
  номер-порта : целое-неотрицательное?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Отправляет отрезок байты с начало до конец на имя-сервера и порт номер-порта. Соединение не должно быть соединено через соединить. Если очередь исходящих полна, ждёт.

функция
(отправить соединение байты [начало конец]) → пусто?
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как отправить-на, но соединение должно быть соединено через соединить, и пакет идёт на заданный адрес.

функция
(отправить-на* соединение
имя-сервера
номер-порта
байты
[ начало
конец]) → булево?
  соединение : соединение?
  имя-сервера : строка?
  номер-порта : целое-неотрицательное?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как отправить-на, но не ждёт: если очередь полна, возвращает ложь, иначе ставит пакет в очередь и возвращает истина.

функция
(отправить* соединение байты [начало конец]) → булево?
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как отправить, но не ждёт и возвращает истина или ложь, как отправить-на*.

функция
(отправить-на/с-прерыванием соединение
имя-сервера
номер-порта
байты
[ начало
конец]) → пусто?
  соединение : соединение?
  имя-сервера : строка?
  номер-порта : целое-неотрицательное?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как отправить-на, но ожидание можно прервать.

функция
(отправить/с-прерыванием соединение
байты
[ начало
конец]) → пусто?
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как отправить, но ожидание можно прервать.

функция
(получить соединение байты [начало конец]) →
целое-неотрицательное?
строка?
целое-неотрицательное?
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Записывает очередной пакет в изменяемые байты, начиная с начало, не дальше конец. Соединение должно быть привязано. Если пакета нет, ждёт. Возвращает число записанных байт, имя отправителя и его порт. Лишнее в пакете отбрасывается.

функция
(получить* соединение байты [начало конец])
→
(один-из целое-неотрицательное? ложь)
(один-из строка? ложь)
(один-из целое-неотрицательное?
ложь)
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как получить, но не ждёт: если пакета нет, все три значения — ложь.

функция
(получить/с-прерыванием соединение
байты
[ начало
конец]) →
целое-неотрицательное?
строка?
целое-неотрицательное?
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Как получить, но ожидание можно прервать.

функция
(установить-размер-буфера-приёма соединение
размер) → пусто?
соединение : соединение?
размер : целое-неотрицательное?

Задаёт размер буфера приёма соединение. Больший буфер снижает потери пакетов при редком опросе.

функция
(событие-готовности-отправки соединение) → любой
соединение : соединение?

Событие, готовое, когда отправить-на не будет ждать.

функция
(событие-готовности-приёма соединение) → любой
соединение : соединение?

Событие, готовое, когда получить не будет ждать.

функция
(событие-отправки-на соединение
имя-сервера
номер-порта
байты
[ начало
конец]) → любой
  соединение : соединение?
  имя-сервера : строка?
  номер-порта : целое-неотрицательное?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Событие: при выборе отправляет пакет, как отправить-на.

функция
(событие-отправки соединение
байты
[ начало
конец]) → любой
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Событие: при выборе отправляет пакет, как отправить.

функция
(событие-приёма соединение
байты
[ начало
конец]) → любой
  соединение : соединение?
  байты : байты?
  начало : целое-неотрицательное? = 0
  конец : целое-неотрицательное? = (длина-байтов байты)

Событие: при выборе принимает пакет в байты, как получить; результат ожидания — список из трёх значений.

функция
(адреса соединение [номера-портов?]) → любой
соединение : соединение?
номера-портов? : любой = ложь

Местный и удалённый адреса соединение. Если номера-портов? — ложь, два значения-строки: местный и удалённый адрес. Если не ложь, четыре значения: местный адрес, местный порт, удалённый адрес, удалённый порт. Непривязанный местный порт и несоединённый удалённый — 0.

функция
(время-жизни соединение) → байт?
соединение : соединение?

Возвращает время жизни пакетов соединение.

функция
(установить-время-жизни соединение
значение) → пусто?
соединение : соединение?
значение : байт?

Задаёт время жизни пакетов соединение.

функция
(войти-в-группу соединение
адрес-группы
имя-сервера) → пусто?
  соединение : соединение?
  адрес-группы : строка?
  имя-сервера : (один-из строка? ложь)

Включает соединение в группу рассылки адрес-группы. имя-сервера выбирает интерфейс приёма; ложь или «0.0.0.0» — выбрать автоматически.

функция
(выйти-из-группы соединение
адрес-группы
имя-сервера) → пусто?
  соединение : соединение?
  адрес-группы : строка?
  имя-сервера : (один-из строка? ложь)

Исключает соединение из группы. Аргументы те же, что при войти-в-группу.

функция
(групповой-интерфейс соединение) → строка?
соединение : соединение?

Интерфейс, через который соединение отправляет групповые пакеты.

функция
(установить-групповой-интерфейс соединение
имя-сервера) → пусто?
соединение : соединение?
имя-сервера : (один-из строка? ложь)

Задаёт интерфейс отправки групповых пакетов. ложь или «0.0.0.0» — выбирать автоматически.

функция
(групповой-возврат? соединение) → булево?
соединение : соединение?

Возвращает истина, если соединение получает свои групповые пакеты.

функция
(установить-групповой-возврат соединение
значение) → пусто?
соединение : соединение?
значение : любой

Задаёт, получает ли соединение свои групповые пакеты.

функция
(групповое-время-жизни соединение) → байт?
соединение : соединение?

Время жизни групповых пакетов соединение.

функция
(установить-групповое-время-жизни соединение
значение) → пусто?
соединение : соединение?
значение : байт?

Задаёт время жизни групповых пакетов соединение.

4.26.3 постоянное-соединение🔗ℹ

Клиент при обрыве подключается снова; сообщения подтверждаются. Данные должны быть такими, чтобы написать вывел их в читаемом обратно виде (строки, числа, списки, массивы). Функции, объекты и пусто так передать нельзя: тогда придёт строка, которую дал написать.

функция
(соединить имя-сервера
номер-порта
[ #:при-подключении при-подключении
#:при-получении при-получении
#:при-изменении-состояния при-изменении-состояния])
→
любой функция?
  имя-сервера : строка?
  номер-порта : целое-неотрицательное?
   при-подключении : функция?
= (функция (причина-отключения соединение) пусто)
  при-получении : функция? = (функция (объект) пусто)
   при-изменении-состояния : функция?
= (функция (состояние) пусто)

Подключается к имя-сервера на порту номер-порта. Возвращает два значения: соединение (его передают в отправить) и функцию без аргументов, которая разрывает связь.

при-подключении вызывается после успешного подключения. Первый аргумент — ложь при первом подключении или причина предыдущего обрыва; второй — соединение. при-получении получает очередное сообщение. при-изменении-состояния — при обрыве; среди причин — 'время-вышло и 'обрыв-связи.

Если долго нет пакетов, клиент считает связь потерянной и подключается снова.

функция
(ждать-соединения порт) → любой
порт : целое-неотрицательное?

Начинает ждать входящие подключения на порту порт. Результат передают в принять-соединение.

функция
(принять-соединение ожидание при-получении) →
любой функция?
ожидание : любой
при-получении : функция?

Принимает одно подключение, полученное через ждать-соединения. при-получении вызывается с сообщением и соединением. Возвращает соединение и функцию завершения, как соединить.

функция
(отправить соединение данные) → пусто?
соединение : любой
данные : любой

Отправляет данные в соединение, полученное от соединить или принять-соединение.

4.27 Почта🔗ℹ

Модуль почта. Отправка писем через SMTP.

функция
(отправить-почту имя-сервера
отправитель
получатели
заголовок
сообщение
[ #:номер-порта номер-порта
#:пользователь пользователь
#:пароль пароль
#:oauth2? oauth2?
#:подключиться подключиться
#:шифрование шифрование]) → пусто?
  имя-сервера : строка?
  отправитель : строка?
  получатели : (список-из строка?)
  заголовок : строка?
  сообщение : (список-из (один-из строка? байты?))
  номер-порта : целое-неотрицательное? = 25
  пользователь : (один-из строка? ложь) = ложь
  пароль : (один-из строка? ложь) = ложь
  oauth2? : любой = ложь
  подключиться : функция? = соединить
  шифрование : (один-из функция? ложь) = ложь

Подключается к серверу имя-сервера и отправляет письмо. отправитель — адрес отправителя. получатели — список адресов (поля «Кому», копия и скрытая копия). заголовок — полный заголовок письма, уже содержащий поля отправителя, получателей и копии, согласованные с отправитель и получатели. сообщение — тело: список строк или байтовых строк; каждый элемент — одна строка текста без перевода строки.

номер-порта по умолчанию 25. пользователь и пароль задают вход на сервер. Если oauth2? не ложь, вместо пароля передают токен доступа.

подключиться получает имя сервера и номер порта и возвращает порты ввода и вывода; по умолчанию как соединить надёжного соединения. Если шифрование не ложь, после приветствия канал защищают этой функцией. Обычно задают либо защищённое подключиться, либо шифрование, а не оба сразу. Модуль почта.

4.28 Клиент гипертекста🔗ℹ

Модуль клиент-гипертекста. Запрос к узлу по HTTP и получение ответа.

функция
(отправить-получить-гипертекст узел
путь
[ #:защищённый? защищённый?
#:порт порт
#:версия версия
#:метод метод
#:заголовки заголовки
#:данные данные
#:декодирование декодирование])
→
байты? список? порт-ввода?
  узел : (один-из байты? строка?)
  путь : (один-из байты? строка?)
  защищённый? : любой = ложь
   порт : целое-неотрицательное?
= (если защищённый? тогда 443 иначе 80)
  версия : (один-из байты? строка?) = #"1.1"
  метод : любой = 'получение
  заголовки : список? = пустой-список
   данные :
(один-из байты? строка? функция?
ложь)
= ложь
  декодирование : список? = (список 'gzip 'deflate)

Открывает соединение с узел, отправляет запрос к путь и возвращает три значения: строку состояния (байты), список заголовков ответа (байты) и порт ввода тела.

Если защищённый? не ложь, соединение шифруют; порт по умолчанию тогда 443, иначе 80. метод — 'получение или 'GET (получение), 'отправка или 'POST (отправка); иные значения передают как есть. данные — тело запроса. декодирование — символы способов сжатия тела ответа; по умолчанию 'gzip и 'deflate.

4.29 Формат JSON🔗ℹ

Модуль формат-json. Имена короткие, поэтому модуль подключают с префиксом:

используется
с-префиксом json: формат-json

функция
(прочитать
[ порт]
#:пусто пусто
[ #:заменять-неверный-сурогат? заменять-неверный-сурогат?])
→ любой
  порт : порт-ввода? = (текущий-порт-ввода)
  пусто : любой
  заменять-неверный-сурогат? : любой = ложь

Читает одно JSON-значение из порт. Если остались только пробелы, результат — конец-файла. пусто — значение, которым представляют JSON null (по умолчанию символ 'null). Если заменять-неверный-сурогат? не ложь, неверный суррогат заменяют литерой замены Юникода, иначе вызывается исключение.

функция
(из-строки
строка
#:пусто пусто
[ #:заменять-неверный-сурогат? заменять-неверный-сурогат?])
→ любой
  строка : строка?
  пусто : любой
  заменять-неверный-сурогат? : любой = ложь

Разбирает JSON из префикса строка. пусто и заменять-неверный-сурогат? — как при чтении из порта.

функция
(в-строку значение
#:пусто пусто
[ #:кодирование кодирование
#:отступ отступ]) → строка?
  значение : любой
  пусто : любой
  кодирование : любой = 'управляющие
   отступ :
(один-из литера? целое-неотрицательное?
ложь)
= ложь

Собирает JSON-текст из значение. кодирование — 'управляющие (экранировать управляющие литеры) или 'все (экранировать все не-ASCII). отступ — ложь (без форматирования), литера табуляции или число пробелов.

4.30 Формат Base64🔗ℹ

Модуль формат-base64. Имена короткие, поэтому модуль подключают с префиксом:

используется
с-префиксом b64: формат-base64

функция
(из-байтов байты) → байты?
байты : байты?

Декодирует Base64 из байты. Пробелы и переводы строк в данных допускаются.

функция
(в-байты байты
[ #:перевод-строки перевод-строки]) → байты?
байты : байты?
перевод-строки : любой = #""

Кодирует байты в Base64. По умолчанию перевод-строки — пустые байты: одна строка без переносов. Если задать, например, #"\r\n", результат разбивается на строки по 72 символа (как в MIME).

4.31 Криптография🔗ℹ

Модуль криптография — обёртка пакета crypto: отпечатки, HMAC, симметричное шифрование, открытый ключ, вывод ключа и пароли. Нужен установленный пакет crypto. Перед операциями задайте фабрики:

используется криптография
использовать-все-фабрики()
; или:
фабрики-криптографических-библиотек(список фабрика-libcrypto)

Имя отпечаток совпадает с модулем отпечаток (функции sha*-bytes); при одновременном подключении используйте с-префиксом.

4.31.1 Фабрики🔗ℹ

функция
(фабрика-криптографической-библиотеки? значение) → булево?
значение : любой

Возвращает истина, если значение — фабрика криптографического провайдера (libcrypto, nettle и т.д.).

parameter
(фабрики-криптографических-библиотек)
→ (список-из фабрика-криптографической-библиотеки?)
(фабрики-криптографических-библиотек фабрики) → void?
фабрики : (список-из фабрика-криптографической-библиотеки?)

Список фабрик, в котором ищут реализации алгоритмов по спецификации ('sha256, '(aes gcm) и т.п.). Изначально пуст: пока список пуст, вызовы вроде отпечаток не находят реализацию.

функция
(фабрика-реализации реализация)
→ фабрика-криптографической-библиотеки?
реализация : любой

Фабрика, связанная с данной реализацией или контекстом алгоритма.

функция
(версия-фабрики фабрика)
→
(один-из (список-из целое-неотрицательное?)
ложь)
фабрика : любой

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

функция
(сведения-фабрики фабрика) → пусто?
фабрика : любой

Печатает в текущий порт вывода сведения о фабрике: версию, доступные отпечатки, шифры, системы открытого ключа, кривые, KDF.

значение
все-фабрики : (список-из фабрика-криптографической-библиотеки?)

Все фабрики из crypto/all. Порядок может меняться между версиями пакета; удобно для интерактивной работы.

функция
(использовать-все-фабрики) → пусто?

Эквивалентно установке фабрики-криптографических-библиотек в все-фабрики.

значение
фабрика-libcrypto : любой

Фабрика OpenSSL libcrypto (обычно есть в системе или с Racket; нужен OpenSSL 3.0 или новее).

значение
фабрика-gcrypt : любой

Фабрика libgcrypt (нужна libgcrypt.so.20, версия 1.8+).

значение
фабрика-nettle : любой

Фабрика Nettle (libnettle.so.8; для открытого ключа ещё libhogweed.so.6, версия 3.6+).

значение
фабрика-sodium : любой

Фабрика libsodium (низкоуровневые примитивы, не высокоуровневый API Sodium).

значение
фабрика-b2 : любой

Фабрика libb2 (Blake2).

значение
фабрика-argon2 : любой

Фабрика Argon2 (хэширование паролей и вывод ключа).

значение
фабрика-decaf : любой

Фабрика libdecaf (Curve25519 / Curve448).

4.31.2 Отпечатки и HMAC🔗ℹ

функция
(спецификация-отпечатка? значение) → булево?
значение : любой

Истина, если значение — спецификация отпечатка (обычно символ вроде 'sha256, 'sha3-512, 'blake2b-256).

функция
(реализация-отпечатка? значение) → булево?
значение : любой

Истина, если значение — конкретная реализация отпечатка, полученная из фабрики.

функция
(получить-отпечаток спецификация [фабрики]) → (один-из любой ложь)
спецификация : любой
фабрики : любой = (фабрики-криптографических-библиотек)

Ищет реализацию спецификация в фабрики. Если нет — ложь.

функция
(размер-отпечатка спецификация) → целое-положительное?
спецификация : любой

Длина отпечатка в байтах (для 'sha1 — 20, для 'sha256 — 32). спецификация может быть спецификацией, реализацией или контекстом.

функция
(размер-блока-отпечатка спецификация) → целое-положительное?
спецификация : любой

Размер внутреннего блока алгоритма в байтах (нужен редким построениям вроде HMAC).

функция
(стойкость-отпечатка спецификация
устойчивость-к-коллизиям?)
→ (один-из целое-неотрицательное? ложь)
спецификация : любой
устойчивость-к-коллизиям? : булево?

Оценка стойкости в битах или ложь, если неизвестна. Если устойчивость-к-коллизиям? — истина, учитывают требование стойкости к коллизиям (как у цифровых подписей); иначе — как у HMAC.

функция
(создать-ключ-отпечатка-hmac спецификация) → байты?
спецификация : любой

Случайный секрет длины (размер-отпечатка спецификация) для HMAC; байты из случайные-байты-криптографии.

функция
(отпечаток спецификация вход [#:ключ ключ]) → байты?
  спецификация : любой
  вход : любой
  ключ : (один-из байты? ложь) = ложь

Считает отпечаток вход. Допустимый вход — как у вход-криптографии/с (байты, строка UTF-8, порт, срез, список таких значений). Для алгоритмов с ключом (Blake2) передайте ключ; иначе ключ должен быть ложь.

функция
(отпечаток-hmac спецификация ключ вход) → байты?
  спецификация : любой
  ключ : байты?
  вход : любой

HMAC от вход с секретом ключ и отпечатком спецификация. Длина ключа произвольна; типична (размер-отпечатка спецификация).

функция
(контекст-отпечатка спецификация
[ #:ключ ключ]) → любой
спецификация : любой
ключ : (один-из байты? ложь) = ложь

Создаёт контекст для пошагового накопления данных (обновить-отпечаток, затем завершить-отпечаток).

функция
(контекст-отпечатка? значение) → булево?
значение : любой

Истина, если значение — контекст отпечатка или HMAC.

функция
(обновить-отпечаток контекст вход) → пусто?
контекст : любой
вход : любой

Добавляет данные вход к контекст. Можно вызывать несколько раз: считается отпечаток конкатенации кусков.

функция
(завершить-отпечаток контекст) → байты?
контекст : любой

Возвращает отпечаток накопленных данных и закрывает контекст. Дальнейшие операции с ним вызывают исключение.

функция
(копия-отпечатка контекст) → (один-из любой ложь)
контекст : любой

Копия контекста или ложь, если провайдер не умеет копировать. Удобно для общих префиксов сообщений.

функция
(подсмотреть-отпечаток контекст) → (один-из байты? ложь)
контекст : любой

Отпечаток без закрытия контекста, или ложь, если копирование не поддерживается.

функция
(контекст-отпечатка-hmac спецификация ключ) → любой
спецификация : любой
ключ : байты?

Как контекст-отпечатка, но для HMAC с данным ключом.

4.31.3 Симметричное шифрование🔗ℹ

функция
(спецификация-шифра? значение) → булево?
значение : любой

Истина, если значение — спецификация шифра: список блочного шифра и режима, например '(aes cbc), '(aes gcm), или потокового вида '(chacha20-poly1305 stream).

функция
(реализация-шифра? значение) → булево?
значение : любой

Истина, если значение — реализация шифра из фабрики.

функция
(получить-шифр спецификация [фабрики]) → (один-из любой ложь)
спецификация : любой
фабрики : любой = (фабрики-криптографических-библиотек)

Реализация спецификация из фабрики или ложь.

функция
(размер-блока-шифра шифр) → целое-положительное?
шифр : любой

Размер блока в байтах. Для потоковых шифров и потоковых режимов (CTR и т.п.) — 1.

функция
(размер-ключа-шифра шифр) → целое-неотрицательное?
шифр : любой

Размер ключа по умолчанию в байтах (для AES часто 16).

функция
(размеры-ключа-шифра шифр) → (список-из целое-неотрицательное?)
шифр : любой

Допустимые длины ключа в байтах (для AES — '(16 24 32)).

функция
(размер-вектора-инициализации шифр) → целое-неотрицательное?
шифр : любой

Длина вектора инициализации (IV / nonce) в байтах; 0, если он не используется (например ECB).

функция
(шифр-с-проверкой-подлинности? шифр) → булево?
шифр : любой

Истина для AEAD-шифров (GCM, ChaCha20-Poly1305 и т.п.): кроме шифртекста есть проверка подлинности. Для таких шифров зашифровать принимает #:дополнительные-данные; для остальных этот ключ в вызов провайдера не передаётся.

функция
(размер-проверки-подлинности-шифра шифр)
→ целое-неотрицательное?
шифр : любой

Длина тега проверки подлинности по умолчанию в байтах; 0, если шифр не AEAD.

функция
(создать-ключ-шифра шифр [#:размер размер]) → байты?
шифр : любой
размер : целое-положительное? = (размер-ключа-шифра шифр)

Случайный секретный ключ длины размер для шифр (случайные-байты-криптографии). Слабые ключи отдельно не отсекаются.

функция
(создать-вектор-инициализации шифр
[ #:размер размер])
→ (один-из байты? ложь)
шифр : любой
размер : целое-положительное?
= (размер-вектора-инициализации шифр)

Случайный вектор инициализации длины размер. Если шифр его не использует — ложь.

функция
(зашифровать
шифр
ключ
вектор-инициализации
вход
[ #:дополнительные-данные дополнительные-данные
#:размер-проверки-подлинности размер-проверки-подлинности
#:дополнение дополнение])
→ байты?
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
  вход : любой
  дополнительные-данные : любой = #""
   размер-проверки-подлинности : целое-неотрицательное?
= (размер-проверки-подлинности-шифра шифр)
  дополнение : любой = истина

Шифрует вход ключом и вектор-инициализации. Если дополнение не ложь и шифр блочный, добавляется PKCS#7; для потоковых режимов дополнение игнорируется. Для AEAD тег проверки подлинности дописывается к шифртексту; длина тега — размер-проверки-подлинности. дополнительные-данные учитываются только если (шифр-с-проверкой-подлинности? шифр).

функция
(расшифровать
шифр
ключ
вектор-инициализации
вход
[ #:дополнительные-данные дополнительные-данные
#:размер-проверки-подлинности размер-проверки-подлинности
#:дополнение дополнение])
→ байты?
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
  вход : любой
  дополнительные-данные : любой = #""
   размер-проверки-подлинности : целое-неотрицательное?
= (размер-проверки-подлинности-шифра шифр)
  дополнение : любой = истина

Расшифровывает вход (байты или порт ввода). Для AEAD тег берётся с конца шифртекста; при ошибке подлинности — исключение.

функция
(зашифровать/проверка-подлинности
шифр
ключ
вектор-инициализации
вход
[ #:дополнительные-данные дополнительные-данные
#:размер-проверки-подлинности размер-проверки-подлинности
#:дополнение дополнение])
→
байты? байты?
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
  вход : любой
  дополнительные-данные : любой = #""
   размер-проверки-подлинности : целое-неотрицательное?
= (размер-проверки-подлинности-шифра шифр)
  дополнение : любой = истина

Как зашифровать, но возвращает два значения: шифртекст и отдельный тег проверки подлинности (для не-AEAD тег — #"").

функция
(расшифровать/проверка-подлинности
шифр
ключ
вектор-инициализации
вход
[ #:дополнительные-данные дополнительные-данные
#:проверка-подлинности проверка-подлинности
#:дополнение дополнение])
→ байты?
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
  вход : любой
  дополнительные-данные : любой = #""
  проверка-подлинности : байты? = #""
  дополнение : любой = истина

Как расшифровать, но тег передаётся отдельно ключом #:проверка-подлинности.

функция
(контекст-шифрования
шифр
ключ
вектор-инициализации
[ #:размер-проверки-подлинности размер-проверки-подлинности
#:проверка-подлинности-прикреплена? проверка-подлинности-прикреплена?
#:дополнение дополнение])
→ любой
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
   размер-проверки-подлинности : целое-неотрицательное?
= (размер-проверки-подлинности-шифра шифр)
  проверка-подлинности-прикреплена? : любой = истина
  дополнение : любой = истина

Контекст пошагового шифрования (обновить-шифр, завершить-шифр). Если проверка-подлинности-прикреплена? — ложь, тег AEAD не вшивается в поток, а снимается проверка-подлинности-шифра.

функция
(контекст-расшифрования
шифр
ключ
вектор-инициализации
[ #:размер-проверки-подлинности размер-проверки-подлинности
#:проверка-подлинности-прикреплена? проверка-подлинности-прикреплена?
#:дополнение дополнение])
→ любой
  шифр : любой
  ключ : байты?
  вектор-инициализации : (один-из байты? ложь)
   размер-проверки-подлинности : целое-неотрицательное?
= (размер-проверки-подлинности-шифра шифр)
  проверка-подлинности-прикреплена? : любой = истина
  дополнение : любой = истина

Контекст пошагового расшифрования.

функция
(контекст-шифра? значение) → булево?
значение : любой

Истина для контекста шифрования или расшифрования.

функция
(контекст-шифрования? значение) → булево?
значение : любой

Истина только для контекста шифрования.

функция
(контекст-расшифрования? значение) → булево?
значение : любой

Истина только для контекста расшифрования.

функция
(обновить-шифр контекст вход) → байты?
контекст : любой
вход : любой

Обрабатывает очередной кусок вход; возвращает доступный фрагмент вывода (может быть короче или длиннее входа из-за буфера блоков).

функция
(обновить-дополнительные-данные-шифра контекст
вход) → пусто?
контекст : любой
вход : любой

Подаёт дополнительные аутентифицируемые данные в AEAD-контекст. Вызывать до любого обновить-шифр; иначе — исключение.

функция
(завершить-шифр контекст
[ проверка-подлинности]) → байты?
контекст : любой
проверка-подлинности : (один-из байты? ложь) = ложь

Дописывает хвост буфера, снимает/проверяет дополнение. Для AEAD в режиме с отдельным тегом при расшифровании передайте тег в проверка-подлинности; иначе аргумент должен быть ложь.

функция
(проверка-подлинности-шифра контекст) → байты?
контекст : любой

Тег проверки подлинности после завершить-шифр для контекста шифрования. Для не-AEAD — #"". До завершить-шифр — исключение.

4.31.4 Открытый ключ🔗ℹ

функция
(спецификация-открытого-ключа? значение) → булево?
значение : любой

Истина для спецификации системы: 'rsa, 'dsa, 'dh, 'ec, 'eddsa, 'ecx.

функция
(реализация-открытого-ключа? значение) → булево?
значение : любой

Истина для реализации системы открытого ключа из фабрики.

функция
(получить-открытый-ключ спецификация
[ фабрики]) → (один-из любой ложь)
спецификация : любой
фабрики : любой = (фабрики-криптографических-библиотек)

Реализация системы спецификация или ложь.

функция
(открытый-ключ-умеет-подписывать? ключ) → булево?
ключ : любой

Умеет ли реализация (или реализация ключа) подписывать. Не проверяет, есть ли у ключа закрытая часть.

функция
(открытый-ключ-умеет-шифровать? ключ) → булево?
ключ : любой

Умеет ли реализация шифровать открытым ключом (типично RSA).

функция
(открытый-ключ-умеет-согласовывать? ключ) → булево?
ключ : любой

Умеет ли реализация согласование секрета (DH, ECDH, X25519).

функция
(открытый-ключ-с-параметрами? ключ) → булево?
ключ : любой

Истина, если у системы есть разделяемые параметры (кривая, модуль DSA/DH и т.п.).

функция
(открытый-ключ? значение) → булево?
значение : любой

Истина для ключа с открытой частью (в том числе для закрытого ключа: он тоже содержит открытую компоненту).

функция
(закрытый-ключ? значение) → булево?
значение : любой

Истина, если есть закрытая компонента.

функция
(только-открытый-ключ? значение) → булево?
значение : любой

Истина для ключа без закрытой части ((и (открытый-ключ? значение) (не (закрытый-ключ? значение)))).

функция
(параметры-открытого-ключа? значение) → булево?
значение : любой

Истина для объекта параметров системы (кривая EC, параметры DSA и т.д.).

функция
(открытый-ключ->параметры ключ) → (один-из любой ложь)
ключ : открытый-ключ?

Параметры ключа или ложь, если система без параметров (RSA).

функция
(стойкость-открытого-ключа ключ)
→ (один-из целое-неотрицательное? ложь)
ключ : любой

Оценка стойкости ключа или параметров в битах, либо ложь.

функция
(открытые-ключи=? ключ1 ключ2 ...) → булево?
ключ1 : открытый-ключ?
ключ2 : открытый-ключ?

Истина, если открытые компоненты всех аргументов совпадают (удобно сверить закрытый ключ с чужим открытым).

функция
(открытый-ключ->только-открытый ключ) → только-открытый-ключ?
ключ : открытый-ключ?

Ключ только с открытой частью; если ключ уже такой, может вернуться он же.

функция
(создать-параметры-открытого-ключа спецификация
[ конфигурация])
→ параметры-открытого-ключа?
спецификация : любой
конфигурация : список? = пустой-список

Генерирует параметры. Для EC/EdDSA/ecx в конфигурация нужна кривая, например '((curve secp256r1)) или '((curve ed25519)).

функция
(создать-закрытый-ключ спецификация
[ конфигурация]) → закрытый-ключ?
спецификация : любой
конфигурация : список? = пустой-список

Генерирует закрытый ключ. Для RSA типично '((nbits 2048)). Если спецификация — уже параметры, конфигурация должна быть пустой.

функция
(подписать-открытым-ключом ключ
сообщение
[ #:дополнение дополнение
#:отпечаток отпечаток]) → байты?
  ключ : закрытый-ключ?
  сообщение : байты?
  дополнение : любой = ложь
  отпечаток : любой = ложь

Подпись сообщение. Для RSA дополнение — 'pkcs1-v1.5, 'pss, 'pss* или ложь; отпечаток — алгоритм, которым считался дайджест в сообщение. Для EdDSA сообщение любой длины, отпечаток — ложь или 'none.

функция
(проверить-открытым-ключом ключ
сообщение
подпись
[ #:отпечаток отпечаток
#:дополнение дополнение]) → булево?
  ключ : открытый-ключ?
  сообщение : байты?
  подпись : байты?
  отпечаток : любой = ложь
  дополнение : любой = ложь

Проверяет подпись для сообщение. Параметры дополнения и отпечатка — как у подписать-открытым-ключом.

функция
(отпечаток/подписать ключ
спецификация-отпечатка
вход
[ #:дополнение дополнение]) → байты?
  ключ : закрытый-ключ?
  спецификация-отпечатка : любой
  вход : любой
  дополнение : любой = ложь

Считает отпечаток вход и подписывает его. Не использовать с EdDSA — там подписывайте сообщение напрямую подписать-открытым-ключом.

функция
(отпечаток/проверить ключ
спецификация-отпечатка
вход
подпись
[ #:дополнение дополнение]) → булево?
  ключ : открытый-ключ?
  спецификация-отпечатка : любой
  вход : любой
  подпись : байты?
  дополнение : любой = ложь

Проверка подписи отпечатка вход.

функция
(подписать-отпечаток-открытым-ключом ключ
спецификация-отпечатка
отпечаток-байты
[ #:дополнение дополнение])
→ байты?
  ключ : закрытый-ключ?
  спецификация-отпечатка : любой
  отпечаток-байты : байты?
  дополнение : любой = ложь

Подпись уже посчитанного отпечатка отпечаток-байты (эквивалент подписать-открытым-ключом с #:отпечаток).

функция
(проверить-отпечаток-открытым-ключом ключ
спецификация-отпечатка
отпечаток-байты
подпись
[ #:дополнение дополнение])
→ булево?
  ключ : открытый-ключ?
  спецификация-отпечатка : любой
  отпечаток-байты : байты?
  подпись : байты?
  дополнение : любой = ложь

Проверка подписи готового отпечатка.

функция
(зашифровать-открытым-ключом ключ
сообщение
[ #:дополнение дополнение]) → байты?
  ключ : открытый-ключ?
  сообщение : байты?
  дополнение : любой = ложь

Шифрование коротким сообщением на открытом ключе (RSA). дополнение — 'pkcs1-v1.5, 'oaep или ложь. Слишком длинное сообщение вызывает исключение.

функция
(расшифровать-открытым-ключом ключ
сообщение
[ #:дополнение дополнение]) → байты?
  ключ : закрытый-ключ?
  сообщение : байты?
  дополнение : любой = ложь

Расшифрование закрытым ключом.

функция
(вывести-секрет-открытым-ключом ключ
ключ-собеседника) → байты?
ключ : закрытый-ключ?
ключ-собеседника : (один-из открытый-ключ? байты?)

Общий секрет согласования (DH/ECDH/X25519) из своего закрытого и чужого открытого ключа (или сырых байтов открытого ключа). Секрет детерминирован и неравномерен — дальше обычно вывод-ключа.

функция
(открытый-ключ->данные ключ формат) → любой
ключ : открытый-ключ?
формат : символ?

Сериализация ключа. Форматы включают 'SubjectPublicKeyInfo, 'PrivateKeyInfo, 'RSAPrivateKey, 'rkt-private, 'rkt-public, 'openssh-public, 'age/v1-public, 'age/v1-private и др.

функция
(данные->открытый-ключ данные
формат
[ источники]) → открытый-ключ?
  данные : любой
  формат : символ?
  источники : любой = (фабрики-криптографических-библиотек)

Разбор данные в ключевом формате формат с реализацией из источники.

функция
(параметры-открытого-ключа->данные параметры
формат) → любой
параметры : параметры-открытого-ключа?
формат : символ?

Сериализация параметров ('AlgorithmIdentifier, 'rkt-params и др.).

функция
(данные->параметры-открытого-ключа данные
формат
[ источники])
→ параметры-открытого-ключа?
  данные : любой
  формат : символ?
  источники : любой = (фабрики-криптографических-библиотек)

Разбор параметров из данные.

функция
(зашифровать-pkcs8/pbkdf2-hmac пароль
ключ
[ #:отпечаток отпечаток
#:итерации итерации
#:шифр шифр
#:размер-ключа размер-ключа])
→ байты?
  пароль : байты?
  ключ : (один-из закрытый-ключ? байты?)
  отпечаток : любой = 'sha512
  итерации : целое-положительное? = 65536
  шифр : любой = '(aes cbc)
   размер-ключа : целое-положительное?
= (размер-ключа-шифра шифр)

Кодирует закрытый ключ как EncryptedPrivateKeyInfo (PKCS #8): ключ шифрования выводится из пароль через PBKDF2-HMAC с отпечаток и итерации, затем шифруется шифр. Если ключ — объект ключа, сначала кодируется как OneAsymmetricKey.

функция
(зашифровать-pkcs8/scrypt пароль
ключ
[ #:N N
#:r r
#:p p
#:шифр шифр
#:размер-ключа размер-ключа]) → байты?
  пароль : байты?
  ключ : (один-из закрытый-ключ? байты?)
  N : целое-положительное? = 16384
  r : целое-положительное? = 8
  p : целое-положительное? = 1
  шифр : любой = '(aes cbc)
   размер-ключа : целое-положительное?
= (размер-ключа-шифра шифр)

Как зашифровать-pkcs8/pbkdf2-hmac, но вывод ключа — scrypt с параметрами N, r, p.

функция
(расшифровать-pkcs8-байты пароль данные) → байты?
пароль : байты?
данные : байты?

Расшифровывает EncryptedPrivateKeyInfo и возвращает сырые байты ключа (структура не проверяется). Неверный пароль часто даёт исключение; для не-AEAD шифров возможен «успех» с мусором.

функция
(расшифровать-pkcs8-ключ пароль данные) → закрытый-ключ?
пароль : байты?
данные : байты?

Как расшифровать-pkcs8-байты, затем разбор как OneAsymmetricKey в объект ключа.

4.31.5 Вывод ключа и пароли🔗ℹ

функция
(спецификация-вывода-ключа? значение) → булево?
значение : любой

Истина для спецификации KDF: 'scrypt, 'argon2id, '(pbkdf2 hmac sha256), '(hkdf sha256) и др.

функция
(реализация-вывода-ключа? значение) → булево?
значение : любой

Истина для реализации KDF из фабрики.

функция
(получить-вывод-ключа спецификация [фабрики])
→ (один-из любой ложь)
спецификация : любой
фабрики : любой = (фабрики-криптографических-библиотек)

Реализация KDF или ложь.

функция
(вывод-ключа спецификация
вход
соль
[ параметры
#:размер-ключа размер-ключа]) → байты?
  спецификация : любой
  вход : байты?
  соль : (один-из байты? ложь)
  параметры : список? = пустой-список
   размер-ключа :
(один-из целое-неотрицательное?
ложь)
= ложь

Выводит ключ (или хэш пароля) длины размер-ключа из вход и соль. Дополнительные параметры — в параметры, например '((iterations 100000)) для PBKDF2, '((N 16384) (r 8) (p 1)) для scrypt, '((m 4096) (t 10) (p 1)) для Argon2. Если размер-ключа — ложь, размер задают в параметры ключом 'key-size.

функция
(хэш-пароля спецификация
пароль
конфигурация) → строка?
  спецификация : любой
  пароль : байты?
  конфигурация : список?

Строка для хранения пароля (Modular Crypt / PHC): алгоритм, параметры из конфигурация, случайная соль и 32 байта выхода. Для scrypt в конфигурации нужен 'ln (логарифм N по основанию 2), а не 'N.

функция
(проверить-хэш-пароля реализация пароль хэш) → булево?
  реализация : (один-из любой ложь)
  пароль : байты?
  хэш : строка?

Сверяет пароль со строкой хэш. Если реализация — ложь, алгоритм берут из строки и ищут среди фабрики-криптографических-библиотек.

функция
(ключ-pbkdf2-hmac спецификация
пароль
соль
#:итерации итерации
[ #:размер-ключа размер-ключа]) → байты?
  спецификация : любой
  пароль : байты?
  соль : байты?
  итерации : целое-положительное?
   размер-ключа : целое-положительное?
= (размер-отпечатка спецификация)

PBKDF2-HMAC с отпечатком спецификация (например 'sha256). итерации задаёт объём работы; размер-ключа — длина результата в байтах.

функция
(ключ-scrypt пароль
соль
#:N N
[ #:p p
#:r r
#:размер-ключа размер-ключа]) → байты?
  пароль : байты?
  соль : байты?
  N : целое-положительное?
  p : целое-положительное? = 1
  r : целое-положительное? = 8
  размер-ключа : целое-положительное? = 32

Выводит ключ длины размер-ключа функцией scrypt. N — цена по CPU и памяти (обычно степень двойки); r — размер блока; p — степень параллелизма.

4.31.6 Утилиты🔗ℹ

контракт
вход-криптографии/с : любой

Контракт входа для отпечаток, зашифровать и др.: байты, строка (UTF-8), порт ввода (читается до EOF, не закрывается), срез байтов или список таких значений (конкатенация).

значение
диапазон-байтов : любой

Конструктор/тип среза байтов (алиас bytes-range / slice в пакете crypto).

функция
(случайные-байты-криптографии число) → байты?
число : целое-неотрицательное?

число криптографически стойких случайных байт (реэкспорт crypto-random-bytes из racket/random).

контракт
стойкость/с : любой

Контракт оценки стойкости в битах (неотрицательное целое).

контракт
уровень-стойкости/с : любой

Контракт уровня стойкости OpenSSL: целое от 0 до 5.

функция
(уровень-стойкости->стойкость уровень) → стойкость/с
уровень : уровень-стойкости/с

Нижняя граница диапазона бит для уровня уровень.

функция
(стойкость->уровень-стойкости стойкость) → уровень-стойкости/с
стойкость : стойкость/с

Уровень, в чей диапазон попадает стойкость.

4.32 База данных🔗ℹ

Модуль база-данных — запросы, транзакции, типы значений и пул подключений. Модуль база-данных-mysql добавляет подключение к MySQL и перепредоставляет общий модуль, поэтому достаточно:

используется база-данных-mysql
подключение = подключить
  #:пользователь «app»
  #:база «app»
  #:пароль «secret»
строки = строки-запроса подключение «select id, name from t where id = ?» 42
отключить подключение

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

В тексте запроса MySQL плейсхолдер параметра — ?.

4.32.1 база-данных-mysql🔗ℹ

функция
(подключить #:пользователь пользователь
[ #:база база
#:сервер сервер
#:порт порт
#:сокет сокет
#:пароль пароль
#:открытый-пароль? открытый-пароль?
#:шифрование шифрование
#:контекст-шифрования контекст-шифрования
#:обработчик-уведомлений обработчик-уведомлений])
→ подключение?
  пользователь : строка?
  база : (один-из строка? ложь) = ложь
  сервер : строка? = "localhost"
  порт : целое-неотрицательное? = 3306
   сокет :
(один-из строка? путь? 'угадать
ложь)
= ложь
  пароль : (один-из строка? ложь) = ложь
  открытый-пароль? : любой = 'местно
  шифрование : любой = 'нет
  контекст-шифрования : любой = ложь
  обработчик-уведомлений : любой = пусто

Подключается к серверу MySQL. Если база — ложь, текущую базу задают позже командой SQL USE. сокет — путь к локальному сокету; символ 'угадать выбирает обычный путь. Нельзя одновременно задать сокет и сервер/порт.

шифрование: 'нет, 'да или 'необязательно. открытый-пароль? — 'местно, истина или ложь. Если контекст-шифрования — ложь, контекст создаётся при необходимости. Если обработчик-уведомлений — пусто, используется поведение по умолчанию. Модуль база-данных-mysql.

функция
(угадать-путь-сокета) → (один-из строка? путь?)

Возвращает первый существующий обычный путь сокета MySQL. Если ни один не найден, вызывается исключение.

4.32.2 база-данных🔗ℹ

функция
(подключение? значение) → булево?
значение : любой

Истина, если значение — подключение к базе данных.

функция
(отключить подключение) → пусто?
подключение : подключение?

Закрывает подключение.

функция
(подключено? подключение) → булево?
подключение : подключение?

Истина, если подключение ещё открыто.

функция
(система-бд подключение) → система-бд?
подключение : подключение?

Объект системы базы данных этого подключения.

функция
(система-бд? значение) → булево?
значение : любой

Истина, если значение — объект системы базы данных.

функция
(имя-системы-бд система) → символ?
система : система-бд?

Символ системы, для MySQL — 'mysql.

функция
(типы-системы-бд система) → (список-из символ?)
система : система-бд?

Список известных типов этой системы.

функция
(устойчивое-подключение подключение) → подключение?
подключение : подключение?

Прокси, при котором убийство потока во время запроса не портит подключение.

функция
(выполнить-запрос подключение
запрос
аргумент ...) → пусто?
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Выполняет SQL ради эффекта (вставка, обновление, удаление).

функция
(строки-запроса подключение
запрос
аргумент ...
[ #:группировка группировка
#:режим-группировки режим-группировки])
→ (список-из массив?)
  подключение : подключение?
  запрос : запрос?
  аргумент : любой
  группировка : любой = пустой-список
  режим-группировки : список? = пустой-список

Возвращает список строк (массивов). режим-группировки — список символов 'список и 'сохранить-нуль.

функция
(список-запроса подключение
запрос
аргумент ...) → список?
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Запрос из одного столбца: список значений.

функция
(строка-запроса подключение
запрос
аргумент ...) → массив?
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Ровно одна строка результата.

функция
(возможная-строка-запроса подключение
запрос
аргумент ...)
→ (один-из массив? ложь)
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Как строка-запроса, но ноль строк дают ложь.

функция
(значение-запроса подключение
запрос
аргумент ...) → любой
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Ровно одна строка и один столбец: само значение.

функция
(возможное-значение-запроса подключение
запрос
аргумент ...) → любой
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Как значение-запроса, но ноль строк дают ложь.

функция
(запрос подключение запрос аргумент ...)
→ (один-из простой-результат? результат-строк?)
  подключение : подключение?
  запрос : запрос?
  аргумент : любой

Общий запрос: либо эффект, либо строки с заголовками.

функция
(в-запросе подключение
запрос
аргумент ...
#:пачка пачка
[ #:группировка группировка
#:режим-группировки режим-группировки])
→ последовательность?
  подключение : подключение?
  запрос : запрос?
  аргумент : любой
  пачка : любой
  группировка : любой = пустой-список
  режим-группировки : список? = пустой-список

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

функция
(запрос? значение) → булево?
значение : любой

Истина, если значение можно выполнить как запрос (строка SQL, подготовленный или виртуальный запрос).

функция
(простой-результат сведения) → простой-результат?
сведения : список?

Результат команды без строк. В сведения бывают ключи 'insert-id и 'affected-rows.

функция
(простой-результат? значение) → булево?
значение : любой

Истина, если значение — простой результат.

функция
(сведения-простого-результата значение) → список?
значение : простой-результат?

Ассоциативный список сведений.

функция
(результат-строк заголовки строки) → результат-строк?
заголовки : список?
строки : (список-из массив?)

Результат выборки: заголовки столбцов и строки.

функция
(результат-строк? значение) → булево?
значение : любой

Истина, если значение — результат со строками.

функция
(заголовки-результата-строк значение) → список?
значение : результат-строк?

Заголовки столбцов.

функция
(строки-результата-строк значение) → (список-из массив?)
значение : результат-строк?

Строки результата.

функция
(сгруппировать-строки результат
#:группировка группировка
[ #:режим-группировки режим-группировки])
→ результат-строк?
  результат : результат-строк?
  группировка : любой
  режим-группировки : список? = пустой-список

Группирует строки результата по полям группировка.

функция
(строки->соответствие результат
#:ключ ключ
#:значение значение
[ #:режим-значения режим-значения])
→ соответствие?
  результат : результат-строк?
  ключ : любой
  значение : любой
  режим-значения : список? = пустой-список

Строит соответствие из строк: ключ и значение — имена или номера полей.

функция
(подготовить подключение запрос) → подготовленный-запрос?
подключение : подключение?
запрос : (один-из строка? виртуальный-запрос?)

Готовит запрос на стороне сервера. Результат привязан к этому подключению.

функция
(подготовленный-запрос? значение) → булево?
значение : любой

Истина, если значение получено из подготовить.

функция
(типы-параметров-подготовленного-запроса запрос) → список?
запрос : подготовленный-запрос?

Описание типов параметров.

функция
(типы-результата-подготовленного-запроса запрос) → список?
запрос : подготовленный-запрос?

Описание типов столбцов результата.

функция
(связать-подготовленный-запрос запрос
параметры) → связанный-запрос?
запрос : подготовленный-запрос?
параметры : список?

Связывает параметры; дальше передаётся в функции запроса.

функция
(связанный-запрос? значение) → булево?
значение : любой

Истина, если значение — связанный подготовленный запрос.

функция
(виртуальный-запрос описание) → виртуальный-запрос?
описание : (один-из строка? функция?)

Запрос, который готовится для каждого подключения при первом исполнении. описание — SQL или функция от системы БД.

функция
(виртуальный-запрос? значение) → булево?
значение : любой

Истина, если значение создано виртуальный-запрос.

функция
(начать-транзакцию подключение
[ #:изоляция изоляция
#:параметр параметр]) → пусто?
  подключение : подключение?
  изоляция : любой = ложь
  параметр : любой = ложь

Начинает транзакцию. изоляция: 'сериализуемая, 'повторяемое-чтение, 'чтение-подтверждённое, 'чтение-неподтверждённое или ложь. У MySQL параметр не используется.

функция
(зафиксировать-транзакцию подключение) → пусто?
подключение : подключение?

Фиксирует текущую транзакцию, если она открыта.

функция
(откатить-транзакцию подключение) → пусто?
подключение : подключение?

Откатывает текущую транзакцию, если она открыта.

функция
(в-транзакции? подключение) → булево?
подключение : подключение?

Истина, если на подключении открыта транзакция.

функция
(нужен-откат? подключение) → булево?
подключение : подключение?

Истина, если транзакция испорчена и её нужно откатить.

функция
(вызывая-транзакцию подключение
обработка
[ #:изоляция изоляция
#:параметр параметр]) → любой
  подключение : подключение?
  обработка : функция?
  изоляция : любой = ложь
  параметр : любой = ложь

Вызывает обработка в транзакции. При нормальном завершении фиксирует, при исключении откатывает.

функция
(список-таблиц подключение [#:схема схема]) → (список-из строка?)
подключение : подключение?
схема : любой = 'поиск-или-текущая

Имена таблиц и представлений. схема: 'поиск, 'текущая или 'поиск-или-текущая.

функция
(существует-таблица? подключение
имя
[ #:схема схема
#:учитывать-регистр? учитывать-регистр?])
→ булево?
  подключение : подключение?
  имя : строка?
  схема : любой = 'поиск-или-текущая
  учитывать-регистр? : любой = ложь

Истина, если таблица или представление имя существует.

функция
(пул-подключений
создать
#:наибольше-подключений наибольше-подключений
[ #:наибольше-простоя наибольше-простоя
#:секунды-простоя секунды-простоя])
→ пул-подключений?
  создать : функция?
  наибольше-подключений : любой
  наибольше-простоя : любой = 10
  секунды-простоя : вещественное? = 300

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

функция
(пул-подключений? значение) → булево?
значение : любой

Истина, если значение — пул подключений.

функция
(взять-из-пула пул
освобождение
[ #:таймаут таймаут]
#:если-нет если-нет) → подключение?
  пул : пул-подключений?
  освобождение : любой
  таймаут : (один-из вещественное? ложь) = ложь
  если-нет : любой

Берёт подключение из пула. По умолчанию освобождение — текущий поток: при его завершении подключение возвращается. отключить тоже возвращает его в пул.

функция
(виртуальное-подключение создать) → подключение?
создать : любой

Подключение по требованию: создать — функция без аргументов или пул.

константа
нуль : любой

Значение SQL NULL. Это не пусто.

функция
(нуль? значение) → булево?
значение : любой

Истина, если значение — нуль.

функция
(нуль->ложь значение) → любой
значение : любой

Если значение — нуль, результат ложь, иначе само значение.

функция
(ложь->нуль значение) → любой
значение : любой

Если значение — ложь, результат нуль, иначе само значение.

функция
(дата год месяц день) → дата?
  год : целое?
  месяц : целое?
  день : целое?

Дата SQL (год, месяц, день). Селекторы год, месяц, день. Для MySQL месяц или день могут быть нулём.

функция
(дата? значение) → булево?
значение : любой

Истина, если значение — дата SQL.

функция
(время час минута секунда наносекунда зона) → время?
  час : целое?
  минута : целое?
  секунда : целое?
  наносекунда : целое?
  зона : (один-из целое? ложь)

Время SQL. Селекторы час, минута, секунда, наносекунда, зона (смещение в секундах к востоку от GMT или ложь).

функция
(время? значение) → булево?
значение : любой

Истина, если значение — время SQL.

функция
(метка-времени год
месяц
день
час
минута
секунда
наносекунда
зона) → метка-времени?
  год : целое?
  месяц : целое?
  день : целое?
  час : целое?
  минута : целое?
  секунда : целое?
  наносекунда : целое?
  зона : (один-из целое? ложь)

Метка времени SQL. Селекторы год-метки-времени, месяц-метки-времени, день-метки-времени, час-метки-времени, минута-метки-времени, секунда-метки-времени, наносекунда-метки-времени, зона-метки-времени.

функция
(метка-времени? значение) → булево?
значение : любой

Истина, если значение — метка времени SQL.

функция
(интервал годы
месяцы
дни
часы
минуты
секунды
наносекунды) → интервал?
  годы : целое?
  месяцы : целое?
  дни : целое?
  часы : целое?
  минуты : целое?
  секунды : целое?
  наносекунды : целое?

Интервал SQL. Селекторы годы, месяцы, дни, часы, минуты, секунды, наносекунды.

функция
(интервал? значение) → булево?
значение : любой

Истина, если значение — интервал SQL.

функция
(интервал-год-месяц? значение) → булево?
значение : любой

Истина, если интервал задаёт только годы и месяцы.

функция
(интервал-день-время? значение) → булево?
значение : любой

Истина, если интервал задаёт только дни и время суток.

функция
(интервал->время интервал) → время?
интервал : интервал?

Переводит интервал «время суток» во время.

функция
(время->интервал время) → интервал?
время : время?

Переводит время в интервал.

функция
(дата-из-базы-данных значение) → дата%
значение : дата?

Дата SQL в дата% (время 00:00:00).

функция
(дата-в-базу-данных значение) → дата?
значение : дата%

дата% в дату SQL (только год, месяц, день).

функция
(метка-времени-из-базы-данных значение) → дата%
значение : метка-времени?

Метка времени SQL в дата%. Если зона не ложь, она становится временной зоной.

функция
(метка-времени-в-базу-данных значение) → метка-времени?
значение : дата%

дата% в метку времени SQL.

функция
(ошибка-базы-данных? значение) → булево?
значение : любой

Истина, если значение — ошибка сервера базы данных.

функция
(состояние-ошибки-базы-данных значение)
→ (один-из строка? символ?)
значение : ошибка-базы-данных?

Код SQLSTATE.

функция
(сведения-ошибки-базы-данных значение) → список?
значение : ошибка-базы-данных?

Ассоциативный список сведений об ошибке. Сообщения сервера не переводятся.

Числа, строки и байты приходят как обычные значения Адины. SQL NULL — нуль. Типы MySQL enum и set нужно приводить к строке или числу в самом SQL.

4.33 Сервер гипертекста🔗ℹ

Модуль сервер-гипертекста/сервер.

функция
(управляющий-ограничением-времени [ обработчик-истечения
секунды-экземпляра
секунды-продолжения]) → любой
  обработчик-истечения : (один-из функция? ложь) = ложь
  секунды-экземпляра : число? = 7200
  секунды-продолжения : число? = 7200

Создаёт управляющего продолжениями сервлета с ограничением времени. секунды-экземпляра — время жизни экземпляра сервлета, секунды-продолжения — время жизни отдельного продолжения. По истечении вызывается обработчик-истечения (функция от запроса, возвращающая ответ) или, если он ложь, стандартная ошибка. Модуль сервер-гипертекста/сервер.

функция
(сервер/единственный
обработчик
[ #:командная-строка? командная-строка?
#:закрывать-соединение? закрывать-соединение?
#:открывать-браузер? открывать-браузер?
#:выход? выход?
#:выводить-сведения? выводить-сведения?
#:слушать-адрес слушать-адрес
#:порт порт
#:наибольшая-очередь наибольшая-очередь
#:пределы-безопасности пределы-безопасности
#:время-жизни-страницы время-жизни-страницы
#:управляющий управляющий
#:путь-сервлета путь-сервлета
#:регулярное-сервлета регулярное-сервлета
#:без-состояния? без-состояния?
#:упаковщик упаковщик
#:пространство-имён-сервлета пространство-имён-сервлета
#:корень-сервера корень-сервера
#:дополнительные-файлы дополнительные-файлы
#:корень-сервлетов корень-сервлетов
#:текущий-каталог-сервлета текущий-каталог-сервлета
#:ответ-файл-не-найден ответ-файл-не-найден
#:ответ-загрузки-сервлета ответ-загрузки-сервлета
#:ответ-ошибки-сервлета ответ-ошибки-сервлета
#:путь-типов-содержимого путь-типов-содержимого
#:защищённый? защищённый?
#:сертификат сертификат
#:ключ ключ
#:журнал журнал
#:формат-журнала формат-журнала])
→ любой
  обработчик : функция?
  командная-строка? : любой = ложь
  закрывать-соединение? : любой = ложь
  открывать-браузер? : любой = (не командная-строка?)
  выход? : любой = (не командная-строка?)
  выводить-сведения? : любой = (не командная-строка?)
  слушать-адрес : (один-из строка? ложь) = «127.0.0.1»
  порт : целое-неотрицательное? = 8000
  наибольшая-очередь : целое-неотрицательное? = 511
  пределы-безопасности : любой = ....
  время-жизни-страницы : (один-из число? ложь) = ложь
  управляющий : любой = ....
  путь-сервлета : строка? = «/servlets/standalone.rkt»
  регулярное-сервлета : любой = ....
  без-состояния? : любой = ложь
  упаковщик : любой = ....
  пространство-имён-сервлета : список? = пустой-список
  корень-сервера : любой = ....
   дополнительные-файлы : список?
= (список (построить-путь корень-сервера «htdocs»))
   корень-сервлетов : любой
= (построить-путь корень-сервера «htdocs»)
  текущий-каталог-сервлета : любой = корень-сервлетов
  ответ-файл-не-найден : функция? = ....
  ответ-загрузки-сервлета : функция? = ....
  ответ-ошибки-сервлета : функция? = ....
  путь-типов-содержимого : любой = ....
  защищённый? : любой = ложь
   сертификат : (один-из путь? ложь)
=
(&& защищённый?
    (построить-путь корень-сервера «server-cert.pem»))
   ключ : (один-из путь? ложь)
=
(&& защищённый?
    (построить-путь корень-сервера «private-key.pem»))
   журнал :
(один-из строка? путь? порт-вывода?
ложь)
= ложь
  формат-журнала : любой = 'апач-умолчание

Запускает сервер с одним обработчиком запросов. обработчик получает запрос и возвращает ответ. Не возвращает управление, пока сервер не остановлен.

Если командная-строка? — истина, то по умолчанию браузер не открывается, адрес остановки не добавляется и сведения о запуске не выводятся.

слушать-адрес — адрес, на котором слушать; по умолчанию только местный. ложь — все интерфейсы. порт по умолчанию 8000.

Если открывать-браузер? — истина, открывает путь-сервлета в браузере. Если выход? — истина, адрес «/quit» останавливает сервер. Если выводить-сведения? — истина, выводит адрес сервера.

регулярное-сервлета по умолчанию — точное совпадение с путь-сервлета. пределы-безопасности учитывают наибольшая-очередь. Если время-жизни-страницы — число, управляющий по умолчанию — управляющий-ограничением-времени с этим временем (секунды) для экземпляра и продолжений; если ложь — управляющий с порогом памяти 128~МБ. корень-сервера — каталог корня сервера по умолчанию; от него считаются дополнительные-файлы, корень-сервлетов и ответы об ошибках. путь-типов-содержимого — файл "mime.types" в корне или в пакете сервера.

защищённый? включает шифрование соединения; тогда сертификат и ключ — пути к файлам, либо умолчание из корень-сервера.

журнал — файл или порт журнала; ложь — не вести журнал. формат-журнала — 'апач-умолчание, 'скобочное-умолчание, 'расширенный, 'совмещённый или своя функция.

Модуль сервер-гипертекста/сервер.

функция
(ответ код
сообщение
секунды
тип-содержимого
заголовки
вывод) → любой
  код : целое-неотрицательное?
  сообщение : байты?
  секунды : число?
  тип-содержимого : (один-из байты? ложь)
  заголовки : список?
  вывод : (порт-вывода? . -> . любой)

Собирает ответ: код (от 100 до 999), краткое сообщение в байтах, время секунды, тип-содержимого (байты или ложь), заголовки и вывод — функция, которая пишет тело в порт. Модуль сервер-гипертекста/обработчик.

функция
(данные-запроса-отправки/необработанные запрос)
→ (один-из байты? ложь)
запрос : любой

Необработанные данные тела отправки запроса или ложь. Модуль сервер-гипертекста/обработчик.

функция
(отправить/приостановить/маршрутизировать генератор) → любой
генератор : функция?

Вызывает генератор с функцией, которая по обработчику запроса строит адрес. Отправляет полученный ответ; при обращении по адресу вызывается этот обработчик, а его результат возвращается из отправить/приостановить/маршрутизировать. Модуль сервер-гипертекста/обработчик.

функция
(ответ/выражение-разметки выражение-разметки
[ #:код код
#:сообщение сообщение
#:секунды секунды]
#:тип-содержимого тип-содержимого
[ #:куки куки
#:заголовки заголовки
#:преамбула преамбула])
→ любой
  выражение-разметки : любой
  код : целое-неотрицательное? = 200
  сообщение : (один-из байты? ложь) = ложь
  секунды : число? = (сейчас)
  тип-содержимого : (один-из байты? ложь)
  куки : список? = пустой-список
  заголовки : список? = пустой-список
  преамбула : байты? = (новые-байты 0)

Ответ из выражения разметки. По умолчанию код 200, время — сейчас, тип содержимого — гипертекст. Модуль сервер-гипертекста/обработчик.

функция
(пустой-запрос [#:заголовки заголовки]) → любой
заголовки : список? = пустой-список

Перенаправляет браузер на адрес продолжения методом получения и возвращает следующий запрос. Модуль сервер-гипертекста/обработчик.

функция
(параметры-запроса запрос) → список?
запрос : любой

Список пар имя–значение из полей запроса. Имя — символ. Модуль сервер-гипертекста/обработчик.

функция
(извлечь-параметр/единственный имя
параметры) → любой
имя : символ?
параметры : список?

Значение единственного параметра с имя в параметры. Если такого нет или их несколько, вызывается исключение. Модуль сервер-гипертекста/обработчик.

функция
(параметры-запроса/необработанные запрос) → список?
запрос : любой

Список необработанных параметров запроса. Модуль сервер-гипертекста/обработчик.

функция
(параметр-файла? значение) → булево?
значение : любой

Истина, если значение — загруженный файл из полей запроса. Модуль сервер-гипертекста/обработчик.

функция
(параметр-файла идентификатор
имя-файла
заголовки
содержимое) → любой
  идентификатор : байты?
  имя-файла : байты?
  заголовки : список?
  содержимое : байты?

Собирает параметр загруженного файла: идентификатор — имя поля формы, имя-файла — имя файла, заголовки — список заголовков MIME-конверта, содержимое — байты файла. Модуль сервер-гипертекста/обработчик.

функция
(идентификатор-параметра-файла параметр) → байты?
параметр : любой

Имя поля формы у загруженного файла. Модуль сервер-гипертекста/обработчик.

функция
(имя-файла-параметра параметр) → байты?
параметр : любой

Имя загруженного файла. Модуль сервер-гипертекста/обработчик.

функция
(заголовки-параметра-файла параметр) → список?
параметр : любой

Заголовки MIME-конверта загруженного файла. Модуль сервер-гипертекста/обработчик.

функция
(содержимое-параметра-файла параметр) → байты?
параметр : любой

Байты загруженного файла. Если параметр создан через параметр-файла/порт, первое обращение читает оставшееся содержимое порта, запоминает его и закрывает порт. Модуль сервер-гипертекста/обработчик.

функция
(параметр-файла/порт? значение) → булево?
значение : любой

Истина, если значение — загруженный файл с содержимым в порте ввода. Модуль сервер-гипертекста/обработчик.

функция
(порт-параметра-файла параметр) → порт-ввода?
параметр : любой

Порт ввода с содержимым файла. Только для значений, для которых параметр-файла/порт? истинен. Модуль сервер-гипертекста/обработчик.

функция
(параметр-файла/порт идентификатор
имя-файла
заголовки
порт) → любой
  идентификатор : байты?
  имя-файла : байты?
  заголовки : список?
  порт : порт-ввода?

Как параметр-файла, но содержимое задаётся портом ввода, а не байтами. Модуль сервер-гипертекста/обработчик.

4.33.1 сервер-гипертекста/формат-url🔗ℹ

Разбор URL запроса: схема, узел, порт, путь и параметры query. Подключение:

используется
с-префиксом url: сервер-гипертекста/формат-url

функция
(строка->url строка) → любой
строка : строка?

Разбирает URI из строка в структуру URL.

функция
(схема-url url) → (один-из строка? ложь)
url : любой

Схема (http, https и т.п.) или ложь, если не указана.

функция
(узел-url url) → (один-из строка? ложь)
url : любой

Имя узла (хост) или ложь.

функция
(порт-url url) → (один-из целое-неотрицательное? ложь)
url : любой

Номер порта или ложь, если порт не задан явно.

функция
(путь-url url) → список?
url : любой

Список сегментов пути. У каждого сегмента путь читают через путь-сегмента.

функция
(параметры-url url) → список?
url : любой

Список пар query (символ . строка или ложь).

функция
(путь-сегмента сегмент) → любой
сегмент : любой

Строка пути сегмента (или символ 'up / 'same из исходного URL).

функция
(список-пар->кодирование-url список) → строка?
список : список?

Собирает строку application/x-www-form-urlencoded из списка пар (как параметры-url).

4.33.2 сервер-гипертекста/форлеты🔗ℹ

Форлет — кусок HTML-формы вместе с разбором ответа. Форлеты можно вкладывать друг в друга. Подключение: сервер-гипертекста/форлеты.

синтаксис
(форлет шаблон выражение)

Собирает форлет. шаблон — разметка: тег с содержимым, например div. Поле вкладывают через запятую и оператор =>: слева форлет поля, справа — имя результата. выражение вычисляется при разборе отправки и может использовать эти имена.

форлет
  (div «Месяц:» ,(ввод-числа => месяц)
       «День:» ,(ввод-числа => день))
  список месяц день

Оператор => в шаблоне форлета — вложение поля, а не ветка если.

синтаксис
(лес узел ...)

В шаблоне форлета — несколько узлов разметки рядом, без общего тега. Допустимо только внутри форлет и форлет*.

синтаксис
(форлет* шаблон выражение)

Как форлет, но шаблон вычисляется как выражение разметки (квазицитата через `). Поле вкладывают оператором =>*. Имена в выражение привязаны к спискам результатов: один форлет может встретиться несколько раз.

форлет*
`(div ,(ввод-строки =>* имя))
первый имя

оператор
(вложенный =>* результат)

Вложение поля в форлет*. Допустимо только внутри форлет*.

функция
(разметка-форлета форлет) → список?
форлет : любой

Лес узлов разметки для показа форлета. Имена полей в атрибуте name уникальны.

функция
(обработать-форлет форлет запрос) → любой
форлет : любой
запрос : любой

Разбирает поля запрос согласно форлет и возвращает результат выражения форлета.

функция
(отправить/форлет форлет
[ #:метод метод]
#:обернуть обернуть) → любой
  форлет : любой
  метод : любой = 'отправка
  обернуть : функция?

Показывает форлет как страницу и возвращает разобранный результат отправки. метод — 'отправка или 'POST (отправка), 'получение или 'GET (получение). обернуть получает разметку формы и возвращает страницу. По умолчанию заголовок страницы — «Ввод формы».

функция
(встроить-форлет встроить форлет) → любой
встроить : функция?
форлет : любой

Строит разметку формы с адресом продолжения из встроить (как у отправить/приостановить/маршрутизировать).

функция
(создать-ввод нарисовать) → любой
нарисовать : функция?

Низкоуровневое поле: нарисовать получает имя поля (строка) и возвращает узел разметки. Результат разбора — привязка поля или ложь.

функция
(создать-ввод* нарисовать) → любой
нарисовать : функция?

Как создать-ввод, но результат разбора — список всех привязок с этим именем.

функция
(поле-ввода [ #:тип тип
#:значение значение
#:наибольшая-длина наибольшая-длина
#:только-чтение? только-чтение?
#:атрибуты атрибуты]) → любой
  тип : строка? = «text»
  значение : (один-из байты? строка? ложь) = ложь
   наибольшая-длина :
(один-из целое-неотрицательное?
ложь)
= ложь
  только-чтение? : любой = ложь
  атрибуты : список? = пустой-список

Поле input.

функция
(текстовый-ввод [ #:значение значение
#:размер размер
#:наибольшая-длина наибольшая-длина
#:только-чтение? только-чтение?
#:атрибуты атрибуты]) → любой
  значение : (один-из байты? строка? ложь) = ложь
   размер :
(один-из целое-неотрицательное?
ложь)
= ложь
   наибольшая-длина :
(один-из целое-неотрицательное?
ложь)
= ложь
  только-чтение? : любой = ложь
  атрибуты : список? = пустой-список

Текстовое поле ввода.

функция
(ввод-пароля [ #:значение значение
#:размер размер
#:наибольшая-длина наибольшая-длина
#:только-чтение? только-чтение?
#:атрибуты атрибуты]) → любой
  значение : (один-из байты? строка? ложь) = ложь
   размер :
(один-из целое-неотрицательное?
ложь)
= ложь
   наибольшая-длина :
(один-из целое-неотрицательное?
ложь)
= ложь
  только-чтение? : любой = ложь
  атрибуты : список? = пустой-список

Поле ввода пароля.

функция
(многострочный-ввод [ #:атрибуты атрибуты
#:значение значение
#:строки строки
#:столбцы столбцы]) → любой
  атрибуты : список? = пустой-список
  значение : (один-из байты? строка? ложь) = ложь
  строки : (один-из число? ложь) = ложь
  столбцы : (один-из число? ложь) = ложь

Поле textarea.

функция
(флажок-формы значение
отмечен?
[ #:атрибуты атрибуты]) → любой
  значение : (один-из байты? строка?)
  отмечен? : любой
  атрибуты : список? = пустой-список

Флажок формы.

функция
(переключатель значение
отмечен?
[ #:атрибуты атрибуты]) → любой
  значение : (один-из байты? строка?)
  отмечен? : любой
  атрибуты : список? = пустой-список

Кнопка-переключатель.

функция
(группа-переключателей варианты
#:атрибуты атрибуты
#:отмечен? отмечен?
#:представить представить
#:обернуть обернуть) → любой
  варианты : любой
  атрибуты : функция?
  отмечен? : функция?
  представить : функция?
  обернуть : функция?

Группа переключателей по последовательности варианты. Результат — выбранный элемент. атрибуты, отмечен? и представить получают элемент; обернуть — разметку поля и подпись.

функция
(группа-флажков варианты
#:атрибуты атрибуты
#:отмечен? отмечен?
#:представить представить
#:обернуть обернуть) → любой
  варианты : любой
  атрибуты : функция?
  отмечен? : функция?
  представить : функция?
  обернуть : функция?

Группа флажков. Результат — список выбранных элементов.

функция
(кнопка-отправки подпись
[ #:атрибуты атрибуты]) → любой
подпись : (один-из байты? строка?)
атрибуты : список? = пустой-список

Кнопка отправки формы.

функция
(кнопка-сброса подпись [#:атрибуты атрибуты]) → любой
подпись : (один-из байты? строка?)
атрибуты : список? = пустой-список

Кнопка сброса формы.

функция
(загрузка-файла [#:атрибуты атрибуты]) → любой
атрибуты : список? = пустой-список

Поле загрузки файла.

функция
(скрытое-поле значение [#:атрибуты атрибуты]) → любой
значение : (один-из байты? строка?)
атрибуты : список? = пустой-список

Скрытое поле.

функция
(рисунок-формы подпись
источник
[ #:высота высота
#:описание описание
#:карта карта
#:ширина ширина
#:атрибуты атрибуты]) → любой
  подпись : (один-из байты? строка?)
  источник : (один-из байты? строка?)
   высота :
(один-из целое-неотрицательное?
ложь)
= ложь
  описание : (один-из байты? строка? ложь) = ложь
  карта : (один-из байты? строка? ложь) = ложь
   ширина :
(один-из целое-неотрицательное?
ложь)
= ложь
  атрибуты : список? = пустой-список

Рисунок в форме (img): подпись — текст alt, источник — адрес изображения.

функция
(кнопка-формы тип
текст
[ #:отключена? отключена?
#:значение значение
#:атрибуты атрибуты]) → любой
  тип : (один-из байты? строка?)
  текст : (один-из байты? строка?)
  отключена? : любой = ложь
  значение : (один-из байты? строка? ложь) = ложь
  атрибуты : список? = пустой-список

Кнопка button с тип и видимым текст.

функция
(множественный-выбор варианты
[ #:атрибуты атрибуты
#:несколько? несколько?]
#:выбран? выбран?
#:представить представить) → любой
  варианты : любой
  атрибуты : список? = пустой-список
  несколько? : любой = истина
  выбран? : функция?
  представить : функция?

Список выбора. По умолчанию можно отметить несколько пунктов. Результат — список выбранных элементов.

функция
(список-выбора варианты
[ #:атрибуты атрибуты]
#:выбран? выбран?
#:представить представить) → любой
  варианты : любой
  атрибуты : список? = пустой-список
  выбран? : функция?
  представить : функция?

Список выбора одного элемента.

функция
(обязательный форлет) → любой
форлет : любой

Требует, чтобы поле было заполнено; иначе исключение. Результат — байты значения.

функция
(с-умолчанием умолчание форлет) → любой
умолчание : байты?
форлет : любой

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

функция
(в-строку форлет) → любой
форлет : любой

Переводит байты значения поля в строку.

функция
(в-число форлет) → любой
форлет : любой

Переводит строку значения поля в число.

функция
(в-символ форлет) → любой
форлет : любой

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

функция
(в-булево форлет) → любой
форлет : любой

Истина, если байты значения равны on.

форлет
ввод-строки : любой

Обязательное текстовое поле; результат — строка.

форлет
ввод-числа : любой

Обязательное текстовое поле; результат — число.

форлет
ввод-символа : любой

Обязательное текстовое поле; результат — символ.

4.34 Проверки🔗ℹ

Модуль проверки — обёртка RackUnit. Подключается командой используется. Введение — в Проверки.

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

синтаксис
(проверки команда ...)

Помещает команда в подмодуль test. При обычном запуске файла тело не выполняется; при raco test и при запуске в DrRacket (если подмодуль test включён) — выполняется.

функция
(проверить оператор
значение1
значение2
[ сообщение]) → пусто?
  оператор : функция?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что (оператор значение1 значение2) не ложь.

функция
(проверить-равно? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет равенство через ==.

функция
(проверить-не-равно? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что значения не равны через ==.

функция
(проверить-эквивалентно? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет равенство через ===.

функция
(проверить-не-эквивалентно? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что значения не равны через ===.

функция
(проверить-eq? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет тождество указателей (eq? в Racket).

функция
(проверить-не-eq? значение1
значение2
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что значения не тождественны по указателю.

функция
(проверить-истину значение [сообщение]) → пусто?
значение : любой
сообщение : (один-из строка? ложь) = ложь

Проверяет, что значение — именно истина.

функция
(проверить-ложь значение [сообщение]) → пусто?
значение : любой
сообщение : (один-из строка? ложь) = ложь

Проверяет, что значение — ложь.

функция
(проверить-не-ложь значение [сообщение]) → пусто?
значение : любой
сообщение : (один-из строка? ложь) = ложь

Проверяет, что значение не ложь.

функция
(проверить-предикатом предикат
значение
[ сообщение]) → пусто?
  предикат : функция?
  значение : любой
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что (предикат значение) не ложь.

функция
(проверить-= значение1
значение2
эпсилон
[ сообщение]) → пусто?
  значение1 : число?
  значение2 : число?
  эпсилон : число?
  сообщение : (один-из строка? ложь) = ложь

Проверяет, что числа отличаются не больше чем на эпсилон.

функция
(проверить-в-пределах значение1
значение2
эпсилон
[ сообщение]) → пусто?
  значение1 : любой
  значение2 : любой
  эпсилон : число?
  сообщение : (один-из строка? ложь) = ложь

Как проверить-равно?, но числа внутри структур (списков и т.п.) допускают отличие до эпсилон.

функция
(проверить-исключение условие
действие
[ сообщение]) → пусто?
  условие : любой
  действие : функция?
  сообщение : (один-из строка? ложь) = ложь

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

функция
(проверить-без-исключения действие
[ сообщение]) → пусто?
действие : функция?
сообщение : (один-из строка? ложь) = ложь

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

синтаксис
(проверить-шаблон значение шаблон)
(проверить-шаблон значение шаблон условие)

Проверяет, что значение соответствует шаблон (синтаксис шаблонов — как у сопоставить). Если задано условие, оно должно быть истинным при успешном сопоставлении.

синтаксис
(проверка-случая имя команда ...+)

Группирует команды в один именованный случай. имя — строка. При первой неудачной проверке остальные команды случая не выполняются; в отчёте указывается имя.

синтаксис
(начало-проверки команда ...)

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

синтаксис
(набор-проверок имя проверка ...)

проверка = выражение
| (проверка-случая имя команда ...+)
| (начало-проверки команда ...)
| (набор-проверок имя проверка ...)

Создаёт набор проверок с именем имя (строка). В отличие от отдельных проверок и проверка-случая, набор сам по себе не запускается: его передают средству запуска тестов. Внутри могут быть проверки, случаи и вложенные наборы.

4.35 Приоритет операторов🔗ℹ

Чем больше число, тем выше приоритет. Если не указано иное, операторы с одинаковым приоритетом группируются слева направо.

Оператор		Приоритет
*		8
/		8
//		8
%		8
+		7
-		7
++		6
==		5
/=		5
<		5
>		5
<=		5
>=		5
&&		4
\|\|		3
?		2
:		2, группировка справа
==>		1,5
:=		1, группировка справа
=		0

5 Надо быстро🔗ℹ

Семантика кода внутри надо-быстро — из Си++, а не из Адины. Обычные функции Адины и Racket внутри блока недоступны. Функции, определённые в блоке, снаружи становятся обычными FFI-процедурами Racket с теми же именами.

синтаксис
(надо-быстро форма ...)

форма = (используется модуль)
| (предоставлять имя ...)
|
(определение-синтаксического-правила
(имя образец ...) шаблон)
| (определение-синтаксиса ...)
| (си текст)
| заголовок = команда ...

заголовок = имя (аргумент ...) тип-возврата

аргумент = имя-аргумента тип

тип = целое
| вещественное
| логическое

модуль = математика
| ввод-вывод
| строка-имени-файла

Компилирует подмножество синтаксиса Адины в Си++ (через g++) во время раскрытия модуля и связывает получившиеся функции через FFI.

Каждая функция в блоке становится процедурой Racket с тем же именем. Типы аргументов и результата: целое, вещественное, логическое.

используется внутри блока:

символ вроде математика — модуль "1/надо-быстро/математика.1";
строка — файл относительно текущего каталога (как у обычной Адины).

Подключение делает два дела: открывает имена (предоставлять макросов и FFI-функций) и вставляет результат трансляции зависимости в единицу компиляции C++ (как #include).

Имена из используется внутри блока импортируются с префиксом надо-быстро:. При трансляции тела этот префикс добавляется к свободным именам неявно; локальные привязки — без префикса. Пространства Адины и быстрого кода не пересекаются: можно предоставлять вывести рядом с вывести из Адины.

Типовые формы (вернуть, вывести, не) — макросы "1/надо-быстро.1" (подключается автоматически), раскрываются в си и обычные выражения. вернуть принимает один аргумент; вывести — несколько, для каждого отдельный std::cout << …; (как pr в L++). Также: локальные привязки через =, арифметика и сравнения.

Конструкция си с текстом в фигурных скобках читается как (си "текст") и вставляет текст буквально в генерируемый Си++. Можно чередовать с выражениями: фрагменты си склеиваются с именами в одну строку C++.

Нужен компилятор g++ в PATH. Несколько блоков надо-быстро в одном модуле накапливают код в общую библиотеку. Shared-библиотека пишется рядом с модулем в "compiled/native/<платформа>/" и подключается через define-runtime-path (абсолютный путь к файлу), чтобы raco exe / raco distribute включали её в поставку.

#!1
надо-быстро
ответ() целое =
вернуть 42

вывести/перенос формат("~a" ответ())

#!1
надо-быстро
  используется математика
  син() вещественное =
    вернуть си{sin(21)}

#!1
надо-быстро
  предоставлять сумма
  определение-синтаксического-правила (сумма а б)
    а + б

1	Основы языка
2	Встроенные типы данных
3	Графический интерфейс
4	Справочник
5	Надо быстро