alterator-sh-functions(3)
| alterator-sh-functions(3) | Alterator user manual | alterator-sh-functions(3) |
NAME
alterator-sh-functions - library to write alterator backends in shell.
SYNOPSIS
message_loop [message-handler]
on_message
_ <string> <domain>
test_bool <value>
write_string_param <name> <value>
write_bool_param <name> <value>
write_blob_param <name> [file]
write_enum_item <name> [<label>]
write_enum
write_table_item <name1> <value1> <name2> <value2> ...
write_type_item <name> <type>
write_error <message>
write_debug <message>
DESCRIPTION
Alterator backends use a very simple communication protocol and can be written in any language. This library contains a set of functions to simplify development of backend on shell.
Main event loop is provided by message_loop function. Default callback is a function called on_message. All incoming parameters are provided as a global variables with prefix 'in_'. For example, incoming parameter 'foo' can be found as variable '$in_foo'.
You should write output parameters using functions with prefix 'write_'. Some parameter names have special meaning. There are: action, _objects, language, expert_mode.
Usually callback determine action using 'action' parameter. Some action types have special meaning. There are: type, help.
Behaviour of the library significantly depends on the alterator_api_version global variable. It is unset by default for backward compatibility. Current API version value is '1', you must explicitely set alterator_api_version=1 to use current API.
Attention: When alterator_api_version < 1, stdout and stdin channels are used for communications between backend and alteratord daemon. Be shure not to write something else to stdout or read from stdin. When alterator_api_version = 1, backend's stdout is redirected to stderr, so you can safely write to it.
Localization
Sometimes it is useful to have answer from backend in user native language. List of preffered languages, separated by semicolon you can find in language parameter. We recommend you to use library function _ to translate messages. This is a wrapper over gettext utility. Default value of dictionary with translated messages for _ function is a 'alterator-<backend-name>', you can change this value by using po_domain global variable.
Type checking
It's very useful to validate parameters before use in backend. You can define parameter types in answer to special action called 'type'. All parameters with defined types will be checked in alteratord daemon before passing request to backend.
EXAMPLE
alterator_api_version=1
po_domain=module-dictionary
. alterator-sh-functions
on_message()
{
case "$in_action" in
type)
write_type_item param1 hostname
;;
read)
write_string_param param1 value
write_string_param param2 "`_ localized value`"
;;
write)
write_debug "param=$in_param"
;;
list)
write_enum_item "param1" "First parameter"
write_enum_item "param2" "Second parameter"
;;
esac
}
message_loop
FUNCTIONS
Common functions
- message_loop
- Main event loop. Default callback is 'on_message', you can specify own callback name.
- on_message
- Default event callback. This function is without parameters. All incoming parameters are coming as global variables. _ <string> [<domain>] Output translated string. Optional parameter <domain> allows you to replace a default dictionary with your one.
- write_debug <string>
- Use this function to debug your backend. This function will print your messages only if global variable ALTERATOR_DEBUG is not empty.
Functions for processing of incoming parameters
- test_bool <value>
- Incoming boolean variable are represented as a string with value '#t' or '#f'. This representation can be changed in the future and we are strongly recommend you to use test_bool function to test variable for true value.
Functions for writing output parameters.
- write_string_param <name> <value>
- Write parameter of string type with name <name> and value <value>.
- write_bool_param <name> <value>
- Write parameter of boolean type with name <name> and value <value>. Strings '1', 'true', 'yes', 'y', and 'on' are treated as a true value, all other strings a treated as a false value.
- write_blob_param <name> [<file>]
- Write parameter with arbitrary binary data from some file or standard input.
- write_enum_item <name> [<label>]
- Write member of enumeration. Optional parameter <label> is a descriptive member name visible for users.
- write_enum
- Read stdin and print enumeration members. Each line is of the format:
<name><separator><label>
Second field is optional. Field separator is a space character or tab. If you want to use other field separator in input stream, then you should set IFS variable to appropriate value.
- write_table_item <name1> <value1> <name2> <value2> ...
- Sometimes we need to fill tables or multicolumn lists in interface. This function will print attributes and it's values for one line of a such table. Please note that all attributes should be of a type "string".
- write_error
- This is a function to notify about problems in backend. This function should work like "throw". You must return from callback immediately after call of this function.
- write_type_item
- Write a parameter definition. All parameters are treated as a strings by default. If you want to have an additional check for values before use, then you should use this function to define a type of parameter. There are a lot of standard types, e.g., ipv-address, tcp-port, hostname etc. You can also create your own types.
FILES
- /usr/lib/alterator/backend3 - directory containing alterator backends.
SEE ALSO
alteratord(8)
AUTHOR
Stanislav Ievlev <inger@altlinux.org>
| 7/04/2009 | ALT Linux |