Alterator/module/types
Материал из ALT Linux Wiki
(Новая: === Типы параметров === Иногда необходимо производить валидацию введённых пользователем данных. Можно ...) |
|||
(16 промежуточных версий не показаны.) | |||
Строка 1: | Строка 1: | ||
- | === | + | === Автоматическая проверка данных === |
- | Иногда необходимо производить валидацию введённых пользователем данных. Можно это делать в | + | Иногда необходимо производить валидацию введённых пользователем данных. Можно это делать вручную в бэкенде, но гораздо удобнее воспользоваться автоматической проверкой типов, выполняемой альтератором при передаче данных в бэкенд. |
- | ==== Изменения в | + | ==== Изменения в бэкенде ==== |
- | Делается это следующим образом. В | + | Делается это следующим образом. В бэкенде добавляется ответ на запрос «type». В нем перечисляются параметры, с которыми работает бэкенд, и их типы. Для формирования правильного ответа стоит воспользоваться стандартной библиотекой, например для бэкенда на shell объявление типов будет выглядить следующим образом. |
- | < | + | <source lang="bash"> |
. alterator-sh-functions | . alterator-sh-functions | ||
Строка 22: | Строка 22: | ||
esac | esac | ||
} | } | ||
- | </ | + | </source> |
- | В примере выше объявлено что параметр 'a' будет иметь тип 'IP адрес', 'b' | + | В примере выше объявлено что параметр 'a' будет иметь тип 'IP адрес', 'b' — 'TCP порт' и теперь пользователь не сможет передать в бэкенд в качестве 'a' что-либо отличное IP адреса и в качестве 'b' что-либо отличное от целого числа находящегося в определённом диапазоне. |
+ | |||
+ | ==== Изменения в интерфейсе ==== | ||
+ | |||
+ | На этом возможности системы типов не исчерпываются. Предположим, что пользователь ввёл-таки неправильное значение в поле, соотвествующее параметру 'a'. Он увидит следующее сообщение об ошибке: | ||
+ | <source lang="text"> | ||
+ | a: недопустимый IP-адрес | ||
+ | </source> | ||
+ | |||
+ | Однако никакого 'a' на его экране не наблюдается. В каком именно поле случилась ошибка? | ||
+ | |||
+ | Система типов alterator в состоянии справиться с этим. Для этого всего-лишь необходимо, чтобы у '''названия поля''' был задан атрибут 'name' содержащий '''имя параметра бэкенда''', которому соответствует это поле. | ||
+ | |||
+ | Пример для qt: | ||
+ | <source lang="lisp"> | ||
+ | ... | ||
+ | (label text "Field" name "a") | ||
+ | (edit name "a") | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | Теперь в случае ошибки, пользователь увидит следующее сообщение: | ||
+ | <source lang="text"> | ||
+ | Field: недопустимый IP-адрес | ||
+ | </source> | ||
+ | |||
+ | Аналогичный пример для html: | ||
+ | <source lang="html4strict"> | ||
+ | .... | ||
+ | <span name="a" translate="_">Field:</span> | ||
+ | <input type="text" name="a"/> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | ==== Стандартные типы ==== | ||
+ | {| class="standard" | ||
+ | |- | ||
+ | !Название типа||Описание | ||
+ | |- | ||
+ | |boolean||булевский тип в стиле scheme, строка <tt>#t</tt> или <tt>#f</tt> | ||
+ | |- | ||
+ | |date|| дата, строка формата <tt>ГГГГ-ММ-ДД</tt> | ||
+ | |- | ||
+ | |time|| время, строка формата <tt>ЧЧ:ММ:СС</tt> | ||
+ | |- | ||
+ | |ipv4-address||IP-адрес, строка формата <tt>NNN.NNN.NNN.NNN</tt> | ||
+ | |- | ||
+ | |ipv4-address-list||список IP адресов, разделённый пробелами | ||
+ | |- | ||
+ | |ipv4-network||описание IP-сети, строка формата <tt>NNN.NNN.NNN.NNN/MM</tt> | ||
+ | |- | ||
+ | |hostname||имя компьютера, строка состоящая из латинских букв, цифр и символов <tt>"_", ".", "-"</tt>. | ||
+ | |- | ||
+ | |hostname-list||список имён компьютеров, разделённый пробелами | ||
+ | |- | ||
+ | |tcp-port|| TCP-порт, целое число от 0 до 65535. | ||
+ | |- | ||
+ | |iso-3166-alpha-2||двухбуквенный код страны согласно стандарту ISO-3166-alpha2 | ||
+ | |- | ||
+ | |system-account-name|| имя системной пользовательской или групповой записи, строка, состоящая из малых латинских буквы, цифр и символов <tt>"_", "-"</tt>. При этом начинаться строка может только с маленькой латинской буквы. | ||
+ | |} | ||
+ | |||
+ | === Пользовательские типы === | ||
+ | Если стандартных типов недостаточно, то можете определить свой. | ||
+ | При этом стоит придерживаться следующего соглашения: имя типа должно начинаться с префикса <tt><имя модуля>-</tt>, например, <tt>foo-type</tt> для модуля alterator-foo. | ||
+ | |||
+ | На данный момент известны следующие типы: | ||
+ | |||
+ | {| class="standard" | ||
+ | |- | ||
+ | !Название||Модуль||Описание | ||
+ | |- | ||
+ | |postfix-address || alterator-postfix-restrictions || компьютер или адрес, строка малых латинских букв, цифр и символов <tt>"@", ".", "-", "_"</tt>. | ||
+ | |- | ||
+ | |postfix-limit || alterator-postfix-restrictions || пороговое значение, целое неотрицательное число | ||
+ | |- | ||
+ | |ahttpd-cert-field || alterator-ahttpd || поле данных в SSL сертификате, строка из латинских букв, цифр, пробелов и символов <tt>"_", "-"</tt>. | ||
+ | |- | ||
+ | |spamassassin-score || alterator-spamassassin || пороговое значение баллов, неотрицательное целое число | ||
+ | |- | ||
+ | |dhcp-mac-address || alterator-dhcp || MAC-адрес сетевой карты, строка формата <tt>HH:HH:HH:HH:HH:HH</tt>, где <tt>H</tt> — шестнадцатиричное число. | ||
+ | |- | ||
+ | |samba-resource || alterator-samba || ресурс SMB, строка из латинских букв, цифр и подчёркивания. | ||
+ | |} | ||
+ | Если вы считаете, что некоторый из этих типов пригодится и в вашем модуле, то стоит сделать запрос на признание типа стандартным. | ||
+ | |||
+ | |||
+ | Для того чтобы создать пользовательский тип, необходимо создать модуль ''(alterator type <тип>)'' (и расположенный внутри проекта в каталоге ''interfaces/guile/type/<тип>.scm''). | ||
+ | |||
+ | В этом модуле необходимо определить функцию '''type''', принимающую два параметра: | ||
+ | * значение, которое надо проверить на соответствие данному типу | ||
+ | * функция для перевода строки на язык пользователя | ||
+ | |||
+ | В случае корректных данных функция должна ответить положительным булевым значением в смысле scheme. | ||
+ | В случае некорректных данных должно быть выдано сообщение об ошибке при помощи функции '''type-error''' из модуля (alterator woo) | ||
+ | |||
+ | Функция для перевода (обычно называется '''_''') принимает два параметра: | ||
+ | * строка для перевода | ||
+ | * словарь, используемый для перевода | ||
+ | |||
+ | Например (файл ''interfaces/guile/type/foo-type.scm''): | ||
+ | <source lang="lisp"> | ||
+ | (define-module (alterator type foo-type) | ||
+ | :use-module (alterator woo) | ||
+ | :export (type)) | ||
+ | |||
+ | (define (type v _) | ||
+ | (or (string? v) | ||
+ | (type-error (_ "Not foo type" "alterator-foo")))) | ||
+ | </source> | ||
+ | |||
+ | В этом примере мы создали тип, который в случае получения данных отличных от строки выдаёт сообщение «Not foo type», причём для перевода этого сообщения используется словарь модуля «alterator-foo». | ||
+ | |||
+ | |||
+ | {{Category navigation|title=Alterator modules|category=Alterator modules|sortkey={{SUBPAGENAME}}}} |
Текущая версия на 15:48, 5 августа 2012
Содержание |
Автоматическая проверка данных
Иногда необходимо производить валидацию введённых пользователем данных. Можно это делать вручную в бэкенде, но гораздо удобнее воспользоваться автоматической проверкой типов, выполняемой альтератором при передаче данных в бэкенд.
Изменения в бэкенде
Делается это следующим образом. В бэкенде добавляется ответ на запрос «type». В нем перечисляются параметры, с которыми работает бэкенд, и их типы. Для формирования правильного ответа стоит воспользоваться стандартной библиотекой, например для бэкенда на shell объявление типов будет выглядить следующим образом.
. alterator-sh-functions on_message() { case "$in_action" in type) write_type_item a ipv4-address write_type_item b tcp-port ;; read) ... esac }
В примере выше объявлено что параметр 'a' будет иметь тип 'IP адрес', 'b' — 'TCP порт' и теперь пользователь не сможет передать в бэкенд в качестве 'a' что-либо отличное IP адреса и в качестве 'b' что-либо отличное от целого числа находящегося в определённом диапазоне.
Изменения в интерфейсе
На этом возможности системы типов не исчерпываются. Предположим, что пользователь ввёл-таки неправильное значение в поле, соотвествующее параметру 'a'. Он увидит следующее сообщение об ошибке:
a: недопустимый IP-адрес
Однако никакого 'a' на его экране не наблюдается. В каком именно поле случилась ошибка?
Система типов alterator в состоянии справиться с этим. Для этого всего-лишь необходимо, чтобы у названия поля был задан атрибут 'name' содержащий имя параметра бэкенда, которому соответствует это поле.
Пример для qt:
... (label text "Field" name "a") (edit name "a") ...
Теперь в случае ошибки, пользователь увидит следующее сообщение:
Field: недопустимый IP-адрес
Аналогичный пример для html:
.... <span name="a" translate="_">Field:</span> <input type="text" name="a"/> ...
Стандартные типы
Название типа | Описание |
---|---|
boolean | булевский тип в стиле scheme, строка #t или #f |
date | дата, строка формата ГГГГ-ММ-ДД |
time | время, строка формата ЧЧ:ММ:СС |
ipv4-address | IP-адрес, строка формата NNN.NNN.NNN.NNN |
ipv4-address-list | список IP адресов, разделённый пробелами |
ipv4-network | описание IP-сети, строка формата NNN.NNN.NNN.NNN/MM |
hostname | имя компьютера, строка состоящая из латинских букв, цифр и символов "_", ".", "-". |
hostname-list | список имён компьютеров, разделённый пробелами |
tcp-port | TCP-порт, целое число от 0 до 65535. |
iso-3166-alpha-2 | двухбуквенный код страны согласно стандарту ISO-3166-alpha2 |
system-account-name | имя системной пользовательской или групповой записи, строка, состоящая из малых латинских буквы, цифр и символов "_", "-". При этом начинаться строка может только с маленькой латинской буквы. |
Пользовательские типы
Если стандартных типов недостаточно, то можете определить свой. При этом стоит придерживаться следующего соглашения: имя типа должно начинаться с префикса <имя модуля>-, например, foo-type для модуля alterator-foo.
На данный момент известны следующие типы:
Название | Модуль | Описание |
---|---|---|
postfix-address | alterator-postfix-restrictions | компьютер или адрес, строка малых латинских букв, цифр и символов "@", ".", "-", "_". |
postfix-limit | alterator-postfix-restrictions | пороговое значение, целое неотрицательное число |
ahttpd-cert-field | alterator-ahttpd | поле данных в SSL сертификате, строка из латинских букв, цифр, пробелов и символов "_", "-". |
spamassassin-score | alterator-spamassassin | пороговое значение баллов, неотрицательное целое число |
dhcp-mac-address | alterator-dhcp | MAC-адрес сетевой карты, строка формата HH:HH:HH:HH:HH:HH, где H — шестнадцатиричное число. |
samba-resource | alterator-samba | ресурс SMB, строка из латинских букв, цифр и подчёркивания. |
Если вы считаете, что некоторый из этих типов пригодится и в вашем модуле, то стоит сделать запрос на признание типа стандартным.
Для того чтобы создать пользовательский тип, необходимо создать модуль (alterator type <тип>) (и расположенный внутри проекта в каталоге interfaces/guile/type/<тип>.scm).
В этом модуле необходимо определить функцию type, принимающую два параметра:
- значение, которое надо проверить на соответствие данному типу
- функция для перевода строки на язык пользователя
В случае корректных данных функция должна ответить положительным булевым значением в смысле scheme. В случае некорректных данных должно быть выдано сообщение об ошибке при помощи функции type-error из модуля (alterator woo)
Функция для перевода (обычно называется _) принимает два параметра:
- строка для перевода
- словарь, используемый для перевода
Например (файл interfaces/guile/type/foo-type.scm):
(define-module (alterator type foo-type) :use-module (alterator woo) :export (type)) (define (type v _) (or (string? v) (type-error (_ "Not foo type" "alterator-foo"))))
В этом примере мы создали тип, который в случае получения данных отличных от строки выдаёт сообщение «Not foo type», причём для перевода этого сообщения используется словарь модуля «alterator-foo».