В этом документе вы найдёте описание множества подпрограмм. Некоторые из них встроены непосредственно в интерпретаторы ex.exe, exw.exe и exu. Другие написаны на Euphoria и, чтобы воспользоваться ими, вы должны будете включать в свою программу стандартные библиотечные .e-файлы, расположенные в каталоге euphoria\include. В этих случаях необходимый библиотечный файла указывается в графе "Синтаксис" описания подпрограммы. Конечно, библиотечный файл требует только однократного включения в вашу программу. Встроенные подпрограммы, не требующие библиотечных файлов, отображаются редактором в малиновом цвете. Вы можете переопределять эти встроенные подпрограммы, создавая свои собственные подпрограммы под теми же самыми именами. Интерпретатор предупредит вас о переопределении сообщением, вывод которого может быть вами отменён.

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

Некоторые подпрограммы доступны только на одной или двух из четырёх платформ. В описаниях такие подпрограммы обозначены как "Платформа: DOS32" или "Платформа: WIN32" или "Платформа: Linux". В некоторых других местах вы можете встретить пометки (DOS32) или (WIN32) или (Linux). Подпрограммы, работающие на Linux, в общем случае работают и на FreeBSD. Единственное исключение относится к управлению мышью.

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

2.1 Стандартные типы

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

integer (целое)		- проверяет, что объект имеет тип integer
atom (число)		- проверяет, что объект имеет тип atom
sequence (ряд)		- проверяет, что объект имеет тип sequence
object (объект)		- проверяет, что объект имеет тип object (всегда истина)

length (длина)		- выдаёт длину ряда
repeat (повторить)		- повторяет элемент n раз и выдаёт ряд длины n
reverse (повернуть)		- поворачивает ряд так, что первые элементы занимают место последних
append (добавить)		- добавляет новый элемент после конца ряда
prepend (прибавить)		- прибавляет новый элемент перед началом ряда

compare (сравнить)		- сравнивает два объекта
equal (равно)		- проверяет два объекта на идентичность
find (найти)		- ищет объект в ряде - начало поиска с первого элемента
find_from (найти_от)		- ищет объект в ряде - начало поиска с заданного элемента
match (сопоставить)		- ищет ряд как отрезок другого ряда - начало поиска с первого элемента
match_from (сопоставить_от)		- ищет ряд как отрезок другого ряда - начало поиска с заданного элемента
sort (сортировать)		- сортирует элементы ряда в порядке возрастания
custom_sort (сортировать_как)		- сортирует элементы ряда, основываясь на заданной вами функции сравнения

lower (нижний_регистр)		- преобразует атом или ряд к нижнему регистру
upper (верхний_регистр)		- преобразует атом или ряд к верхнему регистру
wildcard_match (искать_в_строке_с_догадками)		- сопоставляет строку с заданным образцом, содержащим символы догадок ? и *
wildcard_file (искать_имя_файла_с_догадками)		- сопоставляет имя файла с заданным образцом, содержащим символы догадок

Эти подпрограммы работают с отдельными атомами или рядами величин. См. Часть I - Ядро языка - Операции на рядах.

sqrt (корень)		- вычисляет квадратный корень объекта
rand (случайные_числа)		- выдаёт случайные числа
sin (синус)		- вычисляет синус угла
arcsin (арксинус)		- вычисляет угол для данного синуса
cos (косинус)		- вычисляет косинус угла
arccos (арккосинус)		- вычисляет угол для данного косинуса
tan (тангенс)		- вычисляет тангенс угла
arctan (арктангенс)		- вычисляет угол для данного тангенса
log (логарифм)		- вычисляет натуральный логарифм
floor (целая_часть)		- округляет вниз до ближайшего целого
remainder (остаток)		- вычисляет остаток от деления двух чисел
power (степень)		- вычисляет число, возведённое в степень
PI (Пи)		- число PI (Пи) (3.14159...)

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

and_bits (И_побитно)		- выполняет логическое AND (И) над соответствующими битами
or_bits (ИЛИ_побитно)		- выполняет логическое OR (ИЛИ) над соответствующими битами
xor_bits (НО_побитно)		- выполняет логическое XOR (исключающее ИЛИ, НО) над соответствующими битами
not_bits (НЕ_побитно)		- выполняет логическое NOT (НЕ) над всеми битами

Чтобы произвести операции ввода/вывода в файл или на устройство, вы должны сначала открыть файл или устройство для этих операций, а уже затем применять подпрограммы, описываемые ниже, для ввода и вывода (записи и чтения). По окончании операций чтения или записи вы должны закрыть файл или устройство. Подпрограмма open() выдаст вам номер файла, который вы должны использовать как первый аргумент в других подпрограммах ввода/вывода. Ряд вполне определенных файлов/устройств открыт для вас автоматически (на манер текстовых файлов):

0 - стандартный ввод

1 - стандартный вывод

2 - стандартная ошибка

Примечание:

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

Примечание: На платформе Windows XP, если вы хотите, чтобы мышь DOS работала в окне (не-полный-экран), вы должны выключить режим QuickEdit, воспользовавшись опцией Properties для окна DOS.

get_mouse (что_с_мышью)		- выдаёт информацию о "мышиных событиях" (щелчки, движения)
mouse_events (отслеживать_мышь_по_)		- задаёт мышиные события, подлежащие отслеживанию
mouse_pointer (указатель_мыши)		- включает или выключает отображение указателя (курсора) мыши

time (время)		- выдаёт время в секундах, прошедшее от момента старта данной программы
tick_rate (частота_часов)		- устанавливает число прерываний от таймера в секунду (DOS32)
date (дата)		- выдаёт в виде ряда информацию о текущих дате и времени
command_line (командная_строка)		- выдаёт командную строку, которой запущена данная программа
getenv (получить_окружение)		- выдаёт значение заданной переменной окружения
system (команда_ОС)		- запускает на исполнение командную строку операционной системы
system_exec (внешняя_программа)		- запускает на исполнение дочернюю программу и выдаёт код её завершения
abort (прервать)		- прерывает исполнение данной программы
sleep (спать)		- приостанавливает исполнение данной программы на заданное время
platform (платформа)		- выдаёт код операционной системы, на которой исполняется данная программа

machine_func (машинная_функция)		- выполняет специализированные внутрибиблиотечные операции с выдачей величины
machine_proc (машинная_процедура)		- выполняет специализированные внутрибиблиотечные операции без выдачи величины

trace (трасса)		- динамически включает и выключает трассировку
profile (профиль)		- динамически включает и выключает профилирование

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

Для DOS32 имеется подпрограмма, которая может генерировать звуки на встроенном громкоговорителе вашего компьютера. Чтобы извлекать из машины практически любые необходимые вам звуки, получите библиотеку Sound Blaster, разработанную Жаком Дешеном. Она доступна на Web-узле RDS.

Нижеследующие подпрограммы работают во всех текстовых и пиксельных режимах:

clear_screen (очистить_экран)		- очищает экран
position (знакоместо)		- устанавливает курсор на заданной строке в заданный столбец
get_position (выдать_позицию)		- выдаёт текущие строку и столбец, где находится курсор
graphics_mode (режим_экрана)		- включает новый экранный пиксельный или текстовый режим (DOS32)
video_config (видео_конфигурация)		- выдаёт параметры текущего экранного режима видеосистемы
scroll (прокрутка)		- прокручивает текст на экране вверх или вниз
wrap (перенос)		- задаёт поведение строки при достижении ею правой границы экрана
text_color (цвет_текста)		- задаёт цвет символов текста
bk_color (цвет_фона)		- задаёт цвет фона под текстом
palette (палитра)		- изменяет на экране цвет одного заданного номера на другой заданный цвет (DOS32)
all_palette (вся_палитра)		- изменяет на экране цвета всех номеров на другие заданные цвета (DOS32)
get_all_palette (получить_всю_палитру)		- выдаёт величины составляющих цветов для всех цветов текущей палитры (DOS32)
read_bitmap (читать_биткарту)		- читает биткарту (.bmp-файл) и выдаёт её палитру и двумерный ряд пикселов
save_bitmap (сохранить_ряд_как_биткарту)		- создаёт биткарту (.bmp-файл), заданную палитрой и двумерным рядом пикселов
get_active_page (получить_активную_страницу)		- выдаёт номер текущей активной страницы экрана (той, на которую ведётся запись) (DOS32)
set_active_page (установить_активную_страницу)		- переключает заданную по номеру страницу экрана в активное состояние (на запись) (DOS32)
get_display_page (получить_отображаемую_страницу)		- выдаёт номер текущей отображаемой страницы экрана (той, которая видна на экране) (DOS32)
set_display_page (установить_отображаемую_страницу)		- переключает заданную по номеру страницу экрана на отображение (DOS32)
sound (звук)		- генерирует заданный звук на встроенном излучателе компьютера (DOS32)

Нижеследующие подпрограммы работают только в текстовых режимах:

cursor (курсор)		- задаёт форму курсора клавиатуры (каретки)
text_rows (число_строк)		- задаёт число строк на текстовом экране
get_screen_char (получить_символ_с_экрана)		- выдаёт код и атрибут символа, расположенного на экране в заданной позиции
put_screen_char (поместить_символ_на_экран)		- выводит один или более символов на экран в заданной позиции с заданными атрибутами
save_text_image (сохранить_образ_текста_в_ряде)		- выдаёт ряд, содержащий образ заданного прямоугольного участка текстового экрана
display_text_image (вывести_образ_текста)		- выводит текст, содержащийся в заданном образе, на текстовый экран

Нижеследующие подпрограммы работают только в пиксельных режимах (DOS32):

pixel (точки)		- включает заданный пиксел или ряд пикселов в заданном цвете или цветах
get_pixel (цвет_точек)		- выдаёт текущий цвет заданного пиксела или ряда пикселов
draw_line (линия)		- соединяет заданные точки на экране линией
polygon (многоугольник)		- вычерчивает заданную n-стороннюю фигуру
ellipse (эллипс)		- вычерчивает заданный эллипс или круг
save_screen (сохранить_экран_в_файле)		- записывает содержимое экрана в файл биткарты (.bmp-файл)
save_image (сохранить_изображение_в_ряде)		- выдаёт ряд, содержащий образ заданного прямоугольного участка пиксельного экрана
display_image (вывести_изображение)		- выводит изображение, образ которого содержится в заданном ряде, на пиксельный экран

Здесь сгруппированы подпрограммы, которые пригодятся вам, если вы решите поработать со своей машиной на уровне машинных кодов. Предлагаемый интерфейс низкого уровня позволяет вам читать и записывать данные и код непосредственно в оперативной памяти. Это значит, что вы можете разрабатывать свои собственные подпрограммы в кодах машин 386+ и вызывать их на исполнение.

Некоторые из подпрограмм, перечисленных ниже, не являются безопасными в том смысле, что Euphoria не сможет подстраховать вас при некорректном их использовании. Вы рискуете "подвесить" свою программу, операционную систему или даже машину, если сделаете что-то не так, как следовало бы. Если под DOS32 вы обратитесь к негодным адресам в памяти, то в дело вступит расширитель DOS CauseWay, и вы получите от него на экране сообщение об ошибке плюс распечатку информации на машинной тарабарщине в файле cw.err. Под WIN32 операционная система выдаст вам обычную свою табличку о прерывании прогона вашей программы со скупым диагностическим сообщением плюс информацию из регистров процессора. Под Linux в типовом случае вы получите аварийную остановку программы и сообщение о нарушении сегментации.

Примечание:

Чтобы помочь программистам в этих рискованных занятиях, мы поставляем библиотечный файл safe.e, как отладочную замену файла machine.e. Если вы скопируете safe.e из каталога euphoria\include\ в каталог, содержащий вашу программу, и переименуете safe.e как machine.e в этом вашем рабочем каталоге, ваша программа будет исполняться с использованием более безопасного, но и более медленного, варианта обычных подпрограмм низкого уровня. Этот safe.e может отловить многие ошибки, в том числе и такие, как запись в память по негодным адресам. Просмотрите комментарии в начале файла safe.e, чтобы получить полную инструкцию по его применению и оптимальному его конфигурированию под вашу программу.

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

Подпрограммы в машинных кодах могут быть написаны вручную или же получены путем дизассемблирования выходных файлов компиляторов Си или некоторых других языков. Пит Эберлейн написал "мини-ассемблер" для использования с Euphoria. Просмотрите Архив файлов. Не забывайте, что ваш машинный код будет исполняться в 32-разрядном защищённом режиме. Просмотрите файл demo\dos32\callmach.ex, чтобы получить более конкретное представление о деталях этого дела.

peek (читать_из_памяти)		- выдаёт один или более байтов из памяти с заданного адреса
peek4s (читать_из_памяти_4_байта_и_знак)		- выдаёт 4-х байтовую величину со знаком из памяти с заданного адреса
peek4u (читать_из_памяти_4_байта_без_знака)		- выдаёт 4-х байтовую величину без знака из памяти с заданного адреса
poke (записать_в_память)		- записывает один или более байтов в память, начиная с заданного адреса
poke4 (записать_в_память_4_байта)		- записывает 4-х байтовую величину в память по заданному адресу
mem_copy (копировать_память)		- копирует в памяти последовательность байтов с одного заданного адреса по другому
mem_set (заполнить_память)		- устанавливает все байты заданного участка памяти в заданное значение
call (вызвать)		- вызывает на исполнение подпрограмму, написанную в машинных кодах
dos_interrupt (прерывание_dos)		- вызывает подпрограмму обработки прерывания DOS (DOS32)
allocate (выделить_память)		- выдаёт адрес свободного участка памяти заданного объёма
free (освободить_память)		- освобождает участок памяти, ранее выделенный по команде allocate
allocate_low (выделить_память_внизу)		- выдаёт адрес свободного участка нижней памяти (адреса менее 1Mb) (DOS32)
free_low (освободить_память_внизу)		- освобождает участок памяти, ранее выделенный по команде allocate_low (DOS32)
allocate_string (поместить_строку_в_память)		- размещает в памяти заданную строку с нуль-терминатором и выдаёт её адрес
register_block (учесть_блок)		- регистрирует в списке безопасных блоков участок памяти, ранее уже выделенный какой-либо подпрограммой
unregister_block (вычеркнуть_блок)		- вычёркивает из списка безопасных ранее зарегистрированный блок памяти (см. выше)
get_vector (получить_адрес_вектора)		- выдаёт адрес обработчика прерывания (DOS32)
set_vector (установить_адрес_вектора)		- устанавливает адрес обработчика прерывания (DOS32)
lock_memory (запереть_память)		- предохраняет заданный блок памяти от перенесения на диск при работе виртуальной памяти (DOS32)
int_to_bytes (байты_из_целого)		- выдаёт 4 байта, соответствующие заданному целому
bytes_to_int (целое_из_байтов)		- выдаёт целое, соответствующее заданным 4 байтам
int_to_bits (биты_из_целого)		- выдаёт ряд битов, соответствующий заданному целому
bits_to_int (целое_из_битов)		- выдаёт целое, соответствующее заданному ряду битов
atom_to_float64 (атом_в_плавающее_64_бит)		- выдаёт ряд из 8 байтов, соответствующий заданному атому, в 64-битном формате IEEE для чисел с плавающей точкой
atom_to_float32 (атом_в_плавающее_32_бит)		- выдаёт ряд из 8 байтов, соответствующий заданному атому, в 32-битном формате IEEE для чисел с плавающей точкой
float64_to_atom (плавающее_64_бит_в_атом)		- выдаёт атом, соответствующий ряду из 8 байтов в 64-битном формате IEEE для чисел с плавающей точкой
float32_to_atom (плавающее_32_бит_в_атом)		- выдаёт атом, соответствующий ряду из 4 байтов в 32-битном формате IEEE для чисел с плавающей точкой
set_rand (установить_датчик_случайных_чисел)		- устанавливает датчик случайных чисел в режим выдачи помеченной серии чисел с восстанавливаемым порядком
use_vesa (использовать_vesa)		- переключает интерпретатор Euphoria в режим выполнения рекомендаций видеостандарта VESA (DOS32)
crash_file (файл_отчета_об_авосте)		- определяет файл для записи диагностической информации, если Euphoria обнаруживает ошибку в вашей программе
crash_message (сообщение_об_авосте)		- определяет сообщение об ошибке, которое будет выводиться, если Euphoria обнаруживает ошибку в вашей программе
crash_routine (подпрограмма_по_авосту)		- определяет подпрограмму, которая должна быть вызвана перед аварийной остановкой, если Euphoria обнаруживает ошибку в вашей программе

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

routine_id (подпрограмма_номер)		- выдаёт уникальный идентификационный номер, автоматически присваиваемый заданной подпрограмме Euphoria
call_proc (вызвать_процедуру)		- вызывает процедуру Euphoria по заданному идентификационному номеру
call_func (вызвать_функцию)		- выдаёт результат функции Euphoria, вызванной по заданному идентификационному номеру

Просмотрите файл platform_r.htm, где подробно описано программирование на Euphoria для операционных систем WIN32 и Linux.

open_dll (открыть_dll)		- открывает динамически подключаемую библиотеку Windows (.dll-файл) или общую библиотеку Linux (.so-файл)
define_c_proc (определить_процедуру_Си)		- определяет номер функции Си типа VOID, которая не выдаёт величины, или же когда ваша программа, используя данную функцию Си, игнорирует величину, выдаваемую этой функцией
define_c_func (определить_функцию_Си)		- определяет номер функции Си, которая выдаёт величину, подлежащую учёту и использованию в вашей программе
define_c_var (определить_переменную_Си)		- выдаёт адрес в памяти для заданной переменной Си
c_proc (процедура_Си)		- вызывает функцию Си, игнорируя выдаваемую ею величину
c_func (функция_Си)		- вызывает функцию Си и выдаёт её величину
call_back (обратный_вызов)		- выдаёт 32-битный машинный адрес подпрограммы Euphoria по заданному её номеру для использования в качестве адреса обратного её вызова из операционной системы
message_box (табличка_сообщения)		- выводит диалоговое окно для получения от пользователя ответа Да/Нет/Сброс
free_console (освободить_консоль)		- удаляет текстовое окно консоли
instance (экземпляр)		- выдаёт идентификатор состояния текущей программы

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

Демонстрационная игра The Language War, lw.ex, широко использует механизм многозадачности для создания модели боя, в котором участвуют многочисленные независимо движущиеся корабли, торпеды, фазоры и т.д. Просмотрите также демо-программу taskwire.exw для Windows, и демо-программу news.exu для Linux и FreeBSD.

task_clock_start (задача_часы_старт)		- перезапускает часы диспетчера задач
task_clock_stop (задача_часы_стоп)		- останавливает часы диспетчера задач
task_create (задача_новая)		- создаёт новую задачу
task_list (задача_список)		- выдаёт список всех задач
task_schedule (задача_план)		- задаёт диспетчеру план решения задачи
task_self (задача_какая)		- выдаёт идентификатор текущей задачи (номер)
task_status (задача_состояние)		- выдаёт текущее состояние задачи (активна, приостановлена, прервана)
task_suspend (задача_стоп)		- приостанавливает решение задачи
task_yield (задача_другая)		- управление задачами передаётся диспетчеру, запускающему на исполнение другую задачу.