Стандарт UDF Источник (англ. яз.)

Стандарт UDF (User Defined Functions)


Эта страница содержит инструкцию по отправке UDF для AutoIt3. Это помогает, если код представлен в соответствии со стандартом указанным ниже, включая ниже указанные 2 файла:

  1. Catagory.au3 (сам UDF включая имя файла)
  2. Functionname.au3 (пример скрипта для использования в файле справки)

Вы должны понимать, что можно добавлять только те UDF, которые полезны для большинства скриптёров.
Если вам нравится ваш UDF, тогда он должен быть добавлен :-)

  1. Следуйте инструкциям указанным ниже для ваших файлов UDF.
  2. Убедитесь, что ваши UDF не содержат ошибок, запустив AU3Check с параметрами: -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6.
  3. Убедитесь, что ваш UDF обработан с помощью Tidy.
  4. Отправьте мне в PM (ЛС, Личное сообщение) или на эл.почту (Email) архив (zip-файл) содержащий файлы UDF. (GaryFrost или "Gary на autoitscript.com" ).
  5. Для тех, кто желает проверить формат UDF: Build Templates Application

Спасибо, Gary

Стандарты написания кода UDF (User Defined Function)

Имена функций

Все имена функций должны начинаться с подчеркивания (“_”). *
Каждое слово в имени функции должно полным, главным определяющим и начинаться с заглавной буквы.
Первое слово в имени функции должно начинаться со слова описания общей категории, например “Date”, “String”, “Array”, “Network”, и т.д.. Если слово слишком длинно “Window”, тогда можно использовать аббревиатуру (например “Win” для “Window” или “Net” для “Network”).
Все имена функций должны closely resemble the established naming convention for "internal" AutoIt functions.

Имена переменных

Первый символ после “$” должен определять тип данных содержащихся в переменной. В ниже указанном списке префиксы для различных типов данных.
$a<символ> - (Array) Массив данных (последующий <символ>, взятый из списка ниже, определяет тип данных в массиве)
$b - (Binary data) Двоичные данные
$h - (File or window handle) Дескриптор файла, окна и т.д.
$i - (Integer) Целое число
$f - (Boolean) Логический тип, может принимать значения True или False
$n - (Floating point number) Число с плавающей точкой
$s - (String) Строка
$v - (Variant) Неопределенный или изменяющийся тип данных, базовый тип для Autoit
$t - (Struct) Структура в стиле C/C++, для использования в DllCall, в сообщениях WM_*, при обработке данных и т.п.
$p - (Pointer) Указатель на структуру или на её элемент

Остальные имена используются полными словами, чтобы описать назначение функций и переменных. Такие имена, как $iC неприемлемы. Гораздо предпочтительнее имена $aiWeekDayNames или $iCounter.
Все переменные должны быть объявлены в начале UDF с областью видимости Local перед тем, как использовать их первый раз.
Ключевые слова Dim или Global неоднозначны внутри UDF, поэтому следует их избегать. Все переменные должны быть переданы с помощью параметров функций используя Byref, если необходимо возвращать обновлённые значения этих переменных.

Параметры

Имена параметров должны использовать те же правила именования как для переменных.
Все параметры должны быть проверены на соответствие необходимому формату и возвращать соответствующие коды ошибок в случае несоответствия.
Если параметры используются для передачи данных обратно в вызывающую функцию (Byref), то документация должна точно описывать указанное поведение.

Документация функций

Все UDF должны иметь заголовочную документацию в скрипте в следующем виде:

; #FUNCTION# ;===============================================================================
;
; Name...........: _DateDiff
; Description ...: Возвращает интервал времени между двумя датами, в указанном формате
; Syntax.........: _DateDiff($sType, $sStartDate, $sEndDate)
; Parameters ....: $sType - Одно из следующих значений:
;                  |D = Интервал в днях между указанными датами
;                  |M = Интервал в месяцах между указанными датами
;                  |Y = Интервал в годах между указанными датами
;                  |w = Интервал в неделях между указанными датами
;                  |h = Интервал в часах между указанными датами
;                  |n = Интервал в минутах между указанными датами
;                  |s = Интервал в секундах между указанными датами
;                   $sStartDate  - Дата начала в формате "YYYY/MM/DD[ HH:MM:SS]"
;                   $sEndDate    - Дата окончания в формате "YYYY/MM/DD[ HH:MM:SS]"
; Return values .: Success - Возвращает интервал между двумя датами.
;                  Failure - Возвращает 0 и устанавливает @Error:
;                  |0 - Нет ошибок.
;                  |1 - Неверный $sType
;                  |2 - Неверный $sStartDate
;                  |3 - Неверный $sEndDate
; Author ........: Jos van der Zande
; Modified.......:
; Remarks .......:
; Related .......: _DateAdd
; Link ..........;
; Example .......; Yes
;
; ;==========================================================================================
Func _DateDiff($sType, $sStartDate, $sEndDate)
...

Файл-пример документированной функции

Каждая представленная функция UDF должна включать дополнительный файл примера для возможности вставить его в справочный файл.
Functionname.au3 Это файл-пример для включения в справочный файл.
Пример:

#include <Date.au3>

; Вычислит число секунд, прошедших с начала эпохи (EPOCH) (1970/01/01 00:00:00)
$iDateCalc = _DateDiff( 's',"1970/01/01 00:00:00",_NowCalc())
MsgBox( 4096, "", "Количество секунд с начала эпохи (EPOCH): " & $iDateCalc )

; Вычислит количество часов в этом году
$iDateCalc = _DateDiff( 'h',@YEAR & "/01/01 00:00:00",_NowCalc())
MsgBox( 4096, "", "Количество часов в этом году: " & $iDateCalc )


Маркеры

UDF Может содержать несколько функций, поэтому файл должен содержать дополнительную информацию.

Комментарий с маркером: ; #INDEX# должен содержать строку заголовка, например:
; Title .........: Array

Комментарий с маркером: ; #CURRENT# должен содержать имена функций, например:
;_ArrayAdd
;_ArrayBinarySearch
...

Комментарий с маркером: ; #INTERNAL_USE_ONLY# должен содержать имена внутренних функций, например:
;__Array_ExeterInternal
;__Array_Combinations
...

Комментарий с маркером: ; #FUNCTION# должен содержать информацию о функции, пример смотрите выше