Alterator/module/types: различия между версиями

Материал из ALT Linux Wiki
Нет описания правки
 
(не показано 14 промежуточных версий 4 участников)
Строка 1: Строка 1:
=== Типы параметров ===
=== Автоматическая проверка данных ===


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




==== Изменения в бакенде ====
==== Изменения в бэкенде ====


Делается это следующим образом. В бакенде добавляется ответ на запрос типа "type". В ответе перечисляются параметры, с которыми работает бакенд, и их типы. Для формирования правильного ответа стоит воспользоваться стандартной библиотекой, например для бакенда на shell объявление типов будет выглядить следующим образом.
Делается это следующим образом. В бэкенде добавляется ответ на запрос «type». В нем перечисляются параметры, с которыми работает бэкенд, и их типы. Для формирования правильного ответа стоит воспользоваться стандартной библиотекой, например для бэкенда на shell объявление типов будет выглядить следующим образом.


<pre>
<source lang="bash">
. alterator-sh-functions
. alterator-sh-functions


Строка 22: Строка 22:
  esac
  esac
}
}
</pre>
</source>


В примере выше объявлено что параметр 'a' будет иметь тип 'IP адрес', 'b' - 'TCP порт' и теперь пользователь не сможет передать в бакенд в качестве 'a' что-либо отличное IP адреса и в качестве 'b' что-либо отличное от целого числа находящегося в определённом диапазоне.
В примере выше объявлено что параметр 'a' будет иметь тип 'IP адрес', 'b' — 'TCP порт' и теперь пользователь не сможет передать в бэкенд в качестве 'a' что-либо отличное IP адреса и в качестве 'b' что-либо отличное от целого числа находящегося в определённом диапазоне.


==== Изменения в интерфейсе ====
==== Изменения в интерфейсе ====


На этом возможности системы типов не исчерпываются. Предположим, что пользователь ввёл-таки неправильное значение в поле, соотвествующее параметру 'a'. Он увидит следующее сообщение об ошибке:
На этом возможности системы типов не исчерпываются. Предположим, что пользователь ввёл-таки неправильное значение в поле, соотвествующее параметру 'a'. Он увидит следующее сообщение об ошибке:
<pre>
<source lang="text">
a: недопустимый IP-адрес
a: недопустимый IP-адрес
</pre>
</source>


Однако никакого 'a' на его экране не наблюдается. В каком именно поле случилась ошибка?
Однако никакого 'a' на его экране не наблюдается. В каком именно поле случилась ошибка?


Система типов alterator в состоянии справиться с этим. Для этого всего-лишь необходимо, чтобы у '''названия поля''' был задан атрибут 'name' содержащий '''имя параметра бакенда''', которому соответвует это поле.
Система типов alterator в состоянии справиться с этим. Для этого всего-лишь необходимо, чтобы у '''названия поля''' был задан атрибут 'name' содержащий '''имя параметра бэкенда''', которому соответствует это поле.


Пример для qt:
Пример для qt:
<pre>
<source lang="lisp">
...
...
   (label text "Field" name "a")
   (label text "Field" name "a")
   (edit name "a")
   (edit name "a")
...
...
</pre>
</source>


Теперь в случае ошибки, пользователь увидит следующее сообщение:
Теперь в случае ошибки, пользователь увидит следующее сообщение:
<pre>
<source lang="text">
Field: недопустимый IP-адрес
Field: недопустимый IP-адрес
</pre>
</source>


Аналогичный пример для html:
Аналогичный пример для html:
<pre>
<source lang="html4strict">
....
....
   <span name="a" translate="_">Field:</span>
   <span name="a" translate="_">Field:</span>
   <input type="text" name="a"/>
   <input type="text" name="a"/>
...
...
</pre>
</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».