AddUser Next Generation -- Dokumentacja developerów

Abstrakt

Poniższy dokument przeznaczony jest przede wszystkim dla osób, które chcą przyłączyć się do rozwoju AddUser-NG. Opisane zostało API wtyczek (pluginów) oraz interfejsu użytkownika.


Spis treści

1. UI -- Interfejs Użytkownika
API
display($title, $msg)
display_error($title, $msg)
get_single($plugname, $optname, $synopsis, $description, $default, @answers)
get_long($plugname, $optname, $synopsis, $description, $default)
get_password($plugname, $optname, $synopsis, $description, $default)
Wrappers
2. Wtyczki (pluginy)
API
Kompatybilność wersji
Inicjalizacja
Konfiguracja
Wykonywanie
Cofanie zmian (rollback)

Spis przykładów

2.1. Szkielet metody new
2.2. Szkielet metody configure
2.3. Szkielet metody execute
2.4. Szkielet metody rollback

Rozdział 1. UI -- Interfejs Użytkownika

Wszelka interakcja z użytkownikiem powinna odbywać się przy wykorzystaniu interfejsów użytkownika. Zapewniają one odpowiednią funkcjonalność wymaganą przez wtyczki, a także dają użytkownikowi komfort korzystania z AddUser-NG w sposób taki jak chce lub taki jak musi.

API

display($title, $msg)

Wyświetl komunikat.

$title

Tytuł komunikatu.

$msg

Treść komunikatu.

display_error($title, $msg)

Wyświetl komunikat informujący o błędzie.

$title

Tytuł komunikatu.

$msg

Treść komunikatu.

get_single($plugname, $optname, $synopsis, $description, $default, @answers)

Wybór jednej opcji z kilku.

Metoda zwraca odpowiedź użytkownika (przekonwertowaną na małe litery) lub, w przypadku jej braku, wartość $default.

$plugname

Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.

$optname

Nazwa opcji, o którą pytamy.

$synopsis

Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$description

Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$default

Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.

@answers

Lista odpowiedzi, z spośród których może wybierać użytkownik.

get_long($plugname, $optname, $synopsis, $description, $default)

Pobranie dłuższej odpowiedzi od użytkownika.

Metoda zwraca odpowiedź użytkownika lub, w przypadku jej braku, wartość $default.

$plugname

Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.

$optname

Nazwa opcji, o którą pytamy.

$synopsis

Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$description

Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$default

Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.

get_password($plugname, $optname, $synopsis, $description, $default)

Pobranie hasła od użytkownika.

Metoda zwraca odpowiedź użytkownika lub, w przypadku jej braku, wartość $default.

$plugname

Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.

$optname

Nazwa opcji, o którą pytamy.

$synopsis

Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$description

Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.

$default

Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.

Wrappers

TODO

Rozdział 2. Wtyczki (pluginy)

Cała siła i funkcjonalność AddUser-NG zawarta jest w mechanizmie wtyczek. Każda z nich ma dostęp do API programu oraz posiada określone metody z jakich korzysta AddUser-NG przy wykonywaniu plugina.

API

Każda z metod: configure, execute i rollback otrzymuje jako pierwszy argument referencję do API dostępnego dla wtyczki. Poniżej znajduje się jego struktura i opis.

API => {
    %plugins_options => {
        %keywords => {
            main.login,
            main.group
        },
        verbose,
        login
        documentation_dir,
        GroupConfig (Config::IniFiles),
        UI,
    },
    %opts
            
plugins_options{keywords}{main.group}

Nazwa grupy z konfiguracji AddUser-NG podstawie której ma być utworzony nowy użytkownik.

plugins_options{keywords}{main.login}

Login użytkownika.

plugins_options{verbose}

Czy uruchomiono AddUser-NG parametrem --verbose. Innymi słowy czy AddUser-NG ma wypisywać nadmiarowe, zazwyczaj nie potrzebne, informacje.

plugins_options{login}

Login użytkownika. To samo co plugins_options{keywords}{main.login}

plugins_options{documentation_dir}

Katalog, w których przechowywana jest dokumentacja wszystkich wtyczek.

plugins_options{GroupConfig}

Referencja do obiektu zawierającego odczytaną konfigurację grupy, na podstawie której ma być tworzony nowy użytkownik. Więcej o metodach tego obiektu dowiesz się z perldoc Config::IniFiles

plugins_options{UI}

Referencja do używanego interfejsu użytkownika. Przy wykorzystaniu tego obiektu odbywa się cała interacja wtyczki z użytkownikiem. W rozdziale Rozdział 1, UI -- Interfejs Użytkownika znajdziesz więcej informacji na ten temat.

opts

Opcje konfiguracyjne wtyczki. Przy inicjalizacji powinny zostać ustawione na domyślne wartości, następnie podczas konfiguracji na wartości, które zostaną użyte podczas wykonania wtyczki.

NAME

Nazwa wtyczki.

APIVERSION

Wersja API z jaką zgodna jest wtyczka.

Kompatybilność wersji

Przed fazą konfiguracji wtyczek sprawdzana jest ich kompatybilność z AddUser-NG. W przypadku gdy który kolwiek plugin okaże się niezgodny działanie całego Skryptu jest przerywane. Można to zrobić bezpiecznie, gdyż do tego momentu żadna wtyczka nie powinna była wprowadzić jakichkolwiek modyfikacji do systemu.

Wersja API wtyczki jest dostępna jako atrybut APIVERSION jej obiektu. Natomiast wersja API AddUser-NG jest zapisana w zmiennej globalnej $APIVERSION.

Numery wersji podane są w postaci liczby szestnastkowej.

Inicjalizacja

Podczas ładowania potrzebnych pluginów wywoływana jest metoda new każdego z nich. W jej wywołaniu wtyczka powinna zostać wstępnie skonfigurowana, np. stworzenie listy opcji konfiguracyjnych plugina i ustawienie ich na wartości domyślne.

Przykład 2.1. Szkielet metody new


sub new {
    my ($c, %args) = @_;
    my $class = ref($c) || $c;

    $args{opts} = {
        'your_name'  =>  ''
    };

    bless \%args, $class;
}

                

W momencie wywołania metody new przekazywane jej jest API.

Konfiguracja

Zanim którykolwiek plugin zostanie uruchomiony wcześniej wszystkie muszą zostać skonfigurowane. W tym celu AddUser-NG wywołuje metodę configure każdej wtyczki.

Przykład 2.2. Szkielet metody configure


sub configure {
    my $self = shift;
    
    # ... code follows here :)

    return $ERRNO{'OK'};
}

                

W momencie wywołania metody configure przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.

W obecnej wersji wartość zwracana przez tę metodę nie jest brana pod uwagę, ale może to ulec zmianie w kolejnych wersjach, dlatego zalecamy zwracać warotść informującą o powodzeniu (bądź też niepowodzeniu) wykonania.

Wykonywanie

Wszystkie wtyczki są uruchamiana w takiej samej kolejności jak podczas fazy konfiguracji. Dla każdej uruchamiana jest metoda execute.

Przykład 2.3. Szkielet metody execute


sub execute {
    my $self = shift;
    
    # ... code follows here :)

    return $ERRNO{'OK'};
}

                

W momencie wywołania metody execute przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.

W przypadku gdy wykonanie akcji przewidzianych przez daną wtyczkę powiedzie się, metoda powinna zwrćcić $ERRNO{'OK'}, w przeciwnym wypadku powinna zwrócić $ERRNO{'ERROR'}. W tym drugim przypadku AddUser-NG przerwie wykonywanie kolejnych wtyczek i zacznie cofać zmiany, więcej o tym przeczytasz w podrozdziale „Cofanie zmian (rollback)”.

Cofanie zmian (rollback)

W przypadku, gdy wykonanie któregoś plugina nie powiedzie się (metoda execute zwróci numer błędu inny od $ERRNO{'OK'}) AddUser-NG przerwie wykonywanie kolejnych pluginów i zacznie uruchamiać metodę rollback dla wszystkich wykonanych (włącznie z tym który zwrócił błąd). Jej zadaniem jest cofnięcie wszystkich zmian jakie wprowadziła dana wtyczka.

Przykład 2.4. Szkielet metody rollback


sub rollback {
    my $self = shift;

    # ... code follows here :)

    return $ERRNO{'OK'};
}

                

W momencie wywołania metody rollback przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.

W obecnej wersji wartość zwracana przez tę metodę nie jest brana pod uwagę, ale może to ulec zmianie w kolejnych wersjach, dlatego zalecamy zwracać warotść informującą o powodzeniu (bądź też niepowodzeniu) wykonania.